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.