Administrator's Guide > Codebeamer Integrations with External Services > Configuring External Services: Email (SMTP), LDAP > Configuring Kerberos SSO authentication
Configuring Kerberos SSO authentication
* 
Kerberos SSO integration is no longer supported. You can use OpenID Connect (OAuth2) or SAML as alternative authentication methods.
This section is about configuring SSO authentication.
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
This section lists pre requirements for configuration.
Host Names
Each server in a Kerberos authentication realm must be assigned a Fully Qualified Domain Name (FQDN) that is forward-resolvable.
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
This section is about configuring 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
This section briefs about checking 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. Click 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 theSecurity 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.
Was this helpful?