Sun Java™ System Access Manager contains public data types and functions you can use to communicate with the Session Service for single sign-on. Reference summaries include a short description, syntax, parameters and returns. The code is contained in the <am_sso.h> header file (located in the /AccessManager-base/SUNWam/include directory). The sample source am_sso_test.c (located in the /AccessManager-base/SUNWam/samples/csdk directory) demonstrates the basic usage of the single sign-on API. This chapter contains the following sections:
The Single Sign-on API for C are provided in the SUNWamcom package which comes with Access Manager 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.
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. By default, the properties file used for initializing the Session Service is AMAgent.properties, located in /AccessManager-base/SUNWam/config/. This file is created during the process for installing a web agent. Before using the API be sure the properties in the following table are set in AMAgent.properties.
See Sun Java System Access Manager Policy Agent 2.2 User’s Guide for more information.
Property |
Definition |
---|---|
com.sun.am.naming.url |
Specifies the URL for the Naming Service which, in turn, finds the URL of the Session Service. This property must be set as: com.sun.am.naming.url = protocol://AM_host.domain:port/amserver/namingservice |
com.sun.am.notification.enable |
Specifies whether the Notification Service will be used to update the cache. If enabled, a URL where notification messages from Access Managerare sent must be specified. This property is set as: com.sun.am.notification.enable = true | false Note – If com.sun.am.notification.enable is not found in the properties file, the default value is false. |
com.sun.am.notification.url |
If com.sun.am.notification.enable is set to true, the value of this property specifies a URL where notification messages from Access Managerare sent. This property is set as: com.sun.am.notification.url = protocol//AM_host.domain:port/notification_URL |
com.sun.am.sso.polling.period |
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 in AMAgent.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 in AMAgent.properties but can be added when needed. |
For more information, see the Sun Java System Access Manager Policy Agent 2.2 User’s Guide.
The following sections contain information and code samples for some of the single sign-on calls.
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.
For more information on am_cleanup(), see Chapter 9, Additional Data Types and Functions.
#include <am_sso.h> int main() { am_properties_t *properties; am_status_t status; /* create a properties handle */ status = am_properties_create(&properties); if (status != AM_SUCCESS) { printf("am_properties_create failed.\\n"); exit(1); } /* load properties from a properties file */ status = am_properties_load(properties, "./myPropertiesFile"); if (status != AM_SUCCESS) { printf("am_properties_load failed.\\n"); exit(1); } /* initialize SSO module */ status = am_sso_init(properties); if (status != AM_SUCCESS) { printf("am_sso_init failed.\\n"); return 1; } /* login through auth module, and do auth functions. * ... */ /* do sso functions * ... */ /* done - cleanup. */ status = am_cleanup(); if (status != AM_SUCCESS) { printf("am_cleanup failed!\\n"); return 1; } /* free memory for properties */ status = am_properties_destroy(properties); if (status != AM_SUCCESS) { printf("Failed to free properties.\\n"); return 1; } /* exit program successfully. */ return 0; }
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.
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 Access Manager and caches it. A single sign-on token handle is then assigned to it.
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 Access Manager.
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.
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().
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.
The following code sample shows how you might use the am_sso_get_property() and am_sso_set_property() functions. For additional information, see am_sso_get_property() and am_sso_set_property().
/* initialize sso as in previous sample */ am_status_t status = NULL; am_sso_token_handle_t sso_handle = NULL; char *session_status = NULL; am_string_set_t principal_set = NULL; /* create sso token handle */ status = am_sso_create_sso_token_handle(&sso_handle, sso_token_id, false); if (status != AM_SUCCESS) { printf("Failed getting sso token handle for sso token id %s. \\n", sso_token_id); return 1; } /* check if session is valid */ session_status = am_sso_is_valid_token(sso_handle) ? "Valid" : "Invalid"; printf("Session state is %s\\n", session_status); /* check if session is valid using validate. This also updates the handle with /*info from the server */ status = am_sso_validate_token(sso_handle); if (status == AM_SUCCESS) { printf("Session state is valid.\\n"); } else if (status == AM_INVALID_SESSION) { printf("Session status is invalid.\\n"); } else { printf("Error validating sso token.\\n"); return 1; } /* get info on the session */ printf("SSO Token ID is %s.\\n", am_sso_get_sso_token_id(sso_handle)); printf("Auth type is %s.\\n", am_sso_get_auth_type(sso_handle)); printf("Auth level is %d.\\n", am_sso_get_auth_level(sso_handle)); printf("Idle time is %d.\\n", am_sso_get_idle_time(sso_handle)); printf("Max Idle time is %d.\\n", am_sso_get_max_idle_time(sso_handle)); printf("Time left is %d.\\n", am_sso_get_time_left(sso_handle)); printf("Max session time is %d.\\n", am_sso_get_max_session_time(sso_handle)); printf("Principal is %s.\\n", am_sso_get_principal(sso_handle)); printf("Host is %s.\\n", am_sso_get_host(sso_handle)); principal_set = am_sso_get_principal_set(sso_handle); if (principal_set == NULL) { printf("ERROR: Principal set is NULL!\\n"); }else { printf("Principal set size %d.\\n", principal_set->size); for (i = 0; i < principal_set->size; i++) { printf("Principal[%d] = %s.\\n", i, principal_set->strings[i]); } am_string_set_destroy(principal_set); } /* get "HOST" property on the session. Same as am_sso_get_host(). */ printf("Host is %s.\\n", am_sso_get_property(sso_handle, "HOST")); /* set a application defined property and get it back */ status = am_sso_set_property(sso_handle, "AppPropName", "AppPropValue"); if (status != AM_SUCCESS) { printf("Error setting property.\\n"); return 1; } printf("AppPropName value is %s.\\n", am_sso_get_property (sso_handle, "AppPropName"); /* refresh token, idle time should be 0 after refresh */ status = am_sso_refresh_token(sso_handle); if (status != AM_SUCCESS) { printf("Error refreshing token !\\n"); return 1; } printf("After refresh, idle time is %d.\\n", am_sso_get_idle_time(sso_handle)); /* end this session abruptly. am_auth_logout() is the right way /* to end session */ status = am_sso_invalidate_token(sso_handle); if (status != AM_SUCCESS) { printf("Error invalidating token.\\n"); return 1; } /* we are done with sso token handle. free memory for sso handle. */ status = am_sso_destroy_sso_token_handle(sso_handle); if (status != AM_SUCCESS) { printf("Failed to free sso token handle.\\n"); return 1; } /* call am_cleanup, and other cleanup routines as in previous sample */
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 AMAgent.properties to true, and by providing the com.sun.am.notification.url property a URL which will receive HTTP notification messages from Access Manager. 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.
For more information, see Single Sign-on Properties and <am_notify.h>.
void sample_listener_func( am_sso_token_handle_t sso_token_handle, const am_sso_token_event_type_t event_type, const time_t event_time, void *opaque) { if (sso_token_handle != NULL) { const char *sso_token_id = am_sso_get_sso_token_id(sso_token_handle); boolean_t is_valid = am_sso_is_valid_token(sso_token_handle); printf("sso token id is %s.\\n", sso_token_id==NULL?"NULL":sso_token_id); printf("session state is %s.\\n", is_valid == B_TRUE ? "valid":"invalid"); printf("event type %d.\\n", event_type); printf("event time %d.\\n", event_time); } else { printf("Error: sso token handle is null!"); } if (opaque) *(int *)opaque = 1; return; } int main(int argc, char *argv[]) { am_status_t status; char *sso_token_id = argv[1]; int listener_func_done = 0; /* initialize sso as in previous samples */ /* get sso token handle */ status = am_sso_create_sso_token_handle(&sso_handle, sso_token_id, false); /* register listener function. notification must be enabled, if not, /* status AM_NOTIF_NOT_ENABLED will be returned. */ status = am_sso_add_sso_token_listener(sso_handle, sample_listener_func, &listener_func_done, B_TRUE); if (status != AM_SUCCESS) { printf("Failed to register sample listener function.\\n"); return 1; }
Access Manager 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 Access Manager 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 amadmin, can be used. Session tokens can be created to access Directory Server directly. No session is created, making Access Manager access valid only within that process or virtual machine.
The single sign-on data types defined in <am_sso.h> are:
A pointer to the session information object.
#include "am_sso.h" typedef struct am_sso_token_handle *am_sso_token_handle_t;
am_sso_token_handle is an opaque structure with no accessible members.
Listener function declaration.
#include "am_sso.h" typedef void (*am_sso_token_listener_func_t)( const am_sso_token_handle_t sso_token_handle, const am_sso_token_event_type_t event_type, const time_t event_time, void *args);
am_sso_token_listener_func_t has the following members:
Pointer to the session information object.
Takes one of the following values from the am_sso_token_event_type_t enumeration (defined in the <am_sso.h> header file):
typedef enum { AM_SSO_TOKEN_EVENT_TYPE_UNKNOWN = 0, AM_SSO_TOKEN_EVENT_TYPE_IDLE_TIMEOUT = 1, AM_SSO_TOKEN_EVENT_TYPE_MAX_TIMEOUT = 2, AM_SSO_TOKEN_EVENT_TYPE_LOGOUT = 3, AM_SSO_TOKEN_EVENT_TYPE_DESTROY = 5 } am_sso_token_event_type_t;
Takes a value based on the standard time_t data type that represents the time at which the change event occurred.
Pointer to application-defined parameters.
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.