kim_selection_hints_overview.html [plain text]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Kerberos Identity Management: KIM Selection Hints Overview</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.3 -->
<h1><a class="anchor" name="kim_selection_hints_overview">KIM Selection Hints Overview</a></h1><h2><a class="anchor" name="kim_selection_hints_introduction">
Introduction</a></h2>
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.<p>
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.<p>
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.<p>
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.<h2><a class="anchor" name="kim_selection_hints_creating">
Creating KIM Selection Hints</a></h2>
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.<h2><a class="anchor" name="kim_selection_hints_searching">
Selection Hint Search Behavior</a></h2>
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.<p>
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.<p>
Currently the search order looks like this:<p>
<ul>
<li><b>Service Identity</b> The client identity which has obtained a service credential for this service identity. </li>
<li><b>Server</b> A client identity which has obtained a service credential for this server. </li>
<li><b>Service Realm</b> A client identity which has obtained a service credential for this realm. </li>
<li><b>Service</b> A client identity which has obtained a service credential for this service. </li>
<li><b>Client Realm</b> A client identity in this realm. </li>
<li><b>User</b> A client identity whose first component is this user string.</li>
</ul>
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.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>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.</dd></dl>
<h2><a class="anchor" name="kim_selection_hints_selecting">
Selecting an Identity Using Selection Hints</a></h2>
Once you have provided search criteria for selecting an identity, use <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> to obtain an identity object. You can then use <a class="el" href="group__kim__identity__reference.html#g094e916a4d31556c3ead03f85aafa603" title="Get the string representation of a identity.">kim_identity_get_string()</a> to obtain a krb5 principal string for use with gss_import_name() and gss_acquire_cred(). Alternatively, you can use <a class="el" href="group__kim__ccache__reference.html#g6ecc14b94ffb57ca8008d0a407bb9c7d" title="Find a ccache for a client identity in the cache collection.">kim_ccache_create_from_client_identity()</a> to obtain a ccache containing credentials for the identity.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> obtains an identity based on the current state of the selection hints object. If you change the selection hints object you must call <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> again.</dd></dl>
<h2><a class="anchor" name="kim_selection_hints_caching">
Selection Hint Caching Behavior</a></h2>
In addition to using selection hints to search for an appropriate client identity, KIM can also use them to remember which client identity worked. KIM maintains a per-user cache mapping selection hints to identities so that applications do not have to maintain their own caches or present user interface for selecting which cache to use.<p>
When <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> is called KIM looks up in the cache and returns the identity which the selection hints map to. If there is not a preexisting cache entry for the selection hints then <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> will search for an identity and prompt the user if it cannot find an appropriate one.<p>
If the client identity returned by KIM authenticates and passes authorization checks, you should tell KIM to cache the identity by calling <a class="el" href="group__kim__selection__hints__reference.html#ge33ab4dcf213c7fcb43eea3f35aeef09" title="Add an entry for the selection hints to the selection hints cache, replacing any...">kim_selection_hints_remember_identity()</a>. This will create a cache entry for the mapping between your selection hints and the identity so that subsequent calls to <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> do not need to prompt the user.<p>
If the client identity returned by KIM fails to authenticate or fails authorization checks, you must call <a class="el" href="group__kim__selection__hints__reference.html#g8bc79c133df171182813ca2a8773d19c" title="Remove an entry for the selection hints from the selection hints cache.">kim_selection_hints_forget_identity()</a> to remove any mapping that already exists. After this function is called, future calls to <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> will search for an identity again. You may also wish to call this function if the user changes your application preferences such that the identity might be invalidated.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>It is very important that you call <a class="el" href="group__kim__selection__hints__reference.html#g8bc79c133df171182813ca2a8773d19c" title="Remove an entry for the selection hints from the selection hints cache.">kim_selection_hints_forget_identity()</a> if your application fails to successfully establish a connection with the server. Otherwise the user can get "stuck" using the same non-working identity if they chose the wrong one accidentally or if their identity information changes. Because only your application understands the authorization checksof the protocol it uses, KIM cannot tell whether or not the identity worked.</dd></dl>
If you wish to search and prompt for an identity without using the cached mappings, you can turn off the cached mapping lookups using <a class="el" href="group__kim__selection__hints__reference.html#ga036cbd405130142b460191dc5bf2c37" title="Set whether or not KIM will use cached mappings for this selection hints object.">kim_selection_hints_set_remember_identity()</a>. This is not recommended for most applications since it will result in a lot of unnecessary searching and prompting for identities.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>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.</dd></dl>
<h2><a class="anchor" name="kim_selection_hints_prompt">
Selection Hint Prompting Behavior</a></h2>
If valid credentials for identity in the selection hints cache are unavailable or if no identity could be found using searching or caching when <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a> is called, KIM may present a GUI to ask the user to select an identity or acquire credentials for an identity.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>Because of the caching behavior described above the user will only be prompted to choose an identity when setting up the application or when their identity stops working.</dd></dl>
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 the private function <a class="el" href="group__kim__library__reference.html#gfdf50a60bc513497e47852e43a02c8a9" title="Set the name of your application for KIM to use for user interface.">kim_library_set_application_name()</a>.<p>
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 <a class="el" href="group__kim__selection__hints__reference.html#g8fce520fbadcdd10f8928fbea43083ee" title="Get the strings used to prompt the user to select the identity.">kim_selection_hints_get_explanation()</a>. You can find out what string will be used with <a class="el" href="group__kim__selection__hints__reference.html#gcc6ec35aa53cad7a2eca07ceea66a3c6" title="Set the strings used to prompt the user to select the identity.">kim_selection_hints_set_explanation()</a>.<p>
Since the user may choose to acquire credentials when selection an identity, KIM also provides <a class="el" href="group__kim__selection__hints__reference.html#g2cbc1a52c6fa4c94aa85acf7abb205c4" title="Set the options which will be used if credentials need to be acquired.">kim_selection_hints_set_options()</a> to set what credential acquisition options are used. <a class="el" href="group__kim__selection__hints__reference.html#gb8c6aea4ac6b55d77585a5f3047dd3e7" title="Get the options which will be used if credentials need to be acquired.">kim_selection_hints_get_options()</a> returns the options which will be used.<p>
If you need to disable user interaction, use <a class="el" href="group__kim__selection__hints__reference.html#g290210bc1cb57b49539cc7f8c0d8fa2c" title="Set whether or not KIM may interact with the user to select an identity.">kim_selection_hints_set_allow_user_interaction()</a>. Use <a class="el" href="group__kim__selection__hints__reference.html#g95691183f6a85b8208858bd948a64c55" title="Get whether or not KIM may interact with the user to select an identity.">kim_selection_hints_get_allow_user_interaction()</a> to find out whether or not user interaction is enabled. User interaction is enabled by default.<p>
See <a class="el" href="group__kim__selection__hints__reference.html">KIM Selection Hints Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</html>