Sun Java System Access Manager 7.1 C API Reference

Chapter 2 Authentication Data Types and Functions

Sun Java™ System Access Manager contains public data types and functions you can use in developing custom authentication modules. This chapter provides information and a reference guide to the authentication application programming interface (API). Reference summaries include a short description, syntax, parameters and returns. Prototypes are contained in the <am_auth.h> header file located in the /AccessManager-base/SUNWam/include directory. The sample source am_auth_test.c, located in the /AccessManager-base/SUNWam/samples/csdk directory, demonstrates the basic usage of the API to login to an instance of Access Manager. This chapter contains the following sections:

The Authentication API for C

C applications can authenticate users with the Access Manager Authentication Service by using the authentication API for C. The C application contacts the Authentication Service to initiate the authentication process, and the Authentication Service responds with a set of requirements. The application then submits authentication credentials back to the Authentication Service and receives further authentication requirements back until there are no more to fulfill. After all requirements have been sent, the client makes one final call to determine if authentication has been successful or has failed.

Authentication Call Sequence

The sequence of calls necessary to authenticate to Access Manager begins with the function call am_auth_create_auth_context(). This call returns an am_auth_context structure that is then used for the rest of the authentication calls. Once the structure has been initialized, the am_auth_login() function is called. This indicates to the Authentication Service that an authentication is desired. Depending on the parameters passed when creating the am_auth_context structure and making the am_auth_login() function call, the Authentication Service will determine the login requirements with which to respond. For example, if the requested authentication is to an organization configured for Lightweight Directory Access Protocol (LDAP) authentication with no authentication module chaining involved, the server will respond with a request for a user name and password. The client loops the function call am_auth_has_more_requirements(), fills in the needed information and submits this back to the server using the function call am_auth_submit_requirements(). (When the requirements are a user name and password, this will happen twice.) The final step is to make the function call am_auth_get_status() to determine if the authentication was successful or not.


Note –

The remote-auth.dtd is the template used to format XML authentication requests sent to Access Manager and to parse XML authentication responses received by the external application. The attributes in the requests/responses correspond to elements in the remote-auth.dtd, which can be found in the directory AccessManager-base/SUNWam/dtd. In the example, user name corresponds to the NameCallback element and password to the PasswordCallback element in the remote-auth.dtd. More information on remote-auth.dtd can be found in Chapter 5, Using Authentication APIs and SPIs, in Sun Java System Access Manager 7.1 Developer’s Guide.


Authentication Properties

The following list of properties are used by the authentication API. Some are defined in the AMAgent.properties file and some are not. Those that are not defined can be added to the file so they do not have to be defined for each function call. For example, com.sun.am.auth.org.name, which identifies the organization from which you want to authenticate, can be added to AMAgent.properties.


Tip –

The web agent AMAgent.properties includes information for a variety of configurations. By default, the authentication API checks the directory where Access Manager is installed for AMAgent.properties. After installing Access Manager though, the file does not exist. If the file does not exist, you must create it and add these properties to the file. More information on AMAgent.properties can be found in Appendix C, Web Agent AMAgent.properties Configuration File, in Sun Java System Access Manager Policy Agent 2.2 Guide for Sun Java System Web Server 6.1.


Table 2–1 Properties Needed by the Authentication API for C

Property 

Definition 

com.sun.am.naming.url

URL of the Access Manager Naming Service in the format: 

http://server.domain:port/amserver/namingservice

com.sun.am.policy.agents.config.local.log.file

The logging directory in the format: 

path-to-directory/logs/auth-log


Note –

This property may be added to AMAgent.properties.


com.sun.am.log.level

The level at which logs are written in the format: 

all:#

where # is the level 5 being the highest, 3 medium and 1 the lowest. More information can be found in AMAgent.properties.

com.sun.am.sslcert.dir

Path to the directory containing the certificate and key databases for Secure Sockets Layer (SSL). 

com.sun.am.certdb.prefix

Set this property if the certificate databases in the directory specified by com.sun.am.sslcert.dir has a prefix.

com.sun.am.certDBPassword=

 

The password to the key3.db file.


Note –

This property may be added to AMAgent.properties.


com.sun.am.trust_server_certs

Defines whether or not to trust SSL certificates not defined in the certificate database. Takes a value of true or false where true enables trust.

com.sun.am.auth.certificateAlias=

 

The nick name of the client certificate in the cert7.db.


Note –

This property may be added to AMAgent.properties.


com.sun.am.auth.org.name

The Access Manager organization desired for authentication. The value is the root suffix of the organization using domain-component (dc) as in: 

dc=sun,dc=com


Note –

This property may be added to AMAgent.properties.


Authentication Data Types

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

am_auth_context_t

Pointer to the authentication context object representing the details of an authentication action.

Syntax

#include "am_auth.h"
typedef struct am_auth_context *am_auth_context_t;

Members

am_auth_context is an opaque structure with no accessible members.

Memory Concerns

The implementation takes care of creating memory.

am_auth_callback_t

Primary callback type for authentication.

Details

am_auth_callback_t interacts with the calling application, allowing for the retrieval of specific authentication data (such as user name and password), or the display of error, warning or informational messages. It does not technically retrieve or display the information but provides the means to pass requests between an application and the Access Manager Authentication Service. struct am_auth_callback is a C implementation of the Java javax.security.auth.callback package. The Java API Reference for this package can be found at http://java.sun.com/j2se/1.5.0/docs/api/.

Syntax

#include "am_auth.h"
typedef struct am_auth_callback {
    am_auth_callback_type_t callback_type;
    union am_auth_callback_info {
        am_auth_choice_callback_t choice_callback;
        am_auth_confirmation_callback_t confirmation_callback;
        am_auth_language_callback_t language_callback;
        am_auth_name_callback_t name_callback;
        am_auth_password_callback_t password_callback;
        am_auth_text_input_callback_t text_input_callback;
        am_auth_text_output_callback_t text_output_callback;
    } callback_info;
} am_auth_callback_t;

Members

callback_type

Indicates the kind of callback that will be used. Each callback_type has a defined structure with a response field to submit authentication credentials. The value of callback_type determines the member of the union defined for the callback_info member. The possible values are defined in the enumeration:

typedef enum am_auth_callback_type {
    ChoiceCallback = 0,
    ConfirmationCallback,
    LanguageCallback,
    NameCallback,
    PasswordCallback,
    TextInputCallback,
    TextOutputCallback
} am_auth_callback_type_t;

Note –

Each callback_type corresponds to the callback class of the same name in the Java javax.security.auth.callback package. The Java API Reference for this package can be found at http://java.sun.com/j2se/1.5.0/docs/api/.


callback_info

Represents the defined callback_type. More information on the specific callbacks can be found in Authentication Callback Data Types.

Memory Concerns

Memory for the callback members is allocated in the am_auth_login() call, and freed in the am_auth_destroy_auth_context() call. Memory for the response field, though, must be allocated and freed by the caller.

am_auth_locale_t

Data type that holds the attributes that define the locale retrieved in am_auth_language_callback_t.

Details

For more information, see am_auth_language_callback_t.

Syntax

#include "am_auth.h"
typedef struct am_auth_locale {
    const char *language;
    const char *country;
    const char *variant;
} am_auth_locale_t;

Members

language

Pointer to a valid lower case, two-character ISO—639 language code as defined at http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt.

country

Pointer to a valid upper case, two-character ISO—3166 country code as defined at http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html.

variant

Pointer to a vendor or browser-specific character code. For example, WIN for Windows, MAC for Macintosh, and POSIX for POSIX.

Authentication Callback Data Types

This section contains further details on the callback types as discussed in am_auth_callback_t. They are:


Note –

Each type corresponds to the callback class of the same name in the Java javax.security.auth.callback package. The Java API Reference for this package can be found at http://java.sun.com/j2se/1.5.0/docs/api/.


am_auth_choice_callback_t

Displays a list of choices and submits the selection back to the Access Manager Authentication Service.

Details

am_auth_choice_callback_t is a C implementation of the Java javax.security.auth.callback.ChoiceCallback class.

Syntax

#include "am_auth.h"
typedef struct am_auth_choice_callback {
    const char *prompt;
    boolean_t allow_multiple_selections;
    const char **choices;
    size_t choices_size;
    size_t default_choice;
    const char **response; /* selected indexes */
    size_t response_size;
} am_auth_choice_callback_t;

Members

prompt

Pointer to the user's prompt.

allow_multiple_selections

Takes a value based on the boolean_t defined in the <am_types.h> header file. Set to B_TRUE if multiple selections can be made.

choices

Pointer to a pointer to the strings for the different choices.

choices_size

Value based on the size_t defined in the standard <stddef.h> header file that reflects the number of choices in the list.

default_choice

Takes a value based on the size_t defined in the standard <stddef.h> header file that reflects the choice selected by default when the list is displayed.

response

Pointer to a pointer to the choice(s) returned to Access Manager.

response_size

Takes a value based on the size_t defined in the standard <stddef.h> header file that reflects the number of selected choices in the response.

Memory Concerns

Memory for the choices list is allocated by am_auth_login(), and freed by calling am_auth_destroy_auth_context(). Memory for the response must be allocated and freed by the caller.

am_auth_confirmation_callback_t

Requests YES/NO, OK/CANCEL, YES/NO/CANCEL or similar confirmations.

Details

am_auth_confirmation_callback_t is a C implementation of the Java javax.security.auth.callback.ConfirmationCallback class.

Syntax

#include "am_auth.h"
typedef struct am_auth_confirmation_callback_info {
    const char *prompt;
    const char *message_type;
    const char *option_type;
    const char **options;
    size_t options_size;
    const char *default_option;
    const char *response; /* selected index */
} am_auth_confirmation_callback_t;

Members

prompt

Pointer to the user's prompt.

message_type

Pointer to the message type defined as INFORMATION, WARNING or ERROR.

option_type

Pointer to the option type defined as YES_NO_OPTION, YES_NO_CANCEL_OPTION, OK_CANCEL_OPTION, or UNSPECIFIED.

options

Pointer to a pointer to a list of confirmation options, or NULL if the callback was instantiated with an option_type.

options_size

Takes a value based on the size_t defined in the standard <stddef.h> header file that reflects the number of options in the list.

default_option

Pointer to the option selected by default when the list is displayed.

response

Pointer to the choice returned to Access Manager.

Memory Concerns

Memory is allocated by am_auth_login(), and freed by calling am_auth_destroy_auth_context(). Memory for the response must be allocated and freed by the caller.

am_auth_language_callback_t

Retrieves the locale for localizing text.

Details

am_auth_language_callback_t is a C implementation of the Java javax.security.auth.callback.LanguageCallback class.


Note –

See am_auth_locale_t for the individual components.


Syntax

#include "am_auth.h"
typedef struct am_auth_language_callback_info {
    am_auth_locale_t *locale;
    am_auth_locale_t *response; /* locale */
} am_auth_language_callback_t;

Members

locale

Pointer to the am_auth_locale_t object defining the locale.

response

Pointer to the am_auth_locale_t object being submitted back to Access Manager.

Memory Concerns

Memory is allocated by am_auth_login(), and freed by calling am_auth_destroy_auth_context(). Memory for the response must be allocated and freed by the caller.

am_auth_name_callback_t

Retrieves user name information.

Details

am_auth_name_callback_t is a C implementation of the Java javax.security.auth.callback.NameCallback class.

Syntax

#include "am_auth.h"
typedef struct am_auth_name_callback_info {
    const char *prompt;
    const char *default_name;
    const char *response; /* name */
} am_auth_name_callback_t;

Members

prompt

Pointer to the user's prompt.

default_name

Pointer to the default name displayed with the user prompt, if any.

response

Pointer to the name submitted back to Access Manager.

Memory Concerns

Memory is allocated by am_auth_login(), and freed by calling am_auth_destroy_auth_context(). Memory for the response must be allocated and freed by the caller.

am_auth_password_callback_t

Retrieves user password information.

Details

am_auth_password_callback_t is a C implementation of the Java javax.security.auth.callback.PasswordCallback class.

Syntax

#include "am_auth.h"
typedef struct am_auth_password_callback_info {
    const char *prompt;
    boolean_t echo_on;
    const char *response; /* password */
} am_auth_password_callback_t;

Members

prompt

Pointer to the user's prompt.

echo_on

Takes a value based on the boolean_t defined in the <am_types.h> header file. Set to B_TRUE to display the password as it is typed.

response

Pointer to the password submitted back to Access Manager.

Memory Concerns

Memory is allocated by am_auth_login(), and freed by calling am_auth_destroy_auth_context(). Memory for the response must be allocated and freed by the caller.

am_auth_text_input_callback_t

Retrieves generic textual information.

Details

am_auth_text_input_callback_t is a C implementation of the Java javax.security.auth.callback.TextInputCallback class.

Syntax

#include "am_auth.h"
typedef struct am_auth_text_input_callback_info {
    const char *prompt;
    const char *default_text;
    const char *response; /* text */
} am_auth_text_input_callback_t;

Members

prompt

Pointer to the user's prompt.

default_text

Pointer to the default text to be displayed with the user prompt.

response

Pointer to the text submitted back to Access Manager.

Memory Concerns

Memory is allocated by am_auth_login(), and freed by calling am_auth_destroy_auth_context(). Memory for the response must be allocated and freed by the caller.

am_auth_text_output_callback_t

Displays information messages, warning messages, and error messages.

Details

am_auth_text_output_callback_t is a C implementation of the Java javax.security.auth.callback.TextOutputCallback class.

Syntax

#include "am_auth.h"
typedef struct am_auth_text_output_callback_info {
    const char *message;
    const char *message_type;
} am_auth_text_output_callback_t;

Members

message

Pointer to the message to be displayed.

message_type

Pointer to the message type: INFORMATION, WARNING, or ERROR.

Memory Concerns

Memory is allocated by am_auth_login(), and freed by calling am_auth_destroy_auth_context().

Authentication Functions

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

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 AMAgent.properties file.

cert_nick_name

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

url

Pointer to the Access Manager Naming Service URL. May be NULL to use the Naming Service URL defined in the AMAgent.properties file.

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 Access Manager 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 Authentication Module Types in Sun Java System Access Manager 7.1 Administration Guide for more 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 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.