An authentication service confirms the identity of a user or a client application.
This chapter describes how to configure 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.1. Hints For the Active Directory Authentication Module
- 2.2.2. Hints For the Adaptive Risk Authentication Module
- 2.2.3. Hints For the Anonymous Authentication Module
- 2.2.4. Hints For the Certificate Authentication Module
- 2.2.5. Hints For the Core Authentication Module
- 2.2.6. Hints For the Data Store Authentication Module
- 2.2.7. Hints For the Device Print Authentication Module
- 2.2.8. Hints For the Federation Authentication Module
- 2.2.9. Hints For the HOTP Authentication Module
- 2.2.10. Hints For the HTTP Basic Authentication Module
- 2.2.11. Hints For the JDBC Authentication Module
- 2.2.12. Hints For the LDAP Authentication Module
- 2.2.13. Hints For the Membership Authentication Module
- 2.2.14. Hints For the MSISDN Authentication Module
- 2.2.15. Hints For the OATH Module
- 2.2.16. Hints For the OAuth 2.0 Authentication Module
- 2.2.17. Hints for the Persistent Cookie Module
- 2.2.18. Hints For the RADIUS Authentication Module
- 2.2.19. Hints For the SAE Authentication Module
- 2.2.20. Hints For the SecurID Authentication Module
- 2.2.21. Hints For the Windows Desktop SSO Authentication Module
- 2.2.22. Hints For the Windows NT Authentication Module
- 2.2.23. Hints For the WSSAuth Authentication Module
The OpenAM console provides two places where the OpenAM administrator can configure authentication modules.
Under Configuration > Authentication, you configure available modules for use throughout OpenAM. What you set up here is inherited for use elsewhere.
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.
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 isiplanet-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 isuid=amAdmin,ou=People,, whereOpenAM-deploy-baseOpenAM-deploy-basewas set during OpenAM configuration.ssoadm attributes:
iplanet-am-auth-ldap-bind-dnandiplanet-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=comwith a filter"(MAIL=bjensen@example.com)", then the directory returns the entry that hasMAIL=bjensen@example.com. In this example the attribute used to search for a user ismail. Multiple attribute values mean the user can authenticate with any one of the values. For example, if you have bothuidandmail, then Barbara Jensen can authenticate with eitherbjensenorbjensen@example.com.The User Search Filter text box provides a more complex filter. For example, if you search on
mailand add User Search Filter(objectClass=inetOrgPerson), then OpenAM uses the resulting search filter(&(mail=, whereaddress) (objectClass=inetOrgPerson))addressis 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, andiplanet-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
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.
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
- 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 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 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/YYx.x.x.x-y.y.y.yx.x.x.xtoy.y.y.y).For IPv6, specifies a list of IP ranges either in CIDR-style notation (
X:X:X:X:X:X:X:X/YYX:X:X:X:X:X:X:X-Y:Y:Y:Y:Y:Y:Y:YX:X:X:X:X:X:X:XtoY: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 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:
iphistoryssoadm 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
- 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 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 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 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
- 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 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
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:
anonymousssoadm 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
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 isCN, 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 areCN,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, andiplanet-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
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:
ssoadm service name:
iPlanetAMAuthService
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.
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
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=yesas a parameter to the login URL. OpenAM sets aDProPCookieas 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
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
|to addresses for recipients in non-English locales.locale|charsetssoadm 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
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.AMAuthCallBackOpenAM 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/libdirectory of the deployed OpenAM instance. If you do not build a .jar, add the class files underWEB-INF/classes.ssoadm attribute:
sunAMUserStatusCallbackPlugins- Default Authentication Level
Specifies the default authentication level for authentication modules.
ssoadm attribute:
iplanet-am-auth-default-auth-level
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=login parameter result in failure. It is recommended that this be turned off in a production environment.module-namessoadm 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
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/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|URLssoadm 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.AMPostAuthProcessInterfaceOpenAM interface.A .jar containing the post processing class belongs in the
WEB-INF/libdirectory of the deployed OpenAM instance. If you do not build a .jar, add the class files underWEB-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-NameSession-Attribute-Nameis not specified, the value ofUser-Profile-Attributeis used. All session attributes contain theam.protectedprefix 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 bemail|user.mail. After a successful authentication, theSSOToken.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 theSSOToken.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 anSSOException. Multi-value attributes, such asmemberOf, are listed as a single session variable with a|separator.ssoadm attribute:
sunAMUserAttributesSessionMapping
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
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.
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 ignoreattribute 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 requiredattribute 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 parametersfeature 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 pointsis 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 requiredattribute 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 requiredattribute 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 requiredattribute 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 requiredattribute 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
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
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
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
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/libdirectory 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
JDBCPasswordSyntaxTransforminterface.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
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:portserver-name|host:portserver-nameis the FQDN portion of the OpenAM server from the list under Configuration > Servers and Sites, andhost:portidentifies the directory server.For example, if the
server-namethat is listed ishttp://openam.example.com:8080/openamand the directory server is accessible atopendj.example.com:1389, you would enteropenam.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 isiplanet-am-auth-ldap-server2, andiplanet-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 isuid=amAdmin,ou=People,, whereOpenAM-deploy-baseOpenAM-deploy-baseyou 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=comwith a filter"(mail=bjensen@example.com)", then the directory returns the entry that hasmail=bjensen@example.com. In this example the attribute used to search for a user ismail. Multiple attribute values mean the user can authenticate with any one of the values. For example, if you have bothuidandmail, then Barbara Jensen can authenticate with eitherbjensenorbjensen@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
mailand add User Search Filter(objectClass=inetOrgPerson), then OpenAM uses the resulting search filter(&(mail=, whereaddress)(objectClass=inetOrgPerson))addressis 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, andiplanet-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/EndUserpage, 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
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
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
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.
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_idas described in section 2.2 of RFC 6749.ssoadm attribute:
iplanet-am-auth-oauth-client-id- Client Secret
OAuth
client_secretas 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.jspfile, 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-attremail=mailandid=facebook-id.ssoadm attribute:
org-forgerock-auth-oauth-account-mapper-configuration- Attribute Mapper
Class implementing attribute mapping. Default:
org.forgerock.openam.authentication.modules.oauth2.DefaultAttributeMapperssoadm 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-attrssoadm 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.DefaultEmailGatewayImplssoadm 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 isinfo@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.
| OpenAM Field | Details |
|---|---|
| Authentication Endpoint URL |
Example: |
| Access Token Endpoint URL |
Example: |
| User Profile Service URL |
Example: |
[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 The | |
| 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 |
| 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 |
| 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 |
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.
Scroll down in the properties page for the chain. You should set the
PersistentCookieAuthModule as shown in the following figure:
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”
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 isiplanet-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
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
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.recfile 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
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-nameHere,
hostanddomaincorrespond to the host and domain names of the OpenAM instance, anddc-domain-nameis the domain name of the Windows Kerberos domain controller server. Thedc-domain-namecan 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
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
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
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.
On the Access Control tab page of the OpenAM console, click the realm for which to create the authentication chain.
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.
Give the new authentication chain a name, and add instances of the modules to use in the chain.
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.
If you need modules in the chain to share user credentials, then set options for the module.
iplanet-am-auth-shared-state-enabledSet
iplanet-am-auth-shared-state-enabled=trueto 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-enabledSet
iplanet-am-auth-store-shared-state-enabled=trueto 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-patternSet
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=useFirstPassto 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 criteriaREQUIRED. The second module in the chain has optionsiplanet-am-auth-shared-state-enabled=true,iplanet-am-auth-shared-state-behavior-pattern=tryFirstPass, and criteriaREQUIRED. 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.Save your work.
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.
On the Access Control tab page of the OpenAM console, click the realm for which to set the default authentication chain.
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,
amadmincan login at/openam/UI/Login. You can change that for your deployment.Save your work.
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.
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.jspafter 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.
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, oruser.- 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
IDTokenparameters in the URL. TheIDTokencredentials map to the fields in the login page for the authentication module, such asIDToken1as user ID andIDToken2as password for basic user name, password authentication. The order depends on the callbacks in login page for the module;IDTokenNrepresents 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
DProPCookiethat persists until expiry. The following screen shot shows an example.An alternative persistent cookie mechanism extends the lifetime of the normal
iPlanetDirectoryProusing the advanced server settings,openam.session.persist_am_cookieoropenam.session.allow_persist_am_cookie, andcom.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 setopenam.session.persist_am_cookietotrueandcom.iplanet.am.cookie.timeToLiveto 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 setopenam.session.allow_persist_am_cookietotrueandcom.iplanet.am.cookie.timeToLiveto 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, useopenam.session.persist_am_cookie=Yesas 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, oruser.- 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, oruser.- 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, orservice.
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
inactivein 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
inetuserstatusprofile attribute toinactive. 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.
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.
The session quota applies to all sessions opened for the same user (as represented by the user's universal identifier).
Log in to OpenAM Console as administrator, and then browse to Configuration > Global > Session.
Set Enable Quota Constraints to
ON.Set Resulting behavior if session quota exhausted.
The following settings are available by default.
DENY_ACCESSDeny access, preventing the user from creating an additional session.
DESTROY_NEXT_EXPIRINGRemove 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_SESSIONRemove the oldest session, and create a new session for the user.
DESTROY_OLD_SESSIONSRemove 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.
Set Active User Sessions to the session quota.
The default is 5 sessions.
Save your work.
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
truefor 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.