Contained WithinFind More DocumentationFeatured Support Resources |  Descargar este libro en PDF (1531 KB)
Chapter 2 Authentication Data Types and FunctionsSun 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: The Authentication API for CC 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. Authentication Call SequenceThe 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. Note – 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. Authentication PropertiesWith 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. Note – 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
Authentication Data TypesThe authentication types defined in <am_auth.h> are: am_auth_context_tPointer 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; Membersam_auth_context is an opaque structure with no accessible members. Memory ConcernsThe implementation takes care of creating memory. am_auth_callback_tPrimary callback type for authentication. Detailsam_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/. 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
Memory ConcernsMemory 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_tData type that holds the attributes that define the locale retrieved in am_auth_language_callback_t. DetailsFor 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
Authentication Callback Data TypesThis 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_tDisplays a list of choices and submits the selection back to the OpenSSO Enterprise Authentication Service. Detailsam_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
Memory ConcernsMemory 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_tRequests YES/NO, OK/CANCEL, YES/NO/CANCEL or similar confirmations. Detailsam_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
Memory ConcernsMemory 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_tRetrieves the locale for localizing text. Detailsam_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
Memory ConcernsMemory 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_tRetrieves user name information. Detailsam_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
Memory ConcernsMemory 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_tRetrieves user password information. Detailsam_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
Memory ConcernsMemory 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_tRetrieves generic textual information. Detailsam_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
Memory ConcernsMemory 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_tDisplays information messages, warning messages, and error messages. Detailsam_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
Memory ConcernsMemory is allocated by am_auth_login(), and freed by calling am_auth_destroy_auth_context(). Authentication FunctionsThe 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); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
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);
ParametersThis function takes the following parameters:
ReturnsThis 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_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); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
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);
ParametersThis function takes the following parameters:
ReturnsThis 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. DetailsModule 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);
ParametersThis function takes the following parameters:
ReturnsThis 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):
Memory ConcernsThe 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); ParametersThis function takes the following parameter:
ReturnsThis function returns a pointer with one of the following values:
am_auth_get_sso_token_id()Retrieves the session identifier for the authenticated user. DetailsThe 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); ParametersThis function takes the following parameter:
ReturnsThis function returns a pointer with one of the following values:
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); ParametersThis function takes the following parameter:
ReturnsThis 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_has_more_requirements()Checks to see if there are additional requirements needed to complete the login process. Detailsam_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); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
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); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
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);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
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); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
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); ParametersThis function takes the following parameters:
ReturnsThis 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); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
|
||||||||||||||||||
|