Sun Java System Access Manager 2005Q1 Developer's Reference |
Chapter 7
Single Sign-On FunctionsThis chapter provides a reference to the public functions you can use to implement Single Sign-on (SSO) in Sun Java System Access Manager 6 2005Q. 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()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:
Returns
This function returns am_status_t with one of the following values:
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:
Returns
This function returns am_status_t with one of the following values:
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:
Parameter
Description
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.
Returns
This function returns am_status_t with one of the following values:
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 parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
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 auth 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:
Returns
This function returns the auth level of this session handle; returns ULONG_MAX if there was any error.
am_sso_get_auth_type()Gets the auth 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 parameters:
Returns
This function returns the auth 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 parameters:
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_timeGets 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 parameters:
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 max 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:
Returns
This function returns the max idle time for this session handle in seconds.
(time_t) -1 if there was any error.
am_sso_get_max_session_time()Gets the max session time for this session.
Syntax
#include "am_sso.h"
Parameters
This function takes the following parameters:
Returns
This function returns the max 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);ParametersThis function takes the following parameters:
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:
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:
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:
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:
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:
Returns
This function returns am_status_t with one of the following values:
Value
Description
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:
Returns
This function returns am_status_t with one of the following values:
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:
Returns
This function returns boolean_t with one of the following values:
Value
Description
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:
Returns
This function returns am_status_t with one of the following values:
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 parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
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:
Parameter
Description
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:
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:
Parameter
Description
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:
Value
Description
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:
Returns
This function returns am_status_t with one of the following values:
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.