The single sign-on functions defined in <am_sso.h> are:
Add a listener for any and all event changes related to the referenced single sign-on token handle.
am_sso_add_listener() will not be removed after it is called once like am_sso_add_sso_token_listener().
The caller must do one of the following:
Provide a URL to this function.
Enable notification and provider a valid notification URL in the AMAgent.properties file passed to am_sso_init().
See Listening and Notification for more information.
#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);
This function takes the following parameters:
The listener as described in am_sso_token_listener_func_t.
When the listener is called, updated session information from Access Manager is passed in a temporary sso_token_handle.
Pointer to application-defined arguments to pass to the listener.
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.
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.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the listener was successfully added.
If sso_token_handle or listener is invalid, or the notification URL is not set and none is provided in the properties file.
If notification is not enabled and the notification URL parameter is invalid.
If any other error occurred.
Adds a listener for any and all event changes related to the referenced single sign-on token handle.
am_sso_add_sso_token_listener() is removed from memory after it is called once, differentiating its functionality from am_sso_add_listener().
The caller must do one of the following:
Provide a URL to this function.
Enable notification and provider a valid notification URL in the AMAgent.properties file passed to am_sso_init().
See Listening and Notification for more information.
#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);
This function takes the following parameters:
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.
The session token is a randomly-generated string that represents an authenticated user.
The listener as described in am_sso_token_listener_func_t.
When the listener is called, updated session information from Access Manager is passed in a temporary sso_token_handle.
Arguments to pass to the listener.
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.
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.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the listener was successfully added.
If sso_token_handle or listener is invalid, or the notification URL is not set and none is provided in the properties file.
If notification is not enabled and the notification URL parameter is invalid.
If any other error occurred.
Creates a single sign-on token handle as a container for a valid SSOTokenID.
For more information, see Single Sign-on Token Handles.
#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);
This function takes the following parameters:
Pointer to a am_sso_token_handle_t type which will be assigned if the session validation is successful.
Pointer to the SSOTokenID to which the handle will be associated.
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.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If session validation was successful and a single sign-on token handle was successfully created.
If the Session Service was not initialized.
If the session_token_handle_ptr parameter is NULL.
If there was a memory allocation problem.
If any other error occurred.
Destroys the specified single sign-on token handle.
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.
#include "am_sso.h" AM_EXPORT am_status_t am_sso_destroy_sso_token_handle(am_sso_token_handle_t sso_token_handle);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type which will be destroyed.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the memory release process was successful.
If the sso_token_handle parameter is NULL.
If any other error occurred.
Retrieves the authentication level associated with the specified single sign-on token handle.
#include "am_sso.h" AM_EXPORT unsigned long am_sso_get_auth_level(const am_sso_token_handle_t sso_token);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
This function returns the authentication level of the specified handle, or ULONG_MAX if an error occurred.
Retrieves the authentication type associated with the specified single sign-on token handle.
#include "am_sso.h" AM_EXPORT const char * am_sso_get_auth_type(const am_sso_token_handle_t sso_token);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
This function returns the authentication type of the specified handle, or NULL if an error occurred.
Retrieves the name of the host associated with the specified single sign-on token handle.
#include "am_sso.h" AM_EXPORT const char * am_sso_get_host(const am_sso_token_handle_t sso_token);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
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.
Retrieves the idle time associated with the specified single sign-on token handle.
#include "am_sso.h" AM_EXPORT time_t am_sso_get_idle_time(const am_sso_token_handle_t sso_token_handle);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
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.
Retrieves the maximum idle time associated with the specified single sign-on token handle.
#include "am_sso.h" AM_EXPORT time_t am_sso_get_max_idle_time(const am_sso_token_handle_t sso_token);
This function takes the following parameters:
Pointer to a am_sso_token_handle_t type.
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.
Retrieves the maximum session time associated with the specified single sign-on token handle.
#include "am_sso.h" AM_EXPORT time_t am_sso_get_max_session_time(const am_sso_token_handle_t sso_token);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
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.
Retrieves the principal (user) associated with the specified single sign-on token handle.
#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:
Pointer to a am_sso_token_handle_t type.
This function returns the principal (user) of the specified session, or NULL if the handle is invalid or any other error occurred.
Retrieves a set of principals associated with the specified single sign-on token handle.
#include "am_sso.h" AM_EXPORT am_string_set_t * am_sso_get_principal_set(const am_sso_token_handle_t sso_token);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
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.
Retrieves the value of a property associated with the specified single sign-on token handle.
#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);
This function takes the following parameters:
Pointer to a am_sso_token_handle_t type.
Pointer to the name of the desired property.
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.
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.
Retrieves the SSOTokenID associated with the specified single sign-on token handle.
#include "am_sso.h" AM_EXPORT const char * am_sso_get_sso_token_id(const am_sso_token_handle_t sso_token_handle);
This function takes the following parameters:
Pointer to a am_sso_token_handle_t type.
This function returns a pointer to the SSOTokenID, or NULL if sso_token_handle is invalid or any other error occurred.
Retrieves the time left in the session associated with the specified single sign-on token handle.
#include "am_sso.h" AM_EXPORT time_t am_sso_get_time_left(const am_sso_token_handle_t sso_token_handle);
This function takes the following parameters:
Pointer to a am_sso_token_handle_t type.
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.
Initializes the data structures, allowing communication with the Session Service.
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.
#include "am_sso.h" AM_EXPORT am_status_t am_sso_init(am_properties_t property_map);
This function takes the following parameter:
Pointer to the am_properties_t structure used to initialize the Session Service.
See am_properties_t for more information.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the initialization was successful.
If any error occurs, the type of error indicated by the status value.
Invalidates or destroys the session on Access Manager associated with the single sign-on token handle.
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.
#include "am_sso.h" AM_EXPORT am_status_t am_sso_invalidate_token(const am_sso_token_handle_t sso_token_handle);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
If successful, the single sign-on token handle will have an invalid state after this call.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If session was successfully invalidated.
If the sso_token_handle parameter is NULL.
If the Session Service was not initialized with am_sso_init().
If server returned service not available.
If an HTTP error was encountered while communicating with Access Manager.
If an error occurred while parsing XML from Access Manager.
If access was denied while communicating with Access Manager.
If any other error occurred.
Checks if the SSOToken associated with the specified single sign-on token handle is valid.
am_sso_is_valid_token() looks in the passed sso_token_handle to check for validity. It does not go to Access Manager.
#include "am_sso.h" AM_EXPORT boolean_t am_sso_is_valid_token(const am_sso_token_handle_t sso_token_handle);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the single sign-on token is valid.
If the single sign-on token is invalid or any other error occurred.
Refreshes the session information in the SSOToken associated with the specified single sign-on token handle.
am_sso_refresh_token() goes to Access Manager 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.
#include "am_sso.h" AM_EXPORT am_status_t am_sso_refresh_token(const am_sso_token_handle_t sso_token_handle);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the token was refreshed with no errors.
If the sso_token_handle parameter is invalid.
If the Session Service was not initialized with am_sso_init().
If server returned service not available.
If an HTTP error was encountered while communicating with Access Manager.
If an error occurred while parsing XML from Access Manager.
If access was denied while communicating with Access Manager.
If the session validation failed.
If any other error occurred.
Removes a single sign-on token listener.
If am_sso_add_listener() was called more than once for the same listener function, all instances of the listener function will be removed.
#include "am_sso.h" AM_EXPORT am_status_t am_sso_remove_listener(const am_sso_token_listener_func_t listener);
This function takes the following parameter:
The listener as described in am_sso_token_listener_func_t.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the listener was successfully removed.
If the listener is NULL.
If listener was not found.
If any other error occurred.
Removes a single sign-on token listener associated with the specified single sign-on token handle.
If am_sso_add_listener() was called more than once for the same listener function, all instances of the listener function will be removed.
#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);
This function takes the following parameters:
Pointer to a am_sso_token_handle_t type.
The listener as described in am_sso_token_listener_func_t.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the listener was successfully removed.
If the listener is NULL.
If listener was not found.
If any other error occurred.
Sets a property and its value in the SSOToken associated with the specified single sign-on token handle.
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.
#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);
This function takes the following parameters:
Pointer to a am_sso_token_handle_t type.
Pointer to the name of the property.
If the specified property is protected by Access Manager, am_sso_set_property() will return success, but the value given will not be set.
Pointer to the value for the specified property.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the property was successfully set.
If the sso_token_handle is invalid.
If any other error occurred.
Updates the session information in the SSOToken associated with the specified single sign-on token handle.
This call will go to Access Manager 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.
#include "am_sso.h" AM_EXPORT am_status_t am_sso_validate_token(const am_sso_token_handle_t sso_token_handle);
This function takes the following parameter:
Pointer to a am_sso_token_handle_t type.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If single sign-on token is valid. The information is updated.
If the session is invalid. The information is updated.
If the input parameter is invalid.
If Session Service is not initialized.
If Access Manager returned service not available.
If HTTP error encountered while communicating with Access Manager.
If error parsing XML from Access Manager.
If access is denied while communicating with Access Manager.
If any other error occurred.