3.3. Using the Kerberos STS

Up one level

The steps of the interaction are as follows:

1. The client wishing to access a service first contacts the Kerberos Authentication Server and authenticates using a login/password in order to obtain a Ticket Granting Ticket (TGT).
2. To access the kerberised STS Service, the client contacts the Ticket Granting Server and provides the TGT in order to get a Service Ticket (ST).
3. The client then uses the ST to get a temporary X.509 certificate from the kerberised STS Service (integrated into GRIA’s Client Management package)
4. The client uses the X.509 certificate to access the service.

Kerberos Environment Configuration

We will not cover Kerberos server installation in this document as this is specific to each implementation. We consider that a KDC is already running and that the STS service must be added to the Kerberos domain.

The STS service is added as a user. Below we describe how to add the STS service to two Kerberos implementations: MIT Kerberos and Active Directory KDC.

Setup with MIT Kerberos

You should add the user and STS service principal names to the Kerberos database before being able to use Kerberos. Kadmin.local is a command-line interface to the Kerberos V5 KADM5 administration system. With this interface, you may add the client and service principals into Kerberos database. This can be done using the following commands (for more details see http://linux.die.net/man/8/kadmin.local): Adding the user:

Kadmin.local: addprinc user@REALM

(provide password)

Adding the service:

Kadmin.local: addprinc sts/host.it-innovation.soton.ac.uk@REALM

(provide password)

Creating service keytab file:

Kadmin.local: ktadd –l service_keytab sts/host.it-innovation.soton.ac.uk@REALM

You can check the context of the keytab file with the klist tool: Klist –k –t service_keytab

Setup with Active directory configuration

AD Configuration

1) Create a user account on Microsoft Active Directory for the STS service via the “Active Directory Users and Computers” administration GUI. This is an additional account that is distinct from the account for the user who wishes to access the service. If there is not one already, an account must also be set up for the user.

Start->Programs->Administrative Tools->Active Directory Users and Computers

Add the user account information and then press “Next” to enter a password for the new account. In this example the STS account name is “stsaccount”. On the “password” dialog (not shown here), do not select "User must change password at next logon."

At the end of this step you will have a new account created in Active Directory.

2) Use the setspn command to map the Kerberos service principal name, sts/<host name>, to the created user account. “setspn” tool is part of Windows 2000 Resource Kit and may be downloaded at Microsoft Download Center.

C:\Program Files\Support Tools>setspn -a service/host accountName

In our example the accountName is “stsaccount” and the command to be used in our example becomes:

setspn -a sts/jupiter.test.office.local stsaccount

where “jupiter” is the host name where the STS service is running. You may use the NetBIOS name of the host e.g. JUPITER instead of “jupiter.test.office.local”, if the host is an Active Directory client i.e. logged onto the domain.

To check if the spn has been associated with the account you can use the command:

setspn –l accountName

3) Create the Kerberos keytab file to be used by the STS service. This can be done using the “ktpass” tool which is included with the Microsoft Windows 2000 Resource Kit.

ktpass -out path -princ sevice/host@REALM -mapUser accountName 
-mapOp set -pass somePassword -crypto DES-CBC-MD5 +DesOnly

For our example the following command generates a keytab file called sts.keytab:

ktpass -out c:\sts.keytab -princ sts/jupiter.test.office.local@TEST.OFFICE.LOCAL -mapUser stsaccount 
-mapOp set -pass yourPassword -crypto DES-CBC-MD5 +DesOnly

Service configuration:

Transfer the generated keytab file to the machine on which the STS service will be running. The service uses the keytab file as described in the sections below.

Client configuration

Configure the client to use the STS service and the appropriate KDC, realm and service principal, e.g.:

java.security.krb5.realm=TEST.OFFICE.LOCAL
java.security.krb5.kdc=kdc.test.office.local
service.principal=sts
service.principal.name=sts/jupiter.test.office.local@TEST.OFFICE.LOCAL

When the client tries to access the STS service, it will now call the AD KDC to acquire a TGT. Then the client asks for a STS service ticket. The KDC looks up the information about the STS service in the AD. Being registered at the Active directory, STS service is then known to the KDC that returns a service ticket signed by the STS service key.

The client presents this service ticket to the STS service for authentication. The STS service can get its own key information from the keytab (generated by ktpass) and thus is able to validate the received service ticket and authenticate the user before processing his request.

Kinit and Klist tools

You may use kinit to contact the KDC and get a TGT. Kinit reads configurations from krb5.ini file on Windows platforms or krb5.conf on Linux ones. This config file indicates the KDC server to be used for each realm. whether on Windows or Linux, the format is the same and is defined in the man page. An example of the contents of such a file is given below:

[libdefaults]
default_realm = TEST.OFFICE.LOCAL

[realms]
TEST.OFFICE.LOCAL = {
	kdc = kdc.test.office.local:88
}

By default, the obtained TGT will be stored at {user.home}/krb5cc_username. You may indicate this path in the client configurations by specifying it in the GRIA client’s “Ticket Cache” configuration option. The login module will then use this TGT instead of asking for a new one. You can also see the content of the ticket by using klist command.

N.B. the login module may use the TGT in the cache even if it is not for the appropriate KDC and realm. If the ticket cache option is indicated, the user should make sure that the ticket in the cache is the appropriate one.

STS service installation

Service deployment

Having deployed and configured the GRIA Client Management services WAR file in Tomcat, you should see the screen below. We now have to configure the Kerberos STS Service.

Configuration of the Kerberos STS is divided into basic configuration and CA configuration.

Basic Kerberos Configuration

Kerberos parameters that must be provided are as follows:

• Service principal name: the principal name of the service in the form of service/host@REALM (e.g. sts/jupiter.test.office.local@GRIA-REALM)
• Kerberos realm: the realm in which the service is registered (the same as the realm indicated in the principal name)
• Kerberos keytab file: this is the path of the keytab file to be used by the service

CA Configuration

The CA configuration parameters that must be provided are the following:

• The DN hierarchy: the service will issue certificates with DN formed of the user Kerberos principal name concatenated to the indicated DN hierarchy. If the user principal name is “john” and the DN hierarchy is “OU=realm, C=GB”, then the issued certificate will have a DN= “CN= john, OU=realm, C=GB”. If the DN hierarchy is not indicated then the service will issue a certificate with the DN indicated by the user in his certification request. The requested DN should include the Kerberos principal name as a CN, and the realm as OU.
• The CA certificate: this is the path of the certificate of the kerberised CA
• The CA private key: This is the path of private key file to be used for signing the certificates
• Password: this is the password to access the CA private key.

The service is then configured and ready to issue X.509 certificates based on the caller’s Kerberos credentials.

STS Client Installation

The Kerberized Certification Authority (KCA) client needs both a TGT and a ST to communicate with the STS service. The TGT may be obtained from a KDC or a file cache file. These configurations are indicated in the Kerberos configuration files. Note that if the indicated cache file doesn’t exist, KDC is then automatically called.

An STS client is embedded in GRIA client. Whenever an identity is required, the GRIA client shows a dialog asking for the way to get a X509 certificate. The Kerberos client is involved in two of the choices:

1. Use my windows login credentials
2. Advanced Kerberos credentials translation

Use my Windows login credentials

Considering the first case, “Use my windows login credentials”, and clicking the “Next” button, the client asks for the service principal name in order to get a service ticket. The service principal name may not be deduced of the service url. In fact the KX509 protocol proposes cert.x509@Realm to be the principal name of the STS. However, our client implementation doesn’t have any constraints on the usage of an alternative principal name.

The krb5.ini (windows) or krb5.conf (Linux) contain the realm-KDC mapping (see the explanation above). Then, according to the indicated service realm, Kerberos knows which KDC to contact for obtaining tickets.

Advanced Kerberos credentials translation

Considering the second case, “Advanced Kerberos credentials translation”, the client asks for the following information:

• Configuration alias: it is a reference for the current set of configurations. The GRIA client will create a folder of this name (i.e. conf/GRIA) and store the generated configuration files within it.
• STS url: The url of the STS.
• STS principal name: STS principal name
• Krb5.ini: KDC- realm mapping and configurations.
• Ticket cache file location: This is the path to the file containing a cached TGT. The client will use this ticket (if available) to contact the KDC for any service ticket (ST).

You can still load an existing configuration set by choosing the option “load existing” configurations. This should fill in the parameters automatically.

After supplying the different parameters, clicking “Next” will trigger the following process:

• Client contacts the KDC for a TGT or uses a cached TGT in the specified cache file
• Client contacts the KDC to get a ST
• Client contacts the STS to get an X.509 certificate

The obtained certificate DN and issuer are then shown.