This section describes how to used Integrated Windows Authentication (SPNEGO) between PortalProtect Dispatcher and backend web server (typically Microsoft IIS).

This can be used regardless of the method used to authenticate the user.

Note that there is a rather large performance penalty (typically 60-70 milliseconds per request) for enabling SPNEGO between the Dispatcher and the backend web server, so you should avoid using it for heavy traffic.

How it Works

Once enabled, PortalProtect Dispatcher will monitor the response from the backend webserver. If it returns HTTP response code “401 Authentication Required” with an “WWW-Authenticate: Negotiate” header, then the dispatcher will attempt to create a new SPNEGO token and resend the request with a new HTTP header added, “Authorization: Negotiate xxxxxxx” where xxxxxxx is the SPNEGO/Kerberos ticket.

Generating this ticked involves contacting the Active Directory server to login with the user and obtain a ticket, then the AD server is asked to create a ticket containing the client credentials, encrypted with the credentials of the server. This involves at least 2 roundtrips to the AD server for every request. Because of replay attack defence the tickets cannot be reused but need to be created for each request.

When the IIS server then processes the request, it in turn contacts the AD server to validate the ticket.

If more than one step is required, the backend server keeps sending “401 Authentication Required” and the dispatcher keeps sending a new request until the SPNEGO negotiation has either completed or failed.

Once the IIS returns a reply, the dispatcher is forced to close the persistent HTTP1.1 connection (if any) – otherwise if the connection is later reused for subsequent requests on behalf of other users, the IIS might incorrectly think the request belongs to an authenticated user.

Obtaining Credentials

For the SPNEGO negotiation to work, the PortalProtect Dispatcher requires access to userid and password of either a technical user, or the real user.

A technical userid/password can be configured using integratedWindowsAuthenticationUserid and integratedWindowsAuthenticationPassword. The password can be obfuscated/encrypted using the same mechanisms passwords in the general configuration.

Take care not to expose access to sensitive information when using technical users, since this userid/password will be used by default for all identified and anonymous portalprotect sessions that do not contain a userid/password for integrated windows authentication specifically for this user.

If the portalprotect session / user is authenticated, PortalProtect Dispatcher will look in the session for the state variables integratedWindowsAuthenticationUserid and integratedWindowsAuthenticationPassword – if both are found, they are used instead of the technical user. The password in the session can likewise be encrypted/obfuscated so you do not need to keep the users private password in cleartext and accessible to the applications in the session.

This enables you to authenticate users using e.g. NemID, and then obtain their AD userid/password upon authentication – this can then be used to reauthenticate the user against backend servers. This is often useful if you need to forward credentials to a server which you are unable to modify.

Configuration

The following is an example of configuring the dispatcher to perform SPNEGO towards all backend servers – to only enable this for certain specific alternate server configurations, instead of setting supportIntegratedWindowsAuthentication=true consider setting it to false, and alternateserver.xxxx.supportIntegratedWindowsAuthentication=true – this way SPNEGO is only enabled for the specific alternate server instead of all servers.

<group name="SPNEGO" description="Integrated Windows Authentication (SPNEGO)">
  <property name="integratedWindowsAuthenticationLoginContextName" value="kerberos-client" description="Name of logincontext in login.conf to use"/>
  <property name="integratedWindowsAuthenticationPassword" value="xxxx" description="Password for technical user to authenticate against IIS"/>
  <property name="integratedWindowsAuthenticationUserid" value="testclient@PPTEST.DK" description="Userid for technical user to authenticate against IIS"/>
  <property name="spnego.krb5.conf" value="${portalprotect.home}/config/spnego/krb5.conf" description="Name of kerberos krb5 configuration file"/>
  <property name="spnego.login.conf" value="${portalprotect.home}/config/spnego/login.conf" description="Name of login module configuration file"/>
  <property name="supportIntegratedWindowsAuthentication" value="true" description="If true, support SPNEGO against backend webserver"/>
</group>

The property spnego.login.conf and the property integratedWindowsAuthenticationLoginContextName must point to a login configuration file, and the entry within it respectively.

The following is an example of a valid login.conf file.

kerberos-client {
    com.sun.security.auth.module.Krb5LoginModule required
    storeKey=true
    useTicketCache=false
    isInitiator=true
    client=true;
};

Below is an example of a krb5.conf file – be sure to replace the domain name values with the values appropriate for your domain.

[libdefaults]
    default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
    default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
    permitted_enctypes   = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
    kdc_timeout=2000

[realms]
    ITPTEST.DK  = {
        kdc = testserver.itptest.dk 
        default_domain = ITPTEST.DK
    }
    PPTEST.DK  = {
        kdc = domainadmin.pptest.dk
        default_realm=PPTEST.DK
    }

[domain_realm]
    .ITPTEST.DK = ITPTEST.DK
    .PPTEST.DK = PPTEST.DK

Note that you can only have one login.conf and one krb5.conf file configured per java virtual machine, so if you have more than a single dispatcher running in the same process, or both a dispatcher and a portalprotect server, all configuration entries pointing to krb5.conf or login.conf MUST point to the exact same file.

This is required since Sun in their infinite wisdom requires a system property to point to the files, and there is no way of having more in the same process.

Important Considerations

Hostname

SPNEGO/Kerberos is sensitive to using the correct hostname – make sure that if your hostname for a server is both e.g. www.mycompany.com and mycompany.com that both forms are registered on the AD server.

Case Sensitivity in Username

A Kerberos username is e.g. somebody@somewhere.com or somebody@SOMEWHERE.COM – whatever the domain name, it is important that it matches the configuration in the krb5.conf file or the authentication will fail.

PingURL Hostname

When setting up a ping URL in the dispatcher, instead of setting it to /index.aspx set it to http://somewhere.com/index.aspx - this causes the dispatcher to use “somewhere.com” as the hostname when creating the Kerberos ticket – not having this will cause authentication to fail.

Performance

Again, please realise that there is a significant performance hit on enabling integrated windows authentication, since it prevents the dispatcher from reusing persistent HTTP 1.1 connections, and introduces the overhead of multiple calls to the AD server for each request.

If possible, please configure your IIS or other webserver so it only requires authentication on resources that actually need it, and allow anonymous access to unimportant resources like gifs, javascript files or stylesheets.

Security

When using a technical user to authenticate against the backend web server, note that this userid/password is used for both authenticated and anonymous portalprotect sessions. You need to make sure that you do not inadvertently allow anonymous access to sensitive information by configuring this so always take care if setting up a technical userid for authentication since IIS will happily server content for the authenticated technical user unless the AD group memberships prevents it.