Sun Java System Access Manager 2005Q1 Developer's Reference |
Chapter 2
Authorization FunctionsThis chapter provides a reference to the public functions you can use in developing custom authorization modules for Sun Java System Access Manager 6 2005Q1. Function summaries include a short description, syntax, parameters and returns.
The following functions are contained in the header file am_auth.h:
am_auth_abort()Aborts the authentication process.
Syntax
#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_abort(am_auth_context_t auth_ctx);Parameters
This function takes the following parameter:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the abort process was successfully completed.
AM_INVALID_ARGUMENT
If the auth_ctx parameter is NULL.
am_auth_create_auth_context()Creates a new auth context and returns the handle.
Syntax
#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_create_auth_context(am_auth_context_t *auth_ctx,
const char *org_name,
const char *cert_nick_name,
const char *url);Parameters
This function takes the following parameters:
Returns
This function returns am_status_t with one of the following values:
am_auth_destroy_auth_context()Destroys the given auth context handle.
Syntax
#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_destroy_auth_context(am_auth_context_t auth_ctx);Parameters
This function takes the following parameter:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the auth context was successfully destroyed.
AM_INVALID_ARGUMENT
If the auth_ctx parameter is NULL.
am_auth_get_module_instance_names()Gets the authentication module instances (or plug-ins) configured for an organization, or sub-organization name that was set during the creation of the auth context.
Syntax
#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_get_module_instance_names(am_auth_context_t auth_ctx,
am_string_set_t** module_inst_names_ptr);Parameters
This function takes the following parameters:
Parameter
Description
auth_ctx
Handle of the auth context.
module_inst_names_ptr
Address of a pointer to am_string_set_t.
Returns
This function returns am_status_t with one of the following values:
Details
Supply the address of a pointer to a structure of type am_string_set_t. Module instance names are returned in am_string_set_t. Free the memory allocated for this set by calling am_string_set_destroy().
Returns NULL if the number of modules configured is zero.
am_auth_get_organization_name()Gets the organization to which the user is authenticated.
Syntax
#include "am_auth.h"
AM_EXPORT const char *
am_auth_get_organization_name(am_auth_context_t auth_ctx);Parameters
This function takes the following parameter:
Returns
This function returns const char * with one of the following values:
Value
Description
Zero terminated string representing the organization
When user successfuly logs in.
NULL
If there was an error or the user has not successfully logged in.
am_auth_get_sso_token_id()Get the SSO token id of the authenticated user.
Syntax
#include "am_auth.h"
AM_EXPORT const char *
am_auth_get_sso_token_id(am_auth_context_t auth_ctx);Parameters
This function takes the following parameter:
Returns
This function returns const char * with one of the following values:
Value
Description
Zero terminated string representing the organization
When user successfuly logs in.
NULL
If there was an error or the user has not successfully logged in
am_auth_get_sso_token_id()Get the SSO token id of the authenticated user.
Syntax
#include "am_auth.h"
AM_EXPORT const char *
am_auth_get_sso_token_id(am_auth_context_t auth_ctx);Parameters
This function takes the following parameter:
Returns
This function returns const char * with one of the following values:
Value
Description
Zero terminated string representing the organization.
When user successfuly logs in.
NULL
If there was an error or the user has not successfully logged in.
am_auth_has_more_requirements()Checks to see if there are requirements to be supplied to complete the login process.
Syntax
#include "am_auth.h"
AM_EXPORT boolean_t
am_auth_has_more_requirements(am_auth_context_t auth_ctx);Parameters
This function takes the following parameter:
Returns
This function returns boolean_t with one of the following values:
Details
This call is invoked after invoking the login() call. If there are requirements to be supplied, then the caller can retrieve and submit the requirements in the form of callbacks.
am_auth_init()Initializes the authentication modules.
Syntax
#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_init(const am_properties_t auth_init_params);Parameters
This function takes the following parameter:
Parameter
Description
auth_init_params
The property handle to the property file which contains the properties to initialize the authentication library.
Returns
This function returns am_status_t with one of the following values:
am_auth_login()Starts the login process given the index type and its value.
Syntax
#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_login(am_auth_context_t auth_ctx, am_auth_index_t auth_idx,
const char *value);Parameters
This function takes the following parameters:
Parameter
Description
auth_ctx
Handle of the auth context.
auth_idx
Index type to be used to initiate the login process.
value
Value corresponding to the index type.
Returns
This function returns am_status_t with one of the following values:
am_auth_logout()Logs out the user.
Syntax
#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_logout(am_auth_context_t auth_ctx);Parameters
This function takes the following parameter:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the logout process was successfully completed.
AM_INVALID_ARGUMENT
If the auth_ctx parameter is NULL.
am_auth_num_callbacks()Gets the number of callbacks.
Syntax
#include "am_auth.h"
AM_EXPORT size_t
am_auth_num_callbacks(am_auth_context_t auth_ctx);Parameters
This function takes the following parameters:
Returns
This function returns size_t a value equal to the number of callbacks.
am_auth_submit_requirements()Submits the responses populated in the callbacks to the server.
Syntax
#include "am_auth.h"
AM_EXPORT am_status_t
am_auth_submit_requirements(am_auth_context_t auth_ctx);Parameters
This function takes the following parameter:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the submitted requirements were processed successfully.
AM_AUTH_FAILURE
If the authentication process failed.
AM_INVALID_ARGUMENT
If the auth_ctx parameter is NULL.