Contained WithinFind More DocumentationFeatured Support Resources |  Download this book in PDF (1048 KB)
Chapter 4 Single Sign-On Data Types and FunctionsSun 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 CThe 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:
Single Sign-on PropertiesCertain 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. Note – See Sun Java System Access Manager Policy Agent 2.2 User’s Guide for more information. Table 4–1 Single Sign-on Properties in AMAgent.properties
For more information, see the Sun Java System Access Manager Policy Agent 2.2 User’s Guide. Single Sign-on CallsThe following sections contain information and code samples for some of the single sign-on calls. Initialization and CleanupWhen 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. Note – 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;
}
Single Sign-on Token HandlesWhen 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. Creating Single Sign-on Token HandlesOnce 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. Validating Single Sign-on Token HandlesThe 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. Note – 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. Destroying Session Token HandlesWhen 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(). Tip – 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. Retrieving and Setting PropertiesThe 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 */
Listening and NotificationA 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. Note – 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;
}
Non-Web ApplicationsAccess 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:
Single Sign-on Data TypesThe single sign-on data types defined in <am_sso.h> are: am_sso_token_handle_tA pointer to the session information object. Syntax#include "am_sso.h" typedef struct am_sso_token_handle *am_sso_token_handle_t; Membersam_sso_token_handle is an opaque structure with no accessible members. am_sso_token_listener_func_tListener function declaration. Syntax#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);
Membersam_sso_token_listener_func_t has the following members:
Single Sign-on FunctionsThe single sign-on functions defined in <am_sso.h> are: am_sso_add_listener()Add a listener for any and all event changes related to the referenced single sign-on token handle. Note – am_sso_add_listener() will not be removed after it is called once like am_sso_add_sso_token_listener(). DetailsThe caller must do one of the following:
See Listening and Notification for more information. 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);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_add_sso_token_listener()Adds a listener for any and all event changes related to the referenced single sign-on token handle. Note – am_sso_add_sso_token_listener() is removed from memory after it is called once, differentiating its functionality from am_sso_add_listener(). DetailsThe caller must do one of the following:
See Listening and Notification for more information. 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);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_create_sso_token_handle()Creates a single sign-on token handle as a container for a valid SSOTokenID. DetailsFor more information, see Single Sign-on Token Handles. 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);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_destroy_sso_token_handle()Destroys the specified single sign-on token handle. Detailsam_sso_destroy_sso_token_handle() does not log out the user or invalidate the session. For more information, see Single Sign-on Token Handles. Syntax#include "am_sso.h" AM_EXPORT am_status_t am_sso_destroy_sso_token_handle(am_sso_token_handle_t sso_token_handle); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_get_auth_level()Retrieves the authentication level associated with the specified single sign-on token handle. Syntax#include "am_sso.h" AM_EXPORT unsigned long am_sso_get_auth_level(const am_sso_token_handle_t sso_token); ParametersThis function takes the following parameter:
ReturnsThis function returns the authentication level of the specified handle, or ULONG_MAX if an error occurred. am_sso_get_auth_type()Retrieves the authentication type associated with the specified single sign-on token handle. Syntax#include "am_sso.h" AM_EXPORT const char * am_sso_get_auth_type(const am_sso_token_handle_t sso_token); ParametersThis function takes the following parameter:
ReturnsThis function returns the authentication type of the specified handle, or NULL if an error occurred. am_sso_get_host()Retrieves the name of the host associated with the specified single sign-on token handle. Syntax#include "am_sso.h" AM_EXPORT const char * am_sso_get_host(const am_sso_token_handle_t sso_token); ParametersThis function takes the following parameter:
ReturnsThis 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. am_sso_get_idle_timeRetrieves the idle time associated with the specified single sign-on token handle. Syntax#include "am_sso.h" AM_EXPORT time_t am_sso_get_idle_time(const am_sso_token_handle_t sso_token_handle); ParametersThis function takes the following parameter:
ReturnsThis 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. am_sso_get_max_idle_time()Retrieves the maximum idle time associated with the specified single sign-on token handle. Syntax#include "am_sso.h" AM_EXPORT time_t am_sso_get_max_idle_time(const am_sso_token_handle_t sso_token); ParametersThis function takes the following parameters:
ReturnsThis 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. am_sso_get_max_session_time()Retrieves the maximum session time associated with the specified single sign-on token handle. Syntax#include "am_sso.h" AM_EXPORT time_t am_sso_get_max_session_time(const am_sso_token_handle_t sso_token); ParametersThis function takes the following parameter:
ReturnsThis 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. am_sso_get_principal()Retrieves the principal (user) associated with the specified single sign-on token handle. Syntax#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:
ReturnsThis function returns the principal (user) of the specified session, or NULL if the handle is invalid or any other error occurred. am_sso_get_principal_set()Retrieves a set of principals associated with the specified single sign-on token handle. Syntax#include "am_sso.h" AM_EXPORT am_string_set_t * am_sso_get_principal_set(const am_sso_token_handle_t sso_token); ParametersThis function takes the following parameter:
ReturnsThis 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. am_sso_get_property()Retrieves the value of a property associated with the specified single sign-on token handle. 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);
ParametersThis function takes the following parameters:
ReturnsThis function returns a pointer to the value of the property, or NULL if the property is not set or does not have a value. am_sso_get_sso_token_id()Retrieves the SSOTokenID associated with the specified single sign-on token handle. Syntax#include "am_sso.h" AM_EXPORT const char * am_sso_get_sso_token_id(const am_sso_token_handle_t sso_token_handle); ParametersThis function takes the following parameters:
ReturnsThis function returns a pointer to the SSOTokenID, or NULL if sso_token_handle is invalid or any other error occurred. am_sso_get_time_left()Retrieves the time left in the session associated with the specified single sign-on token handle. Syntax#include "am_sso.h" AM_EXPORT time_t am_sso_get_time_left(const am_sso_token_handle_t sso_token_handle); ParametersThis function takes the following parameters:
ReturnsThis 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. am_sso_init()Initializes the data structures, allowing communication with the Session Service. Detailsam_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. Syntax#include "am_sso.h" AM_EXPORT am_status_t am_sso_init(am_properties_t property_map); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_invalidate_token()Invalidates or destroys the session on Access Manager associated with the single sign-on token handle. Detailsam_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. Syntax#include "am_sso.h" AM_EXPORT am_status_t am_sso_invalidate_token(const am_sso_token_handle_t sso_token_handle); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_is_valid_token()Checks if the SSOToken associated with the specified single sign-on token handle is valid. Detailsam_sso_is_valid_token() looks in the passed sso_token_handle to check for validity. It does not go to Access Manager. Syntax#include "am_sso.h" AM_EXPORT boolean_t am_sso_is_valid_token(const am_sso_token_handle_t sso_token_handle); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
am_sso_refresh_token()Refreshes the session information in the SSOToken associated with the specified single sign-on token handle. Detailsam_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. Syntax#include "am_sso.h" AM_EXPORT am_status_t am_sso_refresh_token(const am_sso_token_handle_t sso_token_handle); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_remove_listener()Removes a single sign-on token listener. DetailsIf am_sso_add_listener() was called more than once for the same listener function, all instances of the listener function will be removed. Syntax#include "am_sso.h" AM_EXPORT am_status_t am_sso_remove_listener(const am_sso_token_listener_func_t listener); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_remove_sso_token_listener()Removes a single sign-on token listener associated with the specified single sign-on token handle. DetailsIf am_sso_add_listener() was called more than once for the same listener function, all instances of the listener function will be removed. 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);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_set_property()Sets a property and its value in the SSOToken associated with the specified single sign-on token handle. DetailsThe 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. 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);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_sso_validate_token()Updates the session information in the SSOToken associated with the specified single sign-on token handle. DetailsThis 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. Syntax#include "am_sso.h" AM_EXPORT am_status_t am_sso_validate_token(const am_sso_token_handle_t sso_token_handle); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
|
||||||||||||
|
Caution –