Implementing single-signon using SPNEGO in an Active Directory domain

A Simple and Protected GSS-API Negotiation (SPNEGO) mechanism is provided to implement single sign-on in Active Directory domains

Before you begin

This task requires the following elements in your network:

The following procedures include examples based on the following setup:
  • mycompany.com is the name of the TCP/IP domain used by all hosts in the domain.
  • ITDEV.COM is the name of the Active Directory domain.
  • it_directory.mycompany.com is the host where the directory server runs. It also runs the Kerberos KDC.
  • it_domain.mycompany.com is the host where the Active Directory domain controller runs.
  • it_buildforge.mycompany.com is the host where Build Forge is installed.
  • bfuser is the domain user name for the Build Forge system.
  • happy_user is the domain user name for an example user who will use SSO in a web browser to access Build Forge.

About this task

Perform the following tasks to implement the SPNEGO SSO in an Active Directory domain and KDC. Each is given a section with detailed procedures.
Note: The SPNEGO interceptor can be used with KDCs other than Active Directory.

Procedure

  1. Set up Active Directory users and service principals.
  2. Set up Kerberos files.
  3. Configure Build Forge to use Active Directory and SPNEGO.
  4. Configure browser clients for secure access.
  5. Access Build Forge through SSO.

Setting up Active Directory users and service principals

The Build Forge server and Build Forge clients must be set up in an Active Directory domain.

Before you begin

Support Tools for Windows 2003 SP2 are required for the following procedure. They contain the setspn command, which is required to set a service principal in Active Directory. Install Support Tools from the Windows Server 2003 product CD or the Microsoft Download Center.

About this task

When the Build Forge client and server are in an Active Directory domain, a user generates a Kerberos credentials token when logging into a Windows host. When the user then attempts to access the Build Forge server, the SPNEGO interceptor receives the user token and validates it. The validated identity is passed to the Build Forge to perform a login through the configured Microsoft Active Directory LDAP server.

Procedure

  1. Log on to the domain controller host. In the example, the host is it_example.mycompany.com.
  2. Add the Build Forge host to the Active Directory domain if it is not already a member. In this example, add host it_buildforge to the ITDEV.COM domain. The host now has a fully qualified name in the domain: it_buildforge.ITDEV.COM
  3. Add a Build Forge user to the Active Directory domain. In this example, create user bfuser.
    Important:
    • Select Password never expires. You may select other password management. However, you will need to enter a new password for the Build Forge server each time it expires.
    • In the Accounts tab, select Account is trusted for delegation
  4. If they do not exist, create user accounts in Microsoft Active Directory for all clients. In this example, there is one user to create, happy_user.
  5. Create a service principal name (SPN) for Build Forge. In the example, the Active Directory user bfuser is associated with service name HTTP/it_buildforge.mycompany.com to create the SPN for the Build Forge server, it_buildforge.
    setspn -A HTTP/it_buildforge.mycompany.com bfuser

    HTTP is the service name for the Build Forge service.

Setting up files for Kerberos authentication

A startup file (Kerberos client configuration file) and a keytab file need to be set up on the Build Forge host.

Procedure

  1. Set up the startup file on the host where Build Forge runs.
    • Windows systems:
      • Name the file krb.ini and place it in C:\winnt. Create C:\winnt if it does not exist.
      • Set default_keytab_name to FILE:C:\winnt\krb5.keytab.
    • UNIX and Linux systems:
      • Name the file krb.conf and place it in C:\winnt.
      Set default_keytab_name to FILE:/etc/krb5.keytab.

    The following example file is set up for Windows using domain and realm settings from the example systems.

    [libdefaults]
    	default_realm = ITDEV.COM
    	default_keytab_name = FILE:C:\winnt\krb5.keytab
    	default_tkt_enctypes = rc4_hmac
    	default_tgs_enctypes = rc4_hmac
    #	kdc_default_options = 0x40800000
    	forwardable  = true
    	renewable  = true
    	noaddresses = true
    	clockskew  = 300
    [realms]
    	ITDEV.COM = {
    		kdc = it_directory.itdev.com:88
    		default_domain = mycompany.com
    [domain_realm]
    	.mycompany.com = ITDEV.COM
    Note: Tokens will not work if the clock skew between client hosts and the Build Forge server host is more than 300 seconds. Set the time, date, and time zone to within skew limits on the client and server hosts.
  2. Set up a Kerberos keytab file. The keytab file is used by the Build Forge server to validate Kerberos tokens when a client attempts to access the Build Forge server URL. Use the ktpass command on the Domain Controller host to create the file. The ktpass command is included in the prerequisite Windows resource toolkit. The following example uses the principal name of the Build Forge service and the Active Directory user name set up for Build Forge in the example scenario. Substitute your own password for -pass Rat1onal. Line breaks are shown in the example for clarity. Do not use them in your ktpass command.
    ktpass -out C:\it_buildforge.keytab 
    -princ HTTP/it_buildforge.mycompany.com@ITDEV.COM 
    -mapuser bfuser -mapop set 
    -pass Rat1onal /crypto RC4-HMAC-NT /rndpass /ptype KRB5_NT_SRV_HST
    Rename it_buildforge.keytab to krb5.keytab and put it on the Build Forge host in the directory that contains the Kerberos startup file.
    • Windows: C:\winnt\
    • UNIX and Linux: /etc

Configuring Build Forge to use Active Directory and SPNEGO

Procedure

  1. In Build Forge, set up LDAP to point to the Active Directory domain controller.
    1. In Build Forge, click Administration > LDAP.
    2. Set up access to your domain controller by creating a new LDAP configuration and setting properties as follows.
      • Name: set to the name of your Active Directory domain. In the example environment this would be itdev.
      • Admin DN: set to an administrator user in the domain.
      • Map Access Groups: No
      • Host: set to the IP address of the domain controller host.
      • Bind User Account: Yes
      • Protocol: LDAP
      • Display Name: displayname
      • Distinguished Name: distinguishedname
      • Group Name: memberof
      • Mail Name: displayname
      • Search Base: on=users,do=domainname,do=domainextension. In the example environment this would be on=users,do=itdev,do=.com
      • Unique Identifier: sAMAccountNames=%
    3. Click Make Default. This configuration needs to be the default LDAP configuration.
  2. Set Build Forge environment variables for SPNEGO.
    1. In Build Forge, go to Environments > Environment for SPNEGO SSO.
    2. Set bf_spnego_service_name to HTTP This matches the service principal name.
    3. Set bf_spnego_server_name to it_buildforge.mycompany.com, the fully qualified host name for the Build Forge server host. If this variable is not set, INetAddress APIs attempt to locate the host name.
    4. Set bf_spnego_realm to ITDEV.COM, the Kerberos realm name. If this variable is not set, the value in the Kerberos startup file is used.
  3. Enable the SPNEGO interceptor.
    1. In Build Forge, go to Administration > Security > SSO > SPNEGO SSO Interceptor.
    2. Set the Active property to Yes, and then click Save.
    3. In Administration > Security > SSO, move SPNEGO SSO Interceptor to the top of the list. Use the Move to Top selection in the SSO Options menu for SPNEGO SSO Interceptor, then click Save.

Configuring client browsers for SSO

Client browsers must have security settings set up to use SPNEGO.

About this task

Use the client setup instructions for the browser used to access Build Forge, either Microsoft Internet Explorer or Mozilla Firefox.

Procedure

Access Build Forge through SSO

Enter the server URL to test login through SSO.

Procedure

  1. Log on to a host that is in the Active Directory domain, using a user name that is in the Active Directory list of users.
  2. Open your browser.
  3. Enter the URL for the Build Forge server host. Using the example configuration, this would be http://it_buildforge.mycompany.com. If SSO is configured correctly, you see the Build Forge management console.
  4. Verify that the user name shown on the upper right of the Build Forge console matches the client's Windows login name.

Feedback