Sun OpenSSO Enterprise 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 interfaces (API). Reference summaries include a short description, syntax, parameters and returns. Prototypes are contained in the <am_auth.h> header file located in the opensso/libraries/native/agent-csdk/is_csdk/include directory (when opensso.war is exploded on Solaris/SPARC). The sample source am_auth_test.c demonstrates the basic usage of the API to login to an instance of OpenSSO Enterprise. This chapter contains the following sections:
C applications can authenticate users with the OpenSSO Enterprise 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 OpenSSO Enterprise 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 a realm 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 OpenSSO Enterprise 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. 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 1, Using the Authentication Service API and SPI, in Sun OpenSSO Enterprise 8.0 Developer’s Guide.
With the newly developed policy agents 3.0, AMAgent.properties has been replaced with OpenSSOAgentBootstrap.properties and OpenSSOAgentConfiguration.properties. Properties in OpenSSOAgentBootstrap.properties are mandatory for any C API to work. Properties in OpenSSOAgentConfiguration.properties will only be used if the repository type of the agent user is local. If the repository type is centralized, any required properties not in OpenSSOAgentBootstrap.properties will be retrieved from the OpenSSO Enterprise server.
See Centralized Agent Configuration in Sun OpenSSO Enterprise 8.0 Technical Overview for more information.
The following table lists the mandatory properties in OpenSSOAgentBootstrap.properties.
Table 2–1 Policy Agent 3.0 Properties Needed by the Authentication API for C
Property |
Definition |
---|---|
com.sun.identity.agents.config.naming.url |
URL of the OpenSSO Enterprise Naming Service in the format: http://server.domain:port/URI/namingservice |
com.sun.identity.agents.config.local.logfile |
The logging directory in the format: path-to-directory/logs/auth-log |
com.sun.identity.agents.config.debug.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. |
com.sun.identity.agents.config.sslcert.dir |
Path to the directory containing the certificate and key databases for Secure Sockets Layer (SSL). |
com.sun.identity.agents.config.certdb.prefix |
Set this property if the certificate databases in the directory specified by com.sun.identity.agents.config.sslcert.dir has a prefix. |
com.sun.identity.agents.config.certdb.password |
The password to the key3.db file. Note – This property may be added to OpenSSOAgentBootstrap.properties. |
com.sun.identity.agents.config.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.identity.agents.config.certificate.alias |
The nickname of the client certificate in the cert7.db. Note – This property may be added to OpenSSOAgentBootstrap.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 OpenSSO Enterprise 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 OpenSSO Enterprise 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 OpenSSO Enterprise.
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 OpenSSO Enterprise.
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 OpenSSO Enterprise.
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 OpenSSO Enterprise.
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 OpenSSO Enterprise.
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 OpenSSO Enterprise.
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 agent configuration properties.
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.
Pointer to the OpenSSO Enterprise Naming Service URL. May be NULL to use the Naming Service URL defined in the agent configuration properties.
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 OpenSSO Enterprise 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 Sun OpenSSO Enterprise 8.0 Administration Guide for more information on authentication modules.
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.