Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Retrieve Kerberos Authentication Credentials Assertion

Last update March 17, 2016

The Retrieve Kerberos Authentication Credentials assertion enables the Gateway to support the following extensions to the Kerberos Protocol:

  • Protocol Transition (S4U2Self): This is used for clients that require access to Active Directory resources, but are unable to acquire a Kerberos token. The Protocol Transition delegation method allows the Gateway to request a Kerberos service ticket on behalf of the client. The client may be using any other authentication methods, such as: basic, or certificate-based authentication, or SAML tokens.
  • Constrained Delegation (S4U2Proxy): Using this method, the client sends a service ticket that will be presented along with the server's TGT (Ticket Granting  Ticket) to Active Directory. This is used to request a service ticket using constrained delegation to another service. Only services in a previously configured list can receive a service ticket. Constrained delegation ensures that only authorized authenticated servers are permitted to perform constrained delegation to the next server.

For a summary of the configuration required to support each delegation method, see "Using the Protocol Transition Delegation Method" and "Using the Constrained Proxy Delegation Method" below.

Prerequisites:

  • Kerberos and the Active Directory should be configured and operational
  • A valid keytab file has been generated on the Active Directory server
  • CA API Gateway must have a valid keytab uploaded, if keytab-based authentication is used

Using the Protocol Transition Delegation Method

The following is a summary of the workflow for using the "Protocol Transition" delegation method. Note: These instructions assume familiarity with Active Directory. If you require assistance, please contact your AD administrator.

Step 1: Configure the Gateway account on the Active Directory:

  1. Log in to the Active Directory and open the properties for the Gateway account.
  2. In the Properties dialog: access [Delegation] tab > choose Trust this user for delegation to specified services only > choose Use any authentication protocol below it.
  3. Click [Add] below the list > click [Users or Computers] in the Add Services dialog > click [Advanced] in the Select Users or Computers dialog.
  4. Click [Find Now] in the Select Users or Computers dialog and then select the server that requires Kerberos authentication.
  5. Click [OK] to dismiss the dialog boxes until you return to the Add Services dialog.
  6. Select the "http" service and then click [OK].
  7. Click [OK] to close the Gateway account Properties dialog.

Step 2: Create a new service and construct a policy that includes:

  • One or more credential source assertions (for example, Require HTTP Basic Credentials)
  • An identity assertion (for example, Authenticate Against Identity Provider)
  • Retrieve Kerberos Authentication Credentials assertion
  • Route via HTTP(S) assertion

Step 3: Configure the Retrieve Kerberos Authentication Credentials assertion as follows:

  • Realm: Realm of service
  • Target SPN: Service Principal Name of the destination service protected by Kerberos. The Kerberos ticket obtained by the Gateway from KDC is passed to that service.
  • Gateway Credentials: Can be either option. If Gateway credentials is "Use Gateway Keytab", then the credentials stored in the keytab file will be used, otherwise you must provide credentials in the assertions.
  • Delegation Method: Choose Protocol Transition
  • Authenticated User: Use either last authenticated user or provide an authenticated user name and user realm.
  • User Realm: The realm of the user. If the user's realm differs from the service realm, the Gateway automatically performs a Kerberos cross-realm referral authentication. For more information about this process, refer to: http://msdn.microsoft.com/en-us/library/cc246109.aspx.

Step 4: Configure the Route via HTTP(S) assertion:

  • In the [Target] tab, set the route URL.
  • In the [Security] tab, choose the Service Authentication method Use Windows Integrated and then choose Use Delegated Credentials.

Step 5: Call the service from a client that is not a part of the authenticating domain or does not have a trusted relationship with the domain.

Using the Constrained Proxy Delegation Method

The following is a summary of the workflow for using the "Constrained Proxy" delegation method. Note: These instructions assume familiarity with Active Directory. If you require assistance, please contact your AD administrator.

Step 1: Configure the Gateway account on the Active Directory:

  1. Log in to the Active Directory and open the properties for the Gateway account.
  2. In the Properties dialog: access [Delegation] tab > choose Trust this user for delegation to specified services only > choose Use Kerberos only below it.
  3. Click [Add] below the list > click [Users or Computers] in the Add Services dialog > click [Advanced] in the Select Users or Computers dialog.
  4. Click [Find Now] in the Select Users or Computers dialog and then select the server that requires Kerberos authentication.
  5. Click [OK] to dismiss the dialog boxes until you return to the Add Services dialog.
  6. Select the "http" service and then click [OK].
  7. Click [OK] to close the Gateway account Properties dialog.

Step 2: Create a new service and construct a policy that includes the following assertions:

  • Require Windows Integrated Authentication Credentials
  • Retrieve Kerberos Authentication Credentials
  • Route via HTTP(S)

Step 3: Configure the Retrieve Kerberos Authentication Credentials assertion as follows:

  • Realm: Realm of authenticated user (provided in the assertion; Gateway will not locate the realm from the KDC)
  • Target SPN: Service Principal Name of the destination service protected by Kerberos. The Kerberos ticket obtained by the Gateway from KDC is passed to that service.
  • Gateway Credentials: Can be either option. If Gateway credentials is "Use Gateway Keytab", then the credentials stored in the keytab file will be used, otherwise you must provide credentials in the assertions.
  • Delegation Method: Choose Constrained Proxy

Step 4: Configure the Route via HTTP(S) assertion:

  • In the [Target] tab, set the route URL.
  • In the [Security] tab, choose the Service Authentication method Use Windows Integrated and then choose Use Delegated Credentials.

Step 5: Call the service from the client that is logged to the authenticating domain or has trusted relationship with the domain.

Kerberos Service Ticket/Session Caching

The Gateway implements Kerberos referral/credentials ticket caching to minimize the number of requests sent to the KDC (Key Distribution Center) and improve transaction response time. The entire referral chain is stored in the cache, as well as the session key. These are reused later when generating a new service ticket. The following cluster properties can be used to configure the cache:

  • kerberos.cache.size: Sets the maximum size of the cache.
  • kerberos.cache.timeToLive: Limits the maximum time the Kerberos tickets are store. If any ticket in the chain expire before the maximum period is reached, the entire chain is discarded and the Gateway will request new referral tickets and session keys from the KDC again.

For more information about these and other Kerberos-related cluster properties, see Kerberos Cluster Properties.

Note the following limitations to the Kerberos caching:

  • Cached data is not persisted to the data source.
  • Cached data is not synchronized to all cluster node.

Using the Assertion

  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Adding an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the Kerberos Authentication Credentials Properties dialog automatically appears; when modifying the assertion, right-click Retrieve Kerberos Authentication Credentials in the policy window and select Kerberos Authentication Credentials Properties or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Configure the properties as follows: Kerberos Authentication Credentials settings

    Setting Description

    KDC Settings

    Enter the following information about the KDC. You may reference context variables in either field.

    • Realm: Enter the location of the KDC.
    • Target SPN: Enter the routing destination service principal name.

    The Target SPN will be used with the Realm to look up the service principal name from the keytab file, if a multiple principal keytab file is provided. For more information on multiple principal keytab files, see Using Windows Domain Login.

    Gateway Credentials

    Specify the credentials for the KDC that will be used to authenticate the Gateway in order to obtain a TGT (Ticket Granting Ticket) on the client's behalf. Choose from the following:

    • Use Gateway Keytab: Use the credentials from the keytab that was uploaded to the Gateway. For more information, see Managing Kerberos Configuration.
    • Use Configured Credentials: Specify the credentials to use in the following fields:
    • Name: Enter the username.
    • Password: From the drop-down list, select the Password to use to log in. If the password you require is not listed, click [Managed Stored Passwords] to add it to the list of store passwords. For more information, see Managing Stored Passwords.

      You cannot type the password directly here; it must be defined in the Gateway's secure password storage.

    Delegation Method

    Choose the delegation method to use:

    • Protocol Transition: Choose this option to use the user login credentials from the policy enforcement context to request a Kerberos service ticket from KDC (Key Distribution Center) for the Gateway on behalf of the authenticated user. This ticket will be passed to the destination service protected by Kerberos via the routing assertion. The Gateway account must be configured to enable delegation to specified services only using any authentication protocol.
    To use this method, the user must have been authenticated via one of the credential source assertions such as Require HTTP Basic Credentials.
    • Constrained Proxy (Kerberos Only): Choose this option if the client forwarded Kerberos service ticket to the Gateway to act on behalf of the client when the Gateway has limited access to the services protected by Kerberos. The Gateway will present this ticket to KDC in exchange to a new ticket for the destination service. The Gateway account must be configured to enable delegation to specified services only using Kerberos authentication protocol.
    Currently, only the Route via HTTP(S) assertion supports Kerberos constrained delegation.

    Authenticated User

    ("Protocol Transition" delegation method only)

    When the delegation method is "Protocol Transition", identify the user who will be acquiring the Kerberos ticket. You may reference context variables.

    This panel is disabled when delegation method is "Constrained Proxy".

    • Last Authenticated User: Use the most recently authenticated user.
    • Specify User Name: Specify any user specified in the User CN text field. You can enter any of the following:
    • a user CN name
    • a context variable that contains the user CN name
    • either of the predefined context variables: ${request.authenticateduser} or ${request.authenticatedusers[<index>]}
    • User Realm: Enter the realm of the authenticated user. If left blank, this assertion will use the service realm as the user realm.

    When the user's realm differs from the service realm, the Gateway automatically performs a Kerberos cross-realm referral authentication, obtaining the necessary referral ticket(s) in the background. For more information, refer to: http://msdn.microsoft.com/en-us/library/cc246109.aspx.

  4. Click [OK] when done.
Was this helpful?

Please log in to post comments.