Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers

Single Sign-on Functions

The single sign-on functions defined in <am_sso.h> are:

Before invoking any of the single sign-on functions, am_web_init() should be invoked by passing the bootstrap property and the local configuration file as parameters, and am_agent_initialized() should be invoked by passing the address of the boolean variable as a parameter — implying that am_web.h should be included in the file.

`am_sso_add_listener()`

Add a listener for any and all event changes related to the referenced single sign-on token handle.

Note –

am_sso_add_listener() will not be removed after it is called once like am_sso_add_sso_token_listener().

Details

The caller must do one of the following:

Provide a URL to this function.
Enable notification and provider a valid notification URL in the agent configuration properties that is passed to am_sso_init().

See Listening and Notification for more information.

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 listener as described in am_sso_token_listener_func_t.

Note –

When the listener is called, updated session information from OpenSSO Enterprise is passed in a temporary sso_token_handle.

args

Pointer to application-defined arguments to pass to the listener.

dispatch_to_sep_thread

Takes one of the values based on the boolean_t (defined in the <am_types.h> header file) that indicates whether the listener function should be called in the calling thread or dispatched to a thread from the internal thread pool managed by the C SDK.

Note –

Calling the listener in a thread from an internal thread pool 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 one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the listener was successfully added.
AM_INVALID_ARGUMENT: If sso_token_handle or listener is invalid, or the notification URL is not set and none is provided in the properties file.
AM_NOTIF_NOT_ENABLED: If notification is not enabled and the notification URL parameter is invalid.
AM_FAILURE: If any other error occurred.

`am_sso_add_sso_token_listener()`

Adds a listener for any and all event changes related to the referenced single sign-on token handle.

Note –

am_sso_add_sso_token_listener() is removed from memory after it is called once, differentiating its functionality from am_sso_add_listener().

Details

The caller must do one of the following:

Provide a URL to this function.
Enable notification and provider a valid notification URL in the agent configuration properties that is passed to am_sso_init().

See Listening and Notification for more information.

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

Pointer to the session information object containing the session token to which the listener corresponds. The handle will be filled with the session information from the notification message, overwriting any existing contents.

Note –

The session token is a randomly-generated string that represents an authenticated user.

listener

The listener as described in am_sso_token_listener_func_t.

Note –

When the listener is called, updated session information from OpenSSO Enterprise is passed in a temporary sso_token_handle.

args

Arguments to pass to the listener.

dispatch_to_sep_thread

Note –

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the listener was successfully added.
AM_INVALID_ARGUMENT: If sso_token_handle or listener is invalid, or the notification URL is not set and none is provided in the properties file.
AM_NOTIF_NOT_ENABLED: If notification is not enabled and the notification URL parameter is invalid.
AM_FAILURE: If any other error occurred.

`am_sso_create_sso_token_handle()`

Creates a single sign-on token handle as a container for a valid SSOTokenID.

Details

For more information, see Single Sign-on Token Handles.

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 a am_sso_token_handle_t type which will be assigned if the session validation is successful.
sso_token_id: Pointer to the SSOTokenID to which the handle will be associated.
reset_idle_timer: Takes one of the values based on the boolean_t (defined in the <am_types.h> header file) that specifies that the idle time of the SSOTokenID on the server will be refreshed when querying for session information.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If session validation was successful and a single sign-on token handle was successfully created.
AM_SERVICE_NOT_INITIALIZED: If the Session Service was not initialized.
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 specified single sign-on token handle.

Details

am_sso_destroy_sso_token_handle() does not log out the user or invalidate the session. For more information, see Single Sign-on Token Handles.

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: Pointer to a am_sso_token_handle_t type which will be destroyed.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the memory release process was successful.
AM_INVALID_ARGUMENT: If the sso_token_handle parameter is NULL.
AM_FAILURE: If any other error occurred.

`am_sso_get_auth_level()`

Retrieves the authentication level associated with the specified single sign-on token handle.

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 parameter:

sso_token: Pointer to a am_sso_token_handle_t type.

Returns

This function returns the authentication level of the specified handle, or ULONG_MAX if an error occurred.

`am_sso_get_auth_type()`

Retrieves the authentication type associated with the specified single sign-on token handle.

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: Pointer to a am_sso_token_handle_t type.

Returns

This function returns the authentication type of the specified handle, or NULL if an error occurred.

`am_sso_get_host()`

Retrieves the name of the host associated with the specified single sign-on token handle.

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: Pointer to a am_sso_token_handle_t type.

Returns

This function returns the host name as defined in the Host property, or NULL if the Host property is not set or does not have a value.

`am_sso_get_idle_time`

Retrieves the idle time associated with the specified single sign-on token 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: Pointer to a am_sso_token_handle_t type.

Returns

This function returns the idle time for this session in seconds, or the standard time_t data structure in the form (time_t) -1 if the token is invalid or some type of error occurs. Detailed error information is logged.

`am_sso_get_max_idle_time()`

Retrieves the maximum idle time associated with the specified single sign-on token handle.

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: Pointer to a am_sso_token_handle_t type.

Returns

This function returns the maximum idle time for this session in seconds, or the standard time_t data structure in the form (time_t) -1 if some type of error occurs.

`am_sso_get_max_session_time()`

Retrieves the maximum session time associated with the specified single sign-on token handle.

Syntax

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

Parameters

This function takes the following parameter:

sso_token: Pointer to a am_sso_token_handle_t type.

Returns

This function returns the maximum session time for this session in seconds, or the standard time_t data structure in the form (time_t) -1 if some type of error occurs.

`am_sso_get_principal()`

Retrieves the principal (user) associated with the specified single sign-on token handle.

Syntax

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

This function takes the following parameter:

sso_token: Pointer to a am_sso_token_handle_t type.

Returns

This function returns the principal (user) of the specified session, or NULL if the handle is invalid or any other error occurred.

`am_sso_get_principal_set()`

Retrieves a set of principals associated with the specified single sign-on token handle.

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 parameter:

sso_token: Pointer to a am_sso_token_handle_t type.

Returns

This function returns the am_string_set_t type (defined in the <am_string_set.h> header file) that points to the set of principals associated with the specified single sign-on token handle. It returns NULL if the applicable property is not set or has no value.

`am_sso_get_property()`

Retrieves the value of a property associated with the specified single sign-on token handle.

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: Pointer to a am_sso_token_handle_t type.
property_key: Pointer to the name of the desired property.
check_if_session_valid: Takes a value based on the boolean_t (defined in the <am_types.h> header file) that specifies if the function should check first if the session is valid. If the session is invalid, NULL will always be returned.

Returns

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

`am_sso_get_sso_token_id()`

Retrieves the SSOTokenID associated with the specified single sign-on token handle.

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: Pointer to a am_sso_token_handle_t type.

Returns

This function returns a pointer to the SSOTokenID, or NULL if sso_token_handle is invalid or any other error occurred.

`am_sso_get_time_left()`

Retrieves the time left in the session associated with the specified single sign-on token 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: Pointer to a am_sso_token_handle_t type.

Returns

This function returns the time left on this session in seconds, or the standard time_t data structure in the form (time_t) -1 if the token is invalid or some other type of error occurs. Detailed error information is logged.

`am_sso_init()`

Initializes the data structures, allowing communication with the Session Service.

Details

am_sso_init() takes as input a properties file that contains name/value pairs, and returns status on the success or failure of the initialization. This call must be made before calling any other am_sso_* functions. See Single Sign-on Properties for more information.

Syntax

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

Parameters

This function takes the following parameter:

property_map

Pointer to the am_properties_t structure used to initialize the Session Service.

Note –

See am_properties_t for more information.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the initialization was successful.
AM_*: If any error occurs, the type of error indicated by the status value.

`am_sso_invalidate_token()`

Invalidates or destroys the session on OpenSSO Enterprise associated with the single sign-on token handle.

Details

am_sso_invalidate_token() does not free the sso_token_handle parameter. You must call am_sso_destroy_sso_token_handle() to free the memory for the handle itself.

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 parameter:

sso_token_handle

Pointer to a am_sso_token_handle_t type.

Note –

If successful, the single sign-on token handle will have an invalid state after this call.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If session was successfully invalidated.
AM_INVALID_ARGUMENT: If the sso_token_handle parameter is NULL.
AM_SERVICE_NOT_INITIALIZED: If the Session Service was not initialized with am_sso_init().
AM_SERVICE_NOT_AVAILABLE: If server returned service not available.
AM_HTTP_ERROR: If an HTTP error was encountered while communicating with OpenSSO Enterprise.
AM_ERROR_PARSING_XML: If an error occurred while parsing XML from OpenSSO Enterprise.
AM_ACCESS_DENIED: If access was denied while communicating with OpenSSO Enterprise.
AM_FAILURE: If any other error occurred.

`am_sso_is_valid_token()`

Checks if the SSOToken associated with the specified single sign-on token handle is valid.

Details

am_sso_is_valid_token() looks in the passed sso_token_handle to check for validity. It does not go to OpenSSO Enterprise.

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 parameter:

sso_token_handle: Pointer to a am_sso_token_handle_t type.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the single sign-on token is valid.
B_FALSE: If the single sign-on token is invalid or any other error occurred.

`am_sso_refresh_token()`

Refreshes the session information in the SSOToken associated with the specified single sign-on token handle.

Details

am_sso_refresh_token() goes to OpenSSO Enterprise to retrieve the latest session information with which to update the SSOToken. This is similar in functionality to am_sso_validate_token() however, am_sso_refresh_token() also refreshes the last access time of the 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 parameter:

sso_token_handle: Pointer to a am_sso_token_handle_t type.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the token was refreshed with no errors.
AM_INVALID_ARGUMENT: If the sso_token_handle parameter is invalid.
AM_SERVICE_NOT_INITIALIZED: If the Session Service was not initialized with am_sso_init().
AM_SERVICE_NOT_AVAILABLE: If server returned service not available.
AM_HTTP_ERROR: If an HTTP error was encountered while communicating with OpenSSO Enterprise.
AM_ERROR_PARSING_XML: If an error occurred while parsing XML from OpenSSO Enterprise.
AM_ACCESS_DENIED: If access was denied while communicating with OpenSSO Enterprise.
AM_SESSION_FAILURE: If the session validation failed.
AM_FAILURE: If any other error occurred.

`am_sso_remove_listener()`

Removes a single sign-on token listener.

Details

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

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 listener as described in am_sso_token_listener_func_t.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the listener was successfully removed.
AM_INVALID_ARGUMENT: If the listener is NULL.
AM_NOT_FOUND: If listener was not found.
AM_FAILURE: If any other error occurred.

`am_sso_remove_sso_token_listener()`

Removes a single sign-on token listener associated with the specified single sign-on token handle.

Details

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

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: Pointer to a am_sso_token_handle_t type.
listener: The listener as described in am_sso_token_listener_func_t.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the listener was successfully removed.
AM_INVALID_ARGUMENT: If the listener is NULL.
AM_NOT_FOUND: If listener was not found.
AM_FAILURE: If any other error occurred.

`am_sso_set_property()`

Sets a property and its value in the SSOToken associated with the specified single sign-on token handle.

Details

The single sign-on token handle for this SSOToken was obtained before this call and thus will not include the new property. You must call am_sso_validate_token() to update the handle.

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

Pointer to a am_sso_token_handle_t type.

name

Pointer to the name of the property.

Caution –

If the specified property is protected by OpenSSO Enterprise, am_sso_set_property() will return success, but the value given will not be set.

value

Pointer to the value for the specified property.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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.

`am_sso_validate_token()`

Updates the session information in the SSOToken associated with the specified single sign-on token handle.

Details

This call will go to OpenSSO Enterprise to retrieve the latest session information. The sso_token_handle 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.

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 parameter:

sso_token_handle: Pointer to a am_sso_token_handle_t type.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If single sign-on token is valid. The information is updated.
AM_INVALID_SESSION: If the session is invalid. The information is updated.
AM_INVALID_ARGUMENT: If the input parameter is invalid.
AM_SERVICE_NOT_INITIALIZED: If Session Service is not initialized.
AM_SERVICE_NOT_AVAILABLE: If OpenSSO Enterprise returned service not available.
AM_HTTP_ERROR: If HTTP error encountered while communicating with OpenSSO Enterprise.
AM_ERROR_PARSING_XML: If error parsing XML from OpenSSO Enterprise.
AM_ACCESS_DENIED: If access is denied while communicating with OpenSSO Enterprise.
AM_FAILURE: If any other error occurred.