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.

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.

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:

AccessManager-base/SUNWam/docs

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:

• A means of producing valid XML compliant with the remote-auth.dtd .

• HTTP 1.1 compliant client implementation to send XML-configured information to Access Manager.

• HTTP 1.1 compliant server implementation to receive XML-configured information from Access Manager.

• An XML parser to interpret the data received from Access Manager.

Examples of XML Messages

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

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>
</IndexTypeNamePair></Login></Request></AuthContext>

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
cqcaN1uW+C7CMdeR2afoN1ZxwY=@AAJTSQACMDE=#">
<GetRequirements><Callbacks length="3">
<PagePropertiesCallback isErrorState="false"><ModuleName>LDAP</ModuleName>
<HeaderValue>This server uses LDAP Authentication</HeaderValue>
<ImageName></ImageName><PageTimeOutValue>120</PageTimeOutValue>
<TemplateName></TemplateName>
<PageState>1</PageState>
</PagePropertiesCallback>
<NameCallback><Prompt> User Name: </Prompt></NameCallback>
<PasswordCallback echoPassword="false"><Prompt> Password: </Prompt>
</PasswordCallback></Callbacks></GetRequirements></Response></AuthContext>

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
N1uW+C7CMdeR2afoN1ZxwY=@AAJTSQACMDE=#">
<SubmitRequirements><Callbacks length="2"><NameCallback><Prompt>User Name:</Prompt>
<Value>amadmin</Value>
</NameCallback>
<PasswordCallback echoPassword="false"><Prompt>Password:</Prompt>
<Value>admin123</Value>
</PasswordCallback></Callbacks></SubmitRequirements></Request></AuthContext>

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+
C7CMdeR2afoN1ZxwY=@AAJTSQACMDE=#">
<LoginStatus status="success" ssoToken="AQIC5wM2LY4SfczGP8Kp9cqcaN1uW+C7CMdeR2afoN1
ZxwY=@AAJTSQACMDE=#" successURL="http://blitz.red.iplanet.com/amserver/console">
<Subject>AQICOIy3FdTlJoAiOyyyZRTjOVBVWAb2e5MOAizI7ky3raaKypFE3e+GGZuX6chvLgDO32Zugn
pijo4xW4wUzyh2OAcdO9r9zhMU2Nhm206IuAmz9m18JWaYJpSHLqtBEcf1GbDrm3VAkERzIqsvkLKHmS1qc
yaT3BJ87wH0YQnPDze4/BroBZ8N5G3mPzPz5RbE07/1/w02yH9w0+UUFwwNBLayywGsr3bJ6emSSYqxos1N
1bo98xqL4FKAzItsfUAMd6v0ylWoqkoyoSdKYNHKbqvLDIeAfhqgoldxt64Or6HMXnOxz/jiVauh2mmwBpH
q1H2mOeF3agfUfuzKxBpLfELLwCH6QWcJmOZl0eNCFkGl7VwfnCJpTx1WcUhPSg0xD26D3dCQNruJpHPgzZ
FThe55M2gQ2qX+I1klmvzghSqiYfyoGg2SFeBeHE7iHuujO0e6UZgKDrOQPjU9aDh1GxxnsMQmaNkjuW+up
ghruWBGy+mDWmPQTme2bQWPIjBgB4wTDXTedeDzDBeulhCH4M0Ak9lvS7EIv6kHX5pRph6d0ND4/RVHka3k
WcQ5e0w2HpPjOxzNrWMfyXTkQJwOrA8yh1eBjG04VwiVqDV4wAV5EsIsIt0TrtAW2VZwV/KtLcGmjaKaT0H
dwRy0M4DHEqDbc6jF5ItVo9NneGFXMswPIoLm2nLuMrteAt7AtK7FGuCHlfYLavKoROtjaSuYTJGFwgz8Oi
vZ2r9boVnWVlz7ehwlyHvdfmpSKVl76Y4qEclX25m+lddAZE92RgSIrg97fp9gBOk2gVJWoQORNRDV2siHr
26 RiPLdvW3foG0hZgpLimJuLdByThRd/tdknDCCNRzelv7khr6nLPVPFVBgEJWlHmuffkdz4OsL0omFWpi
Jq05sQCPs/q6rq9ZJ98a8mcFK10BVPQki/1VfkIbKAdO4eswsIMalYkglBqXT4ARVTWRCWRNMCTDlQitF3g
T51AHn1WioFPm+NZ2KagVjQR6JFxHbdW0bKN7cLQViArJJFRtktR1BJh31/K+dAM2P+KbT1Lq13UUvXCynS
QwVbf7HJP5m3XrIQ6PtgZs4TB026H+iKy5T85YNL03j9sNnALiIKJEgvGLg2jxG+SU10xNLz3P3UVqmAnQI
9FIjmCtJcFtlLYR6BbkTvZVKxWz6+SoxNfDeKhIDwxkTNTLOzK491KzU/XAZTKmvdxTgf+WikbriBhFjsJ4
M6Npsq4p9Ksrjun9FVBTE/EUT5X/bY8zXLm0nw5KspQ7XRHPwrppQMVMMekz5qrNtQ9Cw/TeOhm4jvww/Bz
j4rydi7s7D10s2BWMfcuxmwQEipAWNmraKL37wWskrCdAzO2HXH4iJjWimiJ6J</Subject>
</LoginStatus></Response></AuthContext>

How the Authentication SPIs Work

• Extending the AMLoginModule Class

• Pluggable JAAS Module

• Authentication Post Processing

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.

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 http://java.sun.com/products/jaas/.

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.

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:

• Adding attributes to a user’s session after successful authentication

• Sending notification to an administrator after failed authentication

• General clean-up such as clearing cookies after logout or logging out of other system components.

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:

• onLoginSuccess

• onLoginFailure

• onLogout

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:

AccessManager-base/SUNWam/docs

onLoginSuccess

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;

where

• requestParamaMap is a map containing HttpServletRequest parameters

• request HttpServletRequest object

• response HttpServletResponse object

  com.sun.identity.authentication.spi.AuthenticationException is thrown on error.

onLoginFailure

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;

where

• requestMap is a map containing HttpServletRequest parameters

• request HttpServletRequest object

• response HttpServletRequest object

  com.sun.identity.authentication.spi.AuthenticationException is thrown on error.

onLogout

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;

where

• request HttpServletRequest object is a map containing HttpServletRequest parameters

• response HttpServletResponse object

• ssoToken authenticated user’s single sign on token

  com.sun.identity.authentication.spi AuthenticationException is thrown on error.