# Kerberos Clients

## Contents
Overview Ticket Granting Ticket Source Kerberos Principal Secret Key Advanced Tab

## Overview
The Enterprise 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 on 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 then 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 checkbox at the bottom of the screen, which is checked by default.
## 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. It is important to note that depending on what option is selected here, the Kerberos Principal, Password, and Keytab File fields below may or may not be disabled since some of the TGT source options do not require these fields to be configured. Load via JAAS Login: By default, the Enterprise Gateway will perform a JAAS login to the Kerberos KDC, after which the credentials will be cached by the Enterprise 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 Enterprise 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 Enterprise Gateway will look for the cache in `{user.home}{file.separator}krb5cc_{user.name}`. Note that 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 will have to be explicitly named using the Extract from System Cache option below. 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 `authentication.delegated.credentials.client.name`) 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 Enterprise Gateway, as the Enterprise 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 Enterprise Gateway can support multiple Kerberos clients natively. In this case, the Enterprise 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 Note: Note that in order to use the GSS library and optionally the `kinit` tool in this manner you must select to use the native GSS library on the Process-level Kerberos Configuration settings. To configure these settings, right-click on the Process 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 Enterprise Gateway for use in the Kerberos environment. Select a previously configured Principal from the dropdown. You can configure Kerberos Principals globally on the External Connections tab in the Policy Studio. For more information, see the Kerberos Principals topic. Note that 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, if you want to use the `kinit` utility, the Principal name selected here will be passed as an argument to `kinit`. Finally, if you wish 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. Password: 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. It is important to note that the password entered here is stored by default in clear-text form in the Enterprise Gateway's underlying configuration data. If necessary, this can be encrypted using a Passphrase. For more information on encrypting all sensitive Enterprise Gateway configuration data, such as passwords, see Setting the Encryption Passphrase. Keytab: 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. It is possible to 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. Take a look at the Kerberos Keytab Entry help page for more information on configuring the Keytab Entry dialog. A Ketab Entry can be deleted by selecting the entry in the table and clicking on the Delete Entry button. It is also possible to export the entire contents of the Keytab table by clicking on the Export Keytab button. It is important to note that 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 Enterprise Gateway's underlying configuration data. The Keytab contents can be stored encrypted, if required, by setting a passphrase. For more details, see Setting the Encryption Passphrase. When the server starts up it writes the stored Keytab contents out to the `/conf/plugin/kerberos/keytabs/` folder of your Enterprise Gateway installation. Oracle recommends that you configure directory- or file-based access control for this directory and its contents.
## Advanced Tab
The following fields can be configured on this tab: Mechanism: Select the mechanism used to establish a context between the Enterprise 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. Integrity: Enables data integrity for GSS operations. Confidentiality: 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. Anonymity: 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 checkbox is checked above. It is important to note here that 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.