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.

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.