About SPNEGO/Kerberos

The Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) is a GSSAPI mechanism you use to secure messages when a client application wants to authenticate to a remote server, but does not know what authentication protocol to use.

SPNEGO helps organizations deploy security mechanisms. It determines the available GSSAPI mechanisms, selects one of them and uses it for all security operations.

Configuring ReadyAPI for using SPNEGO/Kerberos involves a number of steps. Typically, the basic steps are enough. In certain cases, you may need to perform some additional steps.

You can add the SPNEGO/Kerberos authentication by using built-in and external profiles.

Use built-in profiles if you do not need to apply the same authentication settings to other requests or test steps.

If you are going to reuse these settings, use external profiles. ReadyAPI stores these profiles in the Authorization manager, so you can later apply them to other requests or test steps. Also, you can use such profiles to specify different authorization settings in various environments.

Basic configuration steps

1. Add a key to the Windows Registry

By default, Windows does not provide access to the TGT session key. To work this around, add the following Registry key on the client machine:

Item	Value
Key	`HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos`
Value Name	`allowtgtsessionkey`
Value Type	`REG_DWORD`
Value	`1`

2. Add a Java Virtual Machine parameter

Add the following parameter to the vmoptions file:

-Djavax.security.auth.useSubjectCredsOnly=false

To learn how to do it, see Modifying JVM Settings.

3. Get a ticket-granting ticket

Run the kinit utility to get a ticket-granting ticket. You can find this utility in the <ReadyAPI>/jre/bin directory.
The utility will ask you for the user account password:

Click the image to enlarge it.
After you specify the password, the utility will create and cache a ticket-granting ticket.

The generated ticket has an expiration date. To check whether a ticket has expired or not, use the klist utility that is located in the <ReadyAPI>/jre/bin directory:

API testing with ReadyAPI: Using klist to configure SPNEGO/Kerberos connections

Click the image to enlarge it.

4. Set request authentication

Restart ReadyAPI.
Open the desired request for editing and switch to the Auth tab.
Select the SPNEGO/Kerberos authentication type from the Authorization drop-down list.

Tip: To reuse the same authentication settings, use external authentication profiles.
Specify the username, password and domain:

Click the image to enlarge it.

In most cases, the actions described above are enough. You should be able to use the SPNEGO/Kerberos authentication in your requests. If this authentication does not work, follow the steps described in the Additional authentication settings.

Additional authentication settings

Bellow are configuration steps you may need to perform during the SPNEGO/Kerberos Authentication configuration. The may help you, if your authentication does not work after the configuration described in Basic Configuration Steps.

1. Add realm and Key Distribution Center info

Create a configuration file, krb5.conf. It should contain realm info and the hostname of the KDC. The file contents should look like this:

[libdefaults]
default_realm = YOUR-DOMAIN-REALM (for example, MY.DOMAIN.LOCAL)
udp_preference_limit = 1
[realms]
YOUR-DOMAIN-REALM = {
kdc = YOUR-KEY-DISTRIBUTION-CENTER-SERVER (for example, kdc.my.domain.local)
default_domain = YOUR-DOMAIN-REALM
}
[domain_realms]
.ad.example.net=YOUR-DOMAIN-REALM
ad.example.net=YOUR-DOMAIN-REALM
Save the krb5.conf file in a directory that can be accessed by ReadyAPI, for example: C:/kerberos.

2. Create a keytab file

You need to create a .keytab file that will store user credentials. This file will be used if the user’s session key is not available in the TGT cache. To create it, your computer should be in the domain and you should be logged in using the credentials for the domain. Then:

Run the following command. You can find the ktab utility in the <ReadyAPI>/jre/bin directory:

ktab -a <username> -k C:\Temp\<your-user-name>.keytab

It will ask you to specify the user’s password:

Click the image to enlarge it.
Store the keytab file (<your-user-name>.keytab) to the appropriate directory (for example, C:\kerberos).

3. Create a JAAS Login Config file

Create a configuration file, login.conf, that will provide configuration details for the Kerberos login module. Below is the contents of a sample JAAS config file:

    com.sun.security.jgss.login {
        com.sun.security.auth.module.Krb5LoginModule
        required
        client=TRUE;
    };
    com.sun.security.jgss.initiate {
        com.sun.security.auth.module.Krb5LoginModule
        required
        debug=true
        useTicketCache=true
        useKeyTab=true
        keyTab="file:///C:/kerberos/user-name.keytab"
        principal=user.name
        doNotPrompt=true;
    };
    com.sun.security.jgss.accept {
        com.sun.security.auth.module.Krb5LoginModule required client=TRUE useTicketCache=true;
    };

Replace file:///C:/kerberos/user-name.keytab with the path to the keytab file you created on step 2.
Replace the user-name with your user name.
Save the login.config file to the appropriate directory, for example, C:\kerberos\login.conf.

4. Set up Java Virtual Machine parameters

Add the following parameters to the vmoptions file in the <ReadyAPI>\bin directory:

-Djava.security.auth.login.config=C:/kerberos/login.conf
-Djava.security.krb5.conf=C:/kerberos/krb5.conf

Make sure the -Djavax.security.auth.useSubjectCredsOnly=false key has already been added.
You may need to avoid using canonical host names. This will help you avoid issues caused by wrong reverse DNS lookups. To do this, add one more parameters to the vmoptions file:
- For SPNEGO:
  
  -Dhttpclient.spnego.usecanonicalname=false
- For Kerberos:
  
  -Dhttpclient.kerberos.usecanonicalname=false
Restart ReadyAPI and use your user name in the SPNEGO/Kerberos Authorization header.

SPNEGO/Kerberos Authentication