Core Authentication Attributes
Every AM realm has a set of authentication properties that applies to all authentication performed to that realm. The settings are referred to as core authentication attributes.
To configure core authentication attributes for an entire AM deployment, go to Configure > Authentication in the AM console, and then click Core Attributes.
To override the global core authentication configuration in a realm, navigate to Realms > Realm Name > Authentication > Settings in the AM console. Note that when you configure core authentication attributes in a realm, the Global Attributes tab does not appear.
amster service name: Authentication
ssoadm service name: iPlanetAMAuthService
The following properties are available under the Global Attributes tab:
- Pluggable Authentication Module Classes
Lists the authentication modules classes available to AM. If you have custom authentication modules, add classes to this list that extend from the
com.sun.identity.authentication.spi.AMLoginModule
class.For more information about custom authentication modules, see "Creating a Custom Authentication Module".
amster attribute:
authenticators
ssoadm attribute:
iplanet-am-auth-authenticators
- LDAP Connection Pool Size
Sets a minimum and a maximum number of LDAP connections to be used by any authentication module that connects to a specific directory server. This connection pool is different than the SDK connection pool configured in
serverconfig.xml
file.Format is
host:port:minimum:maximum
.This attribute is for LDAP and Membership authentication modules only.
amster attribute:
ldapConnectionPoolSize
ssoadm attribute:
iplanet-am-auth-ldap-connection-pool-size
- Default LDAP Connection Pool Size
Sets the default minimum and maximum number of LDAP connections to be used by any authentication module that connects to any directory server. This connection pool is different than the SDK connection pool configured in
serverconfig.xml
file.Format is
minimum:maximum
.When tuning for production, start with 10 minimum, 65 maximum. For example,
10:65
.This attribute is for LDAP and Membership authentication modules only.
amster attribute:
ldapConnectionPoolDefaultSize
ssoadm attribute:
iplanet-am-auth-ldap-connection-pool-default-size
- Remote Auth Security
When enabled, AM requires the authenticating application to send its SSO token. This allows AM to obtain the username and password associated with the application.
amster attribute:
remoteAuthSecurityEnabled
ssoadm attribute:
sunRemoteAuthSecurityEnabled
- Keep Post Process Objects for Logout Processing
When enabled, AM stores instances of post-processing classes into the user session. When the user logs out, the original post-processing classes are called instead of new instances. This may be required for special logout processing.
Enabling this setting increases the memory usage of AM.
amster attribute:
keepPostProcessInstances
ssoadm attribute:
sunAMAuthKeepPostProcessInstances
The following properties are available under the Core tab:
- Administrator Authentication Configuration
Specifies the default authentication chain used when an administrative user, such as
amAdmin
, logs in to the AM console.ssoadm attribute:
iplanet-am-auth-admin-auth-module
- Organization Authentication Configuration
Specifies the default authentication chain used when a non-administrative user logs in to AM.
amster attribute:
orgConfig
ssoadm attribute:
iplanet-am-auth-org-config
The following properties are available under the User Profile tab:
User Profile
Specifies whether a user profile needs to exist in the user data store, or should be created on successful authentication. The possible values are:
true
. Dynamic.After successful authentication, AM creates a user profile if one does not already exist. AM then issues the SSO token. AM creates the user profile in the user data store configured for the realm.
createAlias
. Dynamic with User Alias.After successful authentication, AM creates a user profile that contains the
User Alias List
attribute, which defines one or more aliases for mapping a user's multiple profiles.ignore
. Ignored.After successful authentication, AM issues an SSO token regardless of whether a user profile exists in the data store. The presence of a user profile is not checked.
Warning
Any functionality which needs to map values to profile attributes, such as SAML or OAuth 2.0, will not operate correctly if the User Profile property is set to
ignore
.false
. Required.After successful authentication, the user must have a user profile in the user data store configured for the realm in order for AM to issue an SSO token.
ssoadm attribute:
iplanet-am-auth-dynamic-profile-creation
. Set this attribute's value to one of the following:true
,createAlias
,ignore
, orfalse
.- 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 the
true
orcreateAlias
options are selected under the User Profile property. 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 AM 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 property in the user profile.
This functionality is deprecated.
amster attribute:
defaultRole
ssoadm attribute:
iplanet-am-auth-default-role
- Alias Search Attribute Name
After a user is successfully authenticated, the user's profile is retrieved. AM first searches for the user based on the data store settings. If that fails to find the user, AM will use the attributes listed here to look up the user profile. This setting accepts any data store specific attribute name.
amster attribute:
aliasAttributeName
ssoadm attribute:
iplanet-am-auth-alias-attr-name
Note
If the
Alias Search Attribute Name
property is empty, AM uses theiplanet-am-auth-user-naming-attr
property from theiPlanetAmAuthService
. Theiplanet-am-auth-user-naming-attr
property is only configurable through the ssoadm command-line tool and not through the AM console.$
ssoadm get-realm-svc-attrs \ --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org \ --password-file PATH_TO_PWDFILE \ --realm REALM \ --servicename iPlanetAMAuthService
$ssoadm set-realm-svc-attrs \ --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org \ --password-file PATH_TO_PWDFILE \ --realm REALM \ --servicename iPlanetAMAuthService \ --attributevalues iplanet-am-auth-user-naming-attr=SEARCH_ATTRIBUTE
The following properties are available under the Account Lockout tab:
- Login Failure Lockout Mode
When enabled, AM deactivates the LDAP attribute defined in the Lockout Attribute Name property in the user's profile upon login failure. This attribute works in conjunction with the other account lockout and notification attributes.
amster attribute:
loginFailureLockoutMode
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.
amster attribute:
loginFailureCount
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 by the Login Failure Lockout Count property. If an attempt within the defined lockout interval time proves successful before the number of attempts reaches the number defined by the Login Failure Lockout Count property, the lockout count is reset.
amster attribute:
loginFailureDuration
ssoadm attribute:
iplanet-am-auth-login-failure-duration
- Email Address to Send Lockout Notification
Specifies one or more email addresses to which notification is sent if a user lockout occurs.
Separate multiple addresses with spaces, and append
|locale|charset
to addresses for recipients in non-English locales.amster attribute:
lockoutEmailAddress
ssoadm attribute:
iplanet-am-auth-lockout-email-address
- Warn User After N Failures
Specifies the number of authentication failures after which AM 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.
amster attribute:
lockoutDuration
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. After 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.
amster attribute:
lockoutDurationMultiplier
ssoadm attribute:
sunLockoutDurationMultiplier
- Lockout Attribute Name
Defines the LDAP attribute used for physical lockout. The default attribute is
inetuserstatus
, although the field in the AM console is empty. The Lockout Attribute Value field must also contain an appropriate value.amster attribute:
lockoutAttributeName
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 AM console is empty. The Lockout Attribute Name field must also contain an appropriate value.amster attribute:
lockoutAttributeValue
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. Although the field appears empty in the AM console, AM stores this data in the
sunAMAuthInvalidAttemptsDataAttrName
attribute defined in thesunAMAuthAccountLockout
objectclass by default.amster attribute:
invalidAttemptsDataAttributeName
ssoadm attribute:
sunAMAuthInvalidAttemptsDataAttrName
- Store Invalid Attempts in Data Store
When enabled, AM stores the information regarding failed authentication attempts as the value of the Invalid Attempts Data Attribute Name in the user data store. 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 AM.
Enable this property to track invalid log in attempts when using CTS-based or client-based authentication sessions.
amster attribute:
storeInvalidAttemptsInDataStore
ssoadm attribute:
sunStoreInvalidAttemptsInDS
The following properties are available under the General tab:
- Default Authentication Locale
Specifies the default language subtype to be used by the Authentication Service. The default value is
en_US
.amster attribute:
locale
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 AM to conduct a second lookup if the first lookup fails. The possible values are:
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.
Default:
Agent
andUser
.amster attribute:
identityType
ssoadm attribute:
sunAMIdentityType
- Pluggable User Status Event Classes
Specifies one or more Java classes used to provide a callback mechanism for user status changes during the authentication process. The Java class must implement the
com.sun.identity.authentication.spi.AMAuthCallBack
interface. AM supports account lockout and password changes. AM supports password changes through the LDAP authentication module, and so the feature is only available for the LDAP module.A
.jar
file containing the user status event class belongs in theWEB-INF/lib
directory of the deployed AM instance. If you do not build a.jar
file, add the class files underWEB-INF/classes
.amster attribute:
userStatusCallbackPlugins
ssoadm attribute:
sunAMUserStatusCallbackPlugins
- Use Client-Based Sessions
When enabled, AM assigns client-based sessions to users authenticating to this realm. Otherwise, AM users authenticating to this realm are assigned CTS-based sessions.
For more information about sessions, see Introducing Sessions.
amster attribute:
statelessSessionsEnabled
ssoadm attribute:
openam-auth-stateless-sessions
- Two Factor Authentication Mandatory
When enabled, users authenticating to a chain that includes a ForgeRock Authenticator (OATH) module are always required to perform authentication using a registered device before they can access AM. When not selected, users can opt to forego registering a device and providing a token and still successfully authenticate.
Letting users choose not to provide a verification token while authenticating carries implications beyond the
required
,optional
,requisite
, orsufficient
flag settings on the ForgeRock Authenticator (OATH) module in the authentication chain. For example, suppose you configured authentication as follows:The ForgeRock Authenticator (OATH) module is in an authentication chain.
The ForgeRock Authenticator (OATH) module has the
required
flag set.Two Factor Authentication Mandatory is not selected.
Users authenticating to the chain can authenticate successfully without providing tokens from their devices. The reason for successful authentication in this case is that the
required
setting relates to the execution of the ForgeRock Authenticator (OATH) module itself. Internally, the ForgeRock Authenticator (OATH) module has the ability to forego processing a token while still returning a passing status to the authentication chain.Note
The
Two Factor Authentication Mandatory
property only applies to modules within authentication chains, and does not affect nodes within authentication trees.amster attribute:
twoFactorRequired
ssoadm attribute:
forgerockTwoFactorAuthMandatory
- External Login Page URL
Specifies the URL of the external login user interface, if the authentication user interface is hosted separately from AM.
When set, AM will use the provided URL as the base of the resume URI, rather than using the Base URL Source Service to obtain the base URL. AM will use this URL when constructing the resume URI if authentication is suspended in an authentication tree.
For more information about the Base URL Source Service, see "Configuring the Base URL Source Service".
amster attribute:
externalLoginPageUrl
ssoadm attribute:
externalLoginPageUrl
- Default Authentication Level
Specifies the default authentication level for authentication modules.
amster attribute:
defaultAuthLevel
ssoadm attribute:
iplanet-am-auth-default-auth-level
The following properties are available under the Trees tab:
- Authentication session state management scheme
Specifies the location where AM stores authentication sessions.
Possible values are:
CTS
. AM stores authentication sessions in the CTS token store.JWT
. AM sends the authentication session to the client as a JWT.In-Memory
. AM stores authentication sessions in its memory.
For more information on authentication session storage locations, and the requirements for each, see Introducing Sessions.
Default:
JWT
(new installations),In-Memory
(after upgrade)amster attribute:
authenticationSessionsStateManagement
ssoadm attribute:
openam-auth-authentication-sessions-state-management-scheme
- Max duration (minutes)
Specifies the maximum allowed duration of an authentication session, including any time spent in the suspended state, in minutes.
Values from
1
to2147483647
are allowed.Default:
5
amster attribute:
authenticationSessionsMaxDuration
ssoadm attribute:
openam-auth-authentication-sessions-max-duration
- Suspended authentication duration (minutes)
Specifies the length of time an authentication session can be suspended, in minutes.
Suspending an authentication session allows time for out-of-band authentication methods, such as responding to emailed codes or performing an action on an additional device. The value must be less than or equal to the total time allowed for an authentication session, specified in the Max duration (minutes) property.
Values from
1
to2147483647
are allowed.Default:
5
ssoadm attribute:
suspendedAuthenticationTimeout
- Enable whitelisting
When enabled, AM whitelists authentication sessions to protect them against replay attacks.
Default: Disabled
amster attribute:
authenticationSessionsWhitelist
ssoadm attribute:
openam-auth-authentication-sessions-whitelist
The following properties are available under the Security tab:
- Module Based Authentication
When enabled, users can authenticate using module-based authentication. Otherwise, all attempts at authentication using the
module=module-name
login parameter result in failure.ForgeRock recommends disabling module-based authentication in production environments.
amster attribute:
moduleBasedAuthEnabled
ssoadm attribute:
sunEnableModuleBasedAuth
- Persistent Cookie Encryption Certificate Alias
Specifies the key pair alias in the AM keystore to use for encrypting persistent cookies.
Default:
test
amster attribute:
keyAlias
ssoadm attribute:
iplanet-am-auth-key-alias
- Zero Page Login
When enabled, AM allows users to authenticate using only GET request parameters without showing a login screen.
Caution
Enable with caution as browsers can cache credentials and servers can log credentials when they are part of the URL.
AM always allows HTTP POST requests for zero page login.
Default: false (disabled)
amster attribute:
zeroPageLoginEnabled
ssoadm attribute:
openam.auth.zero.page.login.enabled
- Zero Page Login Referer Whitelist
Lists the HTTP referer URLs for which AM allows zero page login. These URLs are supplied in the
Referer
HTTP request header, allowing clients to specify the web page that provided the link to the requested resource.When zero page login is enabled, including the URLs for the pages from which to allow zero page login will provide some mitigation against Login Cross-Site Request Forgery (CSRF) attacks. Leave this list blank to allow zero page login from any Referer.
This setting applies for both HTTP GET and also HTTP POST requests for zero page login.
amster attribute:
zeroPageLoginReferrerWhiteList
ssoadm attribute:
openam.auth.zero.page.login.referer.whitelist
- Zero Page Login Allowed Without Referer?
When enabled, allows zero page login for requests without an HTTP
Referer
request header. Zero page login must also be enabled.Enabling this setting reduces the risk of login CSRF attacks with zero page login enabled, but may potentially deny legitimate requests.
amster attribute:
zeroPageLoginAllowedWithoutReferrer
ssoadm attribute:
openam.auth.zero.page.login.allow.null.referer
- Organization Authentication Signing Secret
Specifies a cryptographically-secure random-generated HMAC shared secret for signing RESTful authentication requests. When users attempt to authenticate to the UI, AM signs a JSON Web Token (JWT) containing this shared secret. The JWT contains the authentication session ID, realm, and authentication index type value, but does not contain the user's credentials.
When modifying this value, ensure the new shared secret is Base-64 encoded and at least 128 bits in length.
amster attribute:
sharedSecret
ssoadm attribute:
iplanet-am-auth-hmac-signing-shared-secret
The following properties are available under the Post Authentication Processing tab:
- Default Success Login URL
Accepts a list of values that specifies where users are directed after successful authentication. The format of this attribute is
client-type|URL
although the only value you can specify at this time is a URL which assumes the type HTML. The default value is/openam/console
. Values that do not specify HTTP have that appended to the deployment URI.amster attribute:
loginSuccessUrl
ssoadm attribute:
iplanet-am-auth-login-success-url
- Default Failure Login URL
Accepts a list of values that specifies where users are directed after authentication has failed. The format of this attribute is
client-type|URL
although the only value you can specify at this time is a URL which assumes the type HTML. Values that do not specify HTTP have that appended to the deployment URI.amster attribute:
loginFailureUrl
ssoadm attribute:
iplanet-am-auth-login-failure-url
- Authentication Post Processing Classes
Specifies one or more Java classes used to customize post authentication processes for successful or unsuccessful logins. The Java class must implement the
com.sun.identity.authentication.spi.AMPostAuthProcessInterface
AM interface.A
.jar
file containing the post processing class belongs in theWEB-INF/lib
directory of the deployed AM instance. If you do not build a.jar
file, add the class files underWEB-INF/classes
. For deployment, add the.jar
file or classes into a custom AM.war
file.For information on creating post-authentication plugins, see "Creating Post-Authentication Plugins for Chains".
amster attribute:
loginPostProcessClass
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 IDs are generated by the class specified in the Pluggable User Name Generator Class property.
amster attribute:
usernameGeneratorEnabled
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
.amster attribute:
usernameGeneratorClass
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 SSO token. The value takes the format
User-Profile-Attribute|Session-Attribute-Name
. If Session-Attribute-Name is not specified, the value of User-Profile-Attribute is used. All session attributes contain theam.protected
prefix to ensure that they cannot be edited by the client applications.For example, if you define the user profile attribute as
mail
and the user's email address, available in the user session, asuser.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 cannot be modified (for example,
SSOToken.setProperty(String, String)
). This results in anSSOException
. Multivalued attributes, such asmemberOf
, are listed as a single session variable with a|
separator.When configuring authentication for a realm configured for client-based sessions, be careful not to add so many session attributes that the session cookie size exceeds the maximum allowable cookie size. For more information about client-based session cookies, see Session Cookies and Session Security.
amster attribute:
userAttributeSessionMapping
ssoadm attribute:
sunAMUserAttributesSessionMapping
Important
The
User Attribute Mapping to Session Attribute
property only applies to modules within authentication chains. For authentication trees, use the Scripted Decision Node to retrieve user attributes and session properties, or the Set Session Properties Node for session properties only.