Configure Kerberos clients


The API Gateway can act as a Kerberos client. In doing so, it must authenticate to the Kerberos KDC (Key Distribution Center) as a specific principal and use the TGT (Ticket Granting Ticket) granted to it to obtain tickets from the TGS (Ticket Granting Service) so that it can authenticate to Kerberos services.

Kerberos clients can be configured globally under the External Connections node in the tree view of the Policy Studio. To configure a Kerberos client, right-click the Kerberos Clients node in the tree, and select the Add a Kerberos Client option from the context menu. Enter a name for the Kerberos client in the Name field of the Kerberos Client dialog, and complete the following sections where necessary.

Having configured the Kerberos client, it will be available for selection when configuring other Kerberos-related filters. Make sure to select the Enabled check box at the bottom of the window, which is checked by default.

Kerberos endpoint settings

Configure the following settings on the Kerberos Endpoint tab.

Ticket Granting Ticket Source

Use this section to configure where to obtain the Kerberos client credentials required in order to request service tickets, i.e. Ticket Granting Tickets (TGT) and the session key used in communications with the TGS. The TGT can be retrieved from a cache created as part of a JAAS (Java Authentication and Authorization Service) login, from delegated credentials, or from the native GSS implementation on Linux and Solaris platforms.

[Note] Note

Depending on what option is selected here, the Kerberos Principal, Password, and Keytab File fields below may or may not be disabled because some of the TGT source options do not require these fields to be configured.

Load via JAAS Login:

By default, the API Gateway will perform a JAAS login to the Kerberos KDC, after which the credentials will be cached by the API Gateway and used to acquire service tickets as they are needed. The JAAS login acquires the credentials in one of the following ways:

  • Request from KDC:

    Request a new TGT from the Key Distribution Center. This is performed at server startup, refresh (for example, when a configuration update is deployed), and also when the TGT expires.

  • Extract from Default System Ticket Cache:

    If a TGT has already been obtained out of bounds of the API Gateway and has been stored in the default system ticket cache, this option can be used to retrieve the TGT from this cache. On a Windows 2000 machine, the TGT will be extracted from the cache using the Local Security Authority (LSA) API. On a Linux/Solaris box, it is assumed that the ticket cache resides in /tmp/krb5cc_uid, where the uid is a numeric user identifier. If the ticket cache can not be found in these locations (or if we are running on a different Windows platform), the API Gateway will look for the cache in {user.home}{file.separator}krb5cc_{}.

    [Note] Note

    A system ticket cache may only hold the credentials of a single Kerberos client. If you wish to load the credentials of more than one client from system ticket caches, they must be be explicitly named using the Extract from System Cache option. Ticket caches can be populated with client credentials using an external utility such as kinit.

  • Extract from System Ticket Cache:

    Get the TGT from an explicitly named system ticket cache instead of from the default ticket cache. Browse to the location of the alternative cache using the Browse button.

Load from Delegated Credentials:

The Kerberos Client can use a TGT that has been delegated for use by the server and has been already retrieved from a Kerberos Service Authentication filter. In this case, the TGT is extracted from message attributes (i.e. authentication.delegated.credentials and that have been set by a previous Kerberos Service Authentication filter. It is not necessary to configure the Kerberos Principal or Secret Key fields if this option is selected.

Load via Native GSS Library:

Select this option to have the Native GSS API acquire the client's credentials. The Native GSS API will expect the credentials to be already in a system ticket cache that it can access.

If Load via Kinit is not selected, the client credentials must exist in the default system ticket cache. In this case only one Kerberos client can be used within the API Gateway, as the API Gateway cannot support accessing credentials natively from the default system ticket cache and other system ticket caches. See above for more details on the location of the default system ticket cache.

If Load via Kinit is selected the API Gateway can support multiple Kerberos clients natively. In this case, the API Gateway will run kinit and create a ticket cache for each client in the /conf/plugins/kerberos/cache directory. The Native GSS API will know to acquire the client credentials from these caches.

[Important] Important

To use the GSS library and optionally the kinit tool in this manner, you must select to use the native GSS library on the API Gateway instance-level Kerberos Configuration settings. To configure these settings, right-click the instance in the tree view of the Policy Studio, and select the Kerberos > Add option from the context menu. Open the Native GSS Library tab of the Kerberos Configuration dialog and check the Use Native GSS Library checkbox.

Kerberos Principal

A Kerberos principal is used to assign a unique identity to the API Gateway for use in the Kerberos environment. Select a previously configured principal from the list. You can configure Kerberos principals globally under the External Connections node in the Policy Studio tree. For more information, see Configure Kerberos principals.

[Note] Note

The semantics of this field are slightly different depending on what you selected as the TGT source above. If you have opted to retrieve the TGT from the KDC, then you are effectively asking the KDC to issue a TGT for the principal selected here.

Alternatively, if you have opted to retrieve the TGT from a system ticket cache, then the principal selected here will be used to lookup the cache in order to retrieve the TGT for this principal. Similarly, to use the kinit utility, the principal name selected here will be passed as an argument to kinit.

Finally, to retrieve a TGT from delegated credentials, it is not necessary to specify any principal.

Secret Key

The secret key is used by the principal to talk to the KDC's Authentication Service in order to acquire a TGT. The secret key can either be generated from a password or it can be taken from the principal's keytab file. Once again, the options available here will depend on what has been selected as the source of the TGT.


A password can only be entered if you have chosen to request the TGT from the KDC. The password will be used when generating the secret key. A secret key is not required at all if the TGT has been already retrieved either from a system ticket cache or from delegated credentials.

[Important] Important

The password entered here is stored by default in clear-text form in the API Gateway's underlying configuration data. If necessary, this can be encrypted using a passphrase. For more information on encrypting all sensitive API Gateway configuration data, such as passwords, see the API Gateway Administrator Guide.


When the Request from KDC option is selected above, the secret key for the principal can also be extracted from a Keytab file, which maps principal names to encryption keys. Similarly, the kinit tool requires a Keytab file.

You can load the principal-to-key mappings into the table by selecting the Load Keytab button and then browsing to the location of an existing Keytab file. A new Keytab Entry can be added by clicking the Add Principal button. For more information on configuring the Keytab Entry dialog, see the Kerberos Keytab concepts.

A Keytab entry can be deleted by selecting the entry in the table and clicking on the Delete Entry button. You can also export the entire contents of the Keytab table by clicking the Export Keytab button.

[Important] Important

The contents of the Keytab table (whether derived from a Keytab file or manually entered using the Keytab Entry dialog) are stored in the clear in the API Gateway's underlying configuration data. The Keytab contents can be stored encrypted, if required, by setting a passphrase. For more details, see the API Gateway Administrator Guide.

When the server starts up it writes the stored Keytab contents out to the /conf/plugin/kerberos/keytabs/ folder of your API Gateway installation. Oracle recommends that you configure directory- or file-based access control for this directory and its contents.

Advanced settings

The following fields can be configured on the Advanced tab:


Select the mechanism used to establish a context between the API Gateway and the Kerberos service. The Kerberos service must use the same mechanism.

Mutual Authentication:

Request that mutual authentication be carried out during context setup, i.e. the service authenticates back to the client. For the SPNEGO mechanism this must be turned on.


Enables data integrity for GSS operations.


Enables data confidentiality for GSS operations.

Credential Delegation:

Request that the initiator's credentials be delegated to the acceptor during context setup. When this option is checked, the acceptor can then assume the initiator's identity and authenticate to other Kerberos services on behalf of the initiator.


Request that the client's identity is not disclosed to the service.

Replay Detection:

Enables replay detection for the per-message security services after context establishment.

Sequence Checking:

Turns on sequence checking for the per-message security services after context establishment.

Synchronize to Avoid Replays Errors at Service:

In cases where the Kerberos client is running "under stress" and is attempting to send many requests to a Kerberos Service within a very short (millisecond) timeframe, it is possible that sequential Kerberos Authenticator tokens generated by the client will contain identical values for the ctime (i.e. the current time on the client's host) and cusec (i.e. the microsecond portion of the client's timestamp) fields.

Since Kerberos service implementations often compare the ctime and cusec values on successive Authenticator tokens to determine replay attacks, it is possible that the service will reject Authenticator requests in which the ctime and cusec fields have the same value.

To avoid situations where the client may generate successive Authenticator requests (for a particular service) in which the ctime and cusec fields are identical, you can select this option to synchronize the creation of the Authenticator requests. The Authenticator request generation will be synchronized using the Pause Time field below.

Pause Time:

Specify the time interval (in milliseconds) to wait before generating client-side Authenticator tokens when synchronizing to avoid over-zealous replay detection at the Kerberos service. This field is only enabled if the Synchronize to Avoid Replays Errors at Service check box is checked above.

[Note] Note

The default value of 15 milliseconds matches the clock resolution time of operating systems such as Windows. Consult your operating system documentation for more information on the clock resolution for your target system.