OpenAM Administration Guide
Chapter 2. Defining Authentication Services

Procedure 2.1. To Create an Authentication Chain

1. On the Access Control tab page of the OpenAM console, click the realm for which to create the authentication chain.

2. On the Authentication tab page for the realm, scroll to the bottom of the page, and click the New button in the Authentication Chaining table.

3. Give the new authentication chain a name, and add instances of the modules to use in the chain.

4. Assign appropriate criteria (optional, required, requisite, sufficient) as described above in Section 2.1, “About Authentication in OpenAM”. You can also configure where OpenAM redirects the user upon successful and failed authentication, and plug in your post-authentication processing classes as necessary.

5. If you need modules in the chain to share user credentials, then set options for the module.

   iplanet-am-auth-shared-state-enabled

   Set iplanet-am-auth-shared-state-enabled=true to allow subsequent modules in the authentication chain to use the credentials, such as user name and password, captured by this module. (Default: true)

   iplanet-am-auth-store-shared-state-enabled

   Set iplanet-am-auth-store-shared-state-enabled=true to store the captured credentials. Shared state is cleared when the user successfully authenticates, quits the chain, or logs out. (Default: false)

   iplanet-am-auth-shared-state-behavior-pattern

   Set iplanet-am-auth-shared-state-behavior-pattern=tryFirstPass (the default) to try authenticating with the captured password. If authentication fails, then OpenAM prompts the user for the credentials again.

   Set iplanet-am-auth-shared-state-behavior-pattern=useFirstPass to authenticate with the captured password. If authentication fails, then the module fails.

   For example, consider a chain with two modules sharing credentials according to the default settings. The first module in the chain has the option iplanet-am-auth-shared-state-enabled=true, and criteria REQUIRED. The second module in the chain has options iplanet-am-auth-shared-state-enabled=true, iplanet-am-auth-shared-state-behavior-pattern=tryFirstPass, and criteria REQUIRED. A successful authentication sequence happens as follows. The user enters her credentials for the first module, successfully authenticating. The first module shares the credentials with the second module, successfully authenticating the user without prompting again for her credentials, unless the credentials for the first module do not successfully authenticate here to the second module. Just be sure to separate the options with a space and not a comma.

6. Save your work.

Procedure 2.2. To Select the Default Chain

Before you select the default chain for users, and especially for administrators, test the authentication chain first. For example, http://openam.example.com:8080/openam/UI/Login?service=NewChain. If you cannot log in, then go back and fix the authentication chain's configuration before making it the default.

1. On the Access Control tab page of the OpenAM console, click the realm for which to set the default authentication chain.

2. If necessary, on the Authentication tab page for the realm, adjust the drop-down lists for Organization Authentication Configuration and Administrator Authentication Configuration to the appropriate authentication chains.

   The Organization Authentication Configuration serves when users access /openam/UI/Login.

   The Administrator Authentication Configuration serves when users access /openam/console.

   You can set these independently to separate administrative login from user login. For example, you can change the default user chain, but leave the default administrator chain as is to avoid locking yourself out as administrator. By default, amadmin can login at /openam/UI/Login. You can change that for your deployment.

3. Save your work.