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 5–1 Initial AuthContext XML Message

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Request authIdentifier="0">
<NewAuthContext orgName="dc=exampleorg,dc=com">
</NewAuthContext>
</Request>
</AuthContext>


               

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

Example 5–2 AuthIdentifier XML Message Response

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<LoginStatus status="in_progress">
</LoginStatus>
</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 5–3 Second Request Message With Authentication Module Specified

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Request authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<Login>
<IndexTypeNamePair indexType="moduleInstance">
<IndexName>LDAP</IndexName>
</IndexTypeNamePair>
</Login>
</Request>
</AuthContext>


               

The following example illustrates the return message from Access Manager which specifies the authentication module’s login requirements. In this case, the LDAP requirements include a user name and password. Note the page time out value of 120 seconds.

Example 5–4 Return XML Message With Login Callbacks

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">

<GetRequirements>
<Callbacks length="3">
<PagePropertiesCallback isErrorState="false">
<ModuleName>LDAP</ModuleName>
<HeaderValue>This server uses LDAP Authentication</HeaderValue>
<ImageName></ImageName>
<PageTimeOut>120</PageTimeOut>
<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 responses to the call for login requirements. They specify amadmin as the user and 11111111 for the password.

Example 5–5 Response Message With Callback Values

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Request authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<SubmitRequirements>
<Callbacks length="3">

<NameCallback>
<Prompt>User Name:</Prompt>
<Value>amadmin</Value>
</NameCallback>

<PasswordCallback echoPassword="false">
<Prompt>Password:</Prompt>
<Value>11111111</Value>
</PasswordCallback>
</Callbacks>
</SubmitRequirements>
</Request>
</AuthContext>


               

The following example illustrates that a successful authentication has occurred. As the value of <Subject> uses the Java serialization, it can not be used by non-Java client applications. It’s value is retrieved by all applications from the session token.

Example 5–6 Successful Authentication XML Message

<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<LoginStatus status="success" ssoToken="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1o
Vb5esqDlkaY=" successURL="http://torpedo.red.iplanet.com:/amconsole">
<Subject>AQICweczOhuelZ5TqD9kKOtiAepxqGP23q4oTnNMuJY//lI2S4KD1/gEN84uLwDGHll
lyFSthxoKLM7NDHh2vwAvrDmpsomJvUnbqnJJ90DS+28njGiDv+lv8FqIVhhbxrctbiIUEOHYK0F
zXnXjPYizdCmiWXJ+9DJ8T2HbYIDxn9U6eVNAMPq3uVb/RFuErEm5MuPu7PnWeCic12SZre4ZEcw
8TI45NKNjd/NZZD97bcqL5gEV7SVHspFldZKmo9vA86aEkvMs9P53RiJtrusHN1FKt9+4JqSrdcV
LKMzJVAr3z5EohwHh9/hzd7hgucO661gz7IqkT7WEpve/E8R4em0mg3HgHg7Bg7i3AkyX6YSkoAn
cdVXMdmWnb7OV5cBgUjO8zs8Pp5/3dA1XlwACmOqjxshk6Y6Ld6TAQ90qRFwymC1RdLGGCRnrt33
kmYVyB1lJyJxT8utPKyDOEKFRHh57NlKTbFhBKc1IGcdQ2crHifpXawx6YouQgQSWGdsqW9IahY4
+lqbBTPnGDyZkKz9yy2ZKVjDR05Hwku8elvEwBE40XTJ3gF/mbwCGbh3cyprahLqRXboy8eoEQf3
ubQmR2My+bh+NrsRfzfFV5oCcpJE6DtvYE/4zO+uKk3FbG+/NUJzAAor920V/0prtYeS58ZPW8C7
qwXINaW0xdMQV+pgE3NZvMlp5GeZlSIMmSCtXD49n4tqopSlsoK+eiwPODKxp992+6/uJhhVHH5I
0Ozuy6CDM dCJDGvnMENVCUZvki3+tb92fqQbVWixM4Ca6Nnz3jTIKk2uhm559jq9hra8gHHOfnn
u4e5jZjzfRdkO3GodiTMOHDnQATHtvT1PBXgorTfUwUa4ZjptvzFulHSi4eQaqs4Z8FAX2OAr8XG
HRkhBwoxrhjYiCDBpkNmpEiFNhWnTT3bwkAUFhtoDg6836kwHfxeLXKAz3T6qyNQzT+larSXUxrt
/TIjwDPR3vg4GF4RzbHlWA1WQtUS/9Qe/N3aegEEEvxPvo9fWq
</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.