Integrated Windows Authentication

This topic describes how support Single Sign-On (SSO) by configuring Release to use Integrated Windows Authentication to authenticate users and retrieve role (group) membership without prompting the users for a user name and password. In Release, Active Directory users and groups become principals that you can assign to roles.

While role memberships and permissions assigned to roles are stored in the Release repository, Release treats the Active Directory repository as read-only. This means that Release will use information from the Active Directory repository, but it cannot make changes to that information.

note

Currently Release supports only the SPNEGO/Kerberos based cryptographic exchange. NTLMSSP authentication is not supported.

Requirements

Server requirements

Release SPNEGO Authentication plugin is required along with other requirements such as Windows server an so on.

Environment requirements

• Microsoft Windows Server 2012 R2 (or later) Windows domain controller, with configured DNS Server and Active Directory

Client requirements

• Chrome
• Firefox (requires additional configuration)

Setup

Example setup:

• Windows domain: EXAMPLE.COM
• Windows workgroup: EXAMPLE
• Windows Domain Controller machine: dc.example.com
• Windows Workstation machine: client.example.com
• Windows Domain administrator user: Administrator@EXAMPLE.COM
• Some Windows Domain (normal) users: (i.e. Bob@EXAMPLE.COM)
• Release server machine: xl-release.example.com

Please adapt the values to your actual environment.

Server setup

Configure the Windows Domain Controller

On dc.example.com:

1. Create an HTTP server account user for Release server in Active Directory:

• Sam account name: xl-release
• User principal name: xl-release@example.com
• Service principal names: HTTP/xl-release.example.com
• Password: Passw0rd

1. Export the Kerberos Keytab file to C:\example.com_xl-release_keytab:

ktpass `
    /out C:\example.com_xl-release_keytab `
    /mapuser xl-release@EXAMPLE.COM `
    /princ HTTP/xl-release.example.com@EXAMPLE.COM `
    /pass Passw0rd `
    /ptype KRB5_NT_PRINCIPAL `
    /crypto All

1. Copy the Kerberos Keytab file to the xl-release.example.com host.

Configure the Release Server

This example assumes that Release was installed in the XL_RELEASE_SERVER_HOME directory and that the exported Kerberos Keytab file was copied to /tmp.

On xl-release.example.com:

1. Download the Release SPNEGO Authentication plugin ZIP from the distribution site.
2. Install the plugin in Release.
3. To configure the SPNEGO Authentication plugin, modify the XL_RELEASE_SERVER_HOME/conf/xl-release.conf file by adding a xl.security.auth.providers section:

xl {
  security {
    auth {
      providers {
        kerberos {
          servicePrincipal = "HTTP/xl-release.example.com@EXAMPLE.COM"
           keyTabLocation = "file:///tmp/example.com_xl-release_keytab"

            ldap {
              url = "ldap://dc.example.com"
              userDn = "xl-release@example.com"
              password = "Passw0rd"

            userSearch {
              base = "cn=users,dc=example,dc=com"
              filter = "(&(objectClass=user)(userPrincipalName={0}))"
                  }

            groupSearch {
              base = "cn=users,dc=example,dc=com"
              filter = "(&(objectClass=group)(member={0}))"
              rolePrefix = ""
                }
              }
            }
          }
        }
      }
    }

Optional: form-based authentication using domain credentials

With the configuration described in the previous section in place, you can automatically access any Release page directly without entering credentials on the login page. If you still want to provide the classic form-based authentication against Active Directory (e.g. login using domain credentials from non Microsoft Windows client computers), you must modify the XL_RELEASE_SERVER_HOME/conf/xl-release-security.xml security configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:security="http://www.springframework.org/schema/security"
        xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security.xsd
        ">

    <bean id="rememberMeAuthenticationProvider"
        class="com.xebialabs.deployit.security.authentication.RememberMeAuthenticationProvider"
        />

        <security:authentication-manager alias="authenticationManager">
        <security:authentication-provider ref="rememberMeAuthenticationProvider"/>
        <security:authentication-provider ref="activeDirectoryProvider"/>
        <security:authentication-provider ref="xlAuthenticationProvider"/>
        </security:authentication-manager>
</beans>

The activeDirectoryProvider authentication provider uses the values specified in the xl.security.auth.providers.kerberos.ldap section of the xl-release.conf configuration file.

Configure the Windows Client

• Make sure you can log in into your Windows workstation using a domain user.
• Add the network interface that will be used to contact xl-release.example.com to the list of trusted networks.

Browsers

Chrome needs no further configuration.

For Firefox, you must modify your configuration settings by navigating to about:config in the URL, type 'negotiate' into the Filter field, and set the following fields to:

network.negotiate-auth.delegation-uris  xl-release.example.com
network.negotiate-auth.trusted-uris     xl-release.example.com

Test the authentication plugin

1. Restart Release.
2. Log in as a domain user on client.example.com
3. Open a browser and navigate to http://xl-release.example.com/ (or https://xl-release.example.com/ if you use HTTPS).
4. Click Log in with Windows.

If you are using a Windows host, the authentication starts immediately. A confirmation message displays if you have been successfully authenticated. If you are using a non-Windows machine, you must manually enter your Active Directory credentials into the login form.

Troubleshooting

org.ietf.jgss.GSSException: Defective token detected (Mechanism level: GSSHeader did not find the right tag)

The client is initiating an NTLM handshake instead of a SPNEGO handshake. Verify that the browser is correctly configured and that the Release server is accessed using a fully-qualified domain name.

Encryption type AES256 CTS mode with HMAC SHA1-96 is not supported/enabled

The JCE framework within JDK includes an ability to enforce restrictions regarding the cryptographic algorithms and maximum cryptographic strengths available to applications. These restrictions are specified in "jurisdiction policy files". The jurisdiction policy files bundled in Java SE limit the maximum key length.

To use the AES256 encryption type, you will need to install the JCE crypto policy with the unlimited version to allow AES with 256-bit key.

The JCE files can be downloaded from:

http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html

Review the README file within the package and install the two JAR files.