Policy Server Guides › Policy Server Configuration Guide › SiteMinder Kerberos Authentication › Configure an smauthetsso Custom Authentication Scheme › Configure a Kerberos Authentication Scheme

Configure a Kerberos Authentication Scheme

A custom 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.

To configure a Kerberos authentication scheme

1. Log in to 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. Select the System tab.

   A list of system-related objects appears.

3. Right-click Authentication Schemes and click Create Authentication Scheme.

   The Authentication Scheme Properties dialog appears.

4. Select Custom Template from the Authentication Scheme Type list.

   Custom Template settings appear.

5. Enter smauthkerberos in the Library field.
6. Enter the following values in the Parameter field. Enter the values in the order listed below delimited by a semicolon:
   1. The name of the machine hosting web server and target fields
   2. The Policy Server principal name from the Kerberos domain
   3. The mapping between user principl and the user store search filter

   LDAP Example 1: http://win2k3iis6.test.com/siteminderagent/Kerberos/creds.kcc;smps/win2kps.test.com@TEST.COM;(uid=%{UID})

   LDAP Example 2: http://win2k3iis6.test.com/siteminderagent/Kerberos/creds.kcc;smps/win2kps.test.com@TEST.COM;(uid=%{UID})

   AD Example 1: http://win2k3iis6.test.com/siteminderagent/Kerberos/creds.kcc;smps/win2kps.test.com@TEST.COM;(cn=%{UID})

   AD Example 2: http://win2k3iis6.test.com/siteminderagent/Kerberos/creds.kcc;smps/win2kps.test.com@TEST.COM;(cn=%{UID})

   ODBC Example 1: http://win2k3iis6.test.com/siteminderagent/Kerberos/creds.kcc;smps/win2kps.test.com@TEST.COM;%{UID}

   ODBC Example 2: http://win2k3iis6.test.com/siteminderagent/Kerberos/creds.kcc;smps/win2kps.test.com@TEST.COM;%{UID}

7. Click OK.

   The Kerberos Authentication scheme is saved and appears in the Authentication Scheme List.

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 2003 Example

The steps listed following exemplify how to configure a Windows 2003 domain controller to support SiteMinder Kerberos authentication.

1. Promote a Windows 2003 SP 1 Server to a domain controller (named test.com in this example) using Windows dcpromo utility.
2. Raise the domain functional level:
   1. Open the Active Directory users and computers dialog from Administrative tools.
   2. Right-click the test.com drop-down on the left side of dialog.
   3. Click Raise domain functional level.
   4. Raise the domain functional level of Active directory to Windows Server 2003.

      Important! This step is irreversible.

3. Create a user account (for example, testkrb). Provide a password for this account. Clear the option, User must change password at next logon. Add this account to the domain administrators group so that the user has permissions to login. The Windows workstation uses this account to log in to test.com.
4. Create a service account for the web server (for example, wasrvwin2k3iis6). Create a password for this account. Clear the option, User must change password at next logon. Add this account to the domain administrators group so that the user has permissions to login.The Windows 2003 IIS web server host (win2k3iis6) uses this account to log in to test.com.
5. Create a service account for the Policy Server (polsrvwin2kps). Provide a password for this account. Clear the option, User must change password at next logon. Add this account to the domain administrators group so that the user has permissions to login.The Win2k3 Policy Server host (win2kps) uses this account to log in to test.com.
6. Join the web server (win2k3iis6) and the Policy Server (win2kps) hosts to the test.com domain using their service accounts created in Steps 4 and 5.
7. Associate the web server account (wasrvwin2k3iis6) with a web server principal name (HTTP/win2k3iis6.test.com@TEST.COM) and create a keytab file using the Ktpass utility.The syntax differs depending on whether the Policy Server is on Windows or on UNIX.

   Note: The Ktpass command tool utility is a Windows support tool. You can install it from MSDN download or an installation CD. Always verify the version of support tools. The default encryption type must always be RC4-HMAC. The encryption type can be confirmed by running ktpass /? at the command prompt.

   When the Policy Server is on Windows:

   ktpass -out c:\wasrvwin2k3iis6.keytab -princ HTTP/win2k3iis6.test.com@TEST.COM 
   -ptype KRB5_NT_PRINCIPAL -mapuser wasrvwin2k3iis6 -pass <<password>>
   
   Targeting domain controller: winkdc.Test.com
   Using legacy password setting method
   Successfully mapped HTTP/win2k3iis6.test.com to wasrvwin2k3iis6.
   Key created.
   Output keytab to c:\wasrvwin2k3iis6.keytab:
   Keytab version: 0x502
   keysize 67 HTTP/win2k3iis6.test.com@TEST.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 2 etype 0x17 (RC4-HMAC) keylength 16 (0xfd77a26f1f5d61d1fafd67a2d88784c7)
   

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

   When the Policy Server is on UNIX:

   ktpass -out d:\sol8sunone_host.keytab -princ host/sol8sunone.test.com@TEST.COM -pass <<password>> -mapuser sol8sunone -crypto DES-CBC-MD5 +DesOnly -ptype KRB5_NT_PRINCIPAL -kvno 3
   
   Targeting domain controller: winkdc.test.com
   Successfully mapped host/sol8sunone.test.com to sol8sunone.
   Key created.
   Output keytab to d:\sol8sunone_host.keytab:
   Keytab version: 0x502
   keysize 52 host/sol8sunone.test.com@TEST ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x3 (DES-CBC-MD5) keylength 8 (0xb5a87ab5070e7f4a)
   Account sol8sunone has been set for DES-only encryption.
   

8. Associate the Policy Server account (polsrvwin2kps) with a Policy Server principal name (smps/win2kps.test.com@TEST.COM) and create another keytab file destined for the Policy Server host (win2kps).

   When the Policy Server is on Windows

   Ktpass -out c:\polsrvwin2kps.keytab -princ smps/win2kps.test.com@TEST.COM -ptype KRB5_NT_PRINCIPAL -mapuser polsrvwin2kps -pass <<password>>
   Targeting domain controller: winkdc.Test.com
   Using legacy password setting method
   Successfully mapped smps/win2kps.test.com to polsrvwin2kps.
   Key created.
   Output keytab to c:\polsrvwin2kps.keytab:
   Keytab version: 0x502
   keysize 72 smps/win2kps.test.com@TEST.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.

   When the Policy Server is on UNIX:

   ktpass -out d:\sol8polsrv.keytab -princ host/sol8sunone.test.com@TEST.COM -pass <<password>> -mapuser sol8sunone -crypto DES-CBC-MD5 +DesOnly -ptype KRB5_NT_PRINCIPAL -kvno 3
   
   Targeting domain controller: winkdc.test.com
   Successfully mapped host/sol8sunone.test.com to sol8sunone.
   Key created.
   Output keytab to d:\sol8polserv.keytab:
   Keytab version: 0x502
   keysize 52 host/sol8sunone.test.com@TEST ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x3 (DES-CBC-MD5) keylength 8 (0xb5a87ab5070e7f4a)
   Account sol8sunone has been set for DES-only encryption.
   

9. Specify that the web server and Policy Server service accounts are Trusted for Delegation as follows:
   1. Right-click the service account (polsrvwin2kps/wasrvwin2k3iis6) properties.
   2. Select the Delegation tab.
   3. Select the second option, Trust this user for delegation to any service (Kerberos only)

      Or, select the third option, Trust this user for delegation to specified service. Select the Use Kerberos only option button, and add the corresponding service principal name.

The domain controller is ready for SiteMinder Kerberos authentication.

KDC Configuration on UNIX Example

The process listed following exemplifies how to configure a KDC Kerberos Realm on a UNIX host to support SiteMinder Kerberos authentication.

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 (host/win2k3iis6.example.com@EXAMPLE.COM, and a service principal (HTTP/win2k3iis6.example.com@EXAMPLE.COM) 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 (host/win2kps.example.com@EXAMPLE.COM) and service principal (smps/win2kps.example.com@EXAMPLE.COM) 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/win2k3iis6.keytab HTTP/win2k3iis6.example.com
   

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

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

The Kerberos Realm is configured for SiteMInder on a UNIX host.

Kerberos Configuration at the Policy Server on Windows Example

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

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

Follow these steps:

1. Install and configure the SiteMinder Policy Server.
2. Install and configure policy store directory services.
3. Log in to the Policy Server host with the service account (for example, polsrvwin2kps) created in Active Directory on the Windows domain controller.
4. Add a Host Configuration Object referencing the Policy Server.
5. Create an Agent Configuration Object and add these 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 SiteMinder Admin UI:
   1. Create the scheme using the custom template.
   2. Specify the SiteMinder Kerberos Authentication Scheme library.
   3. Select the parameter field and specify the following three semicolon-delimited values in the specified order:
      • Server name and target fields.
      • Policy Server principal name from the Windows 2003 Kerberos realm.
      • Mapping between the user principal and an LDAP search filter.

      Sample parameter field:

      http://win2k3iis6.test.com/siteminderagent/Kerberos/creds.kcc;smps/win2kps.test.com@TES.COM;(uid=%{UID})
      

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 Windows system root path:
   • Configure the KDC for the Windows 2003 Kerberos realm (domain) to use the Windows 2003 domain controller.
   • Configure krb5.ini to use the Windows 2003 KDC keytab file containing the Policy Server principal credentials.

     See the following sample krb5.ini:

     [libdefaults]
     default_realm = TEST.COM
     default_keytab_name = C:\WINDOWS\krb5.keytab
     default_tkt_enctypes = rc4-hmac des-cbc-md5
     default_tgs_enctypes = rc4-hmac des-cbc-md5
     [realms]
     TEST.COM = {
     kdc = winkdc.test.com:88
     default_domain = test.com        
     }
     [domain_realm]
     .test.com = TEST.COM
     

8. 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 SiteMinder Admin UI:
   1. Create the scheme using the custom template.
   2. Specify the SiteMinder Kerberos Authentication Scheme library.
   3. Select the parameter field and specify the following three semicolon-delimited values in the specified order:
      • Server name and target fields.
      • Policy Server principal name from the Windows 2003 Kerberos realm.
      • Mapping between the user principal and an LDAP search filter.

      Sample parameter field:

      http://sol8sunone.test.com/siteminderagent/Kerberos/creds.kcc;smps/sol8ps.test.com@TEST.COM;(uid=%{UID})
      

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 /etc/krb5 system path.
   • Configure the KDC for the Windows 2003 Kerberos realm (domain) to use the Windows 2003 domain controller.
   • Configure krb5.ini to use the Windows 2003 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 2003 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 SiteMinder Kerberos authentication:

• Be sure that the SiteMinder system clocks are 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 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 the Windows resource tool, kerbtray, to see the Kerberos tickets description. The GUI shows the various tickets received by KDC client, its flags, encryption types, and time stamp.
• 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 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 specified in krb5.conf file.
• The SPN is always case-sensitive. The krb5.keytab files for the Policy Server and the web server host must contain the host and service principals for the Policy Server and web server hosts.
• Always 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 or Windows 2003 SP1 CD.
• 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:

  The kvno number of any service principal can be confirmed using 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.

  For UNIX MIT KDC:

  Use the kvno utility. The syntax of this command is:

  Kvno principalname
  

• On Windows:

  You can verify if your keytab file is valid by installing windows support tools on both Policy Server and Web Agent running 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.

• On 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, and in Account tab your SPN can be visible, for example, host/fqdn. If it is visible, make sure no other object has the same entry set as SPN.