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

Environment requirements

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

Client requirements

  • Chrome
  • Internet Explorer 11 or later
  • 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:
  2. Sam account name: xl-release
  3. User principal name: xl-release@example.com
  4. Service principal names: HTTP/xl-release.example.com
  5. Password: Passw0rd
  6. 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 and Internet Explorer do not require any 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.

Cluster environment setup

If you have a cluster environment with a load balancer and multiple Release nodes, the service principal should be added for your load balancer.

No additional configuration on the load balancer is needed.

Important: The keytab file should be generated with fully qualified Service Principal Name of the load balancer.

See Configure the Release Server for the sample configuration file which should be present on all xl-release nodes.

Also see Configuring a cluster to know more about cluster setup.

Does the load balancer use a port other than default (80 or 443)?

By default, the browser doesn’t include the port number information in the SPN that’s used to request a Kerberos ticket. You must pass explicit flags or enable policies to pass the port number information.

Visit the following links for browser specific information. Internet Explorer New Chromium based Microsoft Edge Google Chrome

Crypto

You can export the entire crypto format in a keytab file and use it on xl-release server. Release will then pick up the RC4_HMAC_MD5. This may change based on the flavor of the JDK.

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

Release will throw exception if RC4HMACMD5 is not abled for user.

Note: If you want to use any specific crypto for user account, it should be updated on windows configuration.

More information on can be found here

Use the powershell script below to export the keytab file with the AES256-SHA1 crypto with salt algorithm.

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 AES256-SHA1 `
    /mapOp set +DumpSalt

Now create a kerberos configuration file on xl-release server in the /etc/krb5.conf file, using the following settings:

[libdefaults]
	default_tkt_enctypes = aes256-cts
	default_tgs_enctypes = aes256-cts
	permitted_enctypes = aes256-cts

This will now only allow AES256 encryption types. See permitted enctypes for more information.

Note: If you want to provide a custom path for the krb5.conf file, you can do it by using the java.security.krb5.conf the system property.

To know more about locating the krb5.conf configuration file, see Kerberos requirements.

To know more about ktpass, see ktpass

Debugging

To enable extra debugging in case of any failures, make the changes shown below:

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.