Authentication Functions

The authentication functions defined in <am_auth.h> are:

• am_auth_abort()

• am_auth_create_auth_context()

• am_auth_destroy_auth_context()

• am_auth_get_callback()

• am_auth_get_module_instance_names()

• am_auth_get_organization_name()

• am_auth_get_sso_token_id()

• am_auth_get_status()

• 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 an authentication process that has not been completed.

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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the process was successfully stopped.

AM_INVALID_ARGUMENT

If the auth_ctx parameter is NULL.

am_auth_create_auth_context()

Creates the context for the authentication and a pointer to it.

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 am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

org_name

Pointer to the name of the organization for which the authentication context is being initialized. May be NULL to use the value defined in the agent configuration properties.

cert_nick_name

Pointer to the alias of the certificate being used if the application will connect securely to OpenSSO Enterprise. May be NULL if the connection is not secure.

url

Pointer to the OpenSSO Enterprise Naming Service URL. May be NULL to use the Naming Service URL defined in the agent configuration properties.

Returns

This function returns a pointer to the authentication context object and one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the authentication 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()

Eliminates the specified authentication context.

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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the pointer was successfully destroyed.

AM_INVALID_ARGUMENT

If the auth_ctx parameter is NULL.

am_auth_get_callback()

Retrieves the appropriate callback structure to populate with authentication requirements.

Syntax

#include "am_auth.h"
AM_EXPORT am_auth_callback_t *
am_auth_get_callback(am_auth_context_t auth_ctx,
                     size_t index);

Parameters

This function takes the following parameters:

auth_ctx

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

index

Takes a value based on size_t defined in the standard <stddef.h> header file that initializes the index into the callback array.

Returns

This function returns a pointer to the am_auth_callback_t type. See am_auth_callback_t for more information.

am_auth_get_module_instance_names()

Retrieves the authentication module plug-in instances configured for the organization (or sub-organization) defined in the am_auth_context_t type.

Details

Module instance names are retrieved in pointer to a pointer to a am_string_set_t type (as defined in the <am_string_set.h> header file).

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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

module_inst_names_ptr

Pointer to a pointer to the am_string_set_t type.

Returns

This function returns a pointer to a pointer with the list of module instance names (or NULL if the number of configured modules is zero) and one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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 OpenSSO Enterprise Authentication Service is not initialized.

Memory Concerns

The implementation takes care of allocating memory for the module_inst_names_ptr.

am_auth_get_organization_name()

Retrieves 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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

Returns

This function returns a pointer with one of the following values:

Zero-terminated string representing the organization.

After the user successfully logs in.

NULL

If there was an error or the user has not successfully logged in.

am_auth_get_sso_token_id()

Retrieves the session identifier for the authenticated user.

Details

The SSOTokenID is a randomly-generated string that represents an authenticated user. See Single Sign-on Token Handles for more information.

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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

Returns

This function returns a pointer with one of the following values:

Zero-terminated string representing the session token.

After the user successfully logs in.

NULL

If there was an error or the user has not successfully logged in.

am_auth_get_status()

Retrieves the state of the authentication process.

Syntax

#include "am_auth.h"
AM_EXPORT am_auth_status_t
am_auth_get_status(am_auth_context_t auth_ctx);

Parameters

This function takes the following parameter:

auth_ctx

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

Returns

This function returns one of the following values of the am_auth_status_t enumeration as defined:

typedef enum am_auth_status {
    AM_AUTH_STATUS_SUCCESS = 0,
    AM_AUTH_STATUS_FAILED,
    AM_AUTH_STATUS_NOT_STARTED,
    AM_AUTH_STATUS_IN_PROGRESS,
    AM_AUTH_STATUS_COMPLETED
} am_auth_status_t;

AM_AUTH_STATUS_FAILED

The login process has failed.

AM_AUTH_STATUS_NOT_STARTED

The login process has not started.

AM_AUTH_STATUS_IN_PROGRESS

The login is in progress.

AM_AUTH_STATUS_COMPLETED

The user has been logged out.

AM_AUTH_STATUS_SUCCESS

The user has logged in.

am_auth_has_more_requirements()

Checks to see if there are additional requirements needed to complete the login process.

Details

am_auth_has_more_requirements() is invoked after the am_auth_login() call. If there are requirements to be supplied, the caller retrieves and submits the requirements in the form of callbacks.

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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE

If there are more requirements.

B_FALSE

If there are no more requirements.

am_auth_init()

Initializes the authentication module using the pointer returned by am_auth_create_auth_context().

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 am_properties_t type which contains the module initialization properties.

---

Note –

See am_properties_t for information.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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

See am_status_t.

am_auth_login()

Begins 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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

auth_idx

Defines the resource for which the authentication is being performed. Based on the am_auth_index_t enumeration used to initiate the login process:

typedef enum am_auth_idx {
    AM_AUTH_INDEX_AUTH_LEVEL = 0,
    AM_AUTH_INDEX_ROLE,
    AM_AUTH_INDEX_USER,
    AM_AUTH_INDEX_MODULE_INSTANCE,
    AM_AUTH_INDEX_SERVICE
} am_auth_index_t;

value

Pointer to the authentication module being used.

---

Note –

See Sun OpenSSO Enterprise 8.0 Administration Guide for more information on authentication modules.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the logout process was successfully completed.

AM_INVALID_ARGUMENT

If the auth_ctx parameter is NULL.

am_auth_num_callbacks()

Retrieves 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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

Returns

This function returns a value based on the size_t defined in the standard <stddef.h> header file that reflects the number of callbacks.

am_auth_submit_requirements()

Passes the responses populated in the callbacks to the Authentication Service.

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

The am_auth_context_t type.

---

Note –

See am_auth_context_t for information.

---

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

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.