Chapter 2. Defining Authentication Services
Prev |  | Next

# Chapter 2. Defining Authentication Services

An authentication service confirms the identity of a user or a client application.

This chapter describes how to configure authentication in OpenAM.

## 2.1. About Authentication in OpenAM

Access management is about controlling access to resources. OpenAM plays a role similar to border control at an international airport. Instead of having each and every airline company deal with access to each destination, all airlines redirects passengers to border control. Border control then determines who each passenger is according to passport credentials. Border control also checks whether the identified passenger is authorized to fly to the destination corresponding to the ticket, perhaps based on visa credentials. Then, at the departure gate, an agent enforces the authorization from border control, allowing the passenger to board the plane as long as the passenger has not gotten lost, or tried to board the wrong plane, or swapped tickets with someone else. Thus, border control handles access management at the airport.

OpenAM is most frequently used to protect web-accessible resources. Users browse to a protected web application page. An agent installed on the server with the web application redirects the user to OpenAM for access management. OpenAM determines who the user is, and whether the user has the right to access the protected page. OpenAM then redirects the user back to the protected page, with authorization credentials that can be verified by the agent. The agent allows OpenAM authorized users access the page.

Notice that OpenAM basically needs to determine two things for access management: the identity of the user, and whether the user has access rights to the protected page. Authentication is how OpenAM identifies the user. This chapter covers how to set up the authentication process. Authorization is how OpenAM determines whether a user has access to a protected resource. Authorization is covered later.

For authentication, OpenAM uses credentials from the user or client application. It then uses defined mechanisms to validate credentials and complete the authentication. The authentication methods can vary. For example, passengers travelling on international flights authenticate with passports and visas. In contrast, passengers travelling on domestic flights might authenticate with an identity card or a driver's license. Customers withdrawing cash from an ATM authenticate with a card and a PIN.

OpenAM allows you to configure authentication processes and then customize how they are applied. OpenAM uses authentication modules to handle different ways of authenticating. Basically, each authentication module handles one way of obtaining and verifying credentials. You can chain different authentication modules together. In OpenAM, this is called authentication chaining. Each authentication module can be configured to specify the continuation and failure semantics with one of the following four flags: required, optional, requisite, or sufficient.[3]

- When a required module fails, the rest of the chain is processed, but the authentication fails.

  A required module might be used for login with email and password, but then fall through to another module to handle new users who have not yet signed up.

- When an optional module fails, authentication continues.

  An optional module might be used to permit a higher level of access if the user can present a X.509 certificate for example.

- When a requisite module fails, authentication fails and authentication processing stops.

  A requisite module might be used with exclusive SSO.

- When a sufficient succeeds, authentication is successful and later modules in the chain are skipped.

  You could set Windows Desktop SSO as sufficient, so authenticated Windows users are let through, whereas web users have to traverse another authentication module such as one requiring an email address and a password.

With OpenAM, you can further set authentication levels per module, with higher levels being used typically to allow access to more restricted resources. The OpenAM SPIs also let you develop your own authentication modules, and post-authentication plugins. Client applications can specify the authentication level, module, user, and authentication service to use among those you have configured. As described later in this guide, you can use realms to organize which authentication process applies for different applications or different domains, perhaps managed by different people.

When a user successfully authenticates, OpenAM creates a session, which allows OpenAM to manage that user's access to resources. In some deployments you need to limit how many active sessions a user can have at a given time. For example, you might want to prevent a user from using more than two devices at once. See Section 2.7, “Configuring Session Quotas” for instructions.

OpenAM leaves the authentication process flexible so that you can adapt how it works to your situation. Although at first the number of choices can seem daunting, now that you understand the basic process, you begin to see how choosing authentication modules and arranging them in authentication chains lets you use OpenAM to protect access to a wide range of applications used in your organization.

## 2.2. Configuring Authentication Modules

The OpenAM console provides two places where the OpenAM administrator can configure authentication modules.

1. Under Configuration > Authentication, you configure available modules for use throughout OpenAM. What you set up here is inherited for use elsewhere.

2. Under Access Control > `Realm Name` > Authentication, you configure modules for your realm. What you set up at this level inherits from the global configuration, but you can override what is inherited. You can also add your own modules if necessary.

The configuration of individual modules depend on its function. The configuration of an Active Directory over LDAP user authentication module requires connection information and details about where to search for users. In contrast, the configuration of the HOTP module for OTP authentication requires data about the password length and the mail server or SMS gateway for to send the password during authentication.

### 2.2.1. Hints For the Active Directory Authentication Module

OpenAM connects to Active Directory over Lightweight Directory Access Protocol (LDAP). OpenAM provides separate Active Directory and LDAP modules to support the use of both Active Directory and another directory service in an authentication chain.

ssoadm service name: `sunAMAuthADService`

Primary Active Directory Server, Secondary Active Directory Server

  The default port for LDAP is 389. If you are connecting to Active Directory over SSL, the default port for LDAP/SSL is 636.

  To allow users to change passwords through OpenAM, Active Directory requires that you connect over SSL.

  If you want to use SSL or TLS for security, then scroll down to enable SSL/TLS Access to Active Directory Server. Make sure that OpenAM can trust the Active Directory certificate when using this option.

  OpenAM first attempts to contact primary servers. If no primary server is available, then OpenAM attempts to contact secondaries.

  When authenticating users from a directory server that is remote from OpenAM, set both the primary and secondary server values.

  ssoadm attributes: primary is `iplanet-am-auth-ldap-server`; secondary is `iplanet-am-auth-ldap-server2`

DN to Start User Search

  LDAP data is organized hierarchically, a bit like a file system on Windows or UNIX. More specific DNs likely result in better performance. When configuring the module for a particular part of the organization, you can perhaps start searches from a specific organizational unit such as `OU=sales,DC=example,DC=com`.

  If multiple entries exist with identical search attribute values, make this value specific enough to return only one entry.

  ssoadm attribute: `iplanet-am-auth-ldap-base-dn`

Bind User DN, Bind User Password

  If OpenAM stores attributes in Active Directory, for example to manage account lockout, or if Active Directory requires that OpenAM authenticate in order to read users' attributes, then OpenAM needs the DN and password to authenticate to Active Directory.

  The default is `amldapuser`. If the administrator authentication chain (default: `ldapService`) has been configured to include only the Active Directory module, then make sure that the password is correct before you logout. If it is incorrect, you will be locked out. If you do get locked out, you can login with the super user DN, which by default is `uid=amAdmin,ou=People,`OpenAM-deploy-base``, where `OpenAM-deploy-base` was set during OpenAM configuration.

  ssoadm attributes: `iplanet-am-auth-ldap-bind-dn` and `iplanet-am-auth-ldap-bind-passwd`

Attributes Used to Retrieve User Profile, Attributes Used to Search for a User to be Authenticated, User Search Filter, Search Scope

  LDAP searches for user entries return entries with attribute values matching the filter you provide. For example if you search under `CN=Users,DC=example,DC=com` with a filter `"(MAIL=bjensen@example.com)"`, then the directory returns the entry that has `MAIL=bjensen@example.com`. In this example the attribute used to search for a user is `mail`. Multiple attribute values mean the user can authenticate with any one of the values. For example, if you have both `uid` and `mail`, then Barbara Jensen can authenticate with either `bjensen` or `bjensen@example.com`.

  The User Search Filter text box provides a more complex filter. For example, if you search on `mail` and add User Search Filter `(objectClass=inetOrgPerson)`, then OpenAM uses the resulting search filter `(&(mail=`address`) (objectClass=inetOrgPerson))`, where `address` is the mail address provided by the user.

  This controls how and the level of the directory that will be searched. You can set the search to run at a high level or against a specific area.

  - OBJECT will search only for the entry specified as the DN to Start User Search.

  - ONELEVEL will search only the entries that are directly children of that object.

  - SUBTREE will search the entry specified and every entry under it.

  ssoadm attributes: `iplanet-am-auth-ldap-user-naming-attribute`, `iplanet-am-auth-ldap-user-search-attributes`, `iplanet-am-auth-ldap-search-filter`, and `iplanet-am-auth-ldap-search-scope`

SSL/TLS Access to Active Directory Server

  If you enable SSL/TLS, OpenAM must be able to trust Active Directory certificates, either because the Active Directory certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

  ssoadm attribute: `iplanet-am-auth-ldap-ssl-enabled`

Return User DN to DataStore

  When enabled, and OpenAM uses Active Directory as the user store, the module returns the DN rather than the User ID, so the bind for authentication can be completed without a search to retrieve the DN.

  ssoadm attribute: `iplanet-am-auth-ldap-return-user-dn`

User Creation Attributes

  This list lets you map (external) attribute names from Active Directory to (internal) attribute names used by OpenAM.

  ssoadm attribute: `iplanet-am-ldap-user-creation-attr-list`

LDAP Connection Heartbeat Interval

  Specifies how often OpenAM should send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval use LDAP Connection Heartbeat Time Unit.

  Default: 1

  ssoadm attribute: `openam-auth-ldap-heartbeat-interval`

LDAP Connection Heartbeat Time Unit

  Specifies the time unit corresponding to LDAP Connection Heartbeat Interval.

  Default: minute

  ssoadm attribute: `openam-auth-ldap-heartbeat-interval`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `sunAMAuthADAuthLevel`

### 2.2.2. Hints For the Adaptive Risk Authentication Module

The Adaptive Risk module is designed to assess risk during authentication so that OpenAM can determine whether to require the user to complete further authentication steps. After configuring the Adaptive Risk module, insert it in your authentication chain with criteria set to sufficient as shown in the following example.

[D]

In the example authentication chain shown, OpenAM has users authenticate first using the LDAP module providing a user ID and password combination. Upon success, OpenAM calls the Adaptive Risk module. The Adaptive Risk module assesses the risk based on your configured parameters. If the Adaptive Risk module calculates a total score below the threshold you set, the module returns success, and OpenAM finishes authentication processing without requiring further credentials. Otherwise the Adaptive Risk module evaluates the score to be above the risk threshold, and returns failure. OpenAM then calls the HOTP module, requiring the user to authenticate with a one-time password delivered to her by email or by SMS to her mobile phone.

When you configure the Adaptive Risk module to save cookies and profile attributes after successful authentication, OpenAM performs the save as post-authentication processing, only after the entire authentication chain returns success. You must set up OpenAM to save the data as part of post-authentication processing by editing the authentication chain to add `org.forgerock.openam.authentication.modules.adaptive.Adaptive` to the list of post authentication plugins.

ssoadm service name: `sunAMAuthAdaptiveService`

General

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `openam-auth-adaptive-auth-level`

Risk Threshold

  Risk threshold score. If the sum of the Scores is greater than the threshold, the Adaptive Risk module returns failure. Default: 1

  ssoadm attribute: `openam-auth-adaptive-auth-threshold`

Failed Authentications

Failed Authentication Check

  When enabled, check the user profile for authentication failures since the last successful login. This check therefore requires OpenAM to have access to the user profile, and Account Lockout to be enabled (otherwise OpenAM does not record authentication failures).

  ssoadm attribute: `openam-auth-adaptive-failure-check`

Score

  Value to add to the total score if the user fails the Failed Authentication Check. Default: 1

  ssoadm attribute: `openam-auth-adaptive-failure-score`

Invert Result

  When selected, add the Score to the total score if the user passes the Failed Authentication Check.

  ssoadm attribute: `openam-auth-adaptive-failure-invert`

IP Address Range

IP Range Check

  When enabled, check whether the client IP address is within one of the specified IP Ranges.

  ssoadm attribute: `openam-auth-adaptive-ip-range-check`

IP Range

  For IPv4, specifies a list of IP ranges either in CIDR-style notation (``x.x.x.x`/`YY``) or as a range from one address to another (``x.x.x.x`-`y.y.y.y``, meaning from `x.x.x.x` to `y.y.y.y`).

  For IPv6, specifies a list of IP ranges either in CIDR-style notation (``X:X:X:X:X:X:X:X`/`YY``) or as a range from one address to another (``X:X:X:X:X:X:X:X`-`Y:Y:Y:Y:Y:Y:Y:Y``, meaning from `X:X:X:X:X:X:X:X` to `Y:Y:Y:Y:Y:Y:Y:Y`).

  ssoadm attribute: `openam-auth-adaptive-ip-range-range`

Score

  Value to add to the total score if the user fails the IP Range Check. Default: 1

  ssoadm attribute: `openam-auth-adaptive-ip-range-score`

Invert Result

  When selected, add the Score to the total score if the user passes the IP Range Check.

  ssoadm attribute: `openam-auth-adaptive-ip-range-invert`

IP Address History

IP History Check

  When enabled, check whether the client IP address matches one of the known values stored on the profile attribute you specify. This check therefore requires that OpenAM have access to the user profile.

  ssoadm attribute: `openam-auth-adaptive-ip-history-check`

History Size

  Specifies how many IP address values to retain on the profile attribute you specify. Default: 5

  ssoadm attribute: `openam-auth-ip-adaptive-history-count`

Profile Attribute Name

  Name of the user profile attribute on which to store known IP addresses. Default: `iphistory`

  ssoadm attribute: `openam-auth-adaptive-ip-history-attribute`

Save Successful IP Address

  When enabled, save new client IP addresses to the known IP address list following successful authentication.

  ssoadm attribute: `openam-auth-adaptive-ip-history-save`

Score

  Value to add to the total score if the user fails the IP History Check. Default: 1

  ssoadm attribute: `openam-auth-adaptive-ip-history-score`

Invert Result

  When selected, add the Score to the total score if the user passes the IP History Check.

  ssoadm attribute: `openam-auth-adaptive-ip-history-invert`

Known Cookie

Cookie Value Check

  When enabled, check whether the client browser request has the specified cookie and optional cookie value.

  ssoadm attribute: `openam-auth-adaptive-known-cookie-check`

Cookie Name

  Specifies the name of the cookie for which OpenAM checks when you enable the Cookie Value Check.

  ssoadm attribute: `openam-auth-adaptive-known-cookie-name`

Cookie Value

  Specifies the value of the cookie for which OpenAM checks. If no value is specified, OpenAM does not check the cookie value.

  ssoadm attribute: `openam-auth-adaptive-known-cookie-value`

Save Cookie Value on Successful Login

  When enabled, save the cookie as specified in the client's browser following successful authentication. If no Cookie Value is specified, the value is set to 1.

  ssoadm attribute: `openam-auth-adaptive-known-cookie-save`

Score

  Value to add to the total score if user passes the Cookie Value Check. Default: 1

  ssoadm attribute: `openam-auth-adaptive-known-cookie-score`

Invert Result

  When selected, add the Score to the total score if the user passes the Cookie Value Check.

  ssoadm attribute: `openam-auth-adaptive-known-cookie-invert`

Device Cookie

Device Registration Cookie Check

  When enabled, check whether the client browser request has the specified cookie with the correct device registration identifier as the value.

  ssoadm attribute: `openam-auth-adaptive-device-cookie-check`

Cookie Name

  Specifies the name of the cookie for the Device Registration Cookie Check. Default: Device

  ssoadm attribute: `openam-auth-adaptive-device-cookie-name`

Save Device Registration on Successful Login

  When enabled, save the specified cookie with a hashed device identifier value in the client's browser following successful authentication.

  ssoadm attribute: `openam-auth-adaptive-device-cookie-save`

Score

  Value to add to the total score if the user fails the Device Registration Cookie Check. Default: 1

  ssoadm attribute: `openam-auth-adaptive-device-cookie-score`

Invert Result

  When selected, add the Score to the total score if the user passes the Device Registration Cookie Check.

  ssoadm attribute: `openam-auth-adaptive-device-cookie-invert`

Time Since Last Login

Time Since Last Login Check

  When enabled, check whether the client browser request has the specified cookie that holds the encrypted last login time, and check that the last login time is more recent than a maximum number of days you specify.

  ssoadm attribute: `openam-auth-adaptive-time-since-last-login-check`

Cookie Name

  Specifies the name of the cookie holding the encrypted last login time value.

  ssoadm attribute: `openam-auth-adaptive-time-since-last-login-cookie-name`

Max Time since Last Login

  Specifies a threshold age of the last login time in days. If the client's last login time is more recent than the number of days specified, then the client successfully passes the check.

  ssoadm attribute: `openam-auth-adaptive-time-since-last-login-value`

Save time of Successful Login

  When enabled, save the specified cookie with the current time encrypted as the last login value in the client's browser following successful authentication.

  ssoadm attribute: `openam-auth-adaptive-time-since-last-login-save`

Score

  Value to add to the total score if the user fails the Time Since Last Login Check. Default: 1

  ssoadm attribute: `openam-auth-adaptive-time-since-last-login-score`

Invert Result

  When selected, add the Score to the total score if the user passes the Time Since Last Login Check.

  ssoadm attribute: `openam-auth-adaptive-time-since-last-login-invert`

Profile Attribute

Profile Risk Attribute check

  When enabled, check whether the user profile contains the specified attribute and value.

  ssoadm attribute: `openam-auth-adaptive-risk-attribute-check`

Attribute Name

  Specifies the attribute to check on the user profile for the specified value.

  ssoadm attribute: `openam-auth-adaptive-risk-attribute-name`

Attribute Value

  Specifies the value to match on the profile attribute. If the attribute is multi-valued, a single match is sufficient to pass the check.

  ssoadm attribute: `openam-auth-adaptive-risk-attribute-value`

Score

  Value to add to the total score if the user fails the Profile Risk Attribute Check. Default: 1

  ssoadm attribute: `openam-auth-adaptive-risk-attribute-score`

Invert Result

  When selected, add the Score to the total score if the user passes the Profile Risk Attribute Check.

  ssoadm attribute: `openam-auth-adaptive-risk-attribute-invert`

Geo Location

Geolocation Country Code Check

  When enabled, check whether the client IP address location matches a country specified in the Valid Country Codes list. The

  ssoadm attribute: `forgerock-am-auth-adaptive-geo-location-check`

Geolocation Database location

  Path to GeoIP data file used to convert IP addresses to country locations. The geolocation database is not packaged with OpenAM. You can downloaded the GeoIP Country database from MaxMind. Use the binary .dat file format, rather than .csv. You can use the GeoLite Country database for testing.

  ssoadm attribute: `openam-auth-adaptive-geo-location-database`

Valid Country Codes

  Specifies the list of country codes to match. Use `|` to separate multiple values.

  ssoadm attribute: `openam-auth-adaptive-geo-location-values`.

Score

  Value to add to the total score if the user fails the Geolocation Country Code Check. Default: 1

  ssoadm attribute: `openam-auth-adaptive-geo-location-score`

Invert Result

  When selected, add the Score to the total score if the user passes the Geolocation Country Code Check.

  ssoadm attribute: `openam-auth-adaptive-geo-location-invert`

Request Header

Request Header Check

  When enabled, check whether the client browser request has the specified header with the correct value.

  ssoadm attribute: `openam-auth-adaptive-req-header-check`

Request Header Name

  Specifies the name of the request header for the Request Header Check.

  ssoadm attribute: `openam-auth-adaptive-req-header-name`

Request Header Value

  Specifies the value of the request header for the Request Header Check.

  ssoadm attribute: `openam-auth-adaptive-req-header-value`

Score

  Value to add to the total score if the user fails the Request Header Check. Default: 1

  ssoadm attribute: `openam-auth-adaptive-req-header-score`

Invert Result

  When selected, add the Score to the total score if the user passes the Request Header Check.

  ssoadm attribute: `openam-auth-adaptive-req-header-invert`

### 2.2.3. Hints For the Anonymous Authentication Module

This module lets you track and manage anonymous users, perhaps forcing further authentication later when a user moves to access resources that require more protection.

ssoadm service name: `iPlanetAMAuthAnonymousService`

Valid Anonymous Users

  Specifies valid anonymous user IDs in addition to the default.

  ssoadm attribute: `iplanet-am-auth-anonymous-users-list`

Default Anonymous User Name

  Specifies the user ID assigned by the module if the Valid Anonymous Users list is empty. Default: `anonymous`

  ssoadm attribute: `iplanet-am-auth-anonymous-default-user-name`

Case Sensitive User IDs

  Determines whether case matters for anonymous user IDs.

  ssoadm attribute: `iplanet-am-auth-anonymous-case-sensitive`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-anonymous-auth-level`

### 2.2.4. Hints For the Certificate Authentication Module

X.509 digital certificates can enable secure authentication without the need for user names and passwords or other credentials. Certificate authentication can be handy to manage authentication by applications. If all certificates are signed by a recognized Certificate Authority (CA), then you might get away without additional configuration. If you need to look up public keys of OpenAM clients, this module can also look up public keys in an LDAP directory server.

When you store certificates and certificate revocation lists (CRL) in an LDAP directory service, you must configure both how to access the directory service and also how to look up the certificates and CRLs, based on the fields in the certificates that OpenAM clients present to authenticate.

Access to the LDAP server and how to search for users is similar to LDAP module configuration as in Section 2.2.12, “Hints For the LDAP Authentication Module”. The primary difference is that, unlike for LDAP configuration, OpenAM retrieves the user identifier from a field in the certificate that the client application presents, then uses that identifier to search for the LDAP directory entry that holds the certificate, which should match the certificate presented. For example, if the Subject field of a typical certificate has a DN `C=FR, O=Example Corp, CN=Barbara Jensen`, and Barbara Jensen's entry in the directory has `cn=Barbara Jensen`, then you can use `CN=Barbara Jensen` from the Subject DN to search for the entry with `cn=Barbara Jensen` in the directory.

ssoadm service name: `iPlanetAMAuthCertService`

Match Certificate in LDAP

  When enabled, OpenAM searches for a match for the user's certificate in the LDAP directory. If a match is found and not revoked according to a CRL or OCSP validation, then authentication succeeds.

  ssoadm attribute: `iplanet-am-auth-cert-check-cert-in-ldap`

Subject DN Attribute Used to Search LDAP for Certificates

  Indicates which attribute and value in the certificate Subject DN is used to find the LDAP entry holding the certificate.

  Default: CN

  ssoadm attribute: `iplanet-am-auth-cert-attr-check-ldap`

Match Certificate to CRL

  When enabled, OpenAM checks whether the certificate has been revoked according to a CRL in the LDAP directory.

  ssoadm attribute: `iplanet-am-auth-cert-check-crl`

Issuer DN Attribute Used to Search LDAP for CRLs

  Indicates which attribute and value in the certificate Issuer DN is used to find the CRL in the LDAP directory.

  Default: CN

  If only one attribute is specified, the LDAP search filter used to find the CRL based on the Subject DN of the CA certificate is `(`attr-name`=`attr-value-in-subject-DN`)`.

  For example, if the subject DN of the issuer certificate is `C=US, CN=Some CA, serialNumber=123456`, and the attribute specified is `CN`, then the LDAP search filter used to find the CRL is `(CN=Some CA)`.

  In order to distinguish among different CRLs for the same CA issuer, specify multiple attributes separated by commas (`,`) in the same order they occur in the subject DN. When multiple attribute names are provided in a comma-separated list, the LDAP search filter used is `(cn=`attr1`=`attr1-value-in-subject-DN`,`attr2`=`attr2-value-in-subject-DN`,...,`attrN`=`attrN-value-in-subject-DN`)`.

  For example, if the subject DN of the issuer certificate is `C=US, CN=Some CA, serialNumber=123456`, and the attributes specified are `CN,serialNumber`, then the LDAP search filter used to find the CRL is `(cn=CN=Some CA,serialNumber=123456)`.

  ssoadm attribute: `iplanet-am-auth-cert-attr-check-crl`

HTTP Parameters for CRL Update

  Your certificate authority should provide the URL to use here, from which OpenAM can get CRL updates.

  ssoadm attribute: `iplanet-am-auth-cert-param-get-crl`

Match CA Certificate to CRL

  When enabled, OpenAM checks the CRL against the CA certificate to ensure it has not been compromised.

  ssoadm attribute: `sunAMValidateCACert`

Cache CRLs in Memory

  When enabled, CRLs will be cached.

  ssoadm attribute: `openam-am-auth-cert-attr-cache-crl`

Update CA CRLs from CRLDistributionPoint

  When enabled, OpenAM updates CRLs from the LDAP directory store.

  ssoadm attribute: `openam-am-auth-cert-update-crl`

OCSP Validation

  Enable this to use Online Certificate Status Protocol (OCSP) instead of CRLs to check certificates' revocation status.

  If you enable this, you also must configure OSCP for OpenAM under Configuration > Server and Sites > Default Server Settings, or Configuration > Server and Sites > `Server Name` > Security.

  ssoadm attribute: `iplanet-am-auth-cert-check-ocsp`

LDAP Server Where Certificates are Stored

  Identifies the LDAP server with certificates. Remember to specify URLs with appropriate port numbers (389 for unencrypted LDAP, 636 for LDAP over SSL). When configuring a secure connection, scroll down to enable Use SSL/TLS for LDAP Access.

  ssoadm attribute: `iplanet-am-auth-cert-ldap-provider-url`

LDAP Search Start or Base DN

  Valid base DN for the LDAP search, such as `dc=example,dc=com`.

  ssoadm attribute: `iplanet-am-auth-cert-start-search-loc`

LDAP Server Authentication User, LDAP Server Authentication Password

  If OpenAM stores attributes in the LDAP directory, for example to manage account lockout, or if the LDAP directory requires that OpenAM authenticate in order to read users' attributes, then OpenAM needs the DN and password to authenticate to the LDAP directory.

  ssoadm attributes: `iplanet-am-auth-cert-principal-user`, and `iplanet-am-auth-cert-principal-passwd`

Use SSL/TLS for LDAP Access

  If you use SSL/TLS for LDAP access, OpenAM must be able to trust the LDAP server certificate.

  ssoadm attribute: `iplanet-am-auth-cert-use-ssl`

Certificate Field Used to Access User Profile

  If the user profile is in a different entry from the user certificate, then this can be different from subject DN attribute used to find the entry with the certificate. When you select other, provide an attribute name in the Other Certificate Field Used to Access User Profile text box.

  ssoadm attribute: `iplanet-am-auth-cert-user-profile-mapper`

Other Certificate Field Used to Access User Profile

  This field is only used if the Certificate Field Used to Access User Profile attribute is set to other. This field allows a custom certificate field to be used as the basis of the user search.

  ssoadm attribute: `iplanet-am-auth-cert-user-profile-mapper-other`

SubjectAltNameExt Value Type to Access User Profile

  Use this if you want to look up the user profile from an RFC 822 style name, or a User Principal Name as used in Active Directory.

  ssoadm attribute: `iplanet-am-auth-cert-user-profile-mapper-ext`

Trusted Remote Hosts

  Hosts trusted to send certificates to OpenAM, such as load balancers doing SSL termination, or OpenAM distributed authentication UI instances.

  ssoadm attribute: `iplanet-am-auth-cert-gw-cert-auth-enabled`

HTTP Header Name for Client Certificate

  If you configure trusted hosts, specify the HTTP header name for the client certificate inserted by the trusted host.

  ssoadm attribute: `sunAMHttpParamName`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-cert-auth-level`

### 2.2.5. Hints For the Core Authentication Module

The Core module is a meta-module.

The Core module lets you set up the list of modules available, and specify what types of client applications can authenticate with which modules. It also lets you configure connection pools for access to directory servers, and whether to retain objects used during authentication for use during logout. Furthermore, the Core module lets you set defaults used when configuring authentication in a particular realm.

The Core Authentication module is divided into seven sections:

- Section 2.2.5.1, “Core - Global Attributes”

- Section 2.2.5.2, “Core - Realm Attributes”

- Section 2.2.5.3, “Core - Persistent Cookie (Legacy)”

- Section 2.2.5.4, “Core - Account Lockout”

- Section 2.2.5.5, “Core - General”

- Section 2.2.5.6, “Core - Security”

- Section 2.2.5.7, “Core - Post Authentication Processing”

ssoadm service name: `iPlanetAMAuthService`

#### 2.2.5.1. Core - Global Attributes

The Global Attributes includes the list of available modules, LDAP connection settings, authentication process options, and an option to make the XUI the default interface. The Global Attributes are defined in the Authentication Configuration section of the OpenAM Reference Guide.

#### 2.2.5.2. Core - Realm Attributes

This section of the Core Authentication module is on the Realm Attributes section page before options for Persistent Cookies.

User Profile, User Profile

  Whether a user profile needs to exist in the user data store, or should be created on successful authentication.

  Dynamic

    Specifies that on successful authentication the Authentication Service creates a user profile if one does not already exist. OpenAM then issues the SSOToken. OpenAM creates the user profile in the user data store configured for the realm.

  Dynamic with User Alias

    Specifies that on successful authentication the Authentication Service creates a user profile that contains the User Alias List attribute which defines one or more aliases that for mapping a user's multiple profiles.

  Ignored

    Specifies that a user profile is not required for the Authentication Service to issue an SSOToken after a successful authentication.

  Required

    Specifies that on successful authentication the user must have a user profile in the user data store configured for the realm in order for the Authentication Service to issue an SSOToken.

  ssoadm attribute: `iplanet-am-auth-dynamic-profile-creation`

User Profile Dynamic Creation Default Roles

  Specifies the Distinguished Name (DN) of a role to be assigned to a new user whose profile is created when either of the Dynamic options is selected under the User Profile attribute. There are no default values. The role specified must be within the realm for which the authentication process is configured.

  This role can be either an OpenAM or Sun DSEE role, but it cannot be a filtered role. If you wish to automatically assign specific services to the user, you have to configure the Required Services attribute in the User Profile.

  ssoadm attribute: `iplanet-am-auth-default-role`

Alias Search Attribute Name

  After a user is successfully authenticated, the user's profile is retrieved. OpenAM first searches for the user based on the data store settings. If that fails to find the user, OpenAM will use the attributes listed here to lookup the user profile. This setting accepts any data store specific attribute name.

  ssoadm attribute: `iplanet-am-auth-alias-attr-name`

#### 2.2.5.3. Core - Persistent Cookie (Legacy)

This section of the Core Authentication module covers the Persistent Cookie options.

### Note

Two methods are available in OpenAM to configure persistent cookies. The options described here and in Section 2.5, “Authenticating To OpenAM” specify one method. There is also a new module, described in Section 2.2.17, “Hints for the Persistent Cookie Module”. If you want to set up persistent cookies, you are encouraged to use the new module. The options described here have no effect on that module.

Persistent Cookie Mode

  Determines whether users can return to their authenticated session after restarting the browser. When enabled, the persistent cookie can be used to reauthenticate until the persistent cookie expires (as specified by the value of the Persistent Cookie Maximum Time attribute), or until the user explicitly logs out. By default, the Authentication Service uses only memory cookies (expires when the browser is closed).

  The client must explicitly request a persistent cookie by adding `iPSPCookie=yes` as a parameter to the login URL. OpenAM sets a `DProPCookie` as described in Section 2.5, “Authenticating To OpenAM”.

  ssoadm attribute: `iplanet-am-auth-persistent-cookie-mode`

Persistent Cookie Maximum Time

  Specifies the interval after which a persistent cookie expires. The interval begins when the user's session is successfully authenticated. The maximum value is 2147483647 (in seconds, so a bit more than 68 years). The field accepts any integer value less than the maximum.

  ssoadm attribute: `iplanet-am-auth-persistent-cookie-time`

Persistent Cookie Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `openam-auth-pcookie-auth-level`

#### 2.2.5.4. Core - Account Lockout

This section of the Core Authentication module includes details on how account lockouts can be configured.

Login Failure Lockout Mode

  Selecting this attribute enables a physical lockout. Physical lockout will inactivate an LDAP attribute (defined in the Lockout Attribute Name property) in the user's profile. This attribute works in conjunction with several other lockout and notification attributes.

  ssoadm attribute: `iplanet-am-auth-login-failure-lockout-mode`

Login Failure Lockout Count

  Defines the number of attempts that a user has to authenticate, within the time interval defined in Login Failure Lockout Interval, before being locked out.

  ssoadm attribute: `iplanet-am-auth-login-failure-count`

Login Failure Lockout Interval

  Defines the time in minutes during which failed login attempts are counted. If one failed login attempt is followed by a second failed attempt, within this defined lockout interval time, the lockout count starts, and the user is locked out if the number of attempts reaches the number defined in Login Failure Lockout Count. If an attempt within the defined lockout interval time proves successful before the number of attempts reaches the number defined in Login Failure Lockout Count, the lockout count is reset.

  ssoadm attribute: `iplanet-am-auth-login-failure-duration`

Email Address to Send Lockout Notification

  Specify one (or more) email address(es) to which notification is sent if a user lockout occurs.

  Separate multiple addresses with spaces, and append `|`locale`|`charset`` to addresses for recipients in non-English locales.

  ssoadm attribute: `iplanet-am-auth-lockout-email-address`

Warn User After N Failures

  The number of authentication failures after which OpenAM displays a warning message that the user will be locked out.

  ssoadm attribute: `iplanet-am-auth-lockout-warn-user`

Login Failure Lockout Duration

  Defines how many minutes a user must wait after a lockout before attempting to authenticate again. Entering a value greater than 0 enables memory lockout and disables physical lockout. Memory lockout means the user's account is locked in memory for the number of minutes specified. The account is unlocked after the time period has passed.

  ssoadm attribute: `iplanet-am-auth-lockout-duration`

Lockout Duration Multiplier

  Defines a value with which to multiply the value of the Login Failure Lockout Duration attribute for each successive lockout. For example, if Login Failure Lockout Duration is set to 3 minutes, and the Lockout Duration Multiplier is set to 2, the user is locked out of the account for 6 minutes. Once the 6 minutes has elapsed, if the user again provides the wrong credentials, the lockout duration is then 12 minutes. With the Lockout Duration Multiplier, the lockout duration is incrementally increased based on the number of times the user has been locked out.

  ssoadm attribute: `sunLockoutDurationMultiplier`

Lockout Attribute Name

  Defines the LDAP attribute used for physical lockout. The default value is `inetuserstatus`, although the field in the OpenAM console is empty. The Lockout Attribute Value field must also contain an appropriate value.

  ssoadm attribute: `iplanet-am-auth-lockout-attribute-name`

Lockout Attribute Value

  Specifies the action to take on the attribute defined in Lockout Attribute Name. The default value is `inactive`, although the field in the OpenAM console is empty. The Lockout Attribute Name field must also contain an appropriate value.

  ssoadm attribute: `iplanet-am-auth-lockout-attribute-value`

Invalid Attempts Data Attribute Name

  Specifies the LDAP attribute used to hold the number of failed authentication attempts towards Login Failure Lockout Count.

  ssoadm attribute: `sunAMAuthInvalidAttemptsDataAttrName`

Store Invalid Attempts in Data Store

  Enables the storage of information regarding failed authentication attempts as the value of the Invalid Attempts Data Attribute Name in the user data store. In order to store data in this attribute, the OpenAM schema has to be loaded. Information stored includes number of invalid attempts, time of last failed attempt, lockout time and lockout duration. Storing this information in the identity repository allows it to be shared among multiple instances of OpenAM.

  ssoadm attribute: `sunStoreInvalidAttemptsInDS`

#### 2.2.5.5. Core - General

This section of the Core Authentication module includes general options.

Default Authentication Locale

  Specifies the default language subtype to be used by the Authentication Service. The default value is `en_US`.

  ssoadm attribute: `iplanet-am-auth-locale`

Identity Types

  Lists the type or types of identities used during a profile lookup. You can choose more than one to search on multiple types if you would like OpenAM to conduct a second lookup if the first lookup fails. Default: Agent and User

  Agent

    Searches for identities under your agents.

  agentgroup

    Searches for identities according to your established agent group.

  agentonly

    Searches for identities only under your agents.

  Group

    Searches for identities according to your established groups.

  User

    Searches for identities according to your users.

  ssoadm attribute: `sunAMIdentityType`

Pluggable User Status Event Classes

  Specifies one or more Java classes used to provide a callback mechanism for user status changes during the authentication process. The Java class must implement the `com.sun.identity.authentication.spi.AMAuthCallBack` OpenAM interface. OpenAM supports account lockout and password changes. OpenAM supports password changes through the LDAP authentication module, and so the feature is only available for the LDAP module.

  A .jar containing the user status event class belongs in the `WEB-INF/lib` directory of the deployed OpenAM instance. If you do not build a .jar, add the class files under `WEB-INF/classes`.

  ssoadm attribute: `sunAMUserStatusCallbackPlugins`

Default Authentication Level

  Specifies the default authentication level for authentication modules.

  ssoadm attribute: `iplanet-am-auth-default-auth-level`

#### 2.2.5.6. Core - Security

This section of the Core Authentication module includes basic security options.

Module Based Authentication

  Enables users to authenticate using module-based authentication. Otherwise, all attempts at authentication using the `module=`module-name`` login parameter result in failure. It is recommended that this be turned off in a production environment.

  ssoadm attribute: `sunEnableModuleBasedAuth`

Valid goto URL domains

  List external domains to which clients can be redirected after authentication. This attribute requires valid DNS domains that reflect the set policy rules, such as https://website.example.com/* or https://website.example.com/*?*.

  ssoadm attribute: `iplanet-am-auth-valid-goto-domains`

Zero Page Login

  Enables the administrator to allow users to authenticate to a single authentication screen using GET request parameters. Enable this with caution as it can allow credentials to be cached.

  ssoadm attribute: `openam.auth.zero.page.login.enabled`

#### 2.2.5.7. Core - Post Authentication Processing

This section of the Core Authentication module specifies options for post authentication processing.

Default Success Login URL

  Accepts a list of values that specifies where users are directed after successful authentication. The format of this attribute is ``client-type`|`URL`` although the only value you can specify at this time is a URL which assumes the type HTML. The default value is `/openam/console`. Values that do not specify HTTP have that appended to the deployment URI.

  ssoadm attribute: `iplanet-am-auth-login-success-url`

Default Failure Login URL

  Accepts a list of values that specifies where users are directed after authentication has failed. The format of this attribute is ``client-type`|`URL`` although the only value you can specify at this time is a URL which assumes the type HTML. Values that do not specify HTTP have that appended to the deployment URI.

  ssoadm attribute: `iplanet-am-auth-login-failure-url`

Authentication Post Processing Classes

  Specifies one or more Java classes used to customize post authentication processes for successful or unsuccessful logins. The Java class must implement the `com.sun.identity.authentication.spi.AMPostAuthProcessInterface` OpenAM interface.

  A .jar containing the post processing class belongs in the `WEB-INF/lib` directory of the deployed OpenAM instance. If you do not build a .jar, add the class files under `WEB-INF/classes`. For deployment, add the .jar or classes into a custom OpenAM .war file.

  ssoadm attribute: `iplanet-am-auth-post-login-process-class`

Generate UserID Mode

  When enabled, the Membership module generates a list of alternate user identifiers if the one entered by a user during the self-registration process is not valid or already exists. The user identifiers are generated by the class specified in the Pluggable User Name Generator Class property.

  ssoadm attribute: `iplanet-am-auth-username-generator-enabled`

Pluggable User Name Generator Class

  Specifies the name of the class used to generate alternate user identifiers when Generate UserID Mode is enabled. The default value is `com.sun.identity.authentication.spi.DefaultUserIDGenerator`.

  ssoadm attribute: `iplanet-am-auth-username-generator-class`

User Attribute Mapping to Session Attribute

  Enables the authenticating user's identity attributes (stored in the identity repository) to be set as session properties in the user's SSOToken. The value takes the format ``User-Profile-Attribute`|`Session-Attribute-Name``. If `Session-Attribute-Name` is not specified, the value of `User-Profile-Attribute` is used. All session attributes contain the `am.protected` prefix to ensure that they cannot be edited by the Client SDK.

  For example, if you define the user profile attribute as mail and the user's email address (available in the user session) as `user.mail`, the entry for this attribute would be `mail|user.mail`. After a successful authentication, the `SSOToken.getProperty(String)` method is used to retrieve the user profile attribute set in the session. The user's email address is retrieved from the user's session using the `SSOToken.getProperty("am.protected.user.mail")` method call.

  Properties that are set in the user session using User Attribute Mapping to Session Attributes can not be modified (for example, `SSOToken.setProperty(String, String)`). This results in an `SSOException`. Multi-value attributes, such as `memberOf`, are listed as a single session variable with a `|` separator.

  ssoadm attribute: `sunAMUserAttributesSessionMapping`

### 2.2.6. Hints For the Data Store Authentication Module

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.

Yet, the Data Store module is generic. It does not implement data store-specific capabilities such as the password policy and password reset features provided by LDAP modules. Therefore the Data Store module returns failure when such capabilities are invoked.

ssoadm service name: `sunAMAuthDataStoreService`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `sunAMAuthDataStoreAuthLevel`

### 2.2.7. Hints For the Device Print Authentication Module

The Device Print module is a device fingerprinter. It collects information about client device locations, fonts, plugins, and more through their browsers. This module does not stand on its own, as it uses authentication information from a service to validate a username. The Device Print module then validates other characteristics of the user's system.

If no device print profile is stored for a user, then the user is prompted to fill in an HMAC One-Time Password (HOTP), sent by email or text. The user can then save that device print profile. On subsequent requests the user's device profile is recalled. Each of the device print attributes from the client are compared against each of the stored attributes. If the differences exceed a configured number of penalty points, the user is asked for another HOTP.

If you know the HOTP module, some of the attributes in this section may seem familiar. That is intentional, as the Device Print module includes all HOTP attributes, though not in the same order.

### Note

The following example assumes that the Device Print module comes after LDAP authentication. Alternatively, you could set it up after another directory service module such as Active Directory, Data Store, RADIUS, or Windows NT.

[D]

A device fingerprint is based on the unique characteristics of a user like yourself and your associated device. You can configure the characteristics that should be part of the fingerprint. These characteristics can include:

- User agents, associated with the configuration of a web browser.

- Installed fonts.

- The plugins installed for the web browser.

- The resolution and color depth associated with a display

- The timezone or even the geolocation of a device.

You can specify `penalty points` when characteristics of the fingerprint have changed. If the total `penalty points` exceeds some configured score, the user may be asked to verify their identity using HOTP.

The default value for each `*-penalty-points` attribute is 35, with a `*-max-tolerated-penalty-points` of 50. In other words, if more than one characteristic of the device fingerprint has changed, the module assumes that the user is trying to connect from a different system.

ssoadm service name: `iPlanetAMAuthDevicePrintModuleService`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `openam-auth-adaptive-auth-level`

Profile expiration days

  The list of device attributes is collected in a profile, which automatically expires in a given number of days. Default: 30.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-profile-expiration-days`

Maximum stored profile quantity

  The number of device profiles may be limited by user. Default: 5.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-maximum-profiles-stored-quantity`

Automatically store new profiles

  When enabled, new device profiles are automatically stored, once the HOTP is verified. Otherwise, the user is prompted for confirmation.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-store-profiles-without-confirmation`

Default user profile name

  Every device requires a default profile name that represents the user.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-default-profile-name`

User agent penalty points

  Specifies the number of penalty points added when there is a difference between the current and stored user agent. The module adds a fixed number of points if the web browser or related fields are changed. Version differences are ignored if the `User-Agent version ignore` attribute is active. Default: 35.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-user-agent-penalty-points`

Installed fonts penalty points

  Frequently, when a user installs a new software component, additional fonts are installed. The Device Print module adds a fixed number of penalty points if there is a change in the installed fonts since the last login beyond some maximum tolerated level, and the `Installed fonts required` attribute is enabled. Default: 35.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-installed-fonts-penalty-points`

Installed plugins penalty points

  Most devices have a number of plugins installed on their browsers, such as Java, Flash, and document readers. If the plugins feature is enabled, and there is a change beyond a maximum tolerated level, a fixed number of penalty points is added. Default: 35.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-installed-plugins-penalty-points`

Screen color depth penalty points

  Most client devices are connected to a color monitor, or at least have settings related to such a device. If the `Screen parameters` feature is enabled, and a change in color depth is detected, a fixed number of penalty points is added. Default: 35.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-screen-color-depth-penalty-points`

Screen resolution penalty points

  Differences in screen resolution sometimes indicate that the user has changed monitors, or perhaps is adjusting to changing eyesight. Whenever a different screen resolution is detected, a fixed number of penalty points is added. Default: 35.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-screen-resolution-penalty-points`

Timezone penalty points

  Whenever a connection is made from a different timezone, the Device Print module normally adds a fixed number of penalty points. Organizations where most users travel may want to set this attribute to a lower value. Default: 35.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-timezone-penalty-points`

Allowed location range

  If geolocation is enabled, each profile should include a geographic location. The allowed location range specifies a maximum distance, in miles. If a user has travelled beyond that distance, the `Location penalty points` is added to the total. Default: 100.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-location-allowed-range`

User-Agent version ignore

  Upgrades change the version associated with a user agent. Unless this option is enabled, every change in the version of a browser or related fields is detected as a difference with the stored profile.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-ignore-version-in-user-agent`

Max number of tolerated different installed fonts

  If the `Installed fonts required` attribute is enabled, a comparison is made in installed fonts between the existing and stored profiles.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-max-tolerated-diffs-in-installed-fonts`

Max tolerated percentage difference between installed fonts

  If the `Installed fonts required` attribute is enabled, a comparison is made in installed fonts between the existing and stored profiles. Any differences in number of fonts is noted in percent.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-max-tolerated-percentage-to-mark-as-different-installed-fonts`

Max number of tolerated different installed plugins

  If the `Installed plugins required` attribute is enabled, a comparison is made between the installed plugins defined in the existing and stored profiles.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-max-tolerated-diffs-in-installed-plugins`

Max tolerated percentage difference between installed plugins

  If the `Installed plugins required` attribute is enabled, a comparison is made between the installed plugins defined in the existing and stored profiles. Any differences in number of plugins is noted in percent.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-max-tolerated-percentage-to-mark-as-different-plugins`

User agent required

  The user agent, as defined by RFC 4226 Section 14.43 provides information about the browser, and frequently on the operating system. Default: enabled.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-user-agent-required`

Installed plugins required

  Plugins are components that add a specific feature to an existing application. In this context, examples of browser plugins are flash, java, and shockwave.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-plugins-required`

Installed fonts required

  Fonts are frequently added to an operating system when new applications are installed. If enabled, installed font information is stored as part of the profile, and checked upon reconnection for comparison.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-fonts-required`

Geolocation required

  The geographic location of a device can be tracked. Can be used to limit access from this device to a specified range.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-geolocation-required`

Screen parameters required

  Display parameters can be used to help differentiate a profile. If enabled, the Device Print module uses screen color depth and resolution.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-screen-params-required`

Time zone required

  The time zone of the current and stored profiles can be collected and compared.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-timezone-required`

Location penalty points

  If geo-location has been enabled, and the current location does not match the value stored in the profile this many points are added as a penalty. Default: 35.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-location-penalty-points`

Maximum tolerated penalty points

  A limit, in number of points, between the current and stored Device Print profiles. If the total is below that value, the Device Print module sees a match. Default: 50.

  ssoadm attribute: `iplanet-am-auth-adaptive-device-print-max-tolerated-penalty-points`

SMS Gateway Implementation Class

  Change this if you must customize the SMS gateway implementation. The default class sends an SMS or email, depending on the configuration.

  ssoadm attribute: `sunAMAuthHOTPSMSGatewayImplClassName`

Mail Server Host Name

  Host name of the mail server supporting Simple Message Transfer Protocol for electronic mail.

  ssoadm attribute: `sunAMAuthHOTPSMTPHostName`

Mail Server Host Port

  The default outgoing mail server port is 25, 465 (when connecting over SSL).

  ssoadm attribute: `sunAMAuthHOTPSMTPHostPort`

Mail Server Authentication Username

  User name for OpenAM to connect to the mail server.

  ssoadm attribute: `sunAMAuthHOTPSMTPUserName`

Mail Server Authentication Password

  Password for OpenAM to connect to the mail server.

  ssoadm attribute: `sunAMAuthHOTPSMTPUserPassword`

Mail Server Secure Connection

  If OpenAM connects to the mail server securely, OpenAM must be able to trust the server certificate.

  ssoadm attribute: `sunAMAuthHOTPSMTPSSLEnabled`

Email From Address

  The `From:` address when sending a one-time password by mail.

  ssoadm attribute: `sunAMAuthHOTPSMTPFromAddress`

One Time Password Validity Length (in minutes)

  One-time passwords are valid for 5 minutes after they are generated by default.

  ssoadm attribute: `sunAMAuthHOTPPasswordValidityDuration`

One Time Password Length (in digits)

  Set the length of the one-time password to 6 or 8 digits.

  ssoadm attribute: `sunAMAuthHOTPPasswordLength`

One Time Password Delivery

  Send the one-time password by SMS, by mail, or both.

  ssoadm attribute: `sunAMAuthHOTPasswordDelivery`

Mobile Phone Number Attribute Names

  Provides the attribute name used for the text message. The default value is `telephoneNumber`.

  ssoadm attribute: `openamTelephoneAttribute`

Mobile Carrier Attribute Name

  Provides the name of the carrier that will send the text message.

  Every carrier has their own attribute name ending, for example Verizon uses @vtext.com or vtext.com. Contact your mobile carrier to find out what their attribute name is. If you will be sending international texts, ask your carrier if a country code is a required.

  ssoadm attribute: `openamSMSCarrierAttribute`

Email Attribute Name

  Provides the attribute name used to email the OTP. The default value is `mail` (email).

  ssoadm attribute: `openamEmailAttribute`

Auto Send OTP Code

  Setup the HOTP module to automatically generate an email or text message when users begin the login process.

  ssoadm attribute: `sunAMAuthHOTPAutoClicking`

### 2.2.8. Hints For the Federation Authentication Module

The Federation authentication module is used by a service provider to create a user session after validating single sign-on protocol messages. This authentication module is used by the SAML, SAMLv2, ID-FF, and WS-Federation protocols.

ssoadm service name: `sunAMAuthFederationService`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `sunAMAuthFederationAuthLevel`

### 2.2.9. Hints For the HOTP Authentication Module

The HMAC One-Time Password authentication module works together with the Data Store module to retrieve a user's mail address or telephone number to send a one-time password to complete authentication.

To use HOTP you set up an authentication chain with the Data Store module as the `requisite` first module, and the HOTP module as the second `requisite` module. When authentication succeeds against the Data Store module, OpenAM passes the Email Address and Telephone Number attributes from the user profile to the HOTP module. For the HOTP module to use either attribute, the Email Address must contain a valid email address, or the Telephone Number must contain a valid SMS telephone number.

You can set the HOTP module to automatically generate a password when users begin logging into the system. You can also setup a mobile phone, mobile carrier, and email attributes for tighter controls over where the messages are generated and what provider the messages go through to reach the user.

ssoadm service name: `sunAMAuthHOTPService`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `sunAMAuthHOTPAuthLevel`

SMS Gateway Implementation Class

  Change this if you must customize the SMS gateway implementation. The default class sends an SMS or email, depending on the configuration.

  ssoadm attribute: `sunAMAuthHOTPSMSGatewayImplClassName`

Mail Server Host Name

  Host name of the mail server supporting Simple Message Transfer Protocol for electronic mail.

  ssoadm attribute: `sunAMAuthHOTPSMTPHostName`

Mail Server Host Port

  The default outgoing mail server port is 25, 465 (when connecting over SSL).

  ssoadm attribute: `sunAMAuthHOTPSMTPHostPort`

Mail Server Authentication Username

  User name for OpenAM to connect to the mail server.

  ssoadm attribute: `sunAMAuthHOTPSMTPUserName`

Mail Server Authentication Password

  Password for OpenAM to connect to the mail server.

  ssoadm attribute: `sunAMAuthHOTPSMTPUserPassword`

Mail Server Secure Connection

  If OpenAM connects to the mail server securely, OpenAM must be able to trust the server certificate.

  ssoadm attribute: `sunAMAuthHOTPSMTPSSLEnabled`

Email From Address

  The `From:` address when sending a one-time password by mail.

  ssoadm attribute: `sunAMAuthHOTPSMTPFromAddress`

One Time Password Validity Length (in minutes)

  One-time passwords are valid for 5 minutes after they are generated by default.

  ssoadm attribute: `sunAMAuthHOTPPasswordValidityDuration`

One Time Password Length (in digits)

  Set the length of the one-time password to 6 or 8 digits.

  ssoadm attribute: `sunAMAuthHOTPPasswordLength`

One Time Password Delivery

  Send the one-time password by SMS, by mail, or both.

  ssoadm attribute: `sunAMAuthHOTPasswordDelivery`

Mobile Phone Number Attribute Names

  Provides the attribute name used for the text message. The default value is `telephoneNumber`.

  ssoadm attribute: `openamTelephoneAttribute`

Mobile Carrier Attribute Name

  Provides the name of the carrier that will send the text message.

  Every carrier has their own attribute name ending, for example Verizon uses @vtext.com or vtext.com. Contact your mobile carrier to find out what their attribute name is. If you will be sending international texts, ask your carrier if a country code is a required.

  ssoadm attribute: `openamSMSCarrierAttribute`

Email Attribute Name

  Provides the attribute name used to email the OTP. The default value is `mail` (email).

  ssoadm attribute: `openamEmailAttribute`

Auto Send OTP Code

  Setup the HOTP module to automatically generate an email or text message when users begin the login process.

  ssoadm attribute: `sunAMAuthHOTPAutoClicking`

### 2.2.10. Hints For the HTTP Basic Authentication Module

HTTP basic authentication takes a user name and password from HTTP authentication and tries authentication against the backend module in OpenAM, depending on what you configure as the Backend Module Name.

ssoadm service name: `iPlanetAMAuthHTTPBasicService`

Backend Module Name

  Specifies the module that checks the user credentials. The credentials are then supplied to either a Data Store or other identity repository module for authentication.

  ssoadm attribute: `iplanet-am-auth-http-basic-module-configured`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-httpbasic-auth-level`

### 2.2.11. Hints For the JDBC Authentication Module

The Java Database Connectivity (JDBC) module lets OpenAM connect to a database such as MySQL or Oracle DB to authenticate users.

ssoadm service name: `sunAMAuthJDBCService`

Connection Type

  Choose Connection pool is retrieved via JNDI to connect using the Java Naming and Directory Interface connection pool supported by the web container in which OpenAM runs. Choose Non-persistent JDBC connection to connect directly through the JDBC driver.

  ssoadm attribute: `sunAMAuthJDBCConnectionType`

Connection Pool JNDI Name

  When using Connection pool is retrieved via JNDI, this specifies the pool. How you configure connection pooling depends on the web container where you run OpenAM. Refer to the documentation for your web container for instructions on setting up connection pooling.

  ssoadm attribute: `sunAMAuthJDBCJndiName`

JDBC Driver

  When using Non-persistent JDBC connection, this specifies the JDBC driver provided by the database.

  The .jar containing the JDBC driver belongs in the `WEB-INF/lib` directory of the deployed OpenAM instance, and so you should add it to a custom OpenAM .war file that you deploy.

  ssoadm attribute: `sunAMAuthJDBCDriver`

JDBC URL

  When using Non-persistent JDBC connection, this specifies the URL to connect to the database.

  ssoadm attribute: `sunAMAuthJDBCUrl`

Database Username

  Specify the user name to open the database connection.

  ssoadm attribute: `sunAMAuthJDBCDbuser`

Database Password

  Specify the password for the user opening the database connection.

  ssoadm attribute: `sunAMAuthJDBCDbpassword`

Password Column Name

  Specify the database column name where passwords are stored.

  ssoadm attribute: `sunAMAuthJDBCPasswordColumn`

Prepared Statement

  Specify the SQL query to return the password corresponding to the user to authenticate.

  ssoadm attribute: `sunAMAuthJDBCStatement`

Class to Transform Password Syntax

  Specify the class that transforms the password retrieved to the same format as provided by the user.

  The default class expects the password in clear text. Custom classes must implement the `JDBCPasswordSyntaxTransform` interface.

  ssoadm attribute: `sunAMAuthJDBCPasswordSyntaxTransformPlugin`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `sunAMAuthJDBCAuthLevel`

### 2.2.12. Hints For the LDAP Authentication Module

OpenAM connects to directory servers using Lightweight Directory Access Protocol (LDAP). To build an easy-to-manage, high performance, pure Java, open source directory service, try OpenDJ directory services.

ssoadm service name: `iPlanetAMAuthLDAPService`

Primary LDAP Server, Secondary LDAP Server

  Directory servers generally use built-in data replication for high availability. Thus a directory service likely consists of a pool of replicas to which OpenAM can connect to retrieve and update directory data. You set up primary and secondary servers in case a replica is down due to maintenance or to a problem with a particular server.

  Set one primary and optionally one secondary directory server for each OpenAM server. For the current OpenAM server, specify each directory server as a ``host`:`port`` combination. For other OpenAM servers in the deployment, you can specify each directory server as ``server-name`|`host`:`port``, where `server-name` is the FQDN portion of the OpenAM server from the list under Configuration > Servers and Sites, and `host`:`port` identifies the directory server.

  For example, if the `server-name` that is listed is `http://openam.example.com:8080/openam` and the directory server is accessible at `opendj.example.com:1389`, you would enter `openam.example.com|opendj.example.com:1389`.

  When authenticating users from a directory service that is remote from OpenAM, set both the primary and secondary server values.

  If you want to use SSL or TLS for security, then scroll down to enable SSL/TLS Access to LDAP Server. Make sure that OpenAM can trust the servers' certificates when using this option.

  ssoadm attributes: primary is `iplanet-am-auth-ldap-server`, secondary is `iplanet-am-auth-ldap-server2`, and `iplanet-am-auth-ldap-ssl-enabled`

DN to Start User Search

  LDAP data is organized hierarchically, a bit like a file system on Windows or UNIX. More specific DNs likely result in better search performance. When configuring the module for a particular part of the organization, you can perhaps start searches from a specific organizational unit such as `ou=sales,dc=example,dc=com`.

  If multiple entries exist with identical search attribute values, make this value specific enough to return only one entry.

  ssoadm attribute: `iplanet-am-auth-ldap-base-dn`

Bind User DN, Bind User Password

  If OpenAM stores attributes in the directory, for example to manage account lockout, or if the directory requires that OpenAM authenticate in order to read users' attributes, then OpenAM needs the DN and password to authenticate to the directory.

  The default is `cn=Directory Manager`. Make sure that password is correct before you logout. If it is incorrect, you will be locked out. If this should occur, you can login with the super user DN, which by default is `uid=amAdmin,ou=People,`OpenAM-deploy-base``, where `OpenAM-deploy-base` you set during OpenAM configuration.

  ssoadm attributes: `iplanet-am-auth-ldap-bind-dn`, `iplanet-am-auth-ldap-bind-passwd`

Attributes Used to Retrieve User Profile, Attributes Used to Search for a User to be Authenticated, User Search Filter, Search Scope

  LDAP searches for user entries return entries with attribute values matching the filter you provide. For example if you search under `ou=people,dc=example,dc=com` with a filter `"(mail=bjensen@example.com)"`, then the directory returns the entry that has `mail=bjensen@example.com`. In this example the attribute used to search for a user is `mail`. Multiple attribute values mean the user can authenticate with any one of the values. For example, if you have both `uid` and `mail`, then Barbara Jensen can authenticate with either `bjensen` or `bjensen@example.com`.

  Should you require a more complex filter for performance, you add that to the User Search Filter text box. For example, if you search on `mail` and add User Search Filter `(objectClass=inetOrgPerson)`, then OpenAM uses the resulting search filter `(&(mail=`address`)(objectClass=inetOrgPerson))`, where `address` is the mail address provided by the user.

  Scope OBJECT means search only the entry specified as the DN to Start User Search, whereas ONELEVEL means search only the entries that are directly children of that object. SUBTREE means search the entry specified and every entry under it.

  ssoadm attributes: `iplanet-am-auth-ldap-user-naming-attribute`, `iplanet-am-auth-ldap-user-search-attributes`, `iplanet-am-auth-ldap-search-filter`, and `iplanet-am-auth-ldap-search-scope`

SSL/TLS Access to LDAP Server

  If you enable SSL/TLS, OpenAM must be able to trust LDAP certificates, either because the certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

  ssoadm attribute: `iplanet-am-auth-ldap-ssl-enabled`

Return User DN to Authenticate

  When enabled, and OpenAM uses the directory service as the user store, the module returns the DN rather than the rather than the User ID, so the bind for authentication can be completed without a search to retrieve the DN.

  ssoadm attribute: `iplanet-am-auth-ldap-return-user-dn`

User Creation Attributes

  This list lets you map (external) attribute names from Active Directory to (internal) attribute names used by OpenAM.

  ssoadm attribute: `iplanet-am-ldap-user-creation-attr-list`

Minimum Password Length

  Specify the minimum acceptable password length.

  ssoadm attribute: `iplanet-am-auth-ldap-min-password-length`

LDAP Behera Password Policy Support

  When enabled, support interoperability with servers that implement the Internet-Draft, Password Policy for LDAP Directories.

  Support for this Internet-Draft is limited to the LDAP authentication module. Other components of OpenAM, such as the password change functionality in the `/idm/EndUser` page, do not support the Internet-Draft. In general, outside of the LDAP authentication module, OpenAM binds to the directory server as an administrator, such as Directory Manager. When OpenAM binds to the directory server as an administrator rather than as an end user, many features of the Internet-Draft password policies do not apply.

  ssoadm attribute: `iplanet-am-auth-ldap-behera-password-policy-enabled`

Trust All Server Certificates

  When enabled, blindly trust server certificates, including self-signed test certificates.

  ssoadm attribute: `iplanet-am-auth-ldap-ssl-trust-all`

LDAP Connection Heartbeat Interval

  Specifies how often OpenAM should send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval use LDAP Connection Heartbeat Time Unit.

  Default: 1

  ssoadm attribute: `openam-auth-ldap-heartbeat-interval`

LDAP Connection Heartbeat Time Unit

  Specifies the time unit corresponding to LDAP Connection Heartbeat Interval.

  Default: minute

  ssoadm attribute: `openam-auth-ldap-heartbeat-interval`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-ldap-auth-level`

### 2.2.13. Hints For the Membership Authentication Module

The Membership module permits self-registration for new users. You can then have OpenAM create new user profiles in the identity repository.

ssoadm service name: `iPlanetAMAuthMembershipService`

Minimum Password Length

  Specify the minimum acceptable number of characters in the password provided during self-registration.

  ssoadm attribute: `iplanet-am-auth-membership-min-password-length`

Default User Roles

  Specifies the Distinguished Name (DN) of a role to be assigned to a new user whose profile is created. There are no default values. The role specified must be within the realm for which the authentication process is configured.

  This role can be either an OpenAM or Sun DSEE role, but it cannot be a filtered role. If you wish to automatically assign specific services to the user, you have to configure the Required Services attribute in the User Profile.

  ssoadm attribute: `iplanet-am-auth-membership-default-roles`

User Status After Registration

  If you choose Inactive, then the new user has no access to services until an administrator activates the account.

  ssoadm attribute: `iplanet-am-auth-membership-default-user-status`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-membership-auth-level`

### 2.2.14. Hints For the MSISDN Authentication Module

The Mobile Station Integrated Services Digital Network (MSISDN) authentication module enables non-interactive authentication using a mobile subscriber ISDN associated with a terminal such as a mobile phone. The module checks the subscriber ISDN against the value found on a user's entry in an LDAP directory service.

ssoadm service name: `sunAMAuthMSISDNService`

Trusted Gateway IP Address

  Specifies a list of IP addresses of trusted clients that can access MSIDSN modules. Either restrict the clients allowed to access the MSISDN module by adding each IPv4 or IPv6 address here, or leave the list empty to allow all clients to access the module. If you specify the value `none`, no clients are allowed access.

  ssoadm attribute: `sunAMAuthMSISDNTrustedGatewayList`

MSISDN Number Search Parameter Name

  Specifies a list of parameter names that identify which parameters to search in the request header or cookie header for the MSISDN number. For example, if you define x-Cookie-Param, AM_NUMBER, and COOKIE-ID, the MSISDN authentication service checks those parameters for the MSISDN number.

  ssoadm attribute: `sunAMAuthMSISDNParameterNameList`

LDAP Server and Port

  If you want to use SSL or TLS for security, then scroll down to enable SSL/TLS Access to LDAP. Make sure that OpenAM can trust the servers' certificates when using this option.

  ssoadm attribute: `sunAMAuthMSISDNLdapProviderUrl`

LDAP Start Search DN

  Specify the DN of the entry where the search for the user's MSISDN number should start.

  ssoadm attribute: `sunAMAuthMSISDNBaseDn`

Attribute To Use To Search LDAP

  Specify the name of the attribute in the user's profile that contains the MSISDN number to search for the user. The default is `sunIdentityMSISDNNumber`.

  ssoadm attribute: `sunAMAuthMSISDNUserSearchAttribute`

LDAP Server Authentication User

  If OpenAM must authenticate to the directory server in order to search, then specify the bind DN. The default is `cn=amldapuser,ou=DSAME Users,dc=example,dc=com`.

  ssoadm attribute: `sunAMAuthMSISDNPrincipalUser`

LDAP Server Authentication Password

  Specify the password corresponding to the bind DN.

  ssoadm attribute: `sunAMAuthMSISDNPrincipalPasswd`

SSL/TLS for LDAP Access

  If you choose to enable SSL or TLS, then make sure that OpenAM can trust the servers' certificates.

  ssoadm attribute: `sunAMAuthMSISDNUseSsl`

MSISDN Header Search Attribute

  Specify the headers to use for searching the request for the MSISDN number.

  - Cookie Header tells OpenAM to search the cookie.

  - Request Header tells OpenAM to search the request header.

  - Request Parameter tells OpenAM to search the request parameters.

  ssoadm attribute: `sunAMAuthMSISDNHeaderSearch`

LDAP Attribute Used to Retrieve User Profile

  Specify the LDAP attribute that is used during a search to return the user profile for MSISDN authentication service. The default is `uid`.

  ssoadm attribute: `sunAMAuthMSISDNUserNamingAttribute`

Return User DN to DataStore

  Enable this option only when the OpenAM directory is the same as the directory configured for MSISDN searches. When enabled, this option allows the authentication module to return the DN instead of the User ID. OpenAM thus does not need to perform an additional search with the user ID to find the user's entry.

  ssoadm attribute: `sunAMAuthMSISDNReturnUserDN`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `sunAMAuthMSISDNAuthLevel`

### 2.2.15. Hints For the OATH Module

The Open Authentication (OATH) module provides a more secure method for users to access their accounts with the help of a device, such as their mobile phone or Yubikey. Users can log into OpenAM and update their information more securely from a one-time password (OTP) displayed on their device. The OATH module includes the OATH standard protocols (RFC 4226 and RFC 6238). The OATH module has several enhancements to the HMAC One-Time Password (HOTP) Authentication Module, but does not replace the original module for those already using HOTP prior to the 10.1.0 release. The OATH module includes HOTP authentication and Time-Based One-Time Password (TOTP) authentication. Both types of authentication require an OATH compliant device that can provide the OTP.

HOTP authentication generates the OTP every time the user requests a new OTP on their device. The device tracks the number of times the user requests a new OTP, called the counter. The OTP displays for a period of time you designate in the setup, so the user may be further in the counter on their device than on their account. OpenAM will resynchronize the counter when the user finally logs in. To accommodate this, you set the number of passwords a user can generate before their device cannot be resynchronized. For example, if you set the number of HOTP Window Size to 50 and someone presses the button 30 on the user's device to generate a new OTP, the counter in OpenAM will review the OTPs until it reaches the OTP entered by the user. If someone presses the button 51 times, you will need to reset the counter to match the number on the device's counter before the user can login to OpenAM. HOTP authentication does not check earlier passwords, so if the user attempts to reset the counter on their device, they will not be able to login until you reset the counter in OpenAM to match their device.

TOTP authentication constantly generates a new OTP based on a time interval you specify. The device tracks the last two passwords generated and the current password. The Last Login Time monitors the time when a user logs in to make sure that user is not logged in several times within the present time period. Once a user log into OpenAM, they must wait for the time it takes TOTP to generate the next two passwords and display them. This prevents others from being able to access the users account using the OTP they entered. The user's account can be accessed again after the generation of the third new OTP is generated and displayed on their device. For this reason, the TOTP Time-Step Interval should not be so long as to lock users out, with a recommended time of 30 seconds.

An authentication chain can be created to generate an OTP from either HOTP or TOTP.

ssoadm service name: `iPlanetAMAuthOATHService`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-oath-auth-level`

One Time Password Length (in digits)

  Set the length of the OTP between 6 and 9 digits long. The default value is 6 digits.

  ssoadm attribute: `iplanet-am-auth-oath-password-length`

Minimum Secret Key Length

  The minimal number of characters required to set the Secret Key.

  ssoadm attribute: `iplanet-am-auth-oath-min-secret-key-length`

Secret Key Attribute Name

  The name of the attribute where the key will be stored in the user profile.

  ssoadm attribute: `iplanet-am-auth-oath-secret-key-attribute`

OATH Algorithm to Use

  Select whether to use HOTP or TOTP. You can create an authentication chain to allow for a greater variety of devices. The default value is HOTP.

  ssoadm attribute: `iplanet-am-auth-oath-algorithm`

HOTP Window Size

  The number of requests that the system and the device can be off to resynchronize the password. If a user passes this number of requests before logging into the system, the password will not work. The default value is 100.

  ssoadm attribute: `iplanet-am-auth-oath-hotp-window-size`

Counter Attribute Name

  The name of the HOTP attribute where the counter will be stored in the user profile.

  ssoadm attribute: `iplanet-am-auth-oath-hotp-counter-attribute`

Add Checksum Digit

  Adds a checksum digit at the end of the HOTP password to verify it was entered correctly. The default value is No.

  ssoadm attribute: `iplanet-am-auth-oath-add-checksum`

Truncation Offset

  Advanced feature that is device specific. Any value below 0 or above 15 will turn off the functionality. The default value is -1. If not required by the device, leave at the default setting.

  ssoadm attribute: `iplanet-am-auth-oath-truncation-offset`

TOTP Time Step Interval

  Defines how long the password will appear on the user's device (in seconds). We recommend keeping this number low, for example 30 seconds, because once a user logs out, they will not be able to login again until two full time cycles have passed. The default value is 30 seconds.

  ssoadm attribute: `iplanet-am-auth-oath-size-of-time-step`

TOTP Time Steps

  The number of requests that the system and the device can be off to resynchronize the password. If a user passes this number of requests before logging into the system, the password will not work. The default value is 2.

  ssoadm attribute: `iplanet-am-auth-oath-steps-in-window`

Last Login Time Attribute

  The name of the attribute where both HOTP and TOTP authentication will store information on when a person last logged in.

  ssoadm attribute: `iplanet-am-auth-oath-last-login-time-attribute-name`

If you plan to use Yubikey for your OATH module, you will need to take some time to set it up. Go to the YubiKey website to configure your YubiKey device. If you do not have a YubiKey device, you can purchase them from this page as well.

Select the appropriate instructions, keeping in mind that the cross-platform personalization tool is recommended unless you have specific need for one of the other types. You have the greatest selection of platforms for this choice. Each device will need to be setup before use.

### 2.2.16. Hints For the OAuth 2.0 Authentication Module

The OAuth 2.0 authentication module lets OpenAM authenticate clients of OAuth resource servers. References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.

### Note

The default settings are for Facebook.

ssoadm service name: `sunAMAuthOAuthService`

Client ID

  OAuth `client_id` as described in section 2.2 of RFC 6749.

  ssoadm attribute: `iplanet-am-auth-oauth-client-id`

Client Secret

  OAuth `client_secret` as described in section 2.3 of RFC 6749.

  ssoadm attribute: `iplanet-am-auth-oauth-client-secret`

Authentication Endpoint URL

  URL to the end point handling OAuth authentication as described in section 3.1 of RFC 6749. The default value is `https://www.facebook.com/dialog/oauth`.

  ssoadm attribute: `iplanet-am-auth-oauth-auth-service`

Access Token Endpoint URL

  URL to the end point handling access tokens as described in section 3.2 of RFC 6749. The default value is `https://graph.facebook.com/oauth/access_token`.

  ssoadm attribute: `iplanet-am-auth-oauth-token-service`

User Profile Service URL

  User profile URL that returns profile information in JSON format. The default value is `https://graph.facebook.com/me`.

  ssoadm attribute: `iplanet-am-auth-oauth-user-profile-service`

Scope

  Comma separated list of user profile attributes that the application requires. The default value is `email,read_stream`.

  ssoadm attribute: `iplanet-am-auth-oauth-scope`

Proxy URL

  URL to the `/oauth2c/OAuthProxy.jsp` file, part of OpenAM.

  ssoadm attribute: `iplanet-am-auth-oauth-sso-proxy-url`

Account Mapper

  Class implementing account mapping. The default value is `org.forgerock.openam.authentication.modules.oauth2.DefaultAccountMapper`.

  ssoadm attribute: `org-forgerock-auth-oauth-account-mapper`

Account Mapper Configuration

  Map of OAuth Provider user account attributes used to find the local profile of the authenticated user, with values in the form ``provider-attr`=`local-attr``. Default values `email=mail` and `id=facebook-id`.

  ssoadm attribute: `org-forgerock-auth-oauth-account-mapper-configuration`

Attribute Mapper

  Class implementing attribute mapping. Default: `org.forgerock.openam.authentication.modules.oauth2.DefaultAttributeMapper`

  ssoadm attribute: `org-forgerock-auth-oauth-attribute-mapper`

Attribute Mapper Configuration

  Map of OAuth Provider user account attributes to local user profile attributes, with values in the form ``provider-attr`=`local-attr``.

  ssoadm attribute: `org-forgerock-auth-oauth-attribute-mapper-configuration`

Save attributes in the session

  When enabled, add the mapped attributes to the session saved. The default mode is `Enabled`.

  ssoadm attribute: `org-forgerock-auth-oauth-save-attributes-to-session-flag`

Email attribute in OAuth2 Response

  Specifies the attribute identifying email address in the response from the profile service in the OAuth provider. This setting is used to send an email address with an activation code for accounts created dynamically.

  ssoadm attribute: `org-forgerock-auth-oauth-mail-attribute`

Create account if it does not exist

  When enabled, if the user profile does not exist, optionally retrieve a password and activation code from the user, and then create the profile. The default mode is `Enabled`.

  When the OAuth 2.0 client is configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the OAuth 2.0 client authentication module sends the resource owner an email with an account activation code. To send the mail, OpenAM uses the SMTP settings you provide here in the OAuth 2.0 client configuration.

  ssoadm attribute: `org-forgerock-auth-oauth-createaccount-flag`

Prompt for password setting and activation code

  When enabled, the user sets a password, receives an activation code by email. The user must correctly set both in order for the account to be created. The default mode is `Enabled`.

  ssoadm attribute: `org-forgerock-auth-oauth-prompt-password-flag`

Map to anonymous user

  When enabled, map the OAuth authenticated user to the anonymous user you specify. No account is created, even if Create account if it does not exist is enabled.

  ssoadm attribute: `org-forgerock-auth-oauth-map-to-anonymous-flag`

Anonymous User

  Specifies an anonymous user that exists in the current realm. The default is `anonymous`.

  ssoadm attribute: `org-forgerock-auth-oauth-anonymous-user`

OAuth 2.0 Provider logout service

  Specifies the optional URL of the OAuth Provider.

  ssoadm attribute: `org-forgerock-auth-oauth-logout-service-url`

Logout options

  Specifies whether not to log the user out without prompting from the OAuth Provider on logout, to log the user out without prompting, or to prompt the user regarding whether to logout from the OAuth provider.

  ssoadm attribute: `org-forgerock-auth-oauth-logout-behaviour`

Mail Server Gateway implementation class

  Class to interact with the mail server. Default: `org.forgerock. openam.authentication.modules.oauth2.DefaultEmailGatewayImpl`

  ssoadm attribute: `org-forgerock-auth-oauth-email-gwy-impl`

SMTP host

  Host name of the mail server. The default is `localhost`.

  ssoadm attribute: `org-forgerock-auth-oauth-smtp-hostname`

SMTP port

  SMTP port number for the mail server. The default value is `25`.

  ssoadm attribute: `org-forgerock-auth-oauth-smtp-port`

SMTP User Name

  If the mail server requires authentication to send mail, specifies the user name.

  ssoadm attribute: `org-forgerock-auth-oauth-smtp-username`

SMTP User Password

  If the mail server requires authentication to send mail, specifies the password.

  ssoadm attribute: `org-forgerock-auth-oauth-smtp-password`

SMTP SSL Enabled

  When enabled, connect to the mail server over SSL. OpenAM must be able to trust the SMTP server certificate.

  ssoadm attribute: `org-forgerock-auth-oauth-smtp-ssl_enabled`

SMTP From address

  Specifies the message sender address, such as `no-reply@example.com`. The default value is `info@forgerock.com`.

  ssoadm attribute: `org-forgerock-auth-oauth-smtp-email-from`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-oauth-auth-level`

The following tables show endpoint URLs for OpenAM when configured as an OAuth 2.0 provider, and also URLs for large OAuth 2.0 providers. The default endpoints are for Facebook as the OAuth 2.0 provider.

In addition to the endpoint URLs you can set other fields, like scope and attribute mapping, depending on the provider you use.

Table 2.1. Endpoint URLs for OpenAM

OpenAM Field | Details
--- | ---
Authentication Endpoint URL | `/oauth2/authorize` under the deployment URL.[a] Example: `https://openam.example.com:8443/openam/oauth2/authorize`.
Access Token Endpoint URL | `/oauth2/access_token` under the deployment URL.[a] Example: `https://openam.example.com:8443/openam/oauth2/access_token`.
User Profile Service URL | `/oauth2/tokeninfo` under the deployment URL. Example: `https://openam.example.com:8443/openam/oauth2/tokeninfo`.
[a] This OpenAM endpoint can take additional parameters. In particular you must specify the realm if the OpenAM OAuth 2.0 provider is configured for a subrealm rather than / (Top-Level Realm). For example, if the OAuth 2.0 provider is configured for the realm `/customers`, then the authentication endpoint URL is as follows: `https://openam.example.com:8443/openam/oauth2/authorize?realm=/customers` The `/oauth2/authorize` endpoint can also take `module` and `service` parameters. Use either as described in Authenticating To OpenAM, where `module` specifies the authentication module instance to use or `service` specifies the authentication chain to use when authenticating the resource owner.

Table 2.2. Endpoint URLs for Facebook

OpenAM Field | Details
--- | ---
Authentication Endpoint URL | https://www.facebook.com/dialog/oauth
Access Token Endpoint URL | https://graph.facebook.com/oauth/access_token
User Profile Service URL | https://graph.facebook.com/me
OAuth 2.0 Provider logout service | http://www.facebook.com/logout.php

Table 2.3. Endpoint URLs for Google

OpenAM Field | Details
--- | ---
Authentication Endpoint URL | https://accounts.google.com/o/oauth2/auth
Access Token Endpoint URL | https://accounts.google.com/o/oauth2/token
User Profile Service URL | https://www.googleapis.com/oauth2/v1/userinfo
OAuth 2.0 Provider logout service | https://mail.google.com/mail/?logout

Table 2.4. Endpoint URLs for MSN

OpenAM Field | Details
--- | ---
Authentication Endpoint URL | https://oauth.live.com/authorize
Access Token Endpoint URL | https://oauth.live.com/token
User Profile Service URL | https://apis.live.net/v5.0/me
OAuth 2.0 Provider logout service | http://oauth.live.com/logout

### 2.2.17. Hints for the Persistent Cookie Module

The Persistent Cookie module supports configuration of cookie lifetimes, based on requests and a maximum time. It is the preferred method for creating a persistent cookie. If you choose this method, be aware that it does not interact with the persistent cookie options associated with the Core Authentication module.

ssoadm service name: `iPlanetAMAuthPersistentCookieService`

To configure the Persistent Cookie Module globally in the console, navigate to Configuration > Authentication > Persistent Cookie. In the window that appears you should see the following attributes:

Idle Timeout

  Specify the maximum idle time between requests, in hours. If that time is exceeded, the cookie is no longer valid.

  ssoadm attribute: `openam-auth-persistent-cookie-idle-time`

Max Life

  Specify the maximum life of the cookie in hours.

  ssoadm attribute: `openam-auth-persistent-cookie-max-life`

The Persistent Cookie module belongs with a second module in an authentication chain. To see how this works, navigate to Access Control > `Realm Name` > Authentication > New. Enter a name for the chain and add modules as shown in the figure. The following example shows how a Persistent Cookie module is sufficient; if that cookie does not yet exist, authentication in this case relies on a data store module such as LDAP.

[D]

Scroll down in the properties page for the chain. You should set the `PersistentCookieAuthModule` as shown in the following figure:

[D]

You should now be able to authenticate automatically, as long as the cookie exists for the associated domain.

### Note

Unlike the legacy Core Authentication module, the Persistent Cookie module does not support the iPSPCookie option described in Section 2.5, “Authenticating To OpenAM”

### 2.2.18. Hints For the RADIUS Authentication Module

The Remote Authentication Dial-In User Service (RADIUS) module lets OpenAM authenticate users against RADIUS servers.

ssoadm service name: `iPlanetAMAuthRadiusService`

Primary Radius Servers, Secondary Radius Servers

  Specify the IP address or fully qualified domain name of the primary RADIUS server. The default is `127.0.0.1` (localhost loopback).

  ssoadm attribute: `primary is iplanet-am-auth-radius-server1`; secondary is `iplanet-am-auth-radius-server2`

Shared Secret

  Specify the shared secret for RADIUS authentication. The shared secret should be as secure as a well-chosen password.

  ssoadm attribute: `iplanet-am-auth-radius-secret`

Port Number

  Specify the RADIUS server port. Default is 1645.

  ssoadm attribute: `iplanet-am-auth-radius-server-port`

Timeout

  Specify how many seconds to wait for the RADIUS server to respond. The default value is 3 seconds.

  ssoadm attribute: `iplanet-am-auth-radius-timeout`

Health check interval

  Used for failover. Specify how often OpenAM performs a health check on a previously unavailable RADIUS server by sending an invalid authentication request. Default: 5 minutes

  ssoadm attribute: `openam-auth-radius-healthcheck-interval`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-radius-auth-level`

### 2.2.19. Hints For the SAE Authentication Module

The Secure Attribute Exchange (SAE) module lets OpenAM authenticate a user who has already authenticated with an entity that can vouch for the user to OpenAM, so that OpenAM creates a session for the user. This module is useful in virtual federation, where an existing entity instructs the local OpenAM instance to use federation protocols to transfer authentication and attribute information to a partner application.

ssoadm attribute: `sunAMAuthSAEService`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `sunAMAuthSAEAuthLevel`

### 2.2.20. Hints For the SecurID Authentication Module

The SecurID module lets OpenAM authenticate users with RSA Authentication Manager software and RSA SecurID authenticators.

ssoadm service name: `iPlanetAMAuthSecurIDService`

ACE/Server Configuration Path

  Specify the directory in which the SecurID ACE/Server `sdconf.rec` file is located, which by default is expected under the configuration directory for OpenAM, such as `$HOME/openam/openam/auth/ace/data`. The directory must exist before OpenAM can use SecurID authentication.

  ssoadm attribute: `iplanet-am-auth-securid-server-config-path`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-securid-auth-level`

### 2.2.21. Hints For the Windows Desktop SSO Authentication Module

The Windows Desktop SSO module uses Kerberos authentication. The user presents a Kerberos token to OpenAM through the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol. The Windows Desktop SSO authentication module enables desktop single sign on such that a user who has already authenticated with a Kerberos Key Distribution Center can authenticate to OpenAM without having to provide the login information again. Users might need to set up Integrated Windows Authentication in Internet Explorer to benefit from single sign on when logged on to a Windows desktop.

ssoadm service name: `iPlanetAMAuthWindowsDesktopSSOService`

Service Principal

  Specify the Kerberos principal for authentication in the following format.

      HTTP/host.domain@dc-domain-name

  Here, `host` and `domain` correspond to the host and domain names of the OpenAM instance, and `dc-domain-name` is the domain name of the Windows Kerberos domain controller server. The `dc-domain-name` can differ from the domain name for OpenAM.

  You set up the account on the Windows domain controller, creating a computer account for OpenAM and associating the new account with a service provider name.

  ssoadm attribute: `iplanet-am-auth-windowsdesktopsso-principal-name`

Keytab File Name

  Specify the full path of the keytab file for the Service Principal. You generate the keytab file using the Windows ktpass utility.

  ssoadm attribute: `iplanet-am-auth-windowsdesktopsso-keytab-file`

Kerberos Realm

  Specify the Kerberos Key Distribution Center realm. For the Windows Kerberos service this is the domain controller server domain name.

  ssoadm attribute: `iplanet-am-auth-windowsdesktopsso-kerberos-realm`

Kerberos Server Name

  Specify the fully qualified domain name of the Kerberos Key Distribution Center server, such as that of the domain controller server.

  ssoadm attribute: `iplanet-am-auth-windowsdesktopsso-kdc`

Return Principal with Domain Name

  When enabled, OpenAM automatically returns the Kerberos principal with the domain controller's domain name during authentication.

  ssoadm attribute: `iplanet-am-auth-windowsdesktopsso-returnRealm`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-windowsdesktopsso-auth-level`

Search for the user in the realm

  Validates the user against the configured data stores. If the user from the Kerberos token is not found, authentication will fail. If an authentication chain is set, the user will be able to authenticate through another module.

  ssoadm attribute: `iplanet-am-auth-windowsdesktopsso-lookupUserInRealm`

### Note

Note: For Windows 7 and later, you will need to turn off the "Enable Integrated Windows Authentication" option in Internet Explorer. In addition, you will need to add and activate the DisableNTMLPreAuth key to the Windows Registry. For detailed instructions, see the Microsoft KB article on when You cannot post data to a non-NTLM-authenticated Web site

### 2.2.22. Hints For the Windows NT Authentication Module

The Windows NT module lets OpenAM authenticate against a Microsoft Windows NT server.

This module requires that you install a Samba client in a `bin` directory under the OpenAM configuration directory such as `$HOME/openam/openam/bin`.

ssoadm service name: `iPlanetAMAuthNTService`

Authentication Domain

  Specify the Windows domain name to which users belong.

  ssoadm attribute: `iplanet-am-auth-nt-domain`

Authentication Host

  Specify the NetBIOS name of the Windows NT host to which to authenticate users.

  ssoadm attribute: `iplanet-am-auth-nt-host`

Samba Configuration File Name

  Specify the full path to the Samba configuration file.

  ssoadm attribute: `iplanet-am-auth-samba-config-file-name`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-nt-auth-level`

### 2.2.23. Hints For the WSSAuth Authentication Module

The Web Service Security (WSSAuth) module lets OpenAM validate a user name, password combination received as an authentication token in a request from a Web Service Client to a Web Service Provider.

ssoadm service name: `sunAMAuthWSSAuthModuleService`

User search attribute

  Specify a user attribute to search for a user. Default is `uid`.

  ssoadm attribute: `sunWebservicesUserSearchAttribute`

User realm

  Specify the realm to which users belong. For the OpenAM Security Token Service, this is `/`.

  ssoadm attribute: `sunWebServicesUserRealm`

User password attribute

  Specify the password attribute or that of the password equivalent. The default is `userPassword`.

  ssoadm attribute: `sunWebservicesUserPasswordAttribute`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `sunWebservicesAuthenticationLevel`

## 2.3. Configuring Authentication Chains

Once you have configured authentication modules, and added the modules to the list of module instances, you can configure authentication chains. Authentication chains let you handle situations where alternative modules are needed, or where a single set of credentials is not sufficient.

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.

## 2.4. Post Authentication Plugins

Post authentication plugins include custom processing at the end of the authentication process, immediately before the subject is authenticated. Common uses of post authentication plugins include setting cookies and session variables. Post authentication plugins are often used in conjunction with policy agents. The post authentication plugin sets custom session properties, and then the policy agent injects the custom properties into the request header to the protected application.

In the OpenAM console, you add post authentication plugins to an authentication chain. Navigate to Access Control > `Realm Name` > Authentication > Authentication Chaining > `Auth Chain Name`. Scroll down to the Post Authentication Processing Class list.

Standard Post Authentication Plugins

OpenAM provides some post authentication plugins as part of the standard product delivery.

Class name: `org.forgerock.openam.authentication.modules.adaptive.Adaptive`

  The adaptive authentication plugin serves to save cookies and profile attributes after successful authentication.

  Add it to your authentication chains that use the adaptive authentication module configured to save cookies and profile attributes.

Class name: `org.forgerock.openam.authentication.modules.oauth2.OAuth2PostAuthnPlugin`

  The OAuth 2.0 post authentication plugin builds a global logout URL used by `/oauth2c/OAuthLogout.jsp` after successful OAuth 2.0 client authentication. This logs the resource owner out with the OAuth 2.0 provider when logging out of OpenAM.

  Before using this plugin, configure the OAuth 2.0 authentication module with the correct OAuth 2.0 Provider logout service URL, and set the Logout options to Log out or Prompt. This plugin cannot succeed unless those parameters are correctly set.

  Sometimes OAuth 2.0 providers change their endpoints, including their logout URLs. When using a provider like Facebook, Google, or MSN make sure you are aware when they change their endpoint locations so that you can change your client configuration accordingly.

Class name: `org.forgerock.openam.authentication.plugins.AccountExpirePlugin`

  The account expiration post authentication plugin sets an account expiration date after successful authentication. OpenAM uses this to prevent expired accounts from being used to authenticate.

  The default of 30 days can be changed using the advanced OpenAM server property, `org.forgerock.openam.authentication.accountExpire.days`.

If necessary, you can also write your own custom post authentication plugin as described in the Developer's Guide chapter on Creating a Post Authentication Plugin.

## 2.5. Authenticating To OpenAM

This section explains how to connect to OpenAM for user authentication by adding parameters to the login URL when testing your configuration.

The base URL to authenticate to OpenAM points to `/UI/Login` under the deployment URL, such as `http://openam.example.com:8080/openam/UI/Login`. [4] You can, however, specify parameters in the query string of the URL to request a specific authentication configuration. For example, `http://openam.example.com:8080/openam/UI/Login?module=LDAP` requests that OpenAM use the LDAP authentication module.

OpenAM accepts the following parameters in the query string. With the exception of `IDToken` parameters, use no more than one occurrence of each.

### Note

The way you enter parameters depends on whether you are using the classic UI or the XUI. For example, if you want to request that OpenAM end the user's current session and start a new session in the classic UI, you might enter a URL similar to: `http://openam.example.com:8080/openam/UI/Login?locale=fr`. Alternatively, for the JavaScript-based XUI, the corresponding URL would be subtly different: `http://openam.example.com:8080/openam/XUI/#login/&arg=newsession`.

arg=newsession

  Request that OpenAM end the user's current session and start a new session.

authlevel

  Request that OpenAM authenticate the user using a module with at least the specified authentication level that you have configured.

  As this parameter determines authentication module selection, do not use it with `module`, `service`, or `user`.

ForceAuth

  If `ForceAuth=true`, request that OpenAM force the user to authenticate even if she already has a valid session. On successful authentication, OpenAM updates the session token.

goto

  On successful authentication, or successful logout, request that OpenAM redirect the user to the specified location. Values must be URL encoded.

gotoOnFail

  On authentication failure, request that OpenAM redirect the user to the specified location. Values must be URL encoded.

IDToken1, IDToken2, ..., IDTokenN

  Pass the specified credentials as `IDToken` parameters in the URL. The `IDToken` credentials map to the fields in the login page for the authentication module, such as `IDToken1` as user ID and `IDToken2` as password for basic user name, password authentication. The order depends on the callbacks in login page for the module; `IDTokenN` represents the Nth callback of the login page.

iPSPCookie=yes

  Applicable only if you configure persistent cookies based on Section 2.2.5.3, “Core - Persistent Cookie (Legacy)”

  Request that OpenAM return a persistent cookie that remains in the browser after the browser is closed, allowing the user to login again without being prompted for credentials. This only works if you have configured persistent cookie mode for the realm where the user logs in.

  OpenAM sets an `DProPCookie` that persists until expiry. The following screen shot shows an example.

  An alternative persistent cookie mechanism extends the lifetime of the normal `iPlanetDirectoryPro` using the advanced server settings, `openam.session.persist_am_cookie` or `openam.session.allow_persist_am_cookie`, and `com.iplanet.am.cookie.timeToLive`.

  To set the mechanism globally for the server, browse in the OpenAM console to Configuration > Servers and Sites > `Server Name` > Advanced, and then set `openam.session.persist_am_cookie` to `true` and `com.iplanet.am.cookie.timeToLive` to the cookie lifetime in seconds.

  To allow users to use this mechanism on a per-session basis, browse in the OpenAM console to Configuration > Servers and Sites > `Server Name` > Advanced, and then set `openam.session.allow_persist_am_cookie` to `true` and `com.iplanet.am.cookie.timeToLive` to the cookie lifetime in seconds. (If the OpenAM .war deployed does not include the console, set these properties in the .properties configuration file.) Also configure the session properties either globally under Configuration > Global > Session > Dynamic Attributes, or per realm under Access Control > `Realm Name` > Services > Session. Then, to request the cookie, use `openam.session.persist_am_cookie=Yes` as one of the query string parameters in the login URL.

  ### Note

  Neither the XUI nor the Persistent Cookie module supports the deprecated `iPSPCookie`.

locale

  Request that OpenAM display the user interface in the specified, supported locale. Locale can also be set in the user's profile, in the HTTP header from her browser, configured in OpenAM, and so on.

module

  Request that OpenAM use the authentication module instance as configured for the realm where the user is authenticating.

  As this parameter determines authentication module selection, do not use it with `authlevel`, `service`, or `user`.

realm

  Request that OpenAM authenticate the user to the specified realm.

service

  Request that OpenAM authenticate the user with the specified authentication chain.

  As this parameter determines authentication module selection, do not use it with `authlevel`, `module`, or `user`.

user

  Request that the user, specified by her OpenAM universal ID, authenticate according to the chain specified in her profile.

  As this parameter determines authentication module selection, do not use it with `authlevel`, `module`, or `service`.

## 2.6. Configuring Account Lockout

OpenAM supports two different approaches to account lockout, where OpenAM locks an account after repeated authentication failures. Lockout works with modules for which users can enter a password incorrectly.

- Memory lockout locks the user account, keeping track of the locked state only in memory, and then unlocking the account after a specified delay. Memory lockout is also released when OpenAM restarts.

- Persistent (physical) lockout sets the user account status to `inactive` in the user profile. For persistent lockout, OpenAM tracks failed authentication attempts by writing to the user repository.

  Persistent account lockout works independently of account lockout mechanisms in the underlying directory server that serves as the user data store.

You configure account lockout by editing settings for the core authentication module. Access the settings in OpenAM console under Access Control > `Realm Name` > Authentication > All Core Settings..., and then scroll down to the Account Lockout section. The inline help explains the settings in detail.

- Enable lockout by checking Login Failure Lockout Mode, setting the number of attempts, and setting the lockout interval and duration.

  You can also opt to warn users after several consecutive failures, or to multiply the lockout duration on each successive lockout.

- You can set up email notification upon lockout to an administrator if OpenAM is configured to send mail. (Configuration > Servers and Sites > Default Server Settings > General > Mail Server.)

- For persistent lockout, OpenAM sets the value of the user's `inetuserstatus` profile attribute to `inactive`. You can also specify another attribute to update on lockout. You can further set a non-default attribute on which to store the number of failed authentication attempts. When you do store the number of failed attempts in the data store, other OpenAM servers accessing the user data store can also see the number.

If you need to unlock a user's account, find the user under Access Control > `Realm Name` > Subjects > User, set the user's User Status to Active, and click Save.

## 2.7. Configuring Session Quotas

OpenAM lets you limit the number of active sessions for a user by setting session quotas. You also configure session quota exhaustion actions so that when a user goes beyond the session quota, OpenAM takes the appropriate action.

### Important

To enforce session quotas across multiple servers in a site, configure session failover as described in the Installation Guide chapter, Setting Up OpenAM Session Failover.

Procedure 2.3. To Configure Session Quotas & Exhaustion Actions

The session quota applies to all sessions opened for the same user (as represented by the user's universal identifier).

1. Log in to OpenAM Console as administrator, and then browse to Configuration > Global > Session.

2. Set Enable Quota Constraints to `ON`.

3. Set Resulting behavior if session quota exhausted.

   The following settings are available by default.

   `DENY_ACCESS`

     Deny access, preventing the user from creating an additional session.

   `DESTROY_NEXT_EXPIRING`

     Remove the next session to expire, and create a new session for the user. The next session to expire is the session with the minimum time left until expiration.

     This is the default setting.

   `DESTROY_OLDEST_SESSION`

     Remove the oldest session, and create a new session for the user.

   `DESTROY_OLD_SESSIONS`

     Remove all existing sessions, and create a new session for the user.

   If none of these session quota exhaustion actions fit your deployment, you can implement a custom session quota exhaustion action. See the Developer's Guide chapter on Customizing Session Quota Exhaustion Actions for an example.

4. Set Active User Sessions to the session quota.

   The default is 5 sessions.

5. Save your work.

6. If you have multiple servers but session failover is not configured, configure multi-server mode as described below.

   - If you have only a single OpenAM server, skip this step. OpenAM enforces the session quota you set for the server.

   - If you have multiple servers with session failover configured, then also skip this step. In this case OpenAM uses the session store to enforce session quotas globally across your deployment. In other words when the Set Active User Sessions is 5, a user can have a maximum of 5 active sessions.

   - If you have multiple OpenAM servers but session failover is not configured, configure multi-server mode for session quotas. Browse to Configuration > Servers and Sites > Default Server Settings or Configuration > Servers and Sites > `Server Name`, and then use the Advanced tab page to set the following advanced server property.

     openam.session.useLocalSessionsInMultiServerMode = true

     When you set this property to `true` for your OpenAM servers, users can potentially reach the session quota for each individual server before all session quotas are exhausted. In other words if you have 4 OpenAM servers and Set Active User Sessions is 5, then the user can have a maximum of 20 (5 * 4) sessions.

[3] The four flags, required, optional, requisite, and sufficient, come from the standards created for the Java Authentication and Authorization Service (JAAS).

[4] The base URL to logout is similar, for example `http://openam.example.com:8080/openam/UI/Logout`.

Prev |  | Next
Chapter 1. Administration Interfaces & Tools | Home | Chapter 3. Defining Authorization Policies