The Single Sign-on API for C

The Single Sign-on API for C are provided in the SUNWamcom package which comes with OpenSSO Enterprise or any of its downloadable
policy agents. The package includes header files, libraries and samples.
The header files are:

<am_sso.h> which
must be included for any single sign-on routines.

<am_notify.h> which
must be included for parsing notification messages from the server
and calling single sign-on listeners.

Single Sign-on Properties

The properties required for SSO are not read from AMAgent.properties
but are picked up from either the OpenSSO server (if the mode is
centralized) or from the local configuration file (if the mode is
local). P

Certain properties must be read and passed to am_sso_init() in order to initialize the Session Service. Thus, am_sso_init() must be called before any other single sign-on interface.
The properties required for single sign-on are retrieved from OpenSSO Enterprise if
using centralized agent configuration, and from the configuration
file local to the agent if using local agent configuration.

Specifies how often, in minutes, the cache should be checked
for entries that have reached the cache entry life time. This property
must be set as:

com.sun.am.sso.checkCacheInterval=#

Note –

By default, this property is not part of the agent configuration
properties but can be added when needed.

com.sun.am.sso.max_threads

Specifies the maximum number of threads the single sign-on API
for C should invoke for handling notifications. The API maintains
a thread pool and invokes a thread for each notification. If the maximum
number of threads has been reached, the notification will wait until
a thread is available. This property must be set as:

com.sun.am.sso.maxThreads=#

If not specified the default maximum number of threads is 10.

Note –

By default, this property is not part of the agent configuration
properties but can be added when needed.

Initialization and Cleanup

When implementing single sign-on, am_sso_init() must
be called before any other am_sso_* functions
to initialize the internal data structures. At the end of all single
sign-on routines, am_cleanup() should be called
for cleanup. Following is a code sample using these functions.

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

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.

Note –

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().

Tip –

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.

Listening and Notification

A session may become invalid because it has been idle over a
time limit, it has reached the maximum session time, or it has been
terminated by an administrator. An application can be notified of
this by implementing a listener function. Additionally, notification
must be enabled for the application to receive change notifications
when am_sso_init() is initialized. Notification
is enabled by setting the com.sun.am.notification.enable property
in the agent configuration properties to true,
and by providing the com.sun.am.notification.url property
a URL which will receive HTTP notification messages from OpenSSO Enterprise. Notification
messages are in XML and should be passed as a string (const
char *) to am_notify() which will parse
the message and invoke the appropriate session or policy listener.
Following is a code sample that illustrates this.

Non-Web Applications

OpenSSO Enterprise provides the single sign-on API for C to be used primarily
with web-based applications. It can though be extended to non-web
applications with limitations. You can use the API with non-web applications
in either of the following ways:

The application has to obtain the OpenSSO Enterprise cookie value
and pass it to the single sign-on client methods to retrieve the SSOToken. The method used for this process is application-specific.

Command line applications, such as ssoadn,
can be used. Session tokens can be created to access Directory Server directly.
No session is created, making OpenSSO Enterprise access valid only within that
process or virtual machine.