"Single Sign On" feature based on Kerberos authentication in Windows Active Directory environment is supported by version 7.6.0 and later. Implementing this feature for earlier CodeBeamer releases can be arranged through Intland Consulting Services.

The elements of the example scenario:

• INTLAND.LOCAL: the Windows Domain and Kerberos-realm we want to use for authentication
• winsvr.intland.local: the DNS-name of a Domain Controller (DC) of Windows Domain INTLAND.LOCAL. It also acts as KDC of realm INTLAND.LOCAL
• cb.intland.local: the DNS-name of the codebeamer server we want to kerberize. (It is a linux based Ubuntu server in this example)

Prerequirements

Host Names

Kerberos also expects the server's FQDN to be reverse-resolvable. If reverse domain name resolution is not available, set the rdns variable to false in clients' krb5.conf`

If the server already has an FQDN assigned to it, test forward and reverse look-up with the following commands:

$ nslookup winsvr.intland.local
$ nslookup <server ip address>

The output of the first command should contain the IP address of the server. The output of the second command should contain the FQDN of the server.

Connectivity

To verify connectivity between hosts, ping each host's:

In winsvr.intland.local:

ping cb.intland.local

If the server not accessible you can add it to the hosts file: C:\Windows\System32\drivers\etc\hosts

In cb.intland.local:

ping winsvr.intland.local

If the server not accessible you can add it to the hosts file: /etc/hosts

Time Synchronization

The Kerberos protocol requires the time of the client and server to match: if the system clocks of the client does not match that of the server, authentication will fail. The simplest way to synchronize the system clocks is to use a Network Time Protocol (NTP) server. (Note: Active Directory Domain Controllers are typically also NTP servers.)

Firewalls

As with all network services, Kerberos must be allowed to pass through any firewalls between hosts. The Kerberos System Administration Manual has a detailed section on this topic.

Setup apache 2 mods

The following actions should be performed in cb.intland.local to enable Kerberos and rewrite engine in apache2

Enable rewrite module:

$ a2enmod headers

Install apache2 kerberos module:

$ apt-get install libapache2-mod-auth-kerb krb5-user

Apache 2 restart should be required:

service apache2 restart

These commands only works on Ubuntu

Kerberos configuration of cb.intland.local

Configure Kerberos

The Kerberos realm INTLAND.LOCAL with KDC winsvr.intland.local should be configured in the /etc/krb5.conf file :

...

[libdefaults]

default_realm = INTLAND.LOCAL

...

[domain_realm]

cb.intland.local = INTLAND.LOCAL

intland.local = INTLAND.LOCAL

.intland.local = INTLAND.LOCAL

...

[realms]

INTLAND.LOCAL = {

admin_server = winsvr.intland.local

kdc = winsvr.intland.local

}

...

Test if Kerberos works

Do a basic check of your Kerberos setup using kinit

• have an username and password in Windows Domain INTLAND.LOCAL. In this example bela is used as username.

use your shell and type

$ kinit bela@INTLAND.LOCAL

If everything is OK the command will ask you for bela's domain password and terminates without an error message.

• use klist to show the initial ticket you have got from the KDC

  $ klist
  
  

Creating the HTTP service principal for cb.intland.local

For every kerberized host you have to create a service principal on the KDC.

• create an account in Windows Domain INTLAND.LOCAL. It is used like a machine account. In this example the name of the account is cbsrv.
• login to the DC winsvr.intland.local and use the Windows command line tool ktpass to map the account cbsrv to the service principal HTTP/cb.intland.local@INTLAND.LOCAL You need that service principal to kerberize host cb.intland.local.
• Use ktpass options as describe below:
  

  C:\>ktpass -princ HTTP/cb.intland.local@INTLAND.LOCAL -mapuser cbsrv@INTLAND.LOCAL -crypto ALL -ptype KRB5_NT_PRINCIPAL -pass password-for-cbsrv -out c:\temp\cb-kerberos.keytab
  
  

  
  

The ktpass command creates the pricipal HTTP/cb.intland.local@INTLAND.LOCAL, maps it to AD account cbsrv and exports it's key to the keytabfile c:\temp\cb-kerberos.keytab. Copy that file to cb.intland.local, for example the following path:

/etc/apache2/cb-kerberos.keytab

Check if the KDC sends correct tickets

Check domain and user properties on winsvr.intland.local

Check for SPN associated with account cbsrv:

> C:\Users\Administrator>setspn -L cbsrv
Registered ServicePrincipalNames for CN=cbsrv,CN=Users,DC=intland,DC=local:
   HTTP/cb.intland.local

Check for duplicate SPN:

> C:\Users\Administrator>setspn -X
Checking domain DC=intland,DC=local
Processing entry 0
found 0 group of duplicate SPNs.

If the setspn find duplications for intland.local the ticket request (kvno) will fail on cb.intland.local.

Check if the KDC sends correct tickets (kvno, enctype) on cb.intland.local:

Obtain and cache Kerberos ticket-granting tickets for user cbsvr.

$ kinit cbsrv@INTLAND.LOCAL
Password for cbsrv@INTLAND.LOCAL:

Acquires a service ticket for the service principal:

$ kvno HTTP/cb.intland.local@INTLAND.LOCAL
HTTP/cb.intland.local@INTLAND.LOCAL: kvno = 5, keytab entry valid

List the Kerberos principal and Kerberos tickets held in a credentials cache:

$ klist -e
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: cbsrv@INTLAND.LOCAL

Valid starting     Expires            Service principal
02/03/15 10:47:30  02/03/15 20:47:30  krbtgt/INTLAND.LOCAL@INTLAND.LOCAL
	renew until 02/04/15 10:47:23, Etype (skey, tkt): arcfour-hmac, arcfour-hmac
02/03/15 10:47:32  02/03/15 20:47:30  HTTP/cb.intland.local@INTLAND.LOCAL
	renew until 02/04/15 10:47:23, Etype (skey, tkt): arcfour-hmac, arcfour-hmac

List the Kerberos principal and Kerberos tickets held in the generated keytab file:

$ klist -e -k -t /etc/apache2/cb-kerberos.keytab
Keytab name: FILE:/etc/apache2/cb-kerberos.keytab
KVNO Timestamp         Principal
---- ----------------- --------------------------------------------------------
   5 01/01/70 01:00:00 HTTP/cb.intland.local@INTLAND.LOCAL (arcfour-hmac)

It's important to check in detail:

• ticket's kvno must match kvno in keytab
• principal name in ticket must match the principal name in keytab

Preparing the keytab file

• Make /etc/apache2/cb-kerberos.keytab readable (chmod 400) for the user that owns the httpd process.
• Test if the created keytab file works on cb.intland.local using kinit with loading key from keytab file:
  

  $ kinit -k -t /etc/apache2/cb-kerberos.keytab HTTP/cb.intland.local
  

  
  

If this doesn't work then you know it's your Kerberos config that's the problem and nothing to do with Apache or the module at all.

Configure apache 2 to use kerberos authentication

Open /etc/apache2/apache2.conf file, and append the following lines:

LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so
LoadModule auth_kerb_module modules/mod_auth_kerb.so

<VirtualHost *:80>
    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>
    ProxyRequests Off
    ProxyPreserveHost On
    ProxyPass /cb http://localhost:8080/cb
    ProxyPassReverse /cb http://localhost:8080/cb
    ServerName cb.intland.local
    <Location /cb>
                Order allow,deny
                Allow from all
                AuthType Kerberos
                KrbServiceName HTTP
                AuthName "Domain login"
                KrbAuthRealms INTLAND.LOCAL
                Krb5KeyTab /etc/apache2/cb-kerberos.keytab
                require valid-user
                KrbLocalUserMapping On
                KrbMethodNegotiate  On
                KrbMethodK5Passwd   Off

                # Below directives puts logon name of authenticated user into http header X-User-Global-ID
                RequestHeader unset X-User-Global-ID
                RewriteEngine On
                RewriteCond   %{LA-U:REMOTE_USER} (.+)
                RewriteRule   /cb.* - [E=RU:%1,L,NS]
                RequestHeader set X-User-Global-ID %{RU}e

                # Remove domain suffix to get the simple logon name
                RequestHeader edit X-User-Global-ID "@INTLAND.LOCAL$" ""

   </Location>
</VirtualHost>

If you want to use the AJP port you should use these settings:

LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so
LoadModule proxy_ajp_module /usr/lib/apache2/modules/mod_proxy_ajp.so
LoadModule auth_kerb_module modules/mod_auth_kerb.so

<VirtualHost *:80>
    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>
    ProxyRequests     Off
    ProxyPreserveHost On
    ProxyPass /cb ajp://localhost:8009/cb
    ProxyPassReverse /cb ajp://localhost:8009/cb
    ServerName perf.intland.local
    <Location /cb>
                Order allow,deny
                Allow from all
                AuthType Kerberos
                KrbServiceName HTTP
                AuthName "Domain login"
                KrbAuthRealms INTLAND.LOCAL
                Krb5KeyTab /etc/apache2/kerberos.keytab
                require valid-user
                KrbMethodNegotiate  On
                KrbMethodK5Passwd   Off
                KrbLocalUserMapping On

                # Below directives puts logon name of authenticated user into http header X-User-Global-ID
                RequestHeader unset X-User-Global-ID
                RewriteEngine On
                RewriteCond   %{LA-U:REMOTE_USER} (.+)
                RewriteRule   /cb.* - [E=RU:%1,L,NS]
                RequestHeader set X-User-Global-ID %{RU}e

                # Remove domain suffix to get the simple logon name
                RequestHeader edit X-User-Global-ID "@INTLAND.LOCAL$" ""

    </Location>
</VirtualHost>

Make sure the AJP port enabled in tomcat's server.xml.

The apache2 server should be restarted after the modification.

$ service apache2 restart

Configure codeBeamer to use AD

1. Open codebeamer via tomcat URL (eg.: cb.intland.local:8080/cb) with an administrator account.
2. Open System admin view and click on the User Authentication
3. Fill AD/LDAP properties and check the Authenticate users against LDAP/Active Directory' checkbox
   
4. Save
5. Open the User Authentication view again
6. Test authentication against AD/LDAP. Result should be
   

Enabling SSO in codeBeamer System Administration

• By default this configuration option is disabled.
• To enable SSO go to System Administration and User Registration, and set the check-box:

Enabling Kerberos Authentication in Client

• Login to Workstation by using an account of domain INTLAND.LOCAL
• Turn on "Windows Integrated Authentification" in Internet Explorer.
• Make sure that webservers DNS domain (intland.local in our example) is listed in IE's local intranet site section
  • to access local internet site section click on IE's tools menu and select internet options menu item
  • select the security tab in the opened window
  • click on local intranet icon then the sites button

• 
  
  • add cb.intland.local or intland.local domain to intranet sites

• 
  
  • make sure about the Automatic login is enabled for intranet sites

Enabling Kerberos Authentication in Firefox

1. Open Firefox and enter about:config in the address bar. Dismiss any warnings that appear.
2. In the Filter field, enter negotiate.
3. Double-click the network.negotiate-auth.trusted-uris preference.
4. This preference lists the trusted sites for Kerberos authentication.
5. In the dialog box, enter the domain: intland.local
6. Click the OK button.
7. The domain that you just entered in the network.negotiate-auth.trusted-uris should now appear in Value column. The setting takes effect immediately; you do not have to restart Firefox.

Open codeBeamer with Kerberos SSO

• Login to Workstation by using an account of domain INTLAND.LOCAL
• Open the cb.intland.local/cb URL in a browser
• the codeBeamer should be opened with authenticated user bela

Auto registration via Kerberos using SSO HTTP headers works from version codeBeamer 7.6. First time the user should log with the standard login form to register user in codebeamer from LDAP/AD in previous releases.