Previous Topic: Windows Authentication SchemesNext Topic: Information Card Authentication Schemes

Policy Server Guides › Policy Server Configuration Guide › Authentication Schemes › 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 CA SiteMinder® environment requires a policy administrator to perform the tasks represented in the following diagram:

SM--VISIO--Kerberos authentication2

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

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:

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:

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:

  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.

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:

Parameter

Value

KCCExt

.kcc

HttpServicePrincipal

Specifies the web server principal name.

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

SmpsServicePrincipal

Specifies the Policy Server principal name.

Example: smps.example.com@EXAMPLE.COM

Complete these additional steps at the Policy Server:

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 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:

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 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):

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

Kerberos provides a platform-independent architecture for authentication and single sign-on. Using this authentication scheme presupposes that you have a working Kerberos setup.

Note: The following procedure assumes that you are creating an object. You can also copy the properties of an existing object to create an object. For more information, see Duplicate Policy Server Objects.

Follow these steps:

  1. Click Infrastructure, Authentication.
  2. Click Authentication Schemes.
  3. Click Create Authentication Scheme.

    Verify that the Create a new object of type Authentication Scheme is selected.

    Click OK

  4. Enter a name.
  5. Enter a protection level. The default is 5.
  6. (Optional) Select Password Policies enabled for this authentication scheme.
  7. Select Kerberos Authentication Template from the Authentication Scheme Type list.
  8. Enter Server Name, Target, Principal Name, and User DN information. See the Help for descriptions of these fields.
  9. Specify the mappings between Kerberos realms and Windows domains. You can map one Kerberos realm to many Windows Domains.

    Note: When you specify the DOMAIN variable in the User DN Lookup field, this mapping is required, even when the realm and domain names are the same.

  10. Click Submit.

    The Kerberos authentication scheme is saved. Assign the scheme to a realm.

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.

Troubleshooting SiteMinder Kerberos Authentication

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