This chapter provides a reference to the public functions you can use to implement Single Sign-on (SSO) in Sun JavaTM 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.
Adds a listener for the any SSO token’s change events.
#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 token change event listener.
Arguments to pass to the listener.
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.
This function returns am_status_t with one of the following values:
If the listener was successfully added.
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.
If notification is not enabled and the notification_url input parameter is invalid.
If any other error occurred.
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 .
Adds an SSO token listener for the SSO token’s change events.
#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:
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.
The token change event listener.
Arguments to pass to the listener.
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.
This function returns am_status_t with one of the following values:
If the listener was successfully added.
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.
If notification is not enabled and the notification_url input parameter is invalid.
If any other error occurred.
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.
Creates a handle to session information.
#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 SSO token handle which will be assigned an handle if the session validation is successful.
String representation session identifier.
When querying for session information.
This function returns am_status_t with one of the following values:
If session validation was successful and a handle was successfully created.
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.
If the session_token_handle_ptr parameter is NULL.
If there was a memory allocation problem.
If any other error occurred.
Destroys the handle to session information.
#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:
SSO token handle to be de-allocated.
This function returns am_status_t with one of the following values:
If the memory release process was successful.
If the session_token_handle parameter is NULL.
If any other error occurred.
This function does NOT log out the user or invalidate the session.
Gets the authentication level for this session.
#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 parameters:
The SSO token handle.
This function returns the authentication level of this session handle; returns ULONG_MAX if there was any error.
Gets the authentication type for this session.
#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:
The SSO token handle.
This function returns the authentication type of this session handle. NULL if there was any error.
Gets the host address for this session.
#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:
The SSO token handle.
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.
Gets idle time associated with this session 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:
The SSO token handle.
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.
Gets the maximum idle time for this session.
#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:
The SSO token handle.
This function returns the maximum idle time for this session handle in seconds.( time_t) -1 if there was any error.
Gets the maximum session time for this session.
#include "am_sso.h"
This function takes the following parameters:
The SSO token handle.
This function returns the maximum session time of this session handle in seconds. (time_t) -1 if there was any error.
Gets the principal of this session.
#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:
The SSO token handle.
This function returns the principal of this session handle, NULL if the sso_token handle is invalid or any other error occurred.
Gets the set of principals of this session. A session can have more than one principal.
#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 parameters:
The SSO token handle.
This function returns the set of principals of this session handle, NULL if the principal property is not set or has no value.
Gets the value of a session property.
#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:
The SSO token handle.
The name of property to get.
Whether to check if session is valid first. If true and session is invalid, NULL will always be returned.
This function returns the value of the session property. NULL if property is not set or does not have a value.
Gets the SSO token ID for this session.
#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:
The SSO token handle.
This function returns the SSO token ID of this session. NULL if sso_token_handle is invalid or any other error occurred.
Gets the time left of this session 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:
The SSO token handle.
This function returns the time left of this session handle in seconds. ( time_t) -1 if token is invalid or some error occurs.
Detailed error is logged.
Initializes the SSO module in the C API.
#include "am_sso.h" AM_EXPORT am_status_t am_sso_init(am_properties_t property_map);
This function takes the following parameters:
Properties object to initialize SSO with.
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
This call must be made before any calls to am_sso_* functions.
Invalidates or destroys the session on the server.
#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 parameters:
SSO token handle of session to be invalidated.
This function returns am_status_t with one of the following values:
If session was successfully invalidated.
If the sso_token_handle is invalid.
If the SSO token service was not initialized with am_sso_init().
If server returned service not available.
If HTTP error encountered while communicating with server.
If error parsing XML from server.
If access denied while communicating with server.
If any other error occurred.
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.
Checks if a token is valid.
#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 parameters:
SSO token to check if valid.
This function returns boolean_t with one of the following values:
If SSO token is valid.
If SSO token is invalid or any other error occurred.
This call looks in the passed sso_token_handle to check for validity; it does not go to the server.
Refreshes an SSO token 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 parameters:
SSO token to refresh.
This function returns am_status_t with one of the following values:
If SSO token could be refreshed with no errors.
If the input parameter is invalid.
If SSO token service is not initialized. SSO token service must be initialized by calling am_sso_init() before any call to am_sso*.
If server returned service not available.
If HTTP error encountered while communicating with server.
If error parsing XML from server.
If access denied while communicating with server.
If the session validation failed.
If any other error occurred.
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.
Removes an SSO token listener for any SSO token’s change events.
#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 change event listener.
This function returns am_status_t with one of the following values:
If the listener was successfully removed.
If listener was NULL.
If listener was not found.
If any other error occurred.
If am_sso_add_listener() was called more than once with the same listener function, all instances of the listener function will be removed.
Removes an SSO token listener for the SSO token’s change events.
#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:
The session handle containing the SSO token id for the listener.
The token change event listener.
This function returns am_status_t with one of the following values:
If the listener was successfully removed.
If sso_token_id or listener is invalid or NULL.
If listener was not found for the SSO token id.
If any other error occurred.
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.
Sets a property in the session.
#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:
The session handle.
The property name.
The property value.
This function returns am_status_t with one of the following values:
If the property was successfully set.
If the sso_token_handle is invalid.
If any other error occurred.
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.
Validates an SSO token.
#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 parameters:
SSO token to validate.
This function returns am_status_t with one of the following values:
If SSO token is valid, session handle is updated.
If the session is invalid, session handle is updated.
If the input parameter is invalid.
If SSO token service is not initialized. SSO token service must be initialized by calling am_sso_init() before any call to am_sso.
If server returned service not available.
If HTTP error encountered while communicating with server.
If error parsing XML from server.
If access denied while communicating with server.
If any other error occurred.
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.