This chapter provides a reference to the public functions you can use in developing custom authentication modules for Sun JavaTM System Access Manager. Function summaries include a short description, syntax, parameters and returns.
The following functions are contained in the header file am_auth.h :
Aborts the authentication process.
#include "am_auth.h" AM_EXPORT am_status_t am_auth_abort(am_auth_context_t auth_ctx);
This function takes the following parameter:
Handle of the auth context.
This function returns am_status_t with one of the following values:
If the abort process was successfully completed.
If the auth_ctx parameter is NULL.
Creates a new auth context and returns the handle.
#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);
This function takes the following parameters:
Pointer to the handle of the auth context.
Organization name to authenticate to. May be NULL to use value in property file.
The alias of the certificate to be used if the client is connecting securely. May be NULL in case of non-secure connection.
Service URL, for example:
http://pride.red.iplanet.com:58080/amserver
May be NULL, in which case the naming service URL property is used.
This function returns am_status_t with one of the following values:
If auth context was successfully created.
If unable to allocate memory for the handle.
If the auth_ctx parameter is NULL.
If the authentication initialization failed
Destroys the given auth context handle.
#include "am_auth.h" AM_EXPORT am_status_t am_auth_destroy_auth_context(am_auth_context_t auth_ctx);
This function takes the following parameter:
Handle of the auth context to be destroyed.
This function returns am_status_t with one of the following values:
If the auth context was successfully destroyed.
If the auth_ctx parameter is NULL.
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.
#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);
This function takes the following parameters:
Handle of the auth context.
Address of a pointer to am_string_set_t.
This function returns am_status_t with one of the following values:
If the submitted requirements were processed successfully.
If the authentication process failed.
If the auth_ctx parameter is NULL.
If the Authentication Service is not initialized.
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.
Gets the organization to which the user is authenticated.
#include "am_auth.h" AM_EXPORT const char * am_auth_get_organization_name(am_auth_context_t auth_ctx);
This function takes the following parameter:
Handle of the auth context.
This function returns const char * with one of the following values:
When user successfully logs in.
If there was an error or the user has not successfully logged in.
Get the SSO token id of the authenticated user.
#include "am_auth.h" AM_EXPORT const char * am_auth_get_sso_token_id(am_auth_context_t auth_ctx);
This function takes the following parameter:
Handle of the auth context.
This function returns const char * with one of the following values:
When user successfully logs in.
If there was an error or the user has not successfully logged in
Get the SSO token id of the authenticated user.
#include "am_auth.h" AM_EXPORT const char * am_auth_get_sso_token_id(am_auth_context_t auth_ctx);
This function takes the following parameter:
Handle of the auth context.
This function returns const char * with one of the following values:
When user successfully logs in.
If there was an error or the user has not successfully logged in.
Checks to see if there are requirements to be supplied to complete the login process.
#include "am_auth.h" AM_EXPORT boolean_t am_auth_has_more_requirements(am_auth_context_t auth_ctx);
This function takes the following parameter:
Handle of the auth context.
This function returns boolean_t with one of the following values:
If there are more requirements.
If there are no more requirements.
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.
Initializes the authentication modules.
#include "am_auth.h" AM_EXPORT am_status_t am_auth_init(const am_properties_t auth_init_params);
This function takes the following parameter:
The property handle to the property file which contains the properties to initialize the authentication library.
This function returns am_status_t with one of the following values:
If the initialization of the library is successful.
If unable to allocate memory during initialization.
If auth_init_params is NULL.
If the error was due to other causes. See am_types.h.
Starts the login process given the index type and its value.
#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);
This function takes the following parameters:
Handle of the auth context.
Index type to be used to initiate the login process.
Value corresponding to the index type.
This function returns am_status_t with one of the following values:
If the login process was successfully completed.
If the auth_ctx or value parameter is NULL.
If the auth_idx parameter is invalid.
Logs out the user.
#include "am_auth.h" AM_EXPORT am_status_t am_auth_logout(am_auth_context_t auth_ctx);
This function takes the following parameter:
Handle of the auth context.
This function returns am_status_t with one of the following values:
If the logout process was successfully completed.
If the auth_ctx parameter is NULL.
Gets the number of callbacks.
#include "am_auth.h" AM_EXPORT size_t am_auth_num_callbacks(am_auth_context_t auth_ctx);
This function takes the following parameters:
Handle of the auth context.
This function returns size_t a value equal to the number of callbacks.
Submits the responses populated in the callbacks to the server.
#include "am_auth.h" AM_EXPORT am_status_t am_auth_submit_requirements(am_auth_context_t auth_ctx);
This function takes the following parameter:
Handle of the auth context.
This function returns am_status_t with one of the following values:
If the submitted requirements were processed successfully.
If the authentication process failed.
If the auth_ctx parameter is NULL.