Sun Java System Access Manager 7.1 Developer's Guide

Overview of Authentication APIs and SPIs

Access Manager provides both Java APIs and C APIs for writing authentication clients that remote applications can use to gain access to the Authenticate Service. This communication between the APIs and the Authentication Service occurs by sending XML messages over HTTP(S). The remote-auth.dtd is the template used in formatting the XML request messages sent to Access Manager and for parsing the XML return messages received by the external application. You can access remote-auth.dtd in the directory AccessManager-base /SUNWam/dtd.

New authentication modules are added to Access Manager by using the com.iplanet.authentication.spi package. The SPI implements the JAAS LoginModule, and provides additional methods to access the Authentication Service and module configuration properties files. Because of this architecture, any custom JAAS authentication module will work within the Authentication Service.

Note –

If contacting the Authentication Service directly through its URL http://AcceessManager-HostName.domain_name:port /service_deploy_uri/authservice without the API, a detailed understanding of remote-auth.dtd will be needed for generating and interpreting the messages passed between the client and server.

How the Authentication Java APIs Work

External Java applications can authenticate users with the Access Manager Authentication Service by using the Authentication Java APIs. The APIs are organized in a package called com.sun.identity.authentication and can be executed locally or remotely. The classes and methods defined in this package are used to initiate the authentication process and communicate authentication credentials to the specific modules within the Authentication Service. The classes and methods can be incorporated into a Java application to allow communication with the Authentication Service.

The first step necessary for an external Java application to authenticate to Access Manager is to create a new AuthContext object (com.sun.identity.authentication.AuthContext). The AuthContext class is defined for each authentication request as it initiates the authentication process. Since Access Manager can handle multiple organizations, AuthContext is initialized, at the least, with the name of the organization to which the requestor is authenticating. Once an AuthContext object has been created, the login() method is called indicating to the server what method of authentication is desired.

IndexName is the value of the authentication type. The following table summarizes IndexName values and their corresponding authentication types.

Table 2–1 IndexName Values

IndexName Value

Authentication Type 








Authentication Level-based 



The getRequirements() method then calls the objects that will be populated by the user. Depending on the parameters passed with the instantiated AuthContext object and the two method calls, Access Manager responds to the client request with the correct login requirement screens. For example, if the requested user is authenticating to an organization configured for LDAP authentication only, the server will respond with the LDAP login requirement screen to supply a user name and a password. The client must then loop by calling the hasMoreRequirements() method until the required credentials have been entered. Once entered, the credentials are submitted back to the server with the method call submitRequirements() . The final step is for the client to make a getStatus() method call to determine if the authentication was successful. If successful, the caller obtains a session token for the user; if not, a LoginException is thrown.

Because the Authentication Service is built on the JAAS framework, the Authentication API can also invoke any authentication modules written purely with the JAAS API.

For detailed information about Java APIs for authentication, see the Javadoc in the following directory:


XML/HTTP Interface for Other Applications

Applications written in a programming language other than Java or C can exchange authentication information with Access Manager using the XML/HTTP(s) interface. Using the URL http://server_name.domain_name :port/service_deploy_uri /authservice, an application can open a connection using the HTTP POST method and exchange XML messages with the Authentication Service. The structure of the XML messages is defined in remote-auth.dtd. In order to access the Authentication Service in this manner, the client application must contain the following:

Examples of XML Messages

The following code examples illustrate how customers might configure the XML messages posted to the Authentication Service.

Note –

Although the client application need only write XML based on the remote-auth.dtd, when these messages are sent they include additional XML code produced by the Authentication API. This additional XML code is not illustrated in the following examples.

The following example illustrates the initial XML message sent to the Access Manager. It opens a connection and asks for authentication requirements regarding the exampleorg organization to which the user will login.

Example 2–1 Initial AuthContext XML Message

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0"><Request authIdentifier="0">
<Login orgName="dc=red,dc=iplanet,dc=com">
<IndexTypeNamePair indexType="moduleInstance"><IndexName>LDAP</IndexName>

The following example illustrates the successful response from Access Manager that contains the authIdentifier, the session identifier for the initial request.

Example 2–2 AuthIdentifier XML Message Response

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0"><Response authIdentifier="AQIC5wM2LY4SfczGP8Kp9
<GetRequirements><Callbacks length="3">
<PagePropertiesCallback isErrorState="false"><ModuleName>LDAP</ModuleName>
<HeaderValue>This server uses LDAP Authentication</HeaderValue>
<NameCallback><Prompt> User Name: </Prompt></NameCallback>
<PasswordCallback echoPassword="false"><Prompt> Password: </Prompt>

The following example illustrates the client response message back to Access Manager. It specifies the type of authentication module needed by the user to log in.

Example 2–3 Second Request Message With Authentication Module Specified

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0"><Request authIdentifier="AQIC5wM2LY4SfczGP8Kp9cqca
<SubmitRequirements><Callbacks length="2"><NameCallback><Prompt>User Name:</Prompt>
<PasswordCallback echoPassword="false"><Prompt>Password:</Prompt>

The following example illustrates the return message from Access Manager which specifies the authentication module’s login requirements.

Example 2–4 Return XML Message With Login Callbacks

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0"><Response authIdentifier="AQIC5wM2LY4SfczGP8Kp9cqcaN1uW+
<LoginStatus status="success" ssoToken="AQIC5wM2LY4SfczGP8Kp9cqcaN1uW+C7CMdeR2afoN1
ZxwY=@AAJTSQACMDE=#" successURL="">
26 RiPLdvW3foG0hZgpLimJuLdByThRd/tdknDCCNRzelv7khr6nLPVPFVBgEJWlHmuffkdz4OsL0omFWpi

How the Authentication SPIs Work

Access Manager provides the capability to plug new, Java-based authentication modules into its framework allowing proprietary authentication providers to be managed using the Access Manager console. A custom authentication module must first be created using Java. Once created, the custom module can be added to the list of available authentication modules.

Note –

This guide does not document the JAAS. For more information on these APIs, see the Java Authentication And Authorization Service Developer’s Guide. Additional information can be found at

Extending the AMLoginModule Class

Custom authentication modules extend the com.sun.identity.authentication.spi.AMLoginModule class. The class must also implement the init(), process() and getPrincipal() methods in order to communicate with the authentication module configuration files. The callbacks are then dynamically generated based on this file. Other methods that can be defined include setLoginFailureURL and setLoginSuccessURL which defines URLs to send the user to based on a failed or successful authentication, respectively.

Note –

To make use of the account locking feature with custom authentication modules, the InvalidPasswordException exception should be thrown when the password is invalid.

Pluggable JAAS Module

The Java Authentication and Authorization Service (JAAS) is a set of APIs that enable services to authenticate and enforce access controls upon users. It implements a Java technology version of the standard Pluggable Authentication Module (PAM) framework, and supports user-based authorization. Access Manager supports pure JAAS pluggable authentication modules. In Access Manager, pure JAAS modules extend the JAAS LoginModule rather than AMLoginModule. A pure JAAS module is plugged in to the Authentication framework using the Authentication API.

Authentication Post Processing

The Authentication SPI includes the AMPostAuthProcessInterface which can be implemented for post-processing tasks. The following are examples of post-processing tasks:

The Core Authentication Service contains the Authentication PostProcessing Class attribute which contains the authentication post-processing class name as its value. Custom post processing interfaces can also be implemented.

AMPostAuthProcessInterface can be implemented for post authentication processing on authentication success, failure and logout. The SPI is configurable at the organization , service and role levels. The Authentication Service invokes the post processing SPI methods on successful, failed authentication and logout.

The AMPostProcessInterface class has 3 methods:

Some supporting information on these methods is provided in the following sections. For a comprehensive listing and detailed information on all Access Manager methods, see the Javadoc installed in the following directory:



This method should be implemented for post-processing after a successful authentication. Authentication Service will invoke this method on successful authentication.

Method signature is:

 public void onLoginSuccess(Map requestParamsMap,
                               HttpServletRequest request,
                               HttpServletResponse response,
                               SSOToken ssoToken)
     throws AuthenticationException;



This method should be implemented for post processing after a failed authentication. Authentication Service will invoke this method on failed authentication.

Method signature is:

 public void onLoginFailure(Map requestParamsMap,
                             HttpServletRequest request,
                             HttpServletResponse response)
    throws AuthenticationException;



This method should be implemented for post-processing on a logout request. Authentication Service will invoke this method on logout.

Method signature is:

 public void onLogout(HttpServletRequest request,
                       HttpServletResponse response,
                      SSOToken ssoToken)
    throws AuthenticationException;