Previous      Contents      Next
Sun Java System Access Manager 2005Q1 Developer's Reference

Chapter 7
Single Sign-On Functions

This 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()
am_sso_add_sso_token_listener()
am_sso_create_sso_token_handle()
am_sso_destroy_sso_token_handle()
am_sso_get_auth_level()
am_sso_get_auth_level()
am_sso_get_auth_type()
am_sso_get_host()
am_sso_get_idle_time
am_sso_get_max_idle_time()
am_sso_get_max_session_time()
am_sso_get_principal()
am_sso_get_principal_set()
am_sso_get_property()
am_sso_get_sso_token_id()
am_sso_get_time_left()
am_sso_init()
am_sso_invalidate_token()
am_sso_is_valid_token()
am_sso_refresh_token()
am_sso_remove_listener()
am_sso_remove_sso_token_listener()
am_sso_set_property()
am_sso_validate_token()

---

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:

Parameter	Description
listener	The token change event listener.
args	Arguments to pass to the listener.
dispatch_to_sep_thread	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.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If the listener was successfully added.
AM_INVALID_ARGUMENT	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.
AM_NOTIF_NOT_ENABLED	If notification is not enabled and the notification_url input parameter is invalid.
AM_FAILURE	If any other error occurred.

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:

Parameter	Description
sso_token_handle	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.
listener	The token change event listener.
args	Arguments to pass to the listener.
dispatch_to_sep_thread	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.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If the listener was successfully added.
AM_INVALID_ARGUMENT	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.
AM_NOTIF_NOT_ENABLED	If notification is not enabled and the notification_url input parameter is invalid.
AM_FAILURE	If any other error occurred.

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:

Value	Description
AM_SUCCESS	If session validation was successful and a handle was successfully created.
AM_SERVICE_NOT_INITIALIZED	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.
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 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:

Parameter	Description
sso_token_handle	SSO token handle to be de-allocated.

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:

Parameter	Description
sso_token_handle	The SSO token handle.

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:

Parameter	Description
sso_token_handle	The SSO token handle.

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:

Parameter	Description
sso_token_handle	The SSO token handle.

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_time

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

Parameter	Description
sso_token_handle	The SSO token handle.

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:

Parameter	Description
sso_token_handle	The SSO token handle.

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:

Parameter	Description
sso_token_handle	The SSO token handle.

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);Parameters

This function takes the following parameters:

Parameter	Description
sso_token_handle	The SSO token handle.

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:

Parameter	Description
sso_token_handle	The SSO token handle.

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:

Parameter	Description
sso_token_handle	The SSO token handle.
property_key	The name of property to get.
check_if_session_valid	Whether to check if session is valid first. If true and session is invalid, NULL will always be returned.

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:

Parameter	Description
sso_token_handle	The SSO token handle.

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:

Parameter	Description
sso_token_handle	The SSO token handle.

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:

Parameter	Description
property_map	Properties object to initialize sso with.

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:

Parameter	Description
sso_token_handle	SSO token handle of session to be invalidated.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If session was successfully invalidated.
AM_INVALID_ARGUMENT	If the sso_token_handle is invalid.
AM_SERVICE_NOT_INITIALIZED	If the sso token service was not initialized with am_sso_init().
AM_SERVICE_NOT_AVAILABLE	If server returned service not available.
AM_HTTP_ERROR	If HTTP error encountered while communicating with server.
AM_ERROR_PARSING_XML	If error parsing XML from server.
AM_ACCESS_DENIED	If access denied while communicating with server.
AM_FAILURE	If any other error occurred.

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:

Parameter	Description
sso_token_handle	SSO token to check if valid.

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:

Parameter	Description
sso_token_handle	SSO token to refresh.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If SSO token could be refreshed with no errors.
AM_INVALID_ARGUMENT	If the input parameter is invalid.
AM_SERVICE_NOT_INITIALIZED	If SSO token service is not initialized. SSO token service must be initialized by calling am_sso_init() before any call to am_sso*.
AM_SERVICE_NOT_AVAILABLE	If server returned service not available.
AM_HTTP_ERROR	If HTTP error encountered while communicating with server.
AM_ERROR_PARSING_XML	If error parsing XML from server.
AM_ACCESS_DENIED	If access denied while communicating with server.
AM_SESSION_FAILURE	If the session validation failed.
AM_FAILURE	If any other error occurred.

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:

Parameter	Description
listener	The change event listener.

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:

Value	Description
AM_SUCCESS	If the listener was successfully removed.
AM_INVALID_ARGUMENT	If sso_token_id or listener is invalid or NULL.
AM_NOT_FOUND	If listener was not found for the sso token id.
AM_FAILURE	If any other error occurred.

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:

Parameter	Description
sso_token_handle	SSO token to validate.

Returns

This function returns am_status_t with one of the following values:

Value	Description
AM_SUCCESS	If SSO token is valid, session handle is updated.
AM_INVALID_SESSION	If the session is invalid, session handle is updated.
AM_INVALID_ARGUMENT	If the input parameter is invalid.
AM_SERVICE_NOT_INITIALIZED	If SSO token service is not initialized. sso token service must be initialized by calling am_sso_init() before any call to am_sso*.
AM_SERVICE_NOT_AVAILABLE	If server returned service not available.
AM_HTTP_ERROR	If HTTP error encountered while communicating with server.
AM_ERROR_PARSING_XML	If error parsing XML from server.
AM_ACCESS_DENIED	If access denied while communicating with server.
AM_FAILURE	If any other error occurred.

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.

Previous      Contents      Next

---

Copyright 2005 Sun Microsystems, Inc. All rights reserved.