Policy Server Guides › Policy Server Configuration Guide › SiteMinder Kerberos Authentication › How To Configure Kerberos Authentication

How To Configure Kerberos Authentication

Kerberos authentication supports various configuration scenarios, depending on the host environments of the client and server. Although each scenario is slightly different, implementing Kerberos authentication in a SiteMinder environment requires a policy administrator to perform the tasks represented in the following diagram:

Complete these procedures to configure Kerberos authentication:

1. Configure Kerberos at the Domain Controller.
2. Configure Kerberos at the Policy Server.
3. Configure Kerberos at the Web Server.
4. Configure Kerberos at the Windows Workstation.
5. Configure a Kerberos Authentication Scheme
6. Configure a Kerberos External Realm.

Configure Kerberos at the Domain Controller

In a pure Windows environment, a Kerberos realm is equivalent to a Windows Domain. The domain controller host provides storage for the user, service accounts, credentials, the Kerberos ticketing services, and Windows Domain services.

A keytab file is required for Kerberos authentication, which lets users authenticate with the KDC without being prompted for a password. The keytab file is created with the ktpass utility. The ktpass command tool utility is a Windows support tool. The ktadd utility is the equivalent on UNIX.

KDC configuration for the Policy Server on the domain controller host (Windows or UNIX) follows this general sequence:

1. Create a user account. This account is for logging in to the workstation.
2. Create a service account for the web server for logging in to the web server host.
3. Create a service account for the Policy Server for logging in to the Policy Server host.
4. Associate the web server account with a web server principal name.
5. Create a keytab file, which is transferred to the web server host.
6. Associate the Policy Server account with a Policy Server principal name.
7. Create another keytab file, which is transferred to the Policy Server host.
8. Specify that the web server and Policy Server accounts are Trusted for Delegation.

Important! For any service to use Kerberos protocol, be sure to create the Service Principal Name (SPN) in a standard format, that is, service/fqdn_host@REALM_NAME.

More information:

KDC Configuration on Windows Example

KDC Configuration on UNIX Example

Configure Kerberos Authentication at the Policy Server

The Kerberos authentication scheme requires that you modify the Agent Configuration Object (ACO):

1. Log in the Administrative UI.
2. Click Infrastructure, Agent Configuration, Modify Agent Configuration.
3. Click the edit button for the Agent Configuration object of your agent.
4. Add these three parameters to the Agent Configuration Object:

Complete these additional steps at the Policy Server:

• Deploy the keytab file on the KDC that contains the Policy Server principal credentials to a secure location on the Policy Server.
• Configure a Kerberos configuration file (krb5.ini) and place it in the system root path on Windows and in KRB5_CONFIG on UNIX.

Important! If the Policy Server is installed on Windows and the KDC is deployed on UNIX, perform the additional configuration on the Policy Server host using the Ksetup utility.

More information:

Kerberos Configuration at the Policy Server Example

Kerberos Configuration at the Policy Server on UNIX Example

Kerberos Authentication Configuration at the Web Server

Configuring a Windows or UNIX web server to support Kerberos authentication follows these general steps:

1. Install a Web Agent with the Kerberos authentication scheme support.
2. Register a trusted host with the Policy Server and configure the Web Agent.
3. Deploy the keytab file (created on the KDC) containing the web server credentials to a secure location on the web server.
4. Configure a Kerberos configuration file (krb5.ini):
   • Configure the KDC for the Kerberos realm (domain).
   • Configure krb5.ini to use the keytab file containing the credentials of the web server principal.
   • Place krb5.ini in the system root path on Windows and in KRB5_CONFIG on UNIX.

Important! If the web server is installed on Windows and the KDC is deployed on UNIX, perform additional configuration on the web server using the Ksetup utility.

Configure Kerberos Authentication at the Windows Workstation

To support Kerberos authentication, several Internet Explorer settings are required, and the workstation host is added to the KDC domain.

Important! If the KDC is deployed on UNIX, perform the additional required configuration on the workstation using the Ksetup utility.

Follow these steps:

1. Add the host for the Windows workstation to the KDC domain.
2. Log in to the host using user account created on the KDC.
3. Configure the browser to pass credentials automatically:

Configure a Kerberos Authentication Scheme

An authentication scheme is required to support Kerberos authentication in the SIteMinder environment. Associate this authentication scheme with any realm whose protected resources use Kerberos authentication.

Refer to these instructions for information about creating a Kerberos authentication scheme.

Configure Kerberos External Realm on Windows Host

For the Windows workstation to use a Kerberos KDC deployed on UNIX, you must configure both the Kerberos KDC server and the workstation.

In the Kerberos realm, create a host principal for the Windows host. Use the following command:

kadmin.local: addprinc host/machine-name.dns-domain_name.

For example, if the Windows workstation name is W2KW and the Kerberos realm name is EXAMPLE.COM, the principal name is host/w2kw.example.com.

Because a Kerberos realm is not a Windows domain, the KDC operating environment must be configured as a member of a workgroup, which happens automatically when you follow this process:

1. Remove the host from the Windows domain.
2. Add the test user, for example, testkrb, to the local user database.
3. Add the Kerberos Realm:

   ksetup /SetRealm EXAMPLE.COM
   

4. Restart the host.
5. Add the KDC :

   ksetup /addkdc EXAMPLE.COM rhasmit
   

6. Set a new password:

   ksetup /setmachpassword password
   

   Note: The password used here is same as the one used while creating the host principal account in the MIT KDC.

7. Restart the host.

   Note: Whenever changes are made to the external KDC and realm configuration, a restart is required.

8. Set the Realm Flag

   ksetup /SetRealmFlags EXAMPLE.COM delegate
   

9. Run AddKpasswd:

   ksetup /AddKpasswd EXAMPLE.COM rhasmit
   

10. Use Ksetup to configure single sign on to local workstation accounts by defining the account mappings between the Windows host accounts to Kerberos principals. For example:

    ksetup /mapuser testkrb@EXAMPLE.COM testkrb
    ksetup /mapuser * *
    

    The second command maps clients to local accounts of the same name. Use Ksetup with no arguments to see the current settings.

Kerberos Configuration Examples

The configurations that follow include examples of the specifics, such as keytab file creation, required to implement Kerberos authentication in a SiteMinder environment. Note that additional configuration is required when the KDC is deployed in a UNIX operating environment and the Policy Server, or web server, or workstation is in a Windows operating environment.

KDC Configuration on Windows Example

The following procedure shows how to configure a Windows domain controller/KDC to support Kerberos authentication. This example uses the following server and account names:

• Servers
  Domain Controller: kdc.example.com
  Policy Server: smps.example.com
  Web Server: www.example.com
  Active Directory Domain: EXAMPLE
  Kerberos Realm: EXAMPLE.COM
• Accounts
  User Account: testkrb
  Web Agent Service Account: krbsvc-smwa
  Policy Server Service Account: krbsvc-smps

Follow these steps:

1. Add the Active Directory Domain Services role to your Windows server.

   This action makes your Windows server a domain controller. A Windows domain controller operates as a Kerberos Key Distribution Center (KDC), implements the Kerberos V5 protocol, and performs Kerberos-related authentication functions.

2. Run the Windows dcpromo utility from the command line, or click the link on Service Manager, which launches the dcpromo utiity.
3. Verify the domain functional level:
   1. Open the Active Directory users and computers dialog from Administrative tools.
   2. Right-click the example.com drop-down on the left side of dialog.
   3. Click Raise domain functional level.
   4. Verify the domain functional level of Active Directory is at least Windows Server 2003. If not, raise the domain functional level.

      Important! Raising the domain functional level is irreversible.

4. Create a user account (for example, testkrb). Provide a password for this account. Clear the option, User must change password at next logon. The Windows workstation uses this account to log in to example.com.
5. Create a service account for the web server (for example, krbsvc-smwa). Create a password for this account. Clear the option, User must change password at next logon.
6. Create a service account for the Policy Server (krbsvc-smps). Provide a password for this account. Clear the option, User must change password at next logon.
7. Associate the web server service account (krbsvc-smwa) with a Kerberos service principal name (HTTP/www.example.com@EXAMPLE.COM) and create a keytab file using the Ktpass utility. Always verify the version of support tools. The default encryption type is RC4-HMAC. The encryption type can be confirmed by running ktpass /? at the command prompt.

   ktpass -out c:\krbsvc-smwa.keytab -princ HTTP/www.example.com@EXAMPLE.COM
   dc.example.com -ptype KRB5_NT_PRINCIPAL -mapuser EXAMPLE\krbsvc-smwa -pass "*"
   Targeting domain controller: dc.example.com
   Using legacy password setting method
   Successfully mapped HTTP/wwww.example.com to krbsvc-smwa..
   Key created.
   Output keytab to c:\krbsvc-smwa.keytab:
   Keytab version: 0x502
   keysize 82 dc.example.com ptype 1 (KRB5_NT_PRIN
   CIPAL) vno 3 etype 0x17 (RC4-HMAC) keylength 16 (0xf3d3d2a17c7ea172ff22044806443
   9a9)
   

   The password is the same as the one used for creating the service account for the web server.

8. Associate the Policy Server service account (krbsvc-smps) with a Kerberos service principal name (smps/smps.example.com@EXAMPLE.COM) and create another keytab file for the Policy Server host.

   Ktpass -out c:\krbsvc-smps.keytab -princ smps/smps.example.com@EXAMPLE.COM -ptype KRB5_NT_PRINCIPAL -mapuser EXAMPLE\krbsvc-smps -pass *
   Targeting domain controller: dc.example.com.com
   Using legacy password setting method
   Successfully mapped smps/smps.example.com to krbsvc-smps.
   Key created.
   Output keytab to c:\krbsvc-smps.keytab:
   Keytab version: 0x502
   keysize 72 smps/smps.example.com@EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 2 etype 0x17 (RC4-HMAC) keylength 16 (0xfd77a26f1f5d61d1fafd67a2d88784c7)
   

   The password is same as the one used for creating the service account for Policy Server.

9. Specify that the web server service account is Trusted for Delegation as follows:
   1. Right-click the service account (krbsvc-smwa) properties.
   2. Select the Delegation tab.
   3. Select the second option, Trust this user for delegation to any service (Kerberos only).

The domain controller is ready for Kerberos authentication.

KDC Configuration on UNIX Example

The following process shows how to configure a KDC Kerberos realm on a UNIX host to support Kerberos authentication. This example uses the following server and account names:

• Servers
  Domain Controller: dc.example.com
  Policy Server: smps.example.com
  Web Server: www.example.com
  Active Directory Domain: EXAMPLE
  Kerberos Realm: EXAMPLE.COM
• Accounts
  User Account: testkrb
  Web Agent Service Account: krbsvc-smwa
  Policy Server Service Account: krbsvc-smps

Follow these steps:

1. Install MIT Kerberos, if necessary.
2. Use the kdb5_util command to create the Kerberos database and an optional stash file. The stash file is used to authenticate the KDC to itself automatically before starting the kadmind and krb5kdc daemons as part of the host auto-boot sequence.

   Both the stash file and the keytab file are potential point-of-entry for a break-in. If you install a stash file, it must be readable only by root, must not be backed up, and must exist only on the KDC local disk. If you do not want a stash file, run the kdb5_util without the -s option.

   This example generates the following five database files in the directory specified in kdc.conf file:

   • Two Kerberos database files: principal.db and principal.ok
   • One Kerberos administrative database file: principal.kadm5
   • One administrative database lock file: principal.kadm5.lock
   • One stash file: .k5stash

     [root@rhasmit init.d]# kdb5_util create -r EXAMPLE.COM -s
     Initializing database '/var/kerberos/krb5kdc/principal' for realm 'EXAMPLE.COM',
     master key name 'K/M@EXAMPLE.COM'
     You will be prompted for the database Master Password.
     It is important that you NOT FORGET this password.
     Enter KDC database master key:
     Re-enter KDC database master key to verify:
     

3. Create a user principal (testkrb).
4. Create a user principal (for example, testwakrb), a host principal (HTTP/www.example.com@EXAMPLE.COM), and a service principal (krbsvc-smwa) for the web server host. The password used for creating host account must be same as the password specified when using the ksetup utility on the web server host.
5. Create a user principal (testpskrb), host principal (smps/smps.example.com) and service principal (krbsvc-smps) for the Policy Server host. The password used for creating host account must be same as the password specified when using the ksetup utility on the Policy Server host.
6. Create a keytab file for the web server service principal as follows:

   ktadd -k /tmp/krbsvc-smwa.keytab HTTP/www.example.com
   

7. Create keytab for Policy Server service principal as follows:

   ktadd -k /tmp/krbsvc-smps.keytab smps/smps.example.com
   

The Kerberos realm is configured on a UNIX host.

Kerberos Configuration at the Policy Server Example

The following procedure shows an example of how to configure a Policy Server on Windows to support the Kerberos authentication scheme. The configuration on Windows and UNIX are similar except for the following differences:

• The Kerberos configuration file on Windows is C:\windows\krb5.ini. On UNIX, the file can reside anywhere as long as the KRB5_CONFIG environment variable is set to the fully qualified path.
• The location of the keytab is system dependent. For example, C:\windows\krbsvc-smps.keytab on Windows, or /opt/CA/siteminder/krbsvc-smps.keytab on UNIX. The Kerberos configuration file default_keytab_name configuration option specifies the fully qualified path to the file.
• The UNIX keytab merges the service account keytab and the host keytab into a single keytab file.

Note: If the Policy Server is installed on Windows and the KDC is deployed on UNIX, perform other required configuration on the Policy Server host using the Ksetup utility.

Follow these steps:

1. Install and configure the Policy Server.
2. Install and configure policy store directory services.
3. Add a Host Configuration Object referencing the Policy Server.
4. Create an Agent Configuration Object and add these three new parameters:

   KCCExt

   Value: .kcc

   HttpServicePrincipal

   Specifies the web server principal name.

   Example: HTTP/www.example.com@EXAMPLE.COM

   SmpsServicePrincipal

   Specifies the Policy Server principal name.

   Example: smps@smps.example.com

5. Create a user directory.
6. Create a user, for example, testkrb, in the user directory.
7. Configure a new authentication scheme using the Administrative UI. See Configure a Kerberos Authentication Scheme.
8. Configure a policy domain.
9. Add a realm to protect a resource using the authentication scheme.
10. Add Rules and Policies to allow access for the user, testkrb.
11. Configure a Kerberos configuration file (krb5.ini) and place krb5.ini in the Windows system root path. Configure krb5.ini to use the Windows 2008 KDC keytab file containing the Policy Server principal credentials. See the following sample krb5.ini:

    [libdefaults]
    default_realm = EXAMPLE.COM
    default_keytab_name = C:\WINDOWS\krbsvc-smps.keytab
    default_tkt_enctypes = rc4-hmac
    default_tgs_enctypes = rc4-hmac
    [realms]
    EXAMPLE.COM = {
    kdc = dc.example.com:88
    default_domain = example.com        
    }
    [domain_realm]
    .example.com = EXAMPLE.COM
    

12. Deploy the Windows KDC keytab file containing the Policy Server principal credentials to a secure location on the Policy Server.

The Policy Server on a Windows host is configured for Kerberos authentication.

Kerberos Configuration at the Policy Server on UNIX Example

The following procedure shows an example of how to configure a Policy Server on a UNIX host to support SiteMinder Kerberos authentication.

Follow these steps:

1. Create a user, for example, sol8psuser, with the same password used for creating a service account for the Policy Server host (sol8ps) in Active Directory.
2. Add the host to the test.com domain and login to host with user sol8psuser.
3. Install and configure SiteMinder Policy Server.
4. Install and configure policy store directory services.
5. Add a Host Configuration Object referencing the Solaris Policy Server.
6. Add an Agent Configuration Object and add the following three new parameters:

1. Create a user directory.
2. Create a user, for example, testkrb, in the user directory.
3. Configure a new Authentication Scheme using the Administrative UI. See Configure a Kerberos Authentication Scheme.
4. Configure a policy domain.
5. Add a realm to protect a resource using the Authentication Scheme.
6. Add Rules and Policies to allow access for the user, testkrb.
7. Configure a Kerberos configuration file (krb5.ini) and place krb5.ini in the KRB5_CONFIG system path.
   • Configure the KDC for the Windows 2008 Kerberos realm (domain) to use the Windows 2008 domain controller.
   • Configure krb5.ini to use the Windows 2008 KDC keytab file containing the Policy Server principal credentials.

     See the following sample krb5.ini:

     [libdefaults]
      ticket_lifetime = 24000
      default_realm=TEST.COM
      default_tgs_enctypes = des-cbc-md5
      default_tkt_enctypes = des-cbc-md5
      default_keytab_name = FILE:/etc/krb5.keytab
      dns_lookup_realm = false
      dns_lookup_kdc = false
      forwardable = true
      proxiable = true
     [realms]
      TEST.COM = {
       kdc = winkdc.test.com:88
       admin_server = winkdc.test.com:749
       default_domain = test.com
      }
     [domain_realm]
      .test.com=TEST.COM
       test.com=TEST.COM
     

8. Use the ktutil utility to merge the keytab files (sol8ps_smps.keytab & sol8ps_host.keytab) containing the host principal and service principal names for the Policy Server host in the /etc/krb5.keytab file:

   ktutil: rkt sol8ps_host.keytab
   ktutil: wkt /etc/krb5.keytab
   ktutil: q
   ktutil: rkt sol8ps_smps.keytab
   ktutil: wkt /etc/krb5.keytab
   ktutil: q
   

9. Verify the created krb5.keytab as follows:

   klist -k
   Keytab name: FILE:/etc/krb5.keytab
   KVNO Principal
   ---- --------------------------------------------------------------------------
      3 host/sol8ps.test.com@TEST.COM
      3 smps/sol8ps.test.com@TEST.COM
   

10. Deploy the Windows KDC keytab file containing the host and Policy Server principal credentials to a secure location on the Policy Server.
11. Verify that the following environment variable is set before starting the Policy Server:

    KRB5_CONFIG=/etc/krb5/krb5.conf

The Policy Server on a UNIX host is configured for Kerberos authentication.

Verify that a Resource is Protected

You can verify that a resource in your Kerberos domain is protected by creating a SiteMinder policy using the Kerberos Authentication scheme and attempting to access the resource with a user principle.

To verify that a resource is protected by Kerberos authentication

1. Log into the Administrative UI.

   Note: When you create or modify a Policy Server object in the FSS Administrative UI, use ASCII characters. Object creation or modification with non-ASCII characters is not supported.

2. Configure a policy domain.
3. Configure a realm using the Kerberos Authentication scheme.
4. Configure a rule to protect a specific resource within your Kerberos domain.
5. Configure a policy to protect the Kerberos resource, and add a test user to the policy.
6. Log in to the Kerberos domain as a user principle and attempt to access the protected resource.

SiteMinder authenticates the user using the KDC security token.

Troubleshooting SiteMinder Kerberos Authentication

Be aware of the following issues when working with Kerberos authentication:

• The Policy Server system clocks must be synchronized (within 2 minutes) to the KDC system clock. Otherwise, Kerberos authentication fails because of clock skew errors.
• All the hosts must have suitable entries for the IP Address, fully qualified domain name (FQDN) and hostname in the /etc/hosts file. The order of these entries also matters in some cases. Also, include at least single space between these entries:

  IP Address  FQDN hostname 
  

• Use klist (UNIX KDC clients) to list tickets present in the credential cache. The flag –f provides information about tickets flags. These tickets are forwarded to complete the Kerberos authentication process.

  For example, see sample klist output listed following.

  bash-2.05$ klist
  Ticket cache: /tmp/krb5cc_1002
  Default principal: HTTP/sol8sunone.test.com@TEST.COM
  
  Valid starting            Expires                  Service principal
  Wed Dec 26 15:00:03 2007  Wed Dec 26 21:40:03 2007 krbtgt/TEST.COM@TEST.COM
  

• Always use the kinit program for the user and service principal at the MIT KDC host and UNIX KDC client.

  The kinit syntax for the user principal is:

  kinit principalname
  

  This command prompts for the password used while creating the user

  principal.

  The kinit syntax (it can vary from host to host) for service principal is:

  kinit -k [-t keytab location containing service principal] principalname
  

  The kinit command does not prompt for a password, because it uses a keytab file to authenticate the service principal.

• Install any network packet trace utility on the workstation to see the Kerberos tokens exchanged between the browser and web server. The token starting with TIR indicates NTLM tokens, and tokens starting with YII denote the Kerberos tokens.
• Log off the workstation host after any change in encryption type at the KDC. Also, restart the Policy Server and web server services after any changes are made to the Kerberos configuration or the keytab files.
• The KDC does not support post-dated tickets.
• Only DES-CBC-MD5 and DES-CBC-CRC encryption types are available for MIT interoperability.
• Always enable the Policy Server and the Web Agent logs to record the authentication error messages.
• Verify that the name and location of keytab file for any host matches the ones in the krb5.conf file.
• The SPN is always case-sensitive. The krb5.keytab files for the Policy Server and the web server hosts must contain the host and service principals.
• Verify the version of ktpass utility. The ktpass command tool utility is included in the Windows support tools and can be installed from MSDN download.
• Always confirm the encryption type used while creating the keytab file. Windows by default supports RC4-HMAC encryption.
• Confirm the Kerberos version number (kvno). The kvno of the service principal must match the kvno of its keytab file. The kvno number of any keytab is displayed when it is created.

  To determine the kvno of a service account for Windows Active Directory, use the ADSI Edit as follows:

  1. Run adsiedit.msc from command prompt.
  2. Go to service account, under CN=Users, DC=domain, DC=com under drop-down Domain (fqdn_ADhost) at the left.
  3. Right-click the service account and click properties.
  4. Verify the value of the msDs-KeyVersionNumber attribute, which matches the one shown while creating the keytab file for the service account.

  The kvno for any user account changes every time its password is changed. If the version numbers do not match, create an account and keytab, or change the password to match the kvno to the kvno of the keytab.

  To determine the kvno of a service account for a UNIX MIT KDC, use the kvno utility. The syntax of this command is:

  Kvno principalname
  

• Verify the keytab file validity

  Windows: Verify whether the keytab file is valid by installing Windows support tools on the Policy Server and Web Agent. Run the following command:

  Kinit -k -t <keytab file location> <respective spn>
  

  For example:

  kinit -k -t C:\Windows\webserver.keytab HTTP/websvriis6.test.com@KRISH.COM
  

  This command returns no error when the keytab file is valid.

  Solaris: Verify both keytab files validity by running the following commands:

  Kinit -k -t <keytab file> <SPN>
  

  For example:

  kinit -k -t host.keytab host/<fqdn>@DOMAIN.COM
  kinit -k -t smps.keytab smps/<fqdn>@DOMAIN.COM
  

  • If you get no errors, keytab files are fine, and the krb.conf file has valid values.
  • If you get an error, check whether the SPN is valid in KDC using the following command:

    Kinit host/<fqdn>@DOMAIN.COM
    

    This command usually asks for password. If you provide a valid password, you do not get an error message. If this command does not ask for password, the SPN was not identified. Check the property of that object. The SPN entry is on the Account tab, for example, host/fqdn. Make sure no other object has the same entry set as SPN.