Single Sign-on Token Handles

When a user attempts to access a protected resource, the Session Service creates a new, empty session data structure (also known as an SSOToken) that will store information (such as login time, authentication scheme, authentication level, maximum time out limits and caching time limits) after the user is successfully authenticated. Additionally, the Session Service generates a session identifier (also known as an SSOTokenID) which is a randomly-generated string that identifies the user and corresponding session structure. Technically, the SSOTokenID identifies an instance of an SSOToken.

After a user has been successfully authenticated, the SSOToken is activated and the relevant session information is stored in the structure. Additionally, the state of the SSOTokenID is changed from invalid to valid. When using the single sign-on API for C, a single sign-on token handle contains this valid SSOTokenID and allows for operations based on the SSOToken.

• Creating Single Sign-on Token Handles

• Validating Single Sign-on Token Handles

• Destroying Session Token Handles

Creating Single Sign-on Token Handles

Once activated, an SSOToken can be obtained and inserted into a single sign-on token handle by passing the SSOTokenID to am_sso_create_sso_token_handle(). This function then checks to see if the identifier is in its local cache and, if not, retrieves the session information associated with the SSOTokenID from OpenSSO Enterprise and caches it. A single sign-on token handle is then assigned to it.

Validating Single Sign-on Token Handles

The caller can check if the session is valid using am_sso_is_valid_token(). If not valid, am_sso_validate_token() will flush the old session information from the local cache (if any) and fetch the latest session information from OpenSSO Enterprise.

am_sso_refresh_token() duplicates the functionality of am_sso_validate_token(). In addition, it will reset the idle time of the session on the server.

Destroying Session Token Handles

When the caller is finished with a token handle, it must be freed to prevent memory leak by calling am_sso_destroy_sso_token_handle(). The session associated with the token handle can be invalidated or ended with am_sso_invalidate_token().

Although this ends the session for the user, the proper way to log out is by using am_auth_logout() as described in am_auth_logout(). Not using am_auth_logout() will result in authentication resources associated with the session remaining on the server unnecessarily until the session has timed out.