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:
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.
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.
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.
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.
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.
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. |
The authentication types defined in <am_auth.h> are:
Pointer to the authentication context object representing the details of an authentication action.
#include "am_auth.h" typedef struct am_auth_context *am_auth_context_t;
am_auth_context is an opaque structure with no accessible members.
The implementation takes care of creating memory.
Primary callback type for authentication.
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/.
#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;
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;
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/.
Represents the defined callback_type. More information on the specific callbacks can be found in Authentication Callback Data Types.
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.
Data type that holds the attributes that define the locale retrieved in am_auth_language_callback_t.
For more information, see am_auth_language_callback_t.
#include "am_auth.h" typedef struct am_auth_locale { const char *language; const char *country; const char *variant; } am_auth_locale_t;
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.
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.
Pointer to a vendor or browser-specific character code. For example, WIN for Windows, MAC for Macintosh, and POSIX for POSIX.
This section contains further details on the callback types as discussed in am_auth_callback_t. They are:
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/.
Displays a list of choices and submits the selection back to the Access Manager Authentication Service.
am_auth_choice_callback_t is a C implementation of the Java javax.security.auth.callback.ChoiceCallback class.
#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;
Pointer to the user's prompt.
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.
Pointer to a pointer to the strings for the different choices.
Value based on the size_t defined in the standard <stddef.h> header file that reflects the number of choices in the list.
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.
Pointer to a pointer to the choice(s) returned to Access Manager.
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 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.
Requests YES/NO, OK/CANCEL, YES/NO/CANCEL or similar confirmations.
am_auth_confirmation_callback_t is a C implementation of the Java javax.security.auth.callback.ConfirmationCallback class.
#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;
Pointer to the user's prompt.
Pointer to the message type defined as INFORMATION, WARNING or ERROR.
Pointer to the option type defined as YES_NO_OPTION, YES_NO_CANCEL_OPTION, OK_CANCEL_OPTION, or UNSPECIFIED.
Pointer to a pointer to a list of confirmation options, or NULL if the callback was instantiated with an option_type.
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.
Pointer to the option selected by default when the list is displayed.
Pointer to the choice returned to Access Manager.
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.
Retrieves the locale for localizing text.
am_auth_language_callback_t is a C implementation of the Java javax.security.auth.callback.LanguageCallback class.
See am_auth_locale_t for the individual components.
#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;
Pointer to the am_auth_locale_t object defining the locale.
Pointer to the am_auth_locale_t object being submitted back to Access Manager.
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.
Retrieves user name information.
am_auth_name_callback_t is a C implementation of the Java javax.security.auth.callback.NameCallback class.
#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;
Pointer to the user's prompt.
Pointer to the default name displayed with the user prompt, if any.
Pointer to the name submitted back to Access Manager.
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.
Retrieves user password information.
am_auth_password_callback_t is a C implementation of the Java javax.security.auth.callback.PasswordCallback class.
#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;
Pointer to the user's prompt.
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.
Pointer to the password submitted back to Access Manager.
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.
Retrieves generic textual information.
am_auth_text_input_callback_t is a C implementation of the Java javax.security.auth.callback.TextInputCallback class.
#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;
Pointer to the user's prompt.
Pointer to the default text to be displayed with the user prompt.
Pointer to the text submitted back to Access Manager.
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.
Displays information messages, warning messages, and error messages.
am_auth_text_output_callback_t is a C implementation of the Java javax.security.auth.callback.TextOutputCallback class.
#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;
Pointer to the message to be displayed.
Pointer to the message type: INFORMATION, WARNING, or ERROR.
Memory is allocated by am_auth_login(), and freed by calling am_auth_destroy_auth_context().
The authentication functions defined in <am_auth.h> are:
Aborts an authentication process that has not been completed.
#include "am_auth.h" AM_EXPORT am_status_t am_auth_abort(am_auth_context_t auth_ctx);
This function takes the following parameter:
The am_auth_context_t type.
See am_auth_context_t for information.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the process was successfully stopped.
If the auth_ctx parameter is NULL.
Creates the context for the authentication and a pointer to it.
#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 am_auth_context_t type.
See am_auth_context_t for information.
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.
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.
Pointer to the Access Manager Naming Service URL. May be NULL to use the Naming Service URL defined in the AMAgent.properties file.
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):
If the authentication context was successfully created.
If unable to allocate memory for the handle.
If the auth_ctx parameter is NULL.
If the authentication initialization failed.
Eliminates the specified authentication context.
#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:
The am_auth_context_t type.
See am_auth_context_t for information.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the pointer was successfully destroyed.
If the auth_ctx parameter is NULL.
Retrieves the appropriate callback structure to populate with authentication requirements.
#include "am_auth.h" AM_EXPORT am_auth_callback_t * am_auth_get_callback(am_auth_context_t auth_ctx, size_t index);
This function takes the following parameters:
The am_auth_context_t type.
See am_auth_context_t for information.
Takes a value based on size_t defined in the standard <stddef.h> header file that initializes the index into the callback array.
This function returns a pointer to the am_auth_callback_t type. See am_auth_callback_t for more information.
Retrieves the authentication module plug-in instances configured for the organization (or sub-organization) defined in the am_auth_context_t type.
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).
#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:
The am_auth_context_t type.
See am_auth_context_t for information.
Pointer to a pointer to the am_string_set_t type.
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):
If the submitted requirements were processed successfully.
If the authentication process failed.
If the auth_ctx parameter is NULL.
If the Access Manager Authentication Service is not initialized.
The implementation takes care of allocating memory for the module_inst_names_ptr.
Retrieves 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:
The am_auth_context_t type.
See am_auth_context_t for information.
This function returns a pointer with one of the following values:
After the user successfully logs in.
If there was an error or the user has not successfully logged in.
Retrieves the session identifier for the authenticated user.
The SSOTokenID is a randomly-generated string that represents an authenticated user. See Single Sign-on Token Handles for more information.
#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:
The am_auth_context_t type.
See am_auth_context_t for information.
This function returns a pointer with one of the following values:
After the user successfully logs in.
If there was an error or the user has not successfully logged in.
Retrieves the state of the authentication process.
#include "am_auth.h" AM_EXPORT am_auth_status_t am_auth_get_status(am_auth_context_t auth_ctx);
This function takes the following parameter:
The am_auth_context_t type.
See am_auth_context_t for information.
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;
The login process has failed.
The login process has not started.
The login is in progress.
The user has been logged out.
The user has logged in.
Checks to see if there are additional requirements needed to complete the login process.
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.
#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:
The am_auth_context_t type.
See am_auth_context_t for information.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If there are more requirements.
If there are no more requirements.
Initializes the authentication module using the pointer returned by am_auth_create_auth_context().
#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 am_properties_t type which contains the module initialization properties.
See am_properties_t for information.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the initialization of the library is successful.
If unable to allocate memory during initialization.
If auth_init_params is NULL.
See am_status_t.
Begins 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:
The am_auth_context_t type.
See am_auth_context_t for information.
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;
Pointer to the authentication module being used.
See Authentication Module Types in Sun Java System Access Manager 7.1 Administration Guide for more information.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
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:
The am_auth_context_t type.
See am_auth_context_t for information.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the logout process was successfully completed.
If the auth_ctx parameter is NULL.
Retrieves 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:
The am_auth_context_t type.
See am_auth_context_t for information.
This function returns a value based on the size_t defined in the standard <stddef.h> header file that reflects the number of callbacks.
Passes the responses populated in the callbacks to the Authentication Service.
#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:
The am_auth_context_t type.
See am_auth_context_t for information.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the submitted requirements were processed successfully.
If the authentication process failed.
If the auth_ctx parameter is NULL.