Sun Java System Access Manager 7.1 Administration Guide

Chapter 4 Managing Authentication

The Authentication Service provides a web-based user interface for all of the default authentication types installed in the Access Manager deployment. This interface provides a dynamic and customizable means for gathering authentication credentials by displaying the login requirement screens (based on the invoked authentication module) to a user requesting access. The interface is built using Sun Java System™ Application Framework (sometimes referred to as JATO), a Java 2 Enterprise Edition (J2EE) presentation framework used to help developers build functional web applications.

Configuring Authentication

This section describes how to configure authentication for your deployment. The first section outlines the default authentication module types and provides any necessary pre-configuration instructions. You can configure multiple configuration instances of the same authentication module type for realms, users, roles, and so forth. Additionally, you can add authentication chains so that authentication must pass the criteria for multiple instance before authentication is successful. This section includes:

Authentication Module Types

An authentication module is a plug-in that collects user information such as a user ID and password, and then checks the information against entries in a database. If a user provides information that meets the authentication criteria, then the user is granted access to the requested resource. If the user provides information that does not meet authentication criteria, the user is denied access to the requested resource. Access Manager is installed with the following types of authentication modules:

Note –

Some of the authentication module types require pre-configuration before they can be used as authentication instances. The configuration steps, if necessary, are listed in the module type descriptions.

Core

Access Manager provides, by default, fifteen different authentication modules, as well as a Core authentication module. The Core authentication module provides overall configuration for the authentication module. Before adding and enabling Active Directory, Anonymous, Certificate-based, HTTP Basic, JDBC, LDAP, any authentication module, the Core authentication must be added and enabled. Both the Core and LDAP Authentication modules are automatically enabled for the default realm.

Clicking the Advanced Properties button displays the Core authentication attributes that can be defined for the realm. The global attributes are not applicable to the realm so they are not displayed.

Active Directory

The Active Directory authentication module performs authentication in a similar manner to the LDAP module, but uses Microsoft’s Active Directory™ server (as opposed to Directory Server in LDAP authentication module). Although the LDAP authentication module can be configured for an Active Directory server, this module allows you have both LDAP and Active Directory authentication exist under the same realm.

Note –

For this release, the Active Directory authentication module only supports user authentication. Password policy is only supported in the LDAP authentication module.

Anonymous

By default, when this module is enabled, a user can log in to Access Manager as an anonymous user. A list of anonymous users can also be defined for this module by configuring the Valid Anonymous User List attribute. Granting anonymous access means that it can be accessed without providing a password. Anonymous access can be limited to specific types of access (for example, access for read or access for search) or to specific subtrees or individual entries within the directory.

Certificate

Certificate-based Authentication involves using a personal digital certificate (PDC) to identify and authenticate a user. A PDC can be configured to require a match against a PDC stored in Directory Server, and verification against a Certificate Revocation List.

There are a number of things that need to be accomplished before adding the Certificate-based Authentication module to a realm. First, the web container that is installed with the Access Manager needs to be secured and configured for Certificate-based Authentication.

Note –

If you are configuring Access Manager Certificate authentication with an SSL-enabled Sun Java System WebsServer 6.1 instance, and wish to have the WebServer defined to accept both certificate based and non certificate based authentication requests, you must set the following value in the WebServer's obj.conf file:

PathCheck fn="get-client-cert" dorequest="1" require="0"

This is due to a limitation in the WebServer console when setting the optional attribute for this behavior.

Before enabling the Certificate-based module, see Chapter 6, “Using Certificates and Keys” in the Sun ONE Web Server 6.1 Administrator’s Guide for these initial Web Server configuration steps. This document can be found at the following location:

http://docs.sun.com/db/prod/s1websrv#hic

Or, see the Sun ONE Application Server Administrator’s Guide to Security at http://docs.sun.com/source/816-7158-10/contents.html.

Note –

Each user that will authenticate using the certificate-based module must request a PDC for the user’s browser. Instructions are different depending upon the browser used. See your browser’s documentation for more information.

In order to add this module, you must log in to Access Manager as the realm Administrator and have Access Manager and the web container configured for SSL and with client authentication enabled. For more information, see Configuring Access Manager in SSL Mode in the Access Manager Post Installation Guide.

Data Store

The Data Store authentication module allows a login using the Identity Repository of the realm to authenticate users. Using the Data Store module removes the requirement to write an authentication plug- in module, load, and then configure the authentication module if you need to authenticate against the same data store repository. Additionally, you do not need to write a custom authentication module where flat-file authentication is needed for the corresponding repository in that realm.

This authentication type provides a degree of convenience when configuring Access Manager authentication. In releases prior to Access Manager 7.1, if you wanted users in an LDAPv3 data store to be able to authenticate to their realm, you had to:

Configure the LDAPv3 data store
Configure an LDAP authentication module instance to reference the same realm subjects

The Data Store authentication module lets users defined in the realm's identity repository authenticate. No LDAP authentication configuration is necessary. For example, suppose a realm's identity repository includes an LDAPv3 data store, and suppose the same realm uses data store authentication. In this case, any user defined in the identity repository could authenticate to that realm.

HTTP Basic

This module uses basic authentication, which is the HTTP protocol’s built-in authentication support. The web server issues a client request for username and password, and sends that information back to the server as part of the authorized request. Access Manager retrieves the username and password and then internally authenticates the user to the LDAP authentication module. In order for HTTP Basic to function correctly, the LDAP authentication module must be added (adding the HTTP Basic module alone will not work). Once the user successfully authenticates, the user will be able to re-authenticate without being prompted for username and password.

JDBC

The Java Database Connectivity (JDBC) Authentication module provides a mechanism to allow Access Manager to authenticate users through any SQL databases that provide JDBC technology-enabled drivers. The connection to the SQL database can be either directly through a JDBC driver, or a JNDI connection pool.

Note –

This module has been tested on MySQL4.0 and Oracle 8i.

LDAP

With the LDAP Authentication module, when a user logs in, the user is required to bind to the LDAP Directory Server with a specific user DN and password. This is the default authenticating module for all realm-based authentication. If the user provides a user ID and password that are in the Directory Server, the user is allowed access to, and is set up with, a valid Access Manager session. Both the Core and LDAP Authentication modules are automatically enabled for the default realm

Membership

Membership authentication is implemented similarly to personalized sites such as my.site.com, or mysun.sun.com. When this module is enabled, a user creates an account and personalizes it without the aid of an administrator. With this new account, the user can access it as a added user. The user can also access the viewer interface, saved on the user profile database as authorization data and user preferences.

MSISDN

The Mobile Station Integrated Services Digital Network (MSISDN) authentication module enables authentication using a mobile subscriber ISDN associated with a device such as a cellular telephone. It is a non-interactive module. The module retrieves the subscriber ISDN and validates it against the Directory Server to find a user that matches the number.

RADIUS

Access Manager can be configured to work with a RADIUS server that is already installed. This is useful if there is a legacy RADIUS server being used for authentication in your enterprise. Enabling the RADIUS authentication module is a two-step process:

Configure the RADIUS server.

For detailed instructions, see the RADIUS server documentation.
Register and enable the RADIUS authentication module.

Configuring RADIUS with Sun Java System Application Server

When the RADUIS client forms a socket connection to its server, by default, only the connect permission of the SocketPermissions is allowed in the Application Server’s server.policy file. In order for RADUIS authentication to work correctly, permissions need to be granted for the following actions:

accept
connect
listen
resolve

To grant a permission for a socket connection, you must add an entry into Application Server’s server.policy file. A SocketPermission consists of a host specification and a set of actions specifying ways to connect to that host. The host is specified as the following:

host = hostname | IPaddress:portrange:portrange = portnumber 
| -portnumberportnumber-portnumber

The host is expressed as a DNS name, as a numerical IP address, or as local host (for the local machine). The wildcard “*” may be included once in a DNS name host specification. If it is included, it must be in the left-most position, as in *.example.com.

The port (or port range) is optional. A port specification of the form N-, where N is a port number, signifies all ports numbered N and above. A specification of the form -N indicates all ports numbered N and below.

The listen action is only meaningful when used with a local host. The resolve (resolve host/IP name service lookups) action is implied when any of the other actions are present.

For example, when creating SocketPermissions, note that if the following permission is granted to some code, it allows that code to connect to port 1645 on machine1.example.com, and to accept connections on that port:

permission java.net.SocketPermission machine1.example.com:1645, "connect,accept";

Similarly, if the following permission is granted to some code, it allows that code to accept connections on, connect to, or listen to any port between 1024 and 65535 on the local host:

permission java.net.SocketPermission "machine1.example.com:1645", "connect,accept";
permission java.net.SocketPermission "localhost:1024-", "accept,connect,listen";

Note –

Granting code permission to accept or make connections to remote hosts may cause problems, because malevolent code can then more easily transfer and share confidential data among parties who may not otherwise have access to the data. Make sure to give only appropriate permissions by specifying exact port number instead of allowing a range of port numbers

SafeWord

Access Manager can be configured to handle SafeWord Authentication requests to Secure Computing’s SafeWord™ or SafeWord PremierAccess™ authentication servers. Access Manager provides the client portion of SafeWord authentication. The SafeWord server may exist on the system on which Access Manager is installed, or on a separate system.

Configuring SafeWord with Sun Java System Application Server

When the SafeWord client forms a socket connection to its server, by default, only the connect permission of the SocketPermissions is allowed in the Application Server’s server.policy file. In order for SafeWord authentication to work correctly, permissions need to be granted for the following actions:

accept
connect
listen
resolve

host = (hostname | IPaddress)[:portrange] portrange = 
portnumber | -portnumberportnumber-[portnumber]

The host is expressed as a DNS name, as a numerical IP address, or as localhost (for the local machine). The wildcard “*” may be included once in a DNS name host specification. If it is included, it must be in the left-most position, as in *.example.com.

The port (or portrange) is optional. A port specification of the form N-, where N is a port number, signifies all ports numbered N and above. A specification of the form -N indicates all ports numbered N and below.

The listen action is only meaningful when used with a localhost. The resolve (resolve host/IP name service lookups) action is implied when any of the other actions are present.

permission java.net.SocketPermission machine1.example.com:5030, "connect,accept";

Similarly, if the following permission is granted to some code, it allows that code to accept connections on, connect to, or listen to any port between 1024 and 65535 on the local host:

permission java.net.SocketPermission "machine1.example.com:5030", "connect,accept";
permission java.net.SocketPermission "localhost:1024-", "accept,connect,listen";

Note –

SAML

The Security Assertion Markup Language (SAML) authentication module receives and validates SAML Assertions on a target server. SAML SSO will only work if this module is configured on the target machine, including after an upgrade (for example, Access Manager 2005Q4 to Access Manager 7.1).

SecurID

Access Manager can be configured to handle SecurID Authentication requests to RSA’s ACE/Server authentication servers. Access Manager provides the client portion of SecurID authentication. The ACE/Server may exist on the system on which Access Manager is installed, or on a separate system. In order to authenticate locally-administered user IDs (see admintool (1M)), root access is required.

SecurID Authentication makes use of an authentication helper, amsecuridd, which is a separate process from the main Access Manager process. Upon startup, this helper listens on a port for configuration information. If Access Manager is installed to run as nobody, or a userid other than root, then the AccessManager-base/SUNWam/share/bin/amsecuridd process must still execute as root. For more information on the amsecuridd helper, see “The amSecurID Helper” in the Access Manager Administration Reference.

Note –

For this release of Access Manager, the SecurID Authentication module is not available for the Linux or Solaris x86 platforms and this should not be registered, configured, or enabled on these two platforms. It is only available for SPARC systems.

UNIX

Access Manager can be configured to process authentication requests against Unix user IDs and passwords known to the Solaris or Linux system on which Access Manager is installed. While there is only one realm attribute, and a few global attributes for Unix authentication, there are some system-oriented considerations. In order to authenticate locally-administered user IDS (see admintool (1M)), root access is required

Unix Authentication makes use of an authentication helper, amunixd, which is a separate process from the main Access Manager process. Upon startup, this helper listens on a port for configuration information. There is only one Unix helper per Access Manager to serve all of its realms.

If Access Manager is installed to run as nobody, or a userid other than root, then the AccessManager-base/SUNWam/share/bin/amunixd process must still execute as root. The Unix authentication module invokes the amunixd daemon by opening a socket to localhost:58946 to listen for Unix authentication requests. To run the amunixd helper process on the default port, enter the following command:

./amunixd

To run amunixd on a non-default port, enter the following command:

./amunixd [-c portnm] [ipaddress]

The ipaddress and portnumber is located in the UnixHelper.ipadrs (in IPV4 format) and UnixHelper.port attributes in AMConfig.properties . You can run amunixd through the amserver command line utility (amserver runs the process automatically, retrieving the port number and IP address from AMConfig.properties).

The passwd entry in the /etc/nsswitch.conf file determines whether the /etc/passwd and /etc/shadow files, or NIS are consulted for authentication.

Windows Desktop SSO

The Windows Desktop SSO Authentication module is a Kerberos-based authentication plug-in module used for Windows 2000™. It allows a user who has already authenticated to a Kerberos Distribution Center (KDC) to authenticate to Access Manager without re-submitting the login criteria (Single Sign-on).

The user presents the Kerberos token to the Access Manager through the SPNEGO (Simple and Protected GSS-API Negotiation Mechanism) protocol. In order to perform Kerberos-based Single Sign-on to Access Manager through this authentication module, the user must, on the client side, support the SPNEGO protocol to authenticate itself. In general, any user that supports this protocol should be able to use this module to authenticate to Access Manager. Depending on the availability of the token on the client side, this module provides a SPENGO token or a Kerberos token (in both cases, the protocols are the same). Microsoft Internet Explorer (5.01 or later) running on Windows 2000 (or later) currently supports this protocol. In addition, Mozilla 1.4 on Solaris (9 and 10) has SPNEGO support, but the token returned is only a KERBEROS token, because SPNEGO is not supported on Solaris.

Note –

You must use JDK 1.4 or above to utilize the new features of Kerberos V5 authentication module and Java GSS API to perform Kerberos based SSO in this SPNEGO module.

Known Restriction with Internet Explorer

If you are using Microsoft Internet Explorer 6.x when for WindowsDesktopSSO authentication and the browser does not have access to the user’s Kerberos/SPNEGO token that matches the (KDC) realm configured in the WindowsDesktopSSO module, the browser will behave incorrectly to other modules after it fails authenticating to the WindowsDesktopSSO module. The direct cause of the problem is that after Internet Explorer fails the WindowsDesktopSSO module, the browser becomes incapable of passing callbacks (of other modules) to Access Manager, even if the callbacks are prompted, until the browser is restarted. Therefore all the modules coming after WindowsDesktopSSO will fail due to null user credentials.

See the following documentation for related information:

http://support.microsoft.com/default.aspx?scid=kb;en-us;308074

http://www.wedgetail.com/jcsi/sso/doc/guide/troubleshooting.html#ieNTLM

Note –

As of this release of Access Manager, this restriction has been fixed by Microsoft. For more information, see http://www.microsoft.com/technet/security/bulletin/ms06-042.mspx.

Configuring Windows Desktop SSO

Enabling Windows Desktop SSO Authentication is a two-step process:

Create a User in the Windows 2000 Domain Controller.
Setup Internet Explorer.

To Create a User in the Windows 2000 Domain Controller

In the domain controller, create a user account for the Access Manager authentication module.
1. From the Start menu, go to Programs>Administration Tools.
2. Select Active Directory Users and Computers.
3. Go to Computers>New>computer and add the client computer's name. If you are using Windows XP, this step is performed automatically during the domain controller account configuration.
4. Go to Users>New>Users and create a new user with the Access Manager host name as the User ID (login name). The Access Manager host name should not include the domain name.

Associate the user account with a service provider name and export the keytab files to the system in which Access Manager is installed. To do so, run the following commands:

ktpass -princ host/hostname.domainname@DCDOMAIN -pass password -mapuser userName-out 
hostname.host.keytab
ktpass -princ HTTP/hostname.domainname@DCDOMAIN -pass 
password -mapuser userName-out hostname.HTTP.keytab

Note –

The ktpass utilities are not installed as part of the Windows 2000 server. You must install it from the installation CD to the c:\program files\support tools directory.

The ktpass command accepts the following parameters:

hostname. The host name (without the domain name) on which Access Manager runs.

domainname . The Access Manager domain name.

DCDOMAIN. The domain name of the domain controller. This may be different from the Access Manager domain name.

password . The password of the user account. Make sure that password is correct, as ktpass does not verify passwords.

userName. The user account ID. This should be the same as hostname.

Note –

Make sure that both keytab files are kept secure.

The service template values should be similar to the following example:

Service Principal: HTTP/machine1.EXAMPLE.COM@ISQA.EXAMPLE.COM

Keytab File Name: /tmp/machine1.HTTP.keytab

Kerberos Realm: ISQA.EXAMPLE.COM

Kerberos Server Name: machine2.EXAMPLE.com

Return Principal with Domain Name: false

Authentication Level: 22

Note –

If you are using Windows 2003 or Windows 2003 Service Packs,, use the following ktpass command syntax:

ktpass /out filename /mapuser username /princ HTTP/hostname.domainname 
     /crypto encryptiontype /rndpass /ptype principaltype /target domainname

For example:

ktpass /out demo.HTTP.keytab /mapuser http 
/princ HTTP/demo.identity.sun.com@IDENTITY.SUN.COM /crypto RC4-HMAC-NT 
/rndpass /ptype KRB5_NT_PRINCIPAL /target IDENTITY.SUN.COM

For syntax definitions, see http://technet2.microsoft.com/WindowsServer/en/library/64042138-9a5a-4981-84e9-d576a8db0d051033.mspx?mfr=true web site.

Restart the server.

To Set Up Internet Explorer

These steps apply to Microsoft Internet Explorer™ 6 and later. If you are using an earlier version, make sure that Access Manager is in the browser’s internet zone and enable Native Windows Authentication.

In the Tool menu, go to Internet Options>Advanced/Security>Security.

Select the Integrated Windows Authentication option.

Go to Security>Local Internet.
1. Select Custom Level. In the User Authentication/Logon panel, select the Automatic Logon Only in Intranet Zone option.
2. Go to Sites and select all of the options.
3. Click Advanced and add the Access Manager to the local zone (if it is not added already).

Windows NT

Access Manager can be configured to work with an Windows NT /Windows 2000 server that is already installed. Access Manager provides the client portion of NT authentication.

Configure the NT server. For detailed instructions, see the Windows NT server documentation.
Before you can add and enable the Windows NT authentication module, you must obtain and install a Samba client to communicate with Access Manager on your Solaris system.

Installing the Samba Client

In order to activate the Windows NT Authentication module, Samba Client 2.2.2 must be downloaded and installed to the following directory:

AccessManager-base/SUNWam/bin

Samba Client is a file and print server for blending Windows and UNIX machines together without requiring a separate Windows NT/2000 Server. More information, and the download itself, can be accessed at http://wwws.sun.com/software/download/products/3e3af224.html.

Red Hat Linux ships with a Samba client, located in the following directory:

/usr/bin

In order to authenticate using the Windows NT Authentication module for Linux, copy the client binary to the following Access Manager directory:

AccessManager-base/sun/identity/bin

Note –

If you have multiple interfaces, extra configuration is required. Multiple interfaces can be set by configuration in the smb.conf file so it passes to the mbclient.

Authentication Module Instances

Multiple authentication module instances can be crated for the realm, based on the default authentication modules. You can add individually configured multiple instances of the same authentication module.

To Create a New Authentication Module Instance

Click the name of the realm for which you wish to add a new authentication module instance.

Select the Authentication tab.

Note –
The Administrator Authentication Configuration button defines the authentication service for administrators only. This attribute can be used if the authentication module for administrators needs to be different from the module for end users. The modules configured in this attribute are picked up when the Access Manager console is accessed.

Click New in the Module Instances list.

Enter a Name for the authentication module instance. The names must be unique.

Select the Type of authentication module type for the realm.

Click Create.

Click the name of the newly created module instance and edit the properties for that module. See the Authentication section in the online help for definitions for the properties for each module type.

Repeat these steps to add multiple module instances.

Authentication Chaining

One or more authentication modules can be configured so a user must pass authentication credentials to all of them. This is referred to as authentication chaining . Authentication chaining in Access Manager is achieved using the JAAS framework integrated in the Authentication Service.

To Create a New Authentication Chain

Click the name of the realm for which you wish to add a new authentication chain.

Select the Authentication tab.

Click New in the Authentication Chaining list.

Enter a name for the authentication chain.

Click Create.

Click Add to define the authentication module instance that you wish to include in the chain. To do so, select the module instance name from the Instance list. The module instance names displayed in this list are created in the Module Instances attribute.

Select the criteria for the chain. These flags establish an enforcement criteria for the authentication module for which they are defined. There is hierarchy for enforcement. Required is the highest and Optional is the lowest:

Requisite

The module instance is required to succeed. If it succeeds, authentication continues down the Authentication Chaining list. If it fails, control immediately returns to the application (authentication does not proceed down the Authentication Chaining list).

Required

Authentication to this module is required to succeed. If any of the required modules in the chain fails, the whole authentication chain will ultimately fail. However, whether a required module succeeds or fails, the control will continue down to the next module in the chain.

Sufficient

The module instance is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down the module instance list). If it fails, authentication continues down the Authentication Chaining list.

Optional

The module instance is not required to succeed. If it succeeds or fails, authentication still continues to proceed down the Authentication Chaining list.

Enter options for the chain. This enables additional options for the module as a key=value pair. Multiple options are separated by a space.

Define the following attributes:

Successful Login URL

Specifies the URL that the user will be redirected to upon successful authentication.

Failed Login URL

Specifies the URL that the user will be redirected to upon unsuccessful authentication.

Authentication Post Processing Class

Defines the name of the Java class used to customize the post authentication process after a login success or failure.

Click Save.

Authentication Types

The Authentication Service provides different ways in which authentication can be applied. These different authentication methods can be accessed by specifying Login URL parameters, or through the authentication APIs (see Chapter 2, Using Authentication APIs and SPIs, in Sun Java System Access Manager 7.1 Developer’s Guide in the Developer's Guide for more information). Before an authentication module can be configured, the Core authentication service attribute realm Authentication Modules must be modified to include the specific authentication module name.

The Authentication Configuration service is used to define authentication modules for any of the following authentication types:

Once an authentication module is defined for one of these authentication types, the module can be configured to supply redirect URLs, as well as a post-processing Java class specification, based on a successful or failed authentication process.

How Authentication Types Determine Access

For each of these methods, the user can either pass or fail the authentication. Once the determination has been made, each method follows this procedure. Step 1 through Step 3 follows a successful authentication; Step 4 follows both successful and failed authentication.

Access Manager confirms whether the authenticated user(s) is defined in the Directory Server data store and whether the profile is active.

The User Profile attribute in the Core Authentication module can be defined as Required, Dynamic, Dynamic with User Alias, or Ignored. Following a successful authentication, Access Manager confirms whether the authenticated user(s) is defined in the Directory Server data store and, if the User Profile value is Required, confirms that the profile is active. (This is the default case.) If the User Profile is Dynamically Configured, the Authentication Service will create the user profile in the Directory Server data store. If the User Profile is set to Ignore, the user validation will not be done.
Execution of the Authentication Post Processing SPI is accomplished.

The Core Authentication module contains an Authentication Post Processing Class attribute which may contain the authentication post-processing class name as its value. AMPostAuthProcessInterface is the post-processing interface. It can be executed on either successful or failed authentication or on logout.
The following properties are added to, or updated in, the session token and the user’s session is activated.

realm. This is the DN of the realm to which the user belongs.

Principal. This is the DN of the user.

Principals. This is a list of names to which the user has authenticated. (This property may have more then one value defined as a pipe separated list.)

UserId. This is the user’s DN as returned by the module, or in the case of modules other than LDAP or Membership, the user name. (All Principals must map to the same user. The UserID is the user DN to which they map.)

Note –
This property may be a non-DN value.

UserToken. This is a user name. (All Principals must map to the same user. The UserToken is the user name to which they map.)

Host. This is the host name or IP address for the client.

authLevel. This is the highest level to which the user has authenticated.

AuthType. This is a pipe separated list of authentication modules to which the user has authenticated (for example, module1|module2|module3).

clientType. This is the device type of the client browser.

Locale. This is the locale of the client.

CharSet. This is the determined character set for the client.

Role. Applicable for role-based authentication only, this is the role to which the user belongs.

Service. Applicable for service-based authentication only, this is the service to which the user belongs.
Access Manager looks for information on where to redirect the user after either a successful or failed authentication.

URL redirection can be to either an Access Manager page or a URL. The redirection is based on an order of precedence in which Access Manager looks for redirection based on the authentication method and whether the authentication has been successful or has failed. This order is detailed in the URL redirection portions of the following authentication methods sections.

URL Redirection

In the Authentication Configuration service, you can assign URL redirection for successful or unsuccessful authentication. The URLs, themselves, are defined in the Login Success URL and Login Failure URL attributes in this service. In order to enable URL redirection, you must add the Authentication Configuration service to your realm to make it available to configure for a role, realm, or user. Make sure that you add an authentication module, such as LDAP - REQUIRED, when adding the Authentication Configuration service.

Realm-based Authentication

This method of authentication allows a user to authenticate to an realm or sub-realm. It is the default method of authentication for Access Manager. The authentication method for an realm is set by registering the Core Authentication module to the realm and defining the realm Authentication Configuration attribute.

Realm-based Authentication Login URLs

The realm for authentication can be specified in the User Interface Login URL by defining the realm Parameter or the domain Parameter. The realm of a request for authentication is determined from the following, in order of precedence:

The domain parameter.
The realm parameter.

The value of the DNS Alias Names attribute in the Administration service.

After calling the correct realm, the authentication module(s) to which the user will authenticate are retrieved from the realm Authentication Configuration attribute in the Core Authentication Service. The login URLs used to specify and initiate realm-based authentication are:

http://server_name.domain_name:port/amserver/UI/Login
http://server_name.domain_name:port/amserver/UI/Login?domain=domain_name
http://server_name.domain_name:port/amserver/UI/Login?realm=realm_name

If there is no defined parameter, the realm will be determined from the server host and domain specified in the login URL.

Note –

If a user is member of and is authenticated to a specific realm, and tries to authenticate to different realm, the only two parameters that are passed are realm and module. For example, if User1 is a member of and authenticates to realmA and then tries to switch to or authenticate to realmB, the user will receive a warning page requesting to either start a new authentication to realmB with the module instance specified for realmB, or return to the existing authenticated session with realmA. If the user chooses to authenticate to realmB, only the realm name and module name (if specified) are passed and honored for determining the new authentication process.

Realm-based Authentication Redirection URLs

Upon a successful or failed organization-based authentication, Access Manager looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful realm-based Authentication Redirection URLs

The redirection URL for successful realm-based authentication is determined by checking the following places in order of precedence:

A URL set by the authentication module.
A URL set by a goto Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the iplanet-am-auth-login-success-url attribute as a global default.

Failed Realm-based Authentication Redirection URLs

The redirection URL for failed realm-based authentication is determined by checking the following places in the following order:

A URL set by the authentication module.
A URL set by a gotoOnFail Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s entry ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
A URL set for the iplanet-am-user-failure-url attribute in the user’s entry (amUser.xml).
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set for the iplanet-am-auth-login-failure-url attribute as the global default.

To Configure Realm-Based Authentication

Authentication modules are set for realms by first adding the Core Authentication service to the realm.

To Configure The Realms’s Authentication Attributes

Navigate to the realm for which you wish to add the Authentication Chain.

Click the Authentication tab.

Select the Default Authentication Chain.

Select the Administrator Authentication Chain from the pull down menu. This attribute can be used if the authentication module for administrators needs to be different from the module for end users. The default authentication module is LDAP.

Once you have defined the authentication chains, click Save.

Organization-based Authentication

This authentication type only applies to Access Manager deployments that have been installed in Legacy mode.

This method of authentication allows a user to authenticate to an organization or sub-organization. It is the default method of authentication for Access Manager . The authentication method for an organization is set by registering the Core Authentication module to the organization and defining the Organization Authentication Configuration attribute.

Organization-based Authentication Login URLs

The organization for authentication can be specified in the User Interface Login URL by defining the org Parameter or the domain Parameter. The organization of a request for authentication is determined from the following, in order of precedence:

The domain parameter.
The org parameter.
The value of the DNS Alias Names (Organization alias names) attribute in the Administration Service.

After calling the correct organization, the authentication module(s) to which the user will authenticate are retrieved from the Organization Authentication Configuration attribute in the Core Authentication Service. The login URLs used to specify and initiate organization-based authentication are:
http://server_name.domain_name:port/amserver/UI/Login http://server_name.domain_name:port/amserver/UI/Login?domain=domain_name http://server_name.domain_name:port/amserver/UI/Login?org=org_name
If there is no defined parameter, the organization will be determined from the server host and domain specified in the login URL.

Note –

If a user is member of and is authenticated to a specific organization, and tries to authenticate to different organization, the only two parameters that are passed are org and module. For example, if User1 is a member of and authenticates to orgA and then tries to switch to or authenticate to orgB, the user will receive a warning page requesting to either start a new authentication to orgB with the module instance specified for orgB, or return to the existing authenticated session with orgA. If the user chooses to authenticate to orgB, only the organization name and module name (if specified) are passed and honored for determining the new authentication process.

Organization-based Authentication Redirection URLs

Successful Organization-based Authentication Redirection URLs

The redirection URL for successful organization-based authentication is determined by checking the following places in order of precedence:

A URL set by the authentication module.
A URL set by a goto Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s organization entry.
A URL set in the iplanet-am-auth-login-success-url attribute as a global default.

Failed Organization-based Authentication Redirection URLs

The redirection URL for failed organization-based authentication is determined by checking the following places in the following order:

A URL set by the authentication module.
A URL set by a gotoOnFail Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s entry ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
A URL set for the iplanet-am-user-failure-url attribute in the user’s entry (amUser.xml).
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s organization entry.
A URL set for the iplanet-am-auth-login-failure-url attribute as the global default.

To Configure Organization-Based Authentication

Authentication modules are set for an organization by first adding the Core Authentication service to the organization.

To Configure The Organizations’s Authentication Attributes

Navigate to the organization for which you wish to add the Authentication Chain.

Click the Authentication tab.

Select the Default Authentication Chain.

Select the Administrator Authentication Chain from the pull down menu. This attribute can be used if the authentication module for administrators needs to be different from the module for end users. The default authentication module is LDAP.

Once you have defined the authentication chains, click Save.

Role-based Authentication

This method of authentication allows a user to authenticate to a role (either static or filtered) within an realm or sub realm.

Note –

The Authentication Configuration Service must first be registered to the realm before it can be registered as an instance to the role.

For authentication to be successful, the user must belong to the role and they must authenticate to each module defined in the Authentication Configuration Service instance configured for that role. For each instance of role-based authentication, the following attributes can be specified:

Conflict Resolution Level. This sets a priority level for the Authentication Configuration Service instance defined for different roles that both may contain the same user. For example, if User1 is assigned to both Role1 and Role2, a higher conflict resolution level can be set for Role1 so when the user attempts authentication, Role1 will have the higher priority for success or failure redirects and post-authentication processes.

Authentication Configuration. This defines the authentication modules configured for the role’s authentication process.

Login Success URL. This defines the URL to which a user is redirected on successful authentication.

Login Failed URL. This defines the URL to which a user is redirected on failed authentication.

Authentication Post Processing Classes. This defines the post-authentication interface.

Role-based Authentication Login URLs

Role-based authentication can be specified in The User Interface Login URL by defining a role Parameter. After calling the correct role, the authentication module(s) to which the user will authenticate are retrieved from the Authentication Configuration Service instance defined for the role.

The login URLs used to specify and initiate this role-based authentication are:

http://server_name.domain_name:port/amserver/UI/Login?role=role_name
http://server_name.domain_name:port/amserver/UI/Login?realm=realm_name&role=role_name

If the realm Parameter is not configured, the realm to which the role belongs is determined from the server host and domain specified in the login URL itself.

Role-based Authentication Redirection URLs

Upon a successful or failed role-based authentication, Access Manager looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful Role-based Authentication Redirection URLs

The redirection URL for successful role-based authentication is determined by checking the following places in the following order:

A URL set by the authentication module.
A URL set by a goto Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the role to which the user has authenticated.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of another role entry of the authenticated user. (This option is a fallback if the previous redirection URL fails.)
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
A URL set in the iplanet-am-auth-login-success-url attribute of the role to which the user has authenticated.
A URL set in the iplanet-am-auth-login-success-url attribute of another role entry of the authenticated user. (This option is a fallback if the previous redirection URL fails.)
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the iplanet-am-auth-login-success-url attribute as a global default.

Failed Role-based Authentication Redirection URLs

The redirection URL for failed role-based authentication is determined by checking the following places in the following order:

A URL set by the authentication module.
A URL set by a goto Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s profile ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the role to which the user has authenticated.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of another role entry of the authenticated user. (This option is a fallback if the previous redirection URL fails.)
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
A URL set in the iplanet-am-user-failure-url attribute of the user’s profile (amUser.xml).
A URL set in the iplanet-am-auth-login-failure-url attribute of the role to which the user has authenticated.
A URL set in the iplanet-am-auth-login-failure-url attribute of another role entry of the authenticated user. (This option is a fallback if the previous redirection URL fails.)
A URL set in the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set in the iplanet-am-auth-login-failure-url attribute as a global default.

To Configure Role-Based Authentication

Navigate to the realm (or organization) to which you will add the authentication configuration service.

Click the Subjects tab.

Filtered Roles or Roles.

Select the role for which to set the authentication configuration.

Select the Default Authentication Chain that you wish to enable.

Click Save.

Note –
If you are creating a new role, the Authentication Configuration service is not automatically assigned to it. Make sure that you select the Authentication Configuration service option at the top of the role profile page before you create it.

When role-based authentication is enabled, the LDAP authentication module can be left as the default, as there is no need to configure Membership.

Service-based Authentication

This method of authentication allows a user to authenticate to a specific service or application registered to an realm or sub realm. The service is configured as a Service Instance within the Authentication Configuration Service and is associated with an Instance Name. For authentication to be successful, the user must authenticate to each module defined in the Authentication Configuration service instance configured for the service. For each instance of service-based authentication, the following attributes can be specified:

Authentication Configuration. This defines the authentication modules configured for the service’s authentication process.

Login Success URL. This defines the URL to which a user is redirected on successful authentication.

Login Failed URL. This defines the URL to which a user is redirected on failed authentication.

Authentication Post Processing Classes. This defines the post-authentication interface.

Service-based Authentication Login URLs

Service-based authentication can be specified in the User Interface Login URL by defining a service Parameter. After calling the service, the authentication module(s) to which the user will authenticate are retrieved from the Authentication Configuration service instance defined for the service.

The login URLs used to specify and initiate this service-based authentication are:

http://server_name.domain_name:port/amserver/UI/
Login?service=auth-chain-name

and

http://server_name.domain_name:port/amserver
     /UI/Login?realm=realm_name&service=auth-chain-name

If there is no configured org parameter, the realm will be determined from the server host and domain specified in the login URL itself.

Service-based Authentication Redirection URLs

Upon a successful or failed service-based authentication, Access Manager looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful Service-based Authentication Redirection URLs

The redirection URL for successful service-based authentication is determined by checking the following places in the following order:

A URL set by the authentication module.
A URL set by a goto Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the service to which the user has authenticated.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
A URL set in the iplanet-am-auth-login-success-url attribute of the service to which the user has authenticated.
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the iplanet-am-auth-login-success-url attribute as a global default.

Failed Service-based Authentication Redirection URLs

The redirection URL for failed service-based authentication is determined by checking the following places in the following order:

A URL set by the authentication module.
A URL set by a goto Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s profile ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the service to which the user has authenticated.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
A URL set in the iplanet-am-user-failure-url attribute of the user’s profile (amUser.xml).
A URL set in the iplanet-am-auth-login-failure-url attribute of the service to which the user has authenticated.
A URL set in the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set in the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set in the iplanet-am-auth-login-failure-url attribute as a global default.

To Configure Service-Based Authentication

Authentication modules are set for services after adding the Authentication Configuration service. To do so:

Chose the realm to which you wish to configure service-based authentication.

Click the Authentication tab.

Create the authentication module instances.

Create the authentication chains.

Click Save.

To access service-based authentication for the realm, enter the following address:

http://server_name.domain_name:port/amserver/UI/Login?realm=realm_name&service=auth-chain-name

User-based Authentication

This method of authentication allows a user to authenticate to an authentication process configured specifically for the user. The process is configured as a value of the User Authentication Configuration attribute in the user’s profile. For authentication to be successful, the user must authenticate to each module defined.

User-based Authentication Login URLs

User-based authentication can be specified in the User Interface Login URL by defining a user Parameter. After calling the correct user, the authentication module(s) to which the user will authenticate are retrieved from the User Authentication Configuration instance defined for the user.

The login URLs used to specify and initiate this role-based authentication are:

http://server_name.domain_name:port/amserver/UI/Login?user=user_name
http://server_name.domain_name:port/amserver/UI/Login?org=org_name&user=user_name

If there is no configured realm Parameter, the realm to which the role belongs will be determined from the server host and domain specified in the login URL itself.

User Alias List Attribute

On receiving a request for user-based authentication, the Authentication service first verifies that the user is a valid user and then retrieves the Authentication Configuration data for them. In the case where there is more then one valid user profile associated with the value of the user Login URL parameter, all profiles must map to the specified user. The User Alias Attribute (iplanet-am-user-alias-list ) in the User profile is where other profiles belonging to the user can be defined. If mapping fails, the user is denied a valid session. The exception would be if one of the users is a top-level admin whereby the user mapping validation is not done and the user is given top—level Admin rights.

User-based Authentication Redirection URLs

Upon a successful or failed user-based authentication, Access Manager looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful User-based Authentication Redirection URLs

The redirection URL for successful user-based authentication is determined by checking the following places in order of precedence:

A URL set by the authentication module.
A URL set by a goto Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the iplanet-am-auth-login-success-url attribute as a global default.

Failed User-based Authentication Redirection URLs

The redirection URL for failed user-based authentication is determined by checking the following places in the following order:

A URL set by the authentication module.
A URL set by a gotoOnFail Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s entry ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
A URL set for the iplanet-am-user-failure-url attribute in the user’s entry (amUser.xml).
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set for the iplanet-am-auth-login-failure-url attribute as the global default.

To Configure User-Based Authentication

Navigate to the realm in which you wish to configure authentication for the user.

Click the Subjects tab and click Users.

Click the name of the user you wish to modify

The User Profile is displayed.

Note –
If you are creating a new user, the Authentication Configuration service is not automatically assigned to the user. Make sure that you select the Authentication Configuration service option in the Service profile before you create the user. If this option is not selected, the user will not inherit the authentication configuration defined at for the role.

In the User Authentication Configuration attribute, select the authentication chain you wish to apply.

Click Save.

Authentication Level-based Authentication

Each authentication module can be associated with an integer value for its authentication level. Authentication levels can be assigned changing the corresponding value for the module’s Authentication Level attribute. Higher authentication levels define a higher level of trust for the user once that user has authenticated to one or more authentication modules.

The authentication level will be set on a user’s SSO token after the user has successfully authenticated to the module. If the user is required to authenticate to multiple authentication modules, and does so successfully, the highest authentication level value will be set in user’s SSO token.

If a user attempts to access a service, the service can determine if the user is allowed access by checking the authentication level in user’s SSO token. It then redirects the user to go through the authentication modules with a set authentication level.

Users can also access authentication modules with specific authentication level. For example, a user performs a login with the following syntax:

http://hostname:port/deploy_URI/UI/Login?authlevel=
auth_level_value

All modules whose authentication level is larger or equal to auth_level_value will be displayed as an authentication menu for the user to choose. If only one matching module is found, then the login page for that authentication module will be directly displayed.

This method of authentication allows an administrator to specify the security level of the modules to which identities can authenticate. Each authentication module has a separate Authentication Level attribute and the value of this attribute can be defined as any valid integer. With Authentication Level-based authentication, the Authentication Service displays a module login page with a menu containing the authentication modules that have authentication levels equal to or greater then the value specified in the Login URL parameter. Users can select a module from the presented list. Once the user selects a module, the remaining process is based on Module-based Authentication.

Authentication Level-based Authentication Login URLs

Authentication level-based authentication can be specified in the User Interface Login URL by defining the authlevel Parameter. After calling the login screen with the relevant list of modules, the user must choose one with which to authenticate. The login URLs used to specify and initiate authentication level-based authentication are:

http://server_name.domain_name:port/amserver/UI/Login?authlevel=authentication_level

and

http://server_name.domain_name:port/amserver/UI/
Login?realm=realm_name&authlevel=authentication_level

If there is no configured realm parameter, the realm to which the user belongs will be determined from the server host and domain specified in the login URL itself.

Authentication Level-based Authentication Redirection URLs

Upon a successful or failed authentication level-based authentication, Access Manager looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful Authentication Level-based Authentication Redirection URLs

The redirection URL for successful authentication level-based authentication is determined by checking the following places in order of precedence:

A URL set by the authentication module.
A URL set by a goto Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the iplanet-am-auth-login-success-url attribute as a global default.

Failed Authentication Level-based Authentication Redirection URLs

The redirection URL for failed authentication level-based authentication is determined by checking the following places in the following order:

A URL set by the authentication module.
A URL set by a gotoOnFail Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s entry ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
A URL set for the iplanet-am-user-failure-url attribute in the user’s entry (amUser.xml).
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set for the iplanet-am-auth-login-failure-url attribute as the global default.

Module-based Authentication

Users can access a specific authentication module using the following syntax:

http://hostname:port/deploy_URI/UI/Login?module=
module_name

Before the authentication module can be accessed, the Core authentication service attribute realm Authentication Modules must be modified to include the authentication module name. If the authentication module name is not included in this attribute, the “authentication module denied” page will be displayed when the user attempts to authenticate.

This method of authentication allows a user to specify the module to which they will authenticate. The specified module must be registered to the realm or sub-realm that the user is accessing. This is configured in the realm Authentication Modules attribute of the realm’s Core Authentication Service. On receiving this request for module-based authentication, the Authentication Service verifies that the module is correctly configured as noted, and if the module is not defined, the user is denied access.

Module-based Authentication Login URLs

Module-based authentication can be specified in the User Interface Login URL by defining a module Parameter. The login URLs used to specify and initiate module-based authentication are:

http://server_name.domain_name:port/amserver/UI/Login?module=authentication_module_name
http://server_name.domain_name:port/amserver/UI/
Login?org=org_name&module=authentication_module_name

If there is no configured org parameter, the realm to which the user belongs will be determined from the server host and domain specified in the login URL itself.

Module-based Authentication Redirection URLs

Upon a successful or failed module-based authentication, Access Manager looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

Successful Module-based Authentication Redirection URLs

The redirection URL for successful module-based authentication is determined by checking the following places in order of precedence:

A URL set by the authentication module.
A URL set by a goto Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-success-url attribute of the user’s profile ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-success-url attribute as a global default.
A URL set in the iplanet-am-user-success-url attribute of the user’s profile (amUser.xml).
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s role entry.
A URL set in the iplanet-am-auth-login-success-url attribute of the user’s realm entry.
A URL set in the iplanet-am-auth-login-success-url attribute as a global default.

Failed Module-based Authentication Redirection URLs

The redirection URL for failed module-based authentication is determined by checking the following places in the following order:

A URL set by the authentication module.
A URL set by a gotoOnFail Login URL parameter.
A URL set in the clientType custom files for the iplanet-am-user-failure-url attribute of the user’s entry ( amUser.xml).
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set in the clientType custom files for the iplanet-am-auth-login-failure-url attribute as a global default.
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s role entry.
A URL set for the iplanet-am-auth-login-failure-url attribute of the user’s realm entry.
A URL set for the iplanet-am-auth-login-failure-url attribute as the global default.

The User Interface Login URL

The Authentication Service user interface is accessed by entering a login URL into the Location Bar of a web browser. This URL is:

http://AccessManager-root/.domain_name:port /service_deploy_uri /UI/Login

Note –

During installation, the service_deploy_uri is configured as amserver. This default service deployment URI will be used throughout this document.

The user interface login URL can also be appended with Login URL Parameters to define specific authentication methods or successful/failed authentication redirection URLs.

Login URL Parameters

A URL parameter is a name/value pair appended to the end of a URL. The parameter starts with a question mark (?) and takes the form name=value. A number of parameters can be combined in one login URL, for example:

http://server_name.domain_name:port/amserver/UI/
Login?module=LDAP&locale=ja&goto=http://www.sun.com

If more than one parameter exists, they are separated by an ampersand (&). The combinations though must adhere to the following guidelines:

Each parameter can occur only once in one URL. For example, module=LDAP&module=NT is not computable.
Both the org parameter and the domain parameter determine the login realm. In this case, only one of the two parameters should be used in the login URL. If both are used and no precedence is specified, only one will take effect.
The parameters user, role, service, module and authlevel are for defining authentication modules based on their respective criteria. Due to this, only one of them should be used in the login URL. If more than one is used and no precedence is specified, only one will take effect.

The following sections describe parameters that, when appended to the User Interface Login URL and typed in the Location bar of a web browser, achieve various authentication functionality.

Note –

To simplify an authentication URL and parameters for distribution throughout an realm, an administrator might configure an HTML page with a simple URL that possesses links to the more complicated login URLs for all configured authentication methods.

goto Parameter

A goto=successful_authentication_URL parameter overrides the value defined in the Login Success URL of the Authentication Configuration service. It will link to the specified URL when a successful authentication has been achieved. A goto=logout_URL parameter can also be used to link to a specified URL when the user is logging out. For an example of a successful authentication URL:

http://server_name.domain_name:port/amserver/
UI/Login?goto=http://www.sun.com/homepage.html

An example goto logout URL:

http://server_name.domain_name:port/amserver/
UI/Logout?goto=http://www.sun.com/logout.html.

Note –

There is an order of precedence in which Access Manager looks for successful authentication redirection URLs. Because these redirection URLs and their order are based on the method of authentication, this order (and related information) is detailed in the Authentication Types section.

gotoOnFail Parameter

A gotoOnFail=failed_authentication_URL parameter overrides the value defined in the Login Failed URL of the Authentication Configuration service. It will link to the specified URL if a user has failed authentication. An example gotoOnFail URL might be http:// server_name.domain_name:port /amserver/UI/Login?gotoOnFail=http://www.sun.com/auth_fail.html.

Note –

There is an order of precedence in which Access Manager looks for failed authentication redirection URLs. Because these redirection URLs and their order are based on the method of authentication, this order (and related information) is detailed in Authentication Types section.

realm Parameter

The org=realmName parameter allows a user to authenticate as a user in the specified realm.

Note –

A user who is not already a member of the specified realm will receive an error message when they attempt to authenticate with the realm parameter. A user profile, though, can be dynamically created in the Directory Server if all of the following are TRUE:

The User Profile attribute in the Core Authentication Service must be set to Dynamic or Dynamic with User Alias.
The user must successfully authenticate to the required module.
The user does not already have a profile in Directory Server.

From this parameter, the correct login page (based on the realm and its locale setting) will be displayed. If this parameter is not set, the default is the top-level realm. For example, an org URL might be:

http://server_name.domain_name:port/amserver/UI/Login?realm=sun

org Parameter

The org=orgName parameter allows a user to authenticate as a user in the specified organization.

Note –

A user who is not already a member of the specified organization will receive an error message when they attempt to authenticate with the org parameter. A user profile, though, can be dynamically created in the Directory Server if all of the following are TRUE:

The User Profile attribute in the Core Authentication Service must be set to Dynamic or Dynamic with User Alias.
The user must successfully authenticate to the required module.
The user does not already have a profile in Directory Server.

From this parameter, the correct login page (based on the organization and its locale setting) will be displayed. If this parameter is not set, the default is the top-level organization. For example, an org URL might be:

http://server_name.domain_name:port/amserver/UI/Login?org=sun

user Parameter

The user=userName parameter forces authentication based on the module configured in User Authentication Configuration attribute of the user’s profile. For example, one user’s profile can be configured to authenticate using the Certification module while another user might be configured to authenticate using the LDAP module. Adding this parameter sends the user to their configured authentication process rather than the method configured for their organization. For example:

http://server_name.domain_name:port/amserver/UI/Login?user=jsmith

role Parameter

A role=roleName parameter sends the user to the authentication process configured for the specified role. A user who is not already a member of the specified role will receive an error message when they attempt to authenticate with this parameter. For example:

http://server_name.domain_name:port/amserver/UI/Login?role=manager.

locale Parameter

Access Manager has the capability to display localized screens (translated into languages other than English) for the authentication process as well as for the console itself. The locale=localeName parameter allows the specified locale to take precedence over any other defined locales. The login locale is displayed by the client after searching for the configuration in the following places, order-specific:

Value of locale parameter in Login URL

The value of the locale=localeName parameter takes precedence over all other defined locales.
Locale defined in user’s profile

If there is no URL parameter, the locale is displayed based on the value set in the User Preferred Language attribute of the user profile.
Locale defined in the HTTP header

This locale is set by the web browser.
Locale defined in Core Authentication Service

This is the value of the Default Auth Locale attribute in the Core Authentication module.
Locale defined in Platform Service

This is the value of the Platform Locale attribute in the Platform service.

Operating system locale

The locale derived from this pecking order is stored in the user’s session token and Access Manager uses it for loading the localized authentication module only. After successful authentication, the locale defined in the User Preferred Language attribute of the user’s profile is used. If none is set, the locale used for authentication will be carried over. For example:

http://server_name.domain_name:port/amserver/UI/Login?locale=ja.

Note –

Information on how to localize the screen text and error messages can be found in the Access Manager.

module Parameter

The module=moduleName parameter allows authentication via the specified authentication module. Any of the modules can be specified although they must first be registered under the realm to which the user belongs and selected as one of that realm’s authentication modules in the Core Authentication module. For example:

http://server_name.domain_name:port/amserver/UI/Login?module=Unix.

Note –

The authentication module names are case-sensitive when used in a URL parameter.

service Parameter

The service=serviceName parameter allows a user to authenticate via a service’s configured authentication scheme. Different authentication schemes can be configured for different services using the Authentication Configuration service. For example, an online paycheck application might require authentication using the more secure Certificate Authentication module while an realm’s employee directory application might require only the LDAP Authentication module. An authentication scheme can be configured, and named, for each of these services. For example:

http://server_name.domain_name:port/amserver/UI/Login?service=sv1.

Note –

The Authentication Configuration service is used to define a scheme for service-based authentication.

arg Parameter

The arg=newsession parameter is used to end a user’s current session and begin a new one. The Authentication Service will destroy a user’s existing session token and perform a new login in one request. This option is typically used in the Anonymous Authentication module. The user first authenticates with an anonymous session, and then hits the register or login link. For example:

http://server_name.domain_name:port/amserver/UI/Login?arg=newsession.

authlevel Parameter

An authlevel=value parameter tells the Authentication Service to call a module with an authentication level equal to or greater than the specified authentication level value. Each authentication module is defined with a fixed integer authentication level. For example:

http://server_name.domain_name:port/amserver/UI/Login?authlevel=1.

Note –

The Authentication Level is set in each module’s specific profile. .

domain Parameter

This parameter allows a user to login to an realm identified as the specified domain. The specified domain must match the value defined in the Domain Name attribute of the realm’s profile. For example:

http://server_name.domain_name:port/amserver/UI/Login?domain=sun.com.

Note –

A user who is not already a member of the specified domain/realm will receive an error message when they attempt to authenticate with the org parameter. A user profile, though, can be dynamically created in the Directory Server if all of the following points are TRUE:

The User Profile attribute in the Core Authentication Service must be set to Dynamic or Dynamic With User Alias .
The user must successfully authenticate to the required module.
The user does not already have a profile in Directory Server.

iPSPCookie Parameter

The iPSPCookie=yes parameter allows a user to login with a persistent cookie. A persistent cookie is one that continues to exist after the browser window is closed. In order to use this parameter, the realm to which the user is logging in must have Persistent Cookies enabled in their Core Authentication module. Once the user authenticates and the browser is closed, the user can login with a new browser session and will be directed to console without having to re-authenticate. This will work until the value of the Persistent Cookie Max Time attribute specified in the Core Service elapses. For example:

http://server_name.domain_name:port/amserver/UI/Login?org=example&iPSPCookie=yes

IDTokenN Parameters

This parameter option to enables a user to pass authentication credentials using a URL or HTML forms. With the IDTokenN=value parameters, a user can be authenticated without accessing the Authentication Service User Interface. This process is called Zero Page Login. Zero page login works only for authentication modules that use one login page. The values of IDToken0, IDToken1, ..., IDTokenN map to the fields on the authentication module’s login page. For example, the LDAP authentication module might use IDToken1 for the userID information, and IDToken2 for password information. In this case, the LDAP module IDTokenN URL would be:

http://server_name.domain_name:port/amserver/UI/
Login?module=LDAP&IDToken1=userID&IDToken2=password

(module=LDAP can be omitted if LDAP is the default authentication module.)

For Anonymous authentication, the login URL parameter would be:

http://server_name.domain_name:port/amserver/UI/Login?module=Anonymous&IDToken1=anonymousUserID.

Note –

The token names Login.Token0, Login.Token1, ..., Login.TokenN (from previous releases) are still supported but will be deprecated in a future release. It is recommended to use the new IDTokenN parameters.

Account Locking

The Authentication Service provides a feature where a user will be locked out from authenticating after a defined number of failures. This feature is turned off by default, but can be enabled using the Access Manager console.

Note –

Only modules that throw an Invalid Password Exception can leverage the Account Locking feature.

The Core Authentication service contains attributes for enabling and customizing this feature including (but not limited to):

Login Failure Lockout Mode which enables account locking.
Login Failure Lockout Count which defines the number of tries that a user may attempt to authenticate before being locked out. This count is valid per user ID only; the same user ID needs to fail for the given count after which that user ID would be locked out.
Login Failure Lockout Interval defines (in minutes) the amount of time in which the Login Failure Lockout Count value must be completed before a user is locked out.
Email Address to Send Lockout Notification specifies an email address to which user lockout notifications will be sent.
Warn User After N Failure specifies the number of authentication failures that can occur before a warning message will be displayed to the user. This allows an administrator to set additional login attempts after the user is warned about an impending lockout.
Login Failure Lockout Duration defines (in minutes) how long the user will have to wait before attempting to authenticate again after lockout.
Lockout Attribute Name defines which LDAP attribute in the user’s profile will be set to inactive for Physical Locking.
Lockout Attribute Value defines to what the LDAP attribute specified in Lockout Attribute Name will be set: inactive or active.

Email notifications are sent to administrators regarding any account lockouts. (Account locking activities are also logged.)

Note –

For special instructions when using this feature on a Microsoft® Windows 2000 operating system, see “Simple Mail Transfer Protocol (SMTP)” in Appendix A, “AMConfig.properties File.”

Access Manager supports two types of account locking are supported: Physical Locking and Memory Locking, defined in the following sections.

Physical Locking

This is the default locking behavior for Access Manager The locking is initiated by changing the status of a LDAP attribute in the user’s profile to inactive. The Lockout Attribute Name attribute defines the LDAP attribute used for locking purposes.

Note –

An aliased user is one that is mapped to an existing LDAP user profile by configuring the User Alias List Attribute (iplanet-am-user-alias-list in amUser.xml) in the LDAP profile. Aliased users can be verified by adding iplanet-am-user-alias-list to the Alias Search Attribute Name field in the Core Authentication Service. That said, if an aliased user is locked out, the actual LDAP profile to which the user is aliased will be locked. This pertains only to physical lockout with authentication modules other than LDAP and Membership.

Memory Locking

Memory locking is enabled by changing the Login Failure Lockout Duration attribute to a value greater then 0. The user’s account is then locked in memory for the number of minutes specified. The account will be unlocked after the time period has passed. Following are some special considerations when using the memory locking feature:

If Access Manager is restarted, all accounts locked in memory are unlocked.
If a user’s account is locked in memory and the administrator changes the account locking mechanism to physical locking (by setting the lockout duration back to 0), the user’s account will be unlocked in memory and the lock count reset.
After memory lockout, when using authentication modules other than LDAP and Membership, if the user attempts to login with the correct password, a User does not have profile in this realm error. is returned rather than a User is not active. error.

Note –

If the Failure URL attribute is set in the user’s profile, neither the lockout warning message nor the message indicating that their account has been locked will not be displayed; the user will be redirected to the defined URL.

Authentication Service Failover

Authentication service failover automatically redirects an authentication request to a secondary server if the primary server fails because of a hardware or software problem or if the server is temporarily shut down.

An authentication context must first be created on an instance of Access Manager where the authentication service is available. If this instance of Access Manager is not available, an authentication context can then be created on a different instance of Access Manager through the authentication failover mechanism. The authentication context will check for server availability in the following order:

The authentication service URL is passed to the AuthContext API. For example:
AuthContext(orgName, url)
If this API is used, it will only use the server referenced by the URL. No failover will occur even if the authentication service is available on that server.
The authentication context will check the server defined in the com.iplanet.am.server* attribute of the AMConfig.properties file.
If step 2 fails, then the authentication context queries the platform list from a server where the Naming service is available This platform list is automatically created when multiple instances of Access Manager are installed (generally, for failover purposes) sharing a one instance of Directory Server.

For example, if the platform list contains URLs for Server1, Server2 and Server3, then the authentication context will loop through Server1 , Server2 and Server3 until authentication succeeds on one of them.

The platform list may not always be obtained from the same server, as it depends on the availability of the Naming service. Furthermore, Naming service failover may occur first. Multiple Naming service URLs are specified in the com.iplanet.am.naming.url property (in AMConfing.properties ). The first available Naming service URL will be used to identify the server, which will contain the list of servers (in its platform server list) on which authentication failover will occur.

Fully Qualified Domain Name Mapping

Fully Qualified Domain Name (FQDN) mapping enables the Authentication Service to take corrective action in the case where a user may have typed in an incorrect URL (such as specifying a partial host name or IP address to access protected resources). FQDN mapping is enabled by modifying the com.sun.identity.server.fqdnMap attribute in the AMConfig.properties file. The format for specifying this property is:

com.sun.identity.server.fqdnMap[invalid-name ]=valid-name

The value invalid-name would be a possible invalid FQDN host name that may be typed by the user, and valid-name would be the actual host name to which the filter will redirect the user. Any number of mappings can be specified (as illustrated in Code Example 1-1) as long as they conform to the stated requirements. If this property is not set, the user would be sent to the default server name configured in the com.iplanet.am.server.host= server_name property also found in the AMConfig.properties file.

Example 4–1 FQDN Mapping Attribute In `AMConfig.properties`

com.sun.identity.server.fqdnMap[isserver]=isserver.mydomain.com
com.sun.identity.server.fqdnMap[isserver.mydomain]=isserver.mydomain.com
com.sun.identity.server.fqdnMap[
            IP address]=isserver.mydomain.com

Possible Uses For FQDN Mapping

This property can be used for creating a mapping for more than one host name which may be the case if applications hosted on a server are accessible by more than one host name. This property can also be used to configure Access Manager to not take corrective action for certain URLs. For example, if no redirect is required for users who access applications by using an IP address, this feature can be implemented by specifying a map entry such as:

com.sun.identity.server.fqdnMap[IP address ]=IP address.

Note –

If more than one mapping is defined, ensure that there are no overlapping values in the invalid FQDN name. Failing to do so may result in the application becoming inaccessible.

Persistent Cookie

A persistent cookie is one that continues to exist after the web browser is closed, allowing a user to login with a new browser session without having to re-authenticate. The name of the cookie is defined by the com.iplanet.am.pcookie.name property in AMConfig.properties; the default value is DProPCookie . The cookie value is a 3DES-encrypted string containing the userDN, realm name, authentication module name, maximum session time, idle time, and cache time.

Note –

Persistent cookies does not work with the Distributed Authentication User Interface or Cross Domain Single Sign-on. If enabled with either of these options, the user will receive a regular cookie.

To Enable Persistent Cookies

Turn on the Persistent Cookie Mode in the Core Authentication module.

Configure a time value for the Persistent Cookie Maximum Time attribute in the Core Authentication module.

Append the iPSPCookie Parameter with a value of yes to the User Interface Login URL.

Once the user authenticates using this URL, if the browser is closed, they can open a new browser window and will be redirected to the console without re-authenticating. This will work until the time defined in Step 2 elapses.

Persistent Cookie Mode can be turned on using the Authentication SPI method:

AMLoginModule.setPersistentCookieOn().

Multi-LDAP Authentication Module Configuration In Legacy Mode

As a form of failover or to configure multiple values for an attribute when the Access Manager console only provides one value field, an administrator can define multiple LDAP authentication module configurations under one realm. Although these additional configurations are not visible from the console, they work in conjunction with the primary configuration if an initial search for the requesting user’s authorization is not found. For example, one realm can define a search through LDAP servers for authentication in two different domains or it can configure multiple user naming attributes in one domain. For the latter, which has only one text field in the console, if a user is not found using the primary search criteria, the LDAP module will then search using the second scope. Following are the steps to configure additional LDAP configurations.

To Add An Additional LDAP Configuration

Write an XML file including the complete set of attributes and new values needed for second (or third) LDAP authentication configuration.

The available attributes can be referenced by viewing the amAuthLDAP.xml located in etc/opt/SUNWam/config/xml. This XML file created in this step though, unlike the amAuthLDAP.xml, is based on the structure of the amadmin.dtd. Any or all attributes can be defined for this file. Code Example 1-2 is an example of a sub-configuration file that includes values for all attributes available to the LDAP authentication configuration.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  Copyright (c) 2002 Sun Microsystems, Inc. All rights reserved.
  Use is subject to license terms.
-->
<!DOCTYPE Requests
    PUBLIC "-//iPlanet//Sun ONE Access Manager 6.0 Admin CLI DTD//EN"
    "jar://com/iplanet/am/admin/cli/amAdmin.dtd"
>
<!--
  Before adding subConfiguration load the schema with
GlobalConfiguration defined and replace corresponding
 serviceName and subConfigID in this sample file OR load
 serviceConfigurationRequests.xml before loading this sample
-->
<Requests>
<realmRequests DN="dc=iplanet,dc=com">
    <AddSubConfiguration subConfigName = "ssc"
        subConfigId = "serverconfig"
        priority = "0" serviceName="iPlanetAMAuthLDAPService">

              <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-server"/>
            <Value>vbrao.red.iplanet.com:389</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-base-dn"/>
            <Value>dc=iplanet,dc=com</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="planet-am-auth-ldap-bind-dn"/>
            <Value>cn=amldapuser,ou=DSAME Users,dc=iplanet,dc=com</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-bind-passwd"/>
            <Value>
                  plain text password</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-user-naming-attribute"/>
            <Value>uid</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-user-search-attributes"/>
            <Value>uid</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-search-scope"/>
            <Value>SUBTREE</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-ssl-enabled"/>
            <Value>false</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-return-user-dn"/>
            <Value>true</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-auth-level"/>
            <Value>0</Value>
        </AttributeValuePair>
        <AttributeValuePair>
            <Attribute name="iplanet-am-auth-ldap-server-check"/>
            <Value>15</Value>
        </AttributeValuePair>

    </AddSubConfiguration>

</realmRequests>
</Requests>

Copy the plain text password as the value for the iplanet-am-auth-ldap-bind-passwd in the XML file created in Step 1.

The value of this attribute is formatted in bold in the code example.

Load the XML file using the amadmin command line tool.
./amadmin -u amadmin -w administrator_password -v -t name_of_XML_file.
Note that this second LDAP configuration can not be seen or modified using the console.

Tip –
There is a sample available for multi-LDAP configuration. See the serviceAddMultipleLDAPConfigurationRequests .xml command line template in /AccessManager-base /SUNWam/samples/admin/cli/bulk-ops/. Instructions can be found in Readme.html at /AccesManager-base /SUNWam/samples/admin/cli/.

Session Upgrade

The Authentication service enables you to upgrade a valid session token based on a second, successful authentication performed by the same user to one realm. If a user with a valid session token attempts to authenticate to a resource secured by his current realm and this second authentication request is successful, the session is updated with the new properties based on the new authentication. If the authentication fails, the user’s current session is returned without an upgrade. If the user with a valid session attempts to authenticate to a resource secured by a different realm, the user will receive a message asking whether they would like to authenticate to the new realm. The user can, at this point, maintain the current session or attempt to authenticate to the new realm. Successful authentication will result in the old session being destroyed and a new one being created.

During session upgrade, if a login page times out, redirection to the original success URL will occur. Timeout values are determined based on:

The page timeout value set for each module (default is 1 minute)
com.iplanet.am.invalidMaxSessionTime property in AMConfig.properties (default is 10 minutes)
iplanet-am-max-session-time (default is 120 minutes)

The values of com.iplanet.am.invalidMaxSessionTimeout and iplanet-am-max-session-time should be greater than the page timeout value, or the valid session information during session upgrade will be lost and URL redirection to the previous successful URL will fail.

Validation Plug-in Interface

An administrator can write username or password validation logic suitable to their realm, and plug this into the Authentication Service. (This functionality is supported only by the LDAP and Membership authentication modules.) Before authenticating the user or changing the password, Access Manager will invoke this plug-in. If the validation is successful, authentication continues; if it fails, an authentication failed page will be thrown. The plug-in extends the com.iplanet.am.sdk.AMUserPasswordValidation class which is part of the Service Management SDK. Information on this SDK can be found in the com.iplanet.am.sdk package in the Access Manager Javadocs.

To Write and Configure a Validation Plug-in

The new plug-in class will extend the com.iplanet.am.sdk. AMUserPasswordValidation class and implement the validateUserID() and validatePassword() methods. AMException should be thrown if validation fails.

Compile the plug-in class and place the .class file in the desired location. Update the classpath so that it is accessible by the Access Manager during runtime.

Login to the Access Manager console as top-level administrator. Click on the Configuration tab, and go to the attributes for the Administration Service. Type the name of the plug-in class (including the package name) in the UserID & Password Validation Plugin Class field.

Logout and login.

JAAS Shared State

The JAAS shared state provides sharing of both user ID and password between authentication modules. Options are defined for each authentication module for:

Realm (or, Organization)
User
Service
Role

Upon failure, the module prompts for its required credentials. After failed authentication, the module stops running, or the logout shared state clears.

Enabling JAAS Shared State

To configure the JAAS shared state:

Use the iplanet-am-auth-shared-state-enabled option.
The usage for the shared state option is:iplanet-am-auth-shared-state-enabled=true
The default for this option is true.
This variable is specified in the Options column of the authentication chaining configuration.

Upon failure, the authentication module will prompt for the required credentials as per the tryFirstPass option behavior suggested in the JAAS specification.

JAAS Shared State Store Option

To configure the JAAS shared state store option:

Use the iplanet-amauth-store-shared-state-enabled option.
The usage for the store shared state option is:iplanet-am-auth-store-shared-state-enabled=true
The default for this option is false.
This variable is specified in the Options column of the authentication chaining configuration.

After a commit, an abort or a logout, the shared state will be cleared.