Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

SPNego Authentication with JBoss

DZone's Guide to

SPNego Authentication with JBoss

· Integration Zone
Free Resource

Learn how API management supports better integration in Achieving Enterprise Agility with Microservices and API Management, brought to you in partnership with 3scale

Background

SPNego is RFC 4178 used for negotiation either NTLM or Kerberos based SSO. A typical use case is for web applications to reuse the authentication used by Desktops such as Windows or Linux.


In this article, we will explore approaches for SPNego authentication with JBoss Enterprise Application Platform.

JBoss Negotiation is the library that provides the SPNego authentication support in JBoss. This library has been integrated in JBoss EAP and WildFly Application Server.

Checklist

  1. Obtain JBoss EAP from jboss.org.
  2. Enable your JavaEE Web Application for SPNego Authentication.
  3. Configure JBoss EAP for SPNego.
  4. Configure your Browsers for SPNego.
  5. Start JBoss EAP.
  6. Test your web application.

Obtain JBoss EAP from jboss.org

Download JBoss EAP 6.2 or newer from http://www.jboss.org/products/eap 


You can also use WildFly Application Server from http://www.wildfly.org.  Your configuration may vary slightly.

Enable your JavaEE Web Application for SPNego Authentication

It is easier to use a demo web application as a starting point. You can then modify your web application for SPNego authentication.

The demo web application we use for this article is called spnego-demo, by my colleague, Josef Cazek. The demo web application is available at https://github.com/kwart/spnego-demo . You can also download the spnego-demo.war from here .

Fully configured web application spnego-demo.war can be obtained from  this location .
Copy the spnego-demo.war in your jboss-eap-6.2/standalone/deployments directory.

Configure JBoss EAP for SPNego Authentication

You will need to configure a couple of security domains and system properties in JBoss EAP6.
There are two ways by which you can configure: either manual editing or using CLI tool.

Manual Editing of configuration file standalone.xml in jboss-eap-6.2/standalone/configuration

Add system properties to this file.

<system-properties>
  <property name="java.security.krb5.conf" value="/tmp/spnego-in-as7/krb5.conf"/>
  <property name="java.security.krb5.debug" value="true"/>
  <property name="jboss.security.disable.secdomain.option" value="true"/>
</system-properties>

Remember to put this block right after the extensions block (around line 25 of the configuration file).

Add security domains to this file.

<security-domain name="SPNEGO" cache-type="default">
    <authentication>
         <login-module code="SPNEGO" flag="required">
            <module-option name="serverSecurityDomain" value="host"/>
         </login-module>
     </authentication>
     <mapping>
         <mapping-module code="SimpleRoles" type="role">
            <module-option name="jduke@JBOSS.ORG" value="Admin"/>
            <module-option name="hnelson@JBOSS.ORG" value="User"/>
         </mapping-module>
     </mapping>
 </security-domain>
 <security-domain name="host" cache-type="default">
     <authentication>
         <login-module code="Kerberos" flag="required">
            <module-option name="debug" value="true"/>
            <module-option name="storeKey" value="true"/>
            <module-option name="refreshKrb5Config" value="true"/>
            <module-option name="useKeyTab" value="true"/>
            <module-option name="doNotPrompt" value="true"/>
            <module-option name="keyTab" value="/tmp/spnego-in-as7/http.keytab"/>
            <module-option name="principal" value="HTTP/localhost@JBOSS.ORG"/>
         </login-module>
     </authentication>
  </security-domain>
Remember to put these blocks in the  <subsystem xmlns="urn:jboss:domain:security:1.2"> block.

Using Command Line Interface to update JBoss EAP

Go to the bin directory of JBoss EAP 6.2 and run the following.

$ cat << EOT > $SPNEGO_TEST_DIR/cli-commands.txt
/subsystem=security/security-domain=host:add(cache-type=default)
/subsystem=security/security-domain=host/authentication=classic:add(login-modules=[{"code"=>"Kerberos", "flag"=>"required", "module-options"=>[ ("debug"=>"true"),("storeKey"=>"true"),("refreshKrb5Config"=>"true"),("useKeyTab"=>"true"),("doNotPrompt"=>"true"),("keyTab"=>"$SPNEGO_TEST_DIR/http.keytab"),("principal"=>"HTTP/localhost@JBOSS.ORG")]}]) {allow-resource-service-restart=true}

/subsystem=security/security-domain=SPNEGO:add(cache-type=default)
/subsystem=security/security-domain=SPNEGO/authentication=classic:add(login-modules=[{"code"=>"SPNEGO", "flag"=>"required", "module-options"=>[("serverSecurityDomain"=>"host")]}]) {allow-resource-service-restart=true}
/subsystem=security/security-domain=SPNEGO/mapping=classic:add(mapping-modules=[{"code"=>"SimpleRoles", "type"=>"role", "module-options"=>[("jduke@JBOSS.ORG"=>"Admin"),("hnelson@JBOSS.ORG"=>"User")]}]) {allow-resource-service-restart=true}

/system-property=java.security.krb5.conf:add(value="$SPNEGO_TEST_DIR/krb5.conf")
/system-property=java.security.krb5.debug:add(value=true)
/system-property=jboss.security.disable.secdomain.option:add(value=true)

:reload()
EOT

$ ./jboss-cli.sh -c --file=$SPNEGO_TEST_DIR/cli-commands.txt
This is explained in  https://github.com/kwart/spnego-demo/blob/master/README.md 
We will need a keytab file. 
In this example, we will use the Kerberos Server using ApacheDS (as explained in Appendix A).
$ java -classpath kerberos-using-apacheds.jar org.jboss.test.kerberos.CreateKeytab HTTP/localhost@JBOSS.ORG httppwd http.keytab

Note that the http.keytab has been configured in the security domain called "host" in standalone.conf.  So place the keytab file appropriately while correcting the path defined in security domain.

More information is available at https://github.com/kwart/kerberos-using-apacheds/blob/master/README.md 

JBoss EAP will need a keytab file. In this example we use a keytab called as http.keytab


Different tools such as ktutil exist to create keytab files. Keytab files contain Kerberos Principals and encrypted keys. It is important to safeguard keytab files.


It is very important that JBoss EAP configuration for keytab in the security domain "host" refers to the actual path of the keytab file.


Configure your Browsers for SPNego

The browsers such as Microsoft IE, Mozilla Firefox, Google Chrome, Apple Safari have different settings for enabling SPNego or Integrated Authentication.

Start JBoss EAP

Go to the bin directory of JBoss EAP 6.2 and either use standalone.sh (Unix/Linux) or standalone.bat to start your instance.

Test your Web Application

Assuming you have followed Appendix A steps to start the kerberos server and done kinit, you are ready to test the web application.

In this article we have used spnego-demo, we can test that by going to 

http://localhost:8080/spnego-demo/

You can click on the "User Page" link and you should be able to see the principal name as "hnelson@jboss.org"

Appendix A

Local Kerberos Server

  1. Download the zip file https://github.com/kwart/kerberos-using-apacheds/archive/master.zip 
  2. Unzip the zip file into a directory.
  3. Build the package using maven.  
    $ mvn clean package
  4. Start the Kerberos Server as
    $ java -jar target/kerberos-using-apacheds.jar test.ldif
  5. A krb5.conf file has been created.
  6. Login now using hnelson@jboss.org
    $ kinit hnelson@JBOSS.ORG
    Password for hnelson@JBOSS.ORG: secret
  7. Launch Firefox via command line from where the kinit was run On MacOSX
    $open -a firefox http://localhost:8080/spnego-demo/
    

Appendix B

Kerberos Command Line Utilities

klist can be used to see the current kerberos tickets.

$ klist
Credentials cache: API:501:10
        Principal: hnelson@JBOSS.ORG

  Issued                Expires               Principal
Feb  9 21:19:30 2014  Feb 10 07:19:27 2014  krbtgt/JBOSS.ORG@JBOSS.ORG
kdestroy can be used to clear the current kerberos tickets.

References

  1. SPNego Demo Web Application: https://github.com/kwart/spnego-demo 
  2. Kerberos Server using ApacheDS: https://github.com/kwart/kerberos-using-apacheds 
  3. JBoss EAP 6  http://www.jboss.org/products/eap 
  4. PicketLink Open Source Project: http://www.picketlink.org 

Troubleshooting

https://docs.jboss.org/author/display/PLINK/SPNego+Support+Questions

Remember krb5.conf is important for client side kerberos interactions. You can use a environment variable on Unix/Linux/Mac systems called KRB5_CONFIG to point to your krb5.conf

Acknowledgement

Darran Lofthouse for the wonderful JBoss Negotiation Project and Josef Czacek for the SPNego-demo and Kerberos_using_Apache DS projects.

Unleash the power of your APIs with future-proof API management - Create your account and start your free trial today, brought to you in partnership with 3scale.

Topics:

Opinions expressed by DZone contributors are their own.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}