F5 Logo MyF5
Search
  1. MyF5 Home
  2. Knowledge Centers
  3. BIG-IP APM
  4. BIG-IP Access Policy Manager: Authentication and Single Sign-On
  5. Kerberos Single Sign-On Method
Manual Chapter : Kerberos Single Sign-On Method

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 13.1.5, 13.1.4
Manual Chapter
Table of Contents | << Previous Chapter | Next Chapter >>
 

About Kerberos SSO

Access Policy Manager® provides seamless authentication to application servers (web servers) using Kerberos SSO. It is the only SSO method that can be used when authentication methods used by the access policy do not provide the user's password in clear text. Examples of such methods include client certificate authentication, NTLM authentication, or any other challenge/response authentication method where the password is not transmitted in clear text. To use Kerberos SSO, you must have Kerberos implemented in your environment, such as using Active Directory domain with IIS servers configured for Integrated Windows authentication.

How does Kerberos SSO work in Access Policy Manager?

You can leverage Kerberos SSO in the following ways:

  • Using a virtual server with an access policy associated with it.
  • Handling the SSO event through the use of Portal Access Resource. In this scenario, the Portal Access resource is assigned to the Access Policy and the virtual server attaches a rewrite profile.

Here is a typical scenario showing what occurs when Kerberos SSO is used if client certificate authentication is present:

  1. When a user connects to the virtual server, Access Policy Manager® validates the credentials and extracts the UPN from the certificate through the access policy.
  2. When the client accesses an application that requires a Kerberos ticket, the UPN and the configured Kerberos SSO object are used to retrieve the ticket from Active Directory. The ticket is then cached for the particular client and presented to the application for access.
Important: Under other circumstances, the access policy may not ask for credentials within the certificate, because, for example, a logon page may be present. In such a case, the user name supplied by the client is used at the UPN. Other factors, such as the use of other types of authentication methods, must be present in order to ensure that the credentials are valid in order to retrieve the Kerberos ticket.
Example access policy for Kerberos SSO

Example access policy for Kerberos SSO

Task summary for configuring Kerberos SSO

Access Policy Manager® lets you configure for Kerberos SSO.

To set up this configuration, follow the procedures in the task list.

Task List

Setting up a delegation account to support Kerberos SSO

Before you can configure Kerberos SSO in Access Policy Manager®, you must create a delegation account in Active Directory.
Note: For every server realm, you must create a delegation account in that realm.
  1. Open the Active Directory Users and Computers administrative tool and create a new user account.
    The user account should be dedicated for delegation, and the Password never expires setting enabled.
  2. Set the service principal name (SPN) on the Windows server for the user account.
    For the support tools that you can use, and for the commands, such as setspn and ktpass, refer to Microsoft documentation.
    Note: If you use the ktpass command, it sets the SPN on the Windows server and creates a keytab file. APM Kerberos SSO does not need or use a keytab file.
  3. Verify the result of setting the SPN.
    This example is purely for illustration. Refer to Microsoft documentation for up-to-date commands and correct usage.

    C:\Users\Administrator> setspn -L apm4

    Registered ServicePrincipalNames for CN=apm4,OU=users,DC=yosemite,DC=lab,DC=dnet,DC=com: HTTP/apm4.yosemite.lab.dnet.com where apm4 is the name of the user account that you created.
  4. Return to the Active Directory Users and Computers screen to open your account again.
    A Delegation tab should appear.
  5. Click the Delegation tab.
  6. Select Trust this user for delegation to specified services only.
  7. Select Use any authentication protocol, and add all your services to the list under Services to which this account can present delegated credentials.
    Every service should have Service Type HTTP (or http) and host name of the pool member or web application resource host that you will use in your configuration.
  8. Click OK.
    This creates the new delegation account.

Creating a Kerberos SSO configuration in APM

Before you start, you must have configured a delegation account in Active Directory.
To support Kerberos single sign-on authentication from Access Policy Manager® (APM®), you must create a Kerberos SSO configuration.
Note: To complete this task, you need to know the service principal name (SPN) for the delegation account.
  1. On the Main tab, click Access > Single Sign-On > Kerberos .
    The Kerberos screen opens.
  2. Click Create.
    The New SSO Configuration screen opens.
  3. In the Name field, type a name for the SSO configuration.
  4. From the Log Setting list, select one of the following options:
    • Select an existing APM log setting.
    • Click Create to create a new log setting.
  5. In the Credentials Source area, specify the credentials that you want cached for Single Sign-On.
  6. In the Kerberos Realm field, type the name of the realm in uppercase.
    For example, MY.HOST.LAB.MYNET.COM
  7. In the Account Name field, type the name of the Active Directory account configured for delegation.
    Type the account name in SPN format.
    In this example HTTP/apm4.my.host.lab.mynet.com, apm4 is the delegation account, apm4.my.host.lab.mynet.com is its fully qualified domain name.
  8. In the Account Password and Confirm Account Password fields, type the delegation account password.
  9. Click Finished.

Editing an access policy to support Kerberos SSO

After you create an access profile to support Kerberos SSO, you must edit the policy and add the appropriate agents.
Note: These steps walk you through creating an example access policy that takes information from the client certificate to populate the session variables that Kerberos SSO uses.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. From the list, select an access profile to which you want to add Kerberos SSO support.
    The properties screen for that access profile opens.
  3. On the menu bar, click Access Policy.
    Access policy settings display.
  4. In the General Properties area, click the Edit Access Policy for Profile profile_name link.
    The visual policy editor opens the access policy in a separate screen.
  5. Click the (+) icon anywhere in the access policy to add a new item.
    Note: Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.
    A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
  6. On a policy branch, click the (+) icon to add an item to the policy.
    A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
  7. From Authentication, select Client Cert Inspection, and click Add item.
    A properties screen opens.
  8. Click Save.
    The properties screen closes and the policy displays.
  9. Click the (+) icon anywhere in the access policy to add a new item.
    Note: Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.
    A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
  10. On a policy branch, click the (+) icon to add an item to the policy.
    A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
  11. From General Purpose, select Variable Assign and click Add item.
    A properties screen opens.
  12. Add an entry to the Variable Assign properties to extract the UPN from the client certificate Subject Alternative Name field:
    1. Click Add new entry.
      An empty entry appears in the Assignment table.
    2. Click the change link next to the empty entry.
      A dialog box opens, where you can enter a variable and an expression.
    3. On the left side, retain the selection of Custom Expression and, in the field, type a variable name, such as: session.logon.last.upn.
    4. On the right side, in the field type an expression to extract the UPN from the client certificate:
      For example, type the following expression.
      set e_fields [split  [mcget {session.ssl.cert.x509extension}] "\n"];
foreach qq $e_fields {
  if {[string first "othername:UPN" $qq] >= 0} {
    return [string range $qq [expr { [string first "<" $qq] + 1 } ] [expr { [string first ">" $qq] - 1 } ] ];
  }
}
return "";
    5. Click Finished.
      The popup screen closes.
  13. Add another entry to populate the session.logon.last.username variable by extracting it from the UPN:
    1. Click Add new entry.
      An empty entry appears in the Assignment table.
    2. Click the change link next to the empty entry.
      A dialog box opens, where you can enter a variable and an expression.
    3. On the left side, retain the selection of Custom Expression and, in the field, type this variable name: session.logon.last.username.
    4. On the right side, in the field type an expression to extract the user name from the UPN:
      For example, type the following expression.
      set upn [mcget {session.logon.last.upn}];
if {[string first "@" $upn] >= 0} {
  return [string range $upn 0 [expr { [string first "@" $upn] - 1 } ] ];
} else {
  return $upn;
}
    5. Click Finished.
      The popup screen closes.
  14. Add another entry to populate the session.logon.last.domain variable with the realm by extracting it from the UPN:
    1. Click Add new entry.
      An empty entry appears in the Assignment table.
    2. Click the change link next to the empty entry.
      A dialog box opens, where you can enter a variable and an expression.
    3. On the left side, retain the selection of Custom Expression and, in the field, type this variable name: session.logon.last.domain.
    4. On the right side, in the field type an expression to extract the realm from the UPN:
      For example, type the following expression.
      set upn [mcget {session.logon.last.upn}];
if {[string first "@" $upn] >= 0} {
  return [string range $upn [expr { [string first "@" $upn] + 1 } ] end ];
} else {
  return "";
}
    5. Click Finished.
      The popup screen closes.
  15. Click Save.
    The properties screen closes and the policy displays.
You have created an access policy to support Kerberos SSO.
The next step is to bind the SSO object to the access profile.

Binding a Kerberos SSO object to an access profile

Before beginning this task, configure an SSO object with Kerberos authentication or ensure that such an SSO object exists.
To bind a Kerberos SSO object to an access profile, add an SSO configuration (Kerberos SSO object ) to it.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. From the list, select an access profile to which you want to add Kerberos SSO support.
    The properties screen for that access profile opens.
  3. Click the SSO Auth/Domains tab.
  4. From the SSO Configuration list, select an SSO configuration with Kerberos authentication that you previously identified or configured.
  5. Click Update.

Verifying log settings for the access profile

Confirm that the correct log settings are selected for the access profile to ensure that events are logged as you intend.
Note: Log settings are configured in the Access > Overview > Event Log > Settings area of the product. They enable and disable logging for access system and URL request filtering events. Log settings also specify log publishers that send log messages to specified destinations.
  1. On the Main tab, click Access > Profiles / Policies .
    The Access Profiles (Per-Session Policies) screen opens.
  2. Click the name of the access profile that you want to edit.
    The properties screen opens.
  3. On the menu bar, click Logs.
    The access profile log settings display.
  4. Move log settings between the Available and Selected lists.
    You can assign up to three log settings that enable access system logging to an access profile. You can assign additional log settings to an access profile provided that they enable logging for URl request logging only.
    Note: Logging is disabled when the Selected list is empty.
  5. Click Update.
An access profile is in effect when it is assigned to a virtual server.

Attaching an access profile to a virtual server for Kerberos SSO

  1. On the Main tab, click Local Traffic > Virtual Servers .
    The Virtual Server List screen opens.
  2. Click the Create button.
    The New Virtual Server screen opens.
  3. In the Name field, type a unique name for the virtual server.
  4. In the Destination Address field, type the IP address in CIDR format.
    The supported format is address/prefix, where the prefix length is in bits. For example, an IPv4 address/prefix is 10.0.0.1 or 10.0.0.0/24, and an IPv6 address/prefix is ffe1::0020/64 or 2001:ed8:77b5:2:10:10:100:42/64. When you use an IPv4 address without specifying a prefix, the BIG-IP® system automatically uses a /32 prefix.
    Note: The IP address you type must be available and not in the loopback network.
  5. In the Service Port field, type a port number or select a service name from the Service Port list.
  6. In the Access Policy area, from the Access Profile list, select the access profile that you configured for Kerberos SSO.
  7. Click Finished.

Kerberos SSO configuration settings

These settings are available when you configure a Kerberos SSO method.

General Properties settings for Kerberos SSO configuration

Setting Value Additional Information
General Properties Basic or Advanced. Defaults to Basic. Additional settings are available when you select Advanced.
Name Name of the SSO configuration. The name must begin with a letter, or underscore, and contain only letters, numbers, underscores, dashes, and periods. Avoid using global reserved words in the name, such as all, delete, disable, enable, help, list, none, show, or None.
Headers Header name-value pairs to send with the SSO method. Displayed when you select Advanced in the General Properties list.

Credentials Source settings for Kerberos SSO configuration

Setting Value Additional Information
Username Source Specifies the user name to cache for single sign-on. Defaults to a session variable. Supported session variable: session.sso.token.last.username
User Realm Source Displays the session variable, if configured, that specifies the realm for the user. If the variable is set, it must contain the Kerberos realm for the user. If this field is left empty or the variable does not exist or has no value, the user is assumed to be in the same Kerberos realm as the server.

Supported session variable: session.logon.last.domain

SSO configuration settings for Kerberos SSO configuration

Setting Value Additional Information
Kerberos Realm Specifies the realm of application servers, such as pool members or portal access resource hosts. If servers are located in multiple realms, you must create a separate SSO configuration for each realm. Realm must be specified in uppercase letters or can be specified using the session.logon.last.domain session variable.
Note: The KeepAlive setting on your backend webserver must be enabled for Kerberos authentication to work properly.
KDC Specifies the IP Address or the host name of the Kerberos Key Distribution Center (KDC) (normally an Active Directory domain controller) for the server realm.
Note: KDC must be empty when the user realm is different from the server realm and in the case of multi-domain realms.
If KDC is empty, the KDC must be discoverable through DNS. For example, the BIG-IP® system must be able to fetch SRV records for the server realm's domain, where the domain name is the same as the realm name. If the domain name is different from the realm name, it must be specified in the /etc/krb5.conf file.

Kerberos SSO processing is fastest when KDC is specified by its IP address, slower when specified by host name, and, due to additional DNS queries, even slower when empty.
Account Name Specify the name of the Active Directory account configured for delegation. This account must be configured in the Kerberos realm (AD Domain) of the server.
Note: If servers are from multiple realms, each realm (AD Domain) must have its own delegation account.
Account Password Specifies the password for the delegation account specified in the Account Name field.  
Confirm Account Password Verifies the password specified in the Account Password field.  
SPN Pattern An optional field for modifying how the Service Principal Name (SPN) for the servers is constructed. Leave this field empty unless you need a non-standard SPN format. The default value for this field is HTTP/%s@REALM, where %s is replaced by the server host name discovered through reverse DNS lookup using the server IP address. When entering a string, replace REALM with an actual realm name (as specified in Kerberos Realm setting).
Ticket Lifetime Represents the maximum ticket lifetime in minutes. Defaults to 600. Minimum is 10. Should not be set higher than the value configured for the Active Directory delegation account (which defaults to 600).
Note: The actual lifetime can be less than the configured value by up to 1 hour because the user's ticket lifetime is the same as the Kerberos Ticket Granting Ticket (TGT) ticket lifetime.
The TGT for the delegation account specified in this configuration is obtained. A new TGT is fetched every time the latest TGT is older than one hour, but only when an SSO request is processed.
Send Authorization Specifies when to submit the Kerberos ticket to application servers: Always or On 401 Status Code. Defaults to Always. The Kerberos ticket is submitted in the HTTP Authorization header. The header value starts with the word Negotiate, followed by one space and a base64 encoded GSSIAPI token that contains the Kerberos ticket. If the request contains an Authorization header from the client browser, it is deleted. The options are defined here.
  • Always The Authorization header with a Kerberos ticket is inserted into every HTTP request whether or not it requires authentication; in other words, it is inserted preemptively. The Kerberos ticket GSSAPI representation uses KRB5 Kerberos 5 mechanism displays (OID 1.2.840.113554.1.2.2).

    Selecting Always results in the additional overhead of generating a Kerberos token for every request. Kerberos tickets are fetched for first request only for the user and then cached for up to the configured ticket lifetime, so that subsequent requests involve local processing only.

  • On 401 Status Code The BIG-IP system forwards the user's HTTP request to the web server first without inserting a new Authorization header; (any Authorization header from a browser is also deleted). If the server requests authentication by responding with a 401 status code, the BIG-IP system retries the request with the Authorization header. The Kerberos ticket GSSAPI representation uses the SPNEGO mechanism displays (OID 1.3.6.1.5.5.2).

    Selecting On 401 Status Code results in an additional BIG-IP system and server request round trip when authentication is required for the request.
Username Conversion Check box is cleared by default. When the check box is selected, the PREWIN2k/UPN user name input format is converted to the format you want to use for SSO. For example, convert domain\username or username@domain to username.

Kerberos SSO session variable list

The following session variables are used by Kerberos SSO.

Session Variable name Description
session.logon.last.domain Contains the user's Kerberos realm. If unset, the user's realm is the same as the server's realm. The variable name is specified as User Realm Source in the SSO configuration and can be changed.
session.logon.last.username Contains the user's login name. This can be extracted from the client certificate or supplied by the user on the login screen. The variable name is specified as UsernameSource in the SSO configuration and can be changed.
session.logon.last.username.sso.state This is set to 1 internally when Kerberos SSO fails. When this variable is set, all subsequent requests are passed to the application server without applying SSO for the remainder of the user session. The variable name is constructed by appending .sso.state to the name specified in Username Source.

Tips for successfully deploying Kerberos SSO

If you run into problems with Kerberos SSO, follow these tips to try to resolve issues.

Microsoft® IIS servers

Only Microsoft® IIS servers are supported for pool members or web application resources. First, make sure the server computers running IIS are members of your AD Domain. Then follow these steps to enable Kerberos in IIS Manager:

  1. From Active Directory administrative tool, right-click Web Sites and select Properties.
  2. Select the Directory Security tab and in the Authentication and Access Control area click Edit.
  3. Clear Enable Anonymous Access.
  4. Check Integrated Windows Authentication and click OK. You might need to restart IIS or reboot the server for this to take effect.

Reverse DNS resolution

Kerberos SSO relies on reverse DNS resolution for determining the SPN (Service Principal Name) for each server host, such as a load balanced pool member or a web application resource host. Access Policy Manager® should be configured to use DNS servers that have the appropriate forward and reverse DNS records for those servers. If DNS is lacking, those record host entries can be configured on the BIG-IP® system.

DNS and KDC

Kerberos SSO relies on DNS for KDC discovery when KDC is not specified in an SSO configuration. The DNS server should have SRV records pointing to the KDC servers for the realm's domain. When DNS is not properly configured, or if the realm's DNS domain name is different from the realm's name, you can specify the KDC by adding a realm section to /etc/krb5.conf file on the BIG-IP system. For DNS discovery to work, the dns_lookup_kdc option in the [libdefaults] section of that file must be set to true.

Credential Caching

Kerberos uses credential caching to store Kerberos tickets. Access Policy Manager uses the websso process to maintain credential caches in memory, so restarting the websso process will discard all Kerberos tickets used for SSO.

Credential caching and high availability

The Ticket cache is not synchronized between units in high availability. Each user's Kerberos tickets are stored in a separate cache, where the name is constructed from the username, the user Kerberos realm, and the server Kerberos realm. Each cache contains a copy of the delegation account TGT for the server realm, a S4U2Self ticket for the user for the server realm, and multiple S4U2Proxy tickets for the servers. Once all tickets are fetched and stored in the cache, they remain there until they expire according to their lifetime. Processing of subsequent SSO requests should not require any more queries to the KDC. Since all tickets obtained from the same TGT have that TGT's lifetime, all tickets in the cache expire simultaneously. Each user's cache exists independently from the user's session. If the user has multiple concurrent or sequential sessions, the sessions all share the same cache, as long as it remains valid. The cache continues to exist even without any active sessions.

Maximum number of cache entries

The maximum number of cache entries is set to 20000. If the number is exceeded, it destroys older entries using the LRU algorithm. Delegation account TGT for each server realm is fetched when the first user request for that realm is processed. The TGT is cached and copied into every user's cache when the user accesses servers in that realm. If the TGT remaining lifetime becomes more than one hour shorter than the configured lifetime, the TGT is re-fetched. This is done to ensure that the new user's tickets are fetched with the initial lifetime closer to the configured value, and to avoid all tickets expiring at the same time, causing a performance impact.

Table of Contents | << Previous Chapter | Next Chapter >>
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5 Networks, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information