Most users belong to multiple organizations and thus need to authenticate to multiple Kerberos realms. Traditionally Kerberos sites solved this problem by setting up a cross-realm relationship, which allowed the user to use TGT credentials for their client identity in one realm to obtain credentials in another realm via cross-realm authentication. As a result users could acquire credentials for a single client identity and use them everywhere.
Setting up cross-realm requires that realms share a secret, so sites must coordinate with one another to set up a cross-realm relationship. In addition, sites must set up authorization policies for users from other realms. As Kerberos becomes increasingly wide-spread, many realms will not have cross-realm relationships, and users will need to manually obtain credentials for their client identity at each realm (eg: "user@BANK.COM", "user@UNIVERSITY.EDU", etc). As a result, users will often have multiple credentials caches, one for each client identity.
Unfortunately this presents a problem for applications which need to obtain service credentials. Which client identity should they use? Rather than having each application to manually search the cache collection, KIM provides a selection hints API for choosing the best client identity. This API is intended to simplify the process of choosing credentials and provide consistent behavior across all applications.
Searching the cache collection for credentials may be expensive if there are a large number of caches. If credentials for the client identity are expired or not present, KIM may also wish to prompt the user for new credentials for the appropriate client identity. As a result, applications might want to remember which client identity worked in the past and always request credentials using that identity.
A KIM selection hints object consists of an application identifier and one or more pieces of information about the service the client application will be contacting. The application identifier is used by user preferences to control how applications share cache entries. It is important to be consistent about what application identifier you provide. Java-style identifiers are recommended to avoid collisions.
When using selection hints to search for an appropriate client identity, KIM uses a consistent hint search order. This allows applications to specify potentially contradictory information without preventing KIM from locating a single ccache. In addition the selection hint search order may change, especially if more hints are added.
As a result, callers are encouraged to provide all relevant search hints, even if only a subset of those search hints are necessary to get reasonable behavior in the current implementation. Doing so will provide the most user-friendly selection experience.
Currently the search order looks like this:
- Service Identity The client identity which has obtained a service credential for this service identity.
- Hostname A client identity which has obtained a service credential for this server.
- Service Realm A client identity which has obtained a service credential for this realm.
- Service A client identity which has obtained a service credential for this service.
- Client Realm A client identity in this realm.
- User A client identity whose first component is this user string.
For example, if you specify a service identity and a credential for that identity already exists in the ccache collection, KIM may use that ccache, even if your user and client realm entries in the selection hints would lead it to choose a different ccache. If no credentials for the service identity exist then KIM will fall back on the user and realm hints.
- Note:
- Due to performance and information exposure concerns, currently all searching is done by examining the cache collection. In the future the KIM may also make network requests as part of its search algorithm. For example it might check to see if the TGT credentials in each ccache can obtain credentials for the service identity specified by the selection hints.
Once you have provided search criteria for selecting an identity, use
kim_selection_hints_get_identity() to obtain an identity object. You can then use
kim_identity_get_gss_name() to obtain a gss_name_t for use in gss_acquire_cred() or use
kim_ccache_create_from_client_identity() to obtain a ccache containing credentials for the identity.
- Note:
- kim_selection_hints_get_identity() obtains an identity based on the current state of the selection hints object. Subsequent changes to the selection hints object will not change the identity.
In addition to using selection hints to search for an appropriate client identity, KIM can also use them to remember which client identity worked. When the client identity returned by KIM successfully authenticates to the server and passes authorization checks, you may use
kim_selection_hints_cache_results() to add a mapping to the cache, replacing an existing mapping if there is one. Future calls to KIM using identical selection hints will result in the cached client identity and no searching will occur.
If a cache entry becomes invalid, you can forget the mapping using kim_selection_hints_forget_cached_results(). If you don't want to remove the mapping but also don't want to use it, you can turn off querying of the cache for a particular selection hints object using kim_selection_hints_set_use_cached_results().
- Note:
- Because cache entries key off of selection hints, it is important to always specify the same hints when contacting a particular service. Otherwise KIM will not always find the cache entries.
If valid credentials for identity in the selection hints cache are unavailable or if no identity could be found using searching or caching when
kim_selection_hints_get_identity() is called, KIM may present a GUI to ask the user to select an identity or acquire credentials for an identity.
- Note:
- So long as the caller caches the identity with kim_selection_hints_cache_results() the user will be prompted only when setting up the application or when credentials expire.
In order to let the user know why Kerberos needs their assistance, KIM displays the name of the application which requested the identity selection. Unfortunately, some platforms do not provide a runtime mechanism for determining the name of the calling process. If your application runs on one of these platforms (or is cross-platform) you should provide a localized version of its name with
kim_selection_hints_set_application_name(). You can check what name will be used with
kim_selection_hints_get_application_name().
In many cases a single application may select different identities for different purposes. For example an email application might use different identities to check mail for different accounts. If your application has this property you may need to provide the user with a localized string describing how the identity will be used. You can specify this string with kim_selection_hints_get_explanation(). You can find out what string will be used with kim_selection_hints_set_explanation().
Since the user may choose to acquire credentials when selection an identity, KIM also provides kim_selection_hints_set_options() to set what credential acquisition options are used. kim_selection_hints_get_options() returns the options which will be used.
If you need to disable user interaction, use kim_selection_hints_set_allow_user_interaction. Use kim_selection_hints_get_allow_user_interaction to find out whether or not user interaction is enabled. User interaction is enabled by default.
See KIM Selection Hints Reference Documentation for information on specific APIs.
