Chapter 3 Authentication Functions

This chapter provides a reference to the public functions you can use in developing custom authentication modules for Sun Java^TM 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 :

• am_auth_abort()

• am_auth_create_auth_context()

• am_auth_destroy_auth_context()

• am_auth_get_module_instance_names()

• am_auth_get_organization_name()

• am_auth_get_sso_token_id()

• am_auth_has_more_requirements()

• am_auth_init()

• am_auth_login()

• am_auth_logout()

• am_auth_num_callbacks()

• am_auth_submit_requirements()

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:

auth_ctx

Handle of the auth context.

Returns

This function returns am_status_t with one of the following values:

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:

auth_ctx

Pointer to the handle of the auth context.

org_name

Organization name to authenticate to. May be NULL to use value in property file.

cert_nick_name

The alias of the certificate to be used if the client is connecting securely. May be NULL in case of non-secure connection.

url

Service URL, for example:

http://pride.red.iplanet.com:58080/amserver

May be NULL, in which case the naming service URL property is used.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If auth context was successfully created.

AM_NO_MEMORY

If unable to allocate memory for the handle.

AM_INVALID_ARGUMENT

If the auth_ctx parameter is NULL.

AM_AUTH_CTX_INIT_FAILURE

If the authentication initialization failed

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:

auth_ctx

Handle of the auth context to be destroyed.

Returns

This function returns am_status_t with one of the following values:

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:

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:

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.

AM_SERVICE_NOT_INITIALIZED

If the Authentication Service is not initialized.

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:

auth_ctx

Handle of the auth context.

Returns

This function returns const char * with one of the following values:

Zero-terminated string representing the organization

When user successfully 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:

uth_ctx

Handle of the auth context.

Returns

This function returns const char * with one of the following values:

Zero-terminated string representing the organization

When user successfully 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:

auth_ctx

Handle of the auth context.

Returns

This function returns const char * with one of the following values:

Zero-terminated string representing the organization.

When user successfully 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:

auth_ctx

Handle of the auth context.

Returns

This function returns boolean_t with one of the following values:

B_TRUE

If there are more requirements.

B_FALSE

If there are no more requirements.

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:

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_SUCCESS

If the initialization of the library is successful.

AM_NO_MEMORY

If unable to allocate memory during initialization.

AM_INVALID_ARGUMENT

If auth_init_params is NULL.

Others

If the error was due to other causes. See am_types.h.

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:

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_SUCCESS

If the login process was successfully completed.

AM_INVALID_ARGUMENT

If the auth_ctx or value parameter is NULL.

AM_FEATURE_UNSUPPORTED

If the auth_idx parameter is invalid.

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:

auth_ctx

Handle of the auth context.

Returns

This function returns am_status_t with one of the following values:

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:

auth_ctx

Handle of the auth context.

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:

auth_ctx

Handle of the auth context.

Returns

This function returns am_status_t with one of the following values:

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.