F5 Logo MyF5
Search
  1. MyF5 Home
  2. BIG-IP Access Policy Manager: Single Sign-On Concepts and Configuration
  3. Kerberos Single Sign-On Method
Manual Chapter : Kerberos Single Sign-On Method

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 15.0.1, 15.0.0, 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0
Manual Chapter

Kerberos Single Sign-On Method

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.
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.
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.
    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.
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.
    The maximum length of a single sign-on configuration is 225 characters, including the partition name.
  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.
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.
    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.
    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.
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.
    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
    Create
    .
    The New Virtual Server screen opens.
  3. In the
    Name
     field, type a unique name for the virtual server.
  4. For the
    Destination Address/Mask
     setting, confirm that the
    Host
     button is selected, and 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.
    The IP address you type must be available and not in the loopback network.
  5. In the
    Service Port
     field:
    • If you want to specify a single service port or all ports, confirm that the
      Port
       button is selected, and type or select a service port.
    • If you want to specify multiple ports other than all ports, select the
      Port List
       button, and confirm that the port list that you previously created appears in the box.
  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. Maximum length including the partition name is 225 characters. 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.
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.
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.
UPN support
Enables or disables the UPN suffix support for Kerberos SSO when integrating into Microsoft Active Directory infrastructure. This check box is clear by default.
Select the checkbox to enable username in the form of the NETBIOS style domain. For example,
username@upnsuffix
.
When this option is not enabled, and the user logs in with <username>@<upn_suffix>, then Kerberos SSO fails.
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.
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).
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.
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information