MidVision RapidDeploy technical documentation site

Integrated Windows Auhentication (SPNENGO / Kerberos)

The framework can be configured to support SPNEGO / kerberos Authentication.

What is this?

Kerberos is a standardized network authentication protocol, which is designed to provide strong authentication for client/server application, like web applications where the Browser is the client. It is also the recommended way to authenticate users in a Windows network and it replaces the outdated and relatively insecure NTLM.

Besides this, it is widely used in *NIX environments and there are implementations for every major platform. So, it is very likely that you already have Kerberos in place and now you can use this also in your own web application. That means that your user just enters the URL and he is automatically authenticated with his domain username, for example mvadmin@MYCOMPANY.COM

How does this work?

The Browser sends a GET request to your web application.
which then returns that "negotiate" authentication is required.
The Browser will then ask the Kerberos Server to get a so called service ticket.
The Browser then send this service ticket, which proves the identity of the caller, and some additional things to the web application
After validating the ticket, based on some shared secret between your web application and the Kerberos server, you get back the username.
For this to work, every web applications needs to be registered at the Kerberos server and gets a service prinicipal and a shared secret assigned. For web applications, the service principal must be "HTTP/full qualified domain name@DOMAIN". For example "HTTP/www.midvision.com@MYCOMPANY.COM", if your app runs on www.midvision.com. You then need to export the credentials of this principal to a keytab file (shared secret) and make this available to your application. Every Kerberos based system will work this way, but the creation of this service principal and the keytab is different between the systems.

Creating Service Principal with Microsoft Windows 2008 Server

Although this refers to Microsoft Windows 2008 Server, it should be very similar in 2003 and even 2000 Server. In ActiveDirectory, you just create a normal domain user and then assign him a service principal (SPN), and create the keytab with a command line utility. And now step by step:
Create a normal user which will become the service principal. The username and the password is meaningless for Kerberos, but you should of course choose a useful name, like http-www.midvision.com. Just make sure that you deactivate the option "User must change password at next logon" and activate "Password never expires".
After that, you have to use the command line tool "ktpass.exe". It is already included in Windows 2008 Server, in earlier versions you have to install it yourself. Just make sure that you are using a version which matches to your server version and also the locale should match. This tool will assign the service principal name (SPN) to your earlier created user and will export the user key to a keytab file. If your service principal is "HTTP/www.midvision.com@MYCOMPANY.COM" and your user is http-www.midvision.com, then your ktpass command should look like this:
```
ktpass /out http-web.keytab /mapuser http-www.midvision.com@MYCOMPANY.COM /princ HTTP/www.midvision.com@MYCOMPANY.COM  /pass *
```
ktpass will prompt you for some password. You should choose some secure random one for it. If you now have a file http-web.keytab in your directory, then everything worked fine. This file is needed later in your application, as it contains the shared secret to validate the service tickets.

Creating service principal with MIT Kerberos

On *NIX systems and also in Mac OS X, the MIT Kerberos implementation is widely used. With MIT Kerberos it is even simpler. Just open the kadmin console and execute the following commands:
```
kadmin:  addprinc -randkey HTTP/www.midvision.com
kadmin:  ktadd -k /http-web.keytab HTTP/www.midvision.com
```
You should then have a file http-web.keytab under root. This file is later needed in your application, as it contains the shared secret to validate the service tickets.

Configuring Framework

Here's the steps for SPNEGO / Kerberos setup:

Set up the security context definition in %MV_HOME%/bin/rapiddeploy.properties.

#-----------------------------------------------
# Spring Security Context
#-----------------------------------------------
rapiddeploy.security.context.filename=applicationContext-security-spnego.xml
#-----------------------------------------------

Set up SPNEGO / Kerberos settings in %MV_HOME%/bin/rapiddeploy.properties.

#-----------------------------------------------
# SPNEGO / Kerberos Configuration
#-----------------------------------------------
rapiddeploy.security.spnego.service.principal=HTTP/www.midvision.com
rapiddeploy.security.spnego.key_tab.location=file:/http-web.keytab
rapiddeploy.security.kerberos.debug=false
rapiddeploy.security.kerberos.location=file:/midvision/sso/krb5/kdc.conf
# IBM JDK
rapiddeploy.security.kerberos.ticket.validator.class=com.midvision.rapiddeploy.web.security.kerberos.IbmJaasKerberosTicketValidator
# SUN JDK
#rapiddeploy.security.kerberos.ticket.validator.class=org.springframework.security.extensions.kerberos.SunJaasKerberosTicketValidator
#-----------------------------------------------

rapiddeploy.security.spnego.service.principal Service principal name.
rapiddeploy.security.spnego.key_tab.location KeyTab file location
rapiddeploy.security.kerberos.debug Enable / Disable kerberos debugging option
rapiddeploy.security.kerberos.location Value of the kerberos config location (JAAS). Leave it blank if you don't like to point to a different kerberos config location. It overwrites the default Java cecurity kerberos configuration property value (java.security.krb5.conf).
rapiddeploy.security.kerberos.ticket.validator.class Kerberos Ticket validator full class name.
For IBM JDK set the ticket validator class as com.midvision.rapiddeploy.web.security.kerberos.IbmJaasKerberosTicketValidator.

For Sun/Oracle set the ticket validator class as org.springframework.security.extensions.kerberos.SunJaasKerberosTicketValidator

Kerberos config example (file:/midvision/sso/krb5/kdc.conf):

[libdefaults]
        default_realm = MYCOMPANY.COM
[realms]
        MYCOMPANY.COM = {
                kdc = winsvr2003r2.midvision.com
                kpasswd_server = winsvr2003r2.midvision.com
                admin_server = winsvr2003r2.midvision.com
                kpasswd_protocol = SET_CHANGE
        }

[domain_realm]
        .midvision.com = MYCOMPANY.COM
        midvision.com = MYCOMPANY.COM
        
[logging]
        default = FILE:/midvision/sso/krb5/kdc.log
        kdc = FILE:/midvision/sso/krb5/kdc.log
        kdc_rotate = {
                period = 1d
                versions = 10
        }

[appdefaults]
        kinit = {
                renewable = true
                forwardable = true
        }