Manual Chapter :
Kerberos Single Sign-On Method
Applies To:
Show VersionsBIG-IP APM
- 14.0.1, 14.0.0
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:
- 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.
- 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.
Task summary for configuring Kerberos SSO
Access Policy Manager lets you configure for Kerberos SSO.
To set up this configuration, follow these procedures.
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.
- Open the Active Directory Users and Computers administrative tool and create a new user account.The user account should be dedicated for delegation, and thePassword never expiressetting enabled.
- Create a Service Principal Name (SPN) account for Kerberos in the Active Directory (AD).
- Ensure the keytab files are created for the correct SPN user account.
- Set the SPN on the Windows server for the user account.For the support tools that you can use, and for the commands, such assetspnandktpass, refer to the Microsoft documentation.If you use thektpasscommand, it sets the SPN on the Windows server and creates a keytab file. APM Kerberos SSO does not need or use a keytab file.
- Verify the result of setting the SPN.This example is purely for illustration. Refer to the Microsoft documentation for up-to-date commands and correct usage.C:\Users\Administrator>setspn-Lapm4Registered ServicePrincipalNames for CN=apm4,OU=users,DC=yosemite,DC=lab,DC=dnet,DC=com: HTTP/apm4.yosemite.lab.dnet.comwhereapm4is the name of the user account that you created.
- Return to the Active Directory Users and Computers screen to open your account again.A Delegation tab should appear.
- Click the Delegation tab.
- SelectTrust this user for delegation to specified services only.
- SelectUse any authentication protocol, and add all your services to the list underServices 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.
- ClickOK.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.
- On the Main tab, click.The Kerberos screen opens.
- ClickCreate.The New SSO Configuration screen opens.
- In theNamefield, type a name for the SSO configuration.The maximum length of a single sign-on configuration is 225 characters, including the partition name.
- From theLog Settinglist, select one of the following options:
- Select an existing APM log setting.
- ClickCreateto create a new log setting.
- In the Credentials Source area, specify the credentials that you want cached for Single Sign-On.
- In theKerberos Realmfield, type the name of the realm in uppercase.For example,MY.HOST.LAB.MYNET.COM
- In theAccount Namefield, type the name of the Active Directory account configured for delegation.Type the account name in SPN format.In this exampleHTTP/apm4.my.host.lab.mynet.com, apm4 is the delegation account, apm4.my.host.lab.mynet.com is its fully qualified domain name.
- In theAccount PasswordandConfirm Account Passwordfields, type the delegation account password.
- ClickFinished.
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.
- On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- From the list, select an access profile to which you want to add Kerberos SSO support.The properties screen for that access profile opens.
- On the menu bar, clickAccess Policy.Access policy settings display.
- In the General Properties area, click theEdit Access Policy for Profilelink.profile_nameThe visual policy editor opens the access policy in a separate screen.
- 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.
- 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.
- From Authentication, selectClient Cert Inspection, and clickAdd item.A properties screen opens.
- ClickSave.The properties screen closes and the policy displays.
- 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.
- 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.
- FromGeneral Purpose, selectVariable Assignand clickAdd item.A properties screen opens.
- Add an entry to the Variable Assign properties to extract the UPN from the client certificate Subject Alternative Name field:
- ClickAdd new entry.Anemptyentry appears in the Assignment table.
- Click thechangelink next to the empty entry.A dialog box opens, where you can enter a variable and an expression.
- On the left side, retain the selection ofCustom Expressionand, in the field, type a variable name, such as:session.logon.last.upn.
- 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 "";
- ClickFinished.The popup screen closes.
- Add another entry to populate thesession.logon.last.usernamevariable by extracting it from the UPN:
- ClickAdd new entry.Anemptyentry appears in the Assignment table.
- Click thechangelink next to the empty entry.A dialog box opens, where you can enter a variable and an expression.
- On the left side, retain the selection ofCustom Expressionand, in the field, type this variable name:session.logon.last.username.
- 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; }
- ClickFinished.The popup screen closes.
- Add another entry to populate thesession.logon.last.domainvariable with the realm by extracting it from the UPN:
- ClickAdd new entry.Anemptyentry appears in the Assignment table.
- Click thechangelink next to the empty entry.A dialog box opens, where you can enter a variable and an expression.
- On the left side, retain the selection ofCustom Expressionand, in the field, type this variable name:session.logon.last.domain.
- 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 ""; }
- ClickFinished.The popup screen closes.
- ClickSave.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.
- On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- From the list, select an access profile to which you want to add Kerberos SSO support.The properties screen for that access profile opens.
- Click theSSO Auth/Domainstab.
- From theSSO Configurationlist, select an SSO configuration with Kerberos authentication that you previously identified or configured.
- ClickUpdate.
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
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. - On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- Click the name of the access profile that you want to edit.The properties screen opens.
- On the menu bar, clickLogs.The access profile log settings display.
- Move log settings between theAvailableandSelectedlists.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 theSelectedlist is empty.
- ClickUpdate.
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
- On the Main tab, click.The Virtual Server List screen opens.
- ClickCreate.The New Virtual Server screen opens.
- In theNamefield, type a unique name for the virtual server.
- For theDestination Address/Masksetting, confirm that theHostbutton 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 is10.0.0.1or10.0.0.0/24, and an IPv6 address/prefix isffe1::0020/64or2001: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/32prefix.The IP address you type must be available and not in the loopback network.
- In theService Portfield:
- If you want to specify a single service port or all ports, confirm that thePortbutton is selected, and type or select a service port.
- If you want to specify multiple ports other than all ports, select thePort Listbutton, and confirm that the port list that you previously created appears in the box.
- In the Access Policy area, from theAccess Profilelist, select the access profile that you configured for Kerberos SSO.
- ClickFinished.
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. /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.
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. |
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.
|
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:
- From Active Directory administrative tool, right-clickWeb Sitesand selectProperties.
- Select the Directory Security tab and in the Authentication and Access Control area clickEdit.
- ClearEnable Anonymous Access.
- CheckIntegrated Windows Authenticationand clickOK. 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.