Chapter 8 Single Sign-On Functions

This chapter provides a reference to the public functions you can use to implement Single Sign-on (SSO) in Sun Java^TM System Access Manager. Function summaries include a short description, syntax, parameters and returns.

The following functions are contained in the header file am_sso.h.

• am_sso_add_listener()

• am_sso_add_sso_token_listener()

• am_sso_create_sso_token_handle()

• am_sso_destroy_sso_token_handle()

• am_sso_get_auth_level()

• am_sso_get_auth_level()

• am_sso_get_auth_type()

• am_sso_get_host()

• am_sso_get_idle_time

• am_sso_get_max_idle_time()

• am_sso_get_max_session_time()

• am_sso_get_principal()

• am_sso_get_principal_set()

• am_sso_get_property()

• am_sso_get_sso_token_id()

• am_sso_get_time_left()

• am_sso_init()

• am_sso_invalidate_token()

• am_sso_is_valid_token()

• am_sso_refresh_token()

• am_sso_remove_listener()

• am_sso_remove_sso_token_listener()

• am_sso_set_property()

• am_sso_validate_token()

am_sso_add_listener()

Adds a listener for the any SSO token’s change events.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_add_listener(const am_sso_token_listener_func_t listener,
         void  *args,
         boolean_t dispatch_to_sep_thread);

Parameters

This function takes the following parameters:

listener

The token change event listener.

args

Arguments to pass to the listener.

dispatch_to_sep_thread

Call the listener in a separate thread from an internal thread pool. This allows am_notify to return immediately upon parsing the notification message rather than waiting for the listener functions to finish before returning.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the listener was successfully added.

AM_INVALID_ARGUMENT

If sso_token_handle or listener is invalid, or if notification_url is not set and no notification UR is provided in the properties file.

AM_NOTIF_NOT_ENABLED

If notification is not enabled and the notification_url input parameter is invalid.

AM_FAILURE

If any other error occurred.

Details

Caller must either provide a URL to this function or have notification enabled with a valid notification URL in the properties file used to initialize SSO in am_sso_init(). The URL must point to a HTTP host and port that listens for notification messages from the server.

Notification messages are in XML. XML Notification messages received from the server should be passed to as a string (const char *) to am_notify(), which will parse the message and invoke listeners accordingly.

See the C API samples for more information.

When the listener is called, the sso_token_handle that is passed to the listener is a temporary one containing the updated session information from the server. Note that it is not the original sso_token_handle passed to am_sso_add_sso_token_listener().

Once added the listener will be called for any and all session event change notification. It will not be removed after it is called once like am_sso_add_sso_token_listener .

am_sso_add_sso_token_listener()

Adds an SSO token listener for the SSO token’s change events.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_add_sso_token_listener(am_sso_token_handle_t sso_token_handle,
                                const am_sso_token_listener_func_t listener,
                                void  *args,
                                boolean_t dispatch_to_sep_thread);

Parameters

This function takes the following parameters:

sso_token_handle

The session handle containing the SSO token id to listen for. The handle will be filled with the session information from the notification message. Any existing contents will be overwritten.

listener

The token change event listener.

args

Arguments to pass to the listener.

dispatch_to_sep_thread

Calls the listener in a separate thread from an internal thread pool. This allows am_notify to return immediately upon parsing the notification message rather than waiting for the listener function(s) to finish before returning.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the listener was successfully added.

AM_INVALID_ARGUMENT

If sso_token_handle or listener is invalid, or if notification_url is not set and no notification URL is provided in the properties file.

AM_NOTIF_NOT_ENABLED

If notification is not enabled and the notification_url input parameter is invalid.

AM_FAILURE

If any other error occurred.

Details

Caller must either provide a URL to this function or have notification enabled with a valid notification URL in the properties file used to initialize SSO in am_sso_init(). The URL must point to a HTTP host and port that listens for notification messages from the server.

Notification messages are in XML. XML Notification messages received from the server should be passed to as a string (const char *) to am_notify(), which will parse the message and invoke listeners accordingly.

See the C API samples for more information.

When the listener is called, the sso_token_handle that is passed to the listener is a temporary one containing the updated session information from the server. Note that it is not the original sso_token_handle passed to am_sso_add_sso_token_listener().

Once a listener has been called it is removed from memory; a listener is called only once.

am_sso_create_sso_token_handle()

Creates a handle to session information.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_create_sso_token_handle(am_sso_token_handle_t *sso_token_handle_ptr,
                                   const char *sso_token_id,
                                  boolean_t reset_idle_timer);

Parameters

This function takes the following parameters:

sso_token_handle

Pointer to SSO token handle which will be assigned an handle if the session validation is successful.

sso_token_id

String representation session identifier.

reset_idle_timer

When querying for session information.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If session validation was successful and a handle was successfully created.

AM_SERVICE_NOT_INITIALIZED

If SSO token service was not initialized. SSO token service must be initialized by calling am_sso_init() any call to am_sso_* can be made.

AM_INVALID_ARGUMENT

If the session_token_handle_ptr parameter is NULL.

AM_NO_MEMORY

If there was a memory allocation problem.

AM_FAILURE

If any other error occurred.

am_sso_destroy_sso_token_handle()

Destroys the handle to session information.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_destroy_sso_token_handle(am_sso_token_handle_t sso_token_handle);

Parameters

This function takes the following parameter:

sso_token_handle

SSO token handle to be de-allocated.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the memory release process was successful.

AM_INVALID_ARGUMENT

If the session_token_handle parameter is NULL.

AM_FAILURE

If any other error occurred.

Details

This function does NOT log out the user or invalidate the session.

am_sso_get_auth_level()

Gets the authentication level for this session.

Syntax

#include "am_sso.h"
AM_EXPORT unsigned long
am_sso_get_auth_level(const am_sso_token_handle_t sso_token);

Parameters

This function takes the following parameters:

sso_token_handle

The SSO token handle.

Returns

This function returns the authentication level of this session handle; returns ULONG_MAX if there was any error.

am_sso_get_auth_type()

Gets the authentication type for this session.

Syntax

#include "am_sso.h"
AM_EXPORT const char *
am_sso_get_auth_type(const am_sso_token_handle_t sso_token);

Parameters

This function takes the following parameter:

sso_token_handle

The SSO token handle.

Returns

This function returns the authentication type of this session handle. NULL if there was any error.

am_sso_get_host()

Gets the host address for this session.

Syntax

#include "am_sso.h"
AM_EXPORT const char *
am_sso_get_host(const am_sso_token_handle_t sso_token);

Parameters

This function takes the following parameter:

sso_token_handle

The SSO token handle.

Returns

This function returns the host name of this session handle as given by the Host property. NULL if the Host property is not set or does not have a value.

am_sso_get_idle_time

Gets idle time associated with this session handle.

Syntax

#include "am_sso.h"
AM_EXPORT time_t
am_sso_get_idle_time(const am_sso_token_handle_t sso_token_handle);

Parameters

This function takes the following parameter:

sso_token_handle

The SSO token handle.

Returns

This function returns the idle time of the session handle in seconds.

(time_t) -1 if token is invalid or some error occurs. Detailed error is logged.

am_sso_get_max_idle_time()

Gets the maximum idle time for this session.

Syntax

#include "am_sso.h"
AM_EXPORT time_t
am_sso_get_max_idle_time(const am_sso_token_handle_t sso_token);

Parameters

This function takes the following parameters:

sso_token_handle

The SSO token handle.

Returns

This function returns the maximum idle time for this session handle in seconds.( time_t) -1 if there was any error.

am_sso_get_max_session_time()

Gets the maximum session time for this session.

Syntax

#include "am_sso.h"

Parameters

This function takes the following parameters:

sso_token_handle

The SSO token handle.

Returns

This function returns the maximum session time of this session handle in seconds. (time_t) -1 if there was any error.

am_sso_get_principal()

Gets the principal of this session.

Syntax

#include "am_sso.h"
AM_EXPORT const char *
am_sso_get_principal(const am_sso_token_handle_t sso_token);Parameters

This function takes the following parameter:

sso_token_handle

The SSO token handle.

Returns

This function returns the principal of this session handle, NULL if the sso_token handle is invalid or any other error occurred.

am_sso_get_principal_set()

Gets the set of principals of this session. A session can have more than one principal.

Syntax

#include "am_sso.h"
AM_EXPORT am_string_set_t *
am_sso_get_principal_set(const am_sso_token_handle_t sso_token);

Parameters

This function takes the following parameters:

sso_token_handle

The SSO token handle.

Returns

This function returns the set of principals of this session handle, NULL if the principal property is not set or has no value.

am_sso_get_property()

Gets the value of a session property.

Syntax

#include "am_sso.h"
AM_EXPORT const char *
am_sso_get_property(const am_sso_token_handle_t sso_token,
            const char *property_key, boolean_t check_if_session_valid);

Parameters

This function takes the following parameters:

sso_token_handle

The SSO token handle.

property_key

The name of property to get.

check_if_session_valid

Whether to check if session is valid first. If true and session is invalid, NULL will always be returned.

Returns

This function returns the value of the session property. NULL if property is not set or does not have a value.

am_sso_get_sso_token_id()

Gets the SSO token ID for this session.

Syntax

#include "am_sso.h"
AM_EXPORT const char *
am_sso_get_sso_token_id(const am_sso_token_handle_t sso_token_handle);

Parameters

This function takes the following parameters:

sso_token_handle

The SSO token handle.

Returns

This function returns the SSO token ID of this session. NULL if sso_token_handle is invalid or any other error occurred.

am_sso_get_time_left()

Gets the time left of this session handle.

Syntax

#include "am_sso.h"
AM_EXPORT time_t
am_sso_get_time_left(const am_sso_token_handle_t sso_token_handle);

Parameters

This function takes the following parameters:

sso_token_handle

The SSO token handle.

Returns

This function returns the time left of this session handle in seconds. ( time_t) -1 if token is invalid or some error occurs.

Details

Detailed error is logged.

am_sso_init()

Initializes the SSO module in the C API.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_init(am_properties_t property_map);

Parameters

This function takes the following parameters:

property_map

Properties object to initialize SSO with.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

Details

This call must be made before any calls to am_sso_* functions.

am_sso_invalidate_token()

Invalidates or destroys the session on the server.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_invalidate_token(const am_sso_token_handle_t sso_token_handle);

Parameters

This function takes the following parameters:

sso_token_handle

SSO token handle of session to be invalidated.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If session was successfully invalidated.

AM_INVALID_ARGUMENT

If the sso_token_handle is invalid.

AM_SERVICE_NOT_INITIALIZED

If the SSO token service was not initialized with am_sso_init().

AM_SERVICE_NOT_AVAILABLE

If server returned service not available.

AM_HTTP_ERROR

If HTTP error encountered while communicating with server.

AM_ERROR_PARSING_XML

If error parsing XML from server.

AM_ACCESS_DENIED

If access denied while communicating with server.

AM_FAILURE

If any other error occurred.

Details

If successful the session handler in input argument will have state invalid after this call.

Note: Does not free the sso_token_handle input parameter. Call am_sso_destroy_sso_token_handle() to free memory for the handle itself.

am_sso_is_valid_token()

Checks if a token is valid.

Syntax

#include "am_sso.h"
AM_EXPORT boolean_t
am_sso_is_valid_token(const am_sso_token_handle_t sso_token_handle);

Parameters

This function takes the following parameters:

sso_token_handle

SSO token to check if valid.

Returns

This function returns boolean_t with one of the following values:

B_TRUE

If SSO token is valid.

B_FALSE

If SSO token is invalid or any other error occurred.

Details

This call looks in the passed sso_token_handle to check for validity; it does not go to the server.

am_sso_refresh_token()

Refreshes an SSO token session.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_refresh_token(const am_sso_token_handle_t sso_token_handle);

Parameters

This function takes the following parameters:

sso_token_handle

SSO token to refresh.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If SSO token could be refreshed with no errors.

AM_INVALID_ARGUMENT

If the input parameter is invalid.

AM_SERVICE_NOT_INITIALIZED

If SSO token service is not initialized. SSO token service must be initialized by calling am_sso_init() before any call to am_sso*.

AM_SERVICE_NOT_AVAILABLE

If server returned service not available.

AM_HTTP_ERROR

If HTTP error encountered while communicating with server.

AM_ERROR_PARSING_XML

If error parsing XML from server.

AM_ACCESS_DENIED

If access denied while communicating with server.

AM_SESSION_FAILURE

If the session validation failed.

AM_FAILURE

If any other error occurred.

Details

This goes to the server to get latest session info and update it in the sso_token_handle input parameter like am_sso_validate_token(). However it also refreshes the last access time of the session.

am_sso_remove_listener()

Removes an SSO token listener for any SSO token’s change events.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_remove_listener(const am_sso_token_listener_func_t listener);

Parameters

This function takes the following parameter:

listener

The change event listener.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the listener was successfully removed.

AM_INVALID_ARGUMENT

If listener was NULL.

AM_NOT_FOUND

If listener was not found.

AM_FAILURE

If any other error occurred.

Details

If am_sso_add_listener() was called more than once with the same listener function, all instances of the listener function will be removed.

am_sso_remove_sso_token_listener()

Removes an SSO token listener for the SSO token’s change events.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_remove_sso_token_listener(
    const am_sso_token_handle_t sso_token_handle,
     const am_sso_token_listener_func_t listener);

Parameters

This function takes the following parameters:

sso_token_handle

The session handle containing the SSO token id for the listener.

listener

The token change event listener.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the listener was successfully removed.

AM_INVALID_ARGUMENT

If sso_token_id or listener is invalid or NULL.

AM_NOT_FOUND

If listener was not found for the SSO token id.

AM_FAILURE

If any other error occurred.

Details

If am_sso_token_add_listener() was called more than once with the same listener function, all instances of the listener function will be removed.

am_sso_set_property()

Sets a property in the session.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_set_property(am_sso_token_handle_t sso_token_handle,
                     const char *name,
                     const char *value);

Parameters

This function takes the following parameters:

sso_token_handle

The session handle.

name

The property name.

value

The property value.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the property was successfully set.

AM_INVALID_ARGUMENT

If the sso_token_handle is invalid.

AM_FAILURE

If any other error occurred.

Details

Session handle for this token ID obtained before this call will not be current (not have the newly set property) after this call. Call am_sso_validate_token() to update the handle with the new set of properties.

am_sso_validate_token()

Validates an SSO token.

Syntax

#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_validate_token(const am_sso_token_handle_t sso_token_handle);

Parameters

This function takes the following parameters:

sso_token_handle

SSO token to validate.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If SSO token is valid, session handle is updated.

AM_INVALID_SESSION

If the session is invalid, session handle is updated.

AM_INVALID_ARGUMENT

If the input parameter is invalid.

AM_SERVICE_NOT_INITIALIZED

If SSO token service is not initialized. SSO token service must be initialized by calling am_sso_init() before any call to am_sso.

AM_SERVICE_NOT_AVAILABLE

If server returned service not available.

AM_HTTP_ERROR

If HTTP error encountered while communicating with server.

AM_ERROR_PARSING_XML

If error parsing XML from server.

AM_ACCESS_DENIED

If access denied while communicating with server.

AM_FAILURE

If any other error occurred.

Details

This call will go to the server to get the latest session info and update the sso_token_handle input parameter. The sso_token_handle input parameter is updated if the return status is either AM_SUCCESS or AM_INVALID_SESSION. This is different from am_sso_refresh_token() in that it does not update the last access time on the server.