AM 7.3.1

Deployment configuration

Under Deployment, you can manage different configurations for AM server instances, and site configurations when using multiple AM server instances.

Configure servers

AM server properties reside in two places:

  • The default configuration, under Configure > Server Defaults.

  • Per-server basis configuration, under Deployment > Servers > Server Name.

Default server properties are applied to all server instances, and can be overridden on a per-server basis. Changes to the value of a default server property are applied to all servers that are not overriding that property. The ability to set default properties and override them for an individual server lets you keep a set of properties with identical configuration across the environment, while providing the flexibility to change properties on specific servers when required.

A closed lock means inherited, an open lock means localized.
Figure 1. Inherited properties
  • A closed lock means the property is inherited from the defaults. To change an inherited value click on the lock, and the property will become localized for that server.

  • An open lock means the property is localized for this server. To return to the inherited values, click on the lock.

The Advanced section also takes values from the defaults, but the properties do not have locks for inheritance. Instead, if you want to override a particular advanced property value on a per-server basis, you need to add that property with its new value under Deployment > Servers > Server Name > Advanced.

After changing server configurations, restart AM or the web application container where AM runs for the changes to take effect unless otherwise noted.

General properties

The General page provides access to properties, such as site configuration, server base installation directory, default locale, debug levels, and other properties.

Site

The following properties are available under the Site tab:

Parent Site

Specifies the site the server belongs to. The drop-down list defaults to [empty} until there is at least one site created in the deployment.

The Site tab is only available by navigating to Deployment > Servers > Server Name > General.

System

The following properties are available under the System tab:

Base installation directory

Specifies the directory where AM’s configuration data and logs reside. For example, /path/to/openam/.

property: com.iplanet.services.configpath

Default Locale

Specifies the default locale of the UI pages when the client does not request a locale either by using the locale query string parameter or by setting the HTTP header, Accept-Language.

To set the locale when AM cannot find UI files for the requested locale, set the JVM platform locale instead.

Default: en_US

property: com.iplanet.am.locale

Notification URL

Specifies the URL of the notification service endpoint. For example, https://openam.example.com:443/openam/notificationservice.

Default: %SERVER_PROTO%://%SERVER_HOST%:%SERVER_PORT%/%SERVER_URI%/notificationservice

property: com.sun.identity.client.notification.url

XML Validation

When enabled, AM validates any XML document it parses.

Default: Off

property: com.iplanet.am.util.xml.validating

Debugging

The following properties are available under the Debugging tab:

Debug Level

Specifies the log level shared across components for debug logging.

Changes to this property take effect immediately. No server restart is necessary.

Default: Error

property: com.iplanet.services.debug.level

Merge Debug Files

When enabled, AM writes debug log messages to a single file, debug.out. By default, AM writes a debug log per component.

Changes to this property take effect immediately. No server restart is necessary.

Default:Off

property: com.iplanet.services.debug.mergeall

Debug Directory

Specifies the path where AM writes debug logs. For example, /path/to/openam/var/debug.

Changes to this property do not take effect until you restart the AM server.

Default: %BASE_DIR%/%SERVER_URI%/var/debug

property: com.iplanet.services.debug.directory

Mail server

The following properties are available under the Mail Server tab:

Mail Server Host Name

Specifies the hostname of the SMTP server AM uses for sending email.

Default: localhost

property: com.iplanet.am.smtphost

Mail Server Port Number

Specifies the port of the SMTP server AM uses for sending email.

Default: 25

property: com.iplanet.am.smtpport

Security properties

Most security settings are inherited by default.

Encryption

The following properties are available under the Encryption tab:

Password Encryption Key

Specifies the encryption key for decrypting stored passwords.

The value of the am.encryption.pwd property must be the same for all deployed servers in a site. You can set the Password Encryption Key property at Deployment > Servers > Server Name > Security. Verify that all servers have the same setting for this property.

Example: TF1Aue9c63bWTTY4mmZJeFYubJbNiSE3

property: am.encryption.pwd

Encryption class

Specifies the default class used to handle encryption

Default: com.iplanet.services.util.JCEEncryption

property: com.iplanet.security.encryptor

Secure Random Factory Class

Specifies the class used to provide AM with cryptographically strong random strings. Possible values are the com.iplanet.am.util.JSSSecureRandomFactoryImpl class for JSS and the com.iplanet.am.util.SecureRandomFactoryImpl class for pure Java.

Default: com.iplanet.am.util.SecureRandomFactoryImpl

property: com.iplanet.security.SecureRandomFactorImpl

Validation

The following properties are available under the Validation tab:

Platform Low Level Comm. Max. Content Length

Specifies the maximum content length for an HTTP request.

Default: 16384

property: com.iplanet.services.comm.server.pllrequest.maxContentLength

Client IP Address Check

When enabled, AM checks client IP addresses when creating and validating SSO tokens.

Default: Disabled

property: com.iplanet.am.clientIPCheckEnabled

The following properties are available under the Cookie tab:

Cookie Name

Specifies the cookie name AM uses to set a session handler ID during authentication.

Default: iPlanetDirectoryPro

property: com.iplanet.am.cookie.name

Secure Cookie

When enabled, AM generates secure cookies, which are only transmitted over an encrypted connection like HTTPS.

Default: Disabled

property: com.iplanet.am.cookie.secure

Encode Cookie Value

When enabled, AM URL-encodes the cookie values.

Default: Disabled

property: com.iplanet.am.cookie.encode

Key store

The following properties are available under the Key Store tab:

Keystore File

Specifies the path to the AM keystore file, for example, /path/to/openam/security/keystores/keystore.jceks.

Default: %BASE_DIR%/%SERVER_URI%/keystore.jceks

property: com.sun.identity.saml.xmlsig.keystore

Keystore Type

Specifies the keystore type, for example JKS, JCEKS, PKCS11, or PKCS12.

This can be a custom keystore type, which must be supported by, and configured in, the local Java runtime environment.

Default: JCEKS

property: com.sun.identity.saml.xmlsig.storetype

Keystore Password File

Specifies the path to the password file for the keystore, for example, /path/to/openam/security/secrets/default/.storepass. The password contained in this file is in cleartext.

Default: %BASE_DIR%/%SERVER_URI%/.storepass

property: com.sun.identity.saml.xmlsig.storepass

Private Key Password File

Specifies the path to the password file for the private key aliases contained in the keystore, for example, /path/to/openam/security/secrets/default/.keypass. The password contained in this file is in cleartext.

Default: %BASE_DIR%/%SERVER_URI%/.keypass

property: com.sun.identity.saml.xmlsig.keypass

Certificate Alias

Leave the default test alias.

property: com.sun.identity.saml.xmlsig.certalias

Certificate revocation list caching

The following properties are available under the Certificate Revocation List Caching tab:

LDAP server host name

Specifies the hostname of the LDAP server where AM caches the certificate revocation list (CRL).

property: com.sun.identity.crl.cache.directory.host

LDAP server port number

Specifies the port number of the LDAP server where AM caches the certificate revocation list.

property: com.sun.identity.crl.cache.directory.port

SSL/TLS Enabled

When enabled, AM connects securely to the directory server holding the CRL cache. Ensure that AM trust the certificate from the LDAP server when enabling this option.

Default: Disabled

property: com.sun.identity.crl.cache.directory.ssl

LDAP server bind user name

Specifies the bind DN of the service account AM uses to authenticate to the LDAP server holding the CRL cache.

property: com.sun.identity.crl.cache.directory.user

LDAP server bind password

Specifies the bind password of the username set in the LDAP server bind user name property.

property: com.sun.identity.crl.cache.directory.password

LDAP search base DN

Specifies a valid Base DN for the LDAP search, such as dc=example,dc=com.

property: com.sun.identity.crl.cache.directory.searchlocs

Search Attributes

Specifies which DN component of issuer’s subject DN is used to retrieve the CRL in the LDAP server, for example, cn.

property: com.sun.identity.crl.cache.directory.searchattr

Online certificate status protocol check

The following properties are available under the Online Certificate Status Protocol Check tab:

Check Enabled

When enabled, AM checks the revocation status of certificates using the Online Certificate Status Protocol (OCSP).

Default: Disabled

property: com.sun.identity.authentication.ocspCheck

Responder URL

Specifies the URL for the OCSP responder to contact about the revocation status of certificates.

property: com.sun.identity.authentication.ocsp.responder.url

Certificate Nickname

Specifies the nickname for the OCSP responder certificate set in the Responder URL property.

property: com.sun.identity.authentication.ocsp.responder.nickname

Object deserialisation class allowlist

Whitelist

Specifies a list of classes that are considered valid when AM performs object deserialization operations.

Default: com.iplanet.dpro.session.DNOrIPAddressListTokenRestriction, com.sun.identity.common.CaseInsensitiveHashMap,com.sun.identity.common.CaseInsensitiveHashSet, com.sun.identity.common.CaseInsensitiveKey, com.sun.identity.common.configuration.ServerConfigXML, com.sun.identity.common.configuration.ServerConfigXML$DirUserObject, com.sun.identity.common.configuration.ServerConfigXML$ServerGroup, com.sun.identity.common.configuration.ServerConfigXML$ServerObject, com.sun.identity.console.base.model.SMSubConfig, com.sun.identity.console.service.model.SMDescriptionData, com.sun.identity.console.service.model.SMDiscoEntryData, com.sun.identity.console.session.model.SMSessionData, com.sun.identity.console.user.model.UMUserPasswordResetOptionsData, com.sun.identity.shared.datastruct.OrderedSet,com.sun.xml.bind.util.ListImpl, com.sun.xml.bind.util.ProxyListImpl, java.lang.Boolean,java.lang.Integer, java.lang.Number,java.lang.StringBuffer, java.net.InetAddress,java.security.cert.Certificate, java.security.cert.Certificate$CertificateRep, java.util.ArrayList,java.util.Collections$EmptyMap, java.util.Collections$EmptySet, java.util.Collections$SingletonList, java.util.HashMap,java.util.HashSet, java.util.LinkedHashSet, java.util.Locale, org.forgerock.openam.authentication.service.protocol.RemoteCookie, org.forgerock.openam.authentication.service.protocol.RemoteHttpServletRequest, org.forgerock.openam.authentication.service.protocol.RemoteHttpServletResponse, org.forgerock.openam.authentication.service.protocol.RemoteServletRequest, org.forgerock.openam.authentication.service.protocol.RemoteServletResponse, org.forgerock.openam.authentication.service.protocol.RemoteSession, org.forgerock.openam.dpro.session.NoOpTokenRestriction

property: openam.deserialisation.classes.whitelist

Session properties

Session settings are inherited by default.

Session limits

The following properties are available under the Sessions Limits tab:

Maximum Session Cache Size

Specifies the maximum number of sessions to cache in the AM server’s internal session cache.

Default: 5000

property: org.forgerock.openam.session.service.access.persistence.caching.maxsize

Invalidate Session Max Time

Specifies the time in minutes after which invalid server-side sessions are removed from the session table.

Default: 3 (minutes)

property: com.iplanet.am.session.invalidsessionmaxtime

Statistics

The following properties are available under the Statistics tab:

Logging Interval (in seconds)

Specifies the time in seconds AM delays between logging server-side session statistics. Any value lower than 5 is interpreted as 5 seconds.

Default: 60

property: com.iplanet.am.stats.interval

State

Specifies whether to write statistics to a File, to the Console, or to turn recording Off.

Default: File

property: com.iplanet.services.stats.state

Directory

Specifies the path where AM writes the statistic files, for example, /path/to/openam/var/stats.

Default: %BASE_DIR%/%SERVER_URI%/var/stats

property: com.iplanet.services.stats.directory

Enable Host Lookup

When enabled, AM performs host lookup during server-side session logging.

Default: Disabled

property: com.sun.am.session.enableHostLookUp

Notification

The following properties are available under the Notification tab:

Notification Pool Size

Specifies the number of threads in the session change notification thread pool. Session notification applies to server-side sessions only.

Default: 10

property: com.iplanet.am.notification.threadpool.size

Notification Thread Pool Threshold

Specifies the maximum number of tasks in the queue for serving session change notification threads. Session notification applies to server-side sessions only.

Default: 5000

property: com.iplanet.am.notification.threadpool.threshold

Validation

The following properties are available under the Validation tab:

Case Insensitive client DN comparison

When enabled, AM performs case insensitive distinguished name comparison.

Default: Enabled

property: com.sun.am.session.caseInsensitiveDN

SDK properties

Most SDK settings are inherited.

Data store

The following properties are available under the Data Store tab:

Enable Datastore Notification

When enabled, AM uses data store notification. Otherwise, AM uses in-memory notification.

Changes to this property take effect immediately. No server restart is necessary.

Default: Enabled

property: com.sun.identity.sm.enableDataStoreNotification

Enable Directory Proxy

When enabled, AM accounts for the use of a directory proxy to access the directory server, for example, by enabling delegation privileges rather than ACIs for access control to the proxy.

Enable this option if you have deployed Directory Services as a directory proxy in front of a number of additional DS instances. For more information, see Directory Proxy in the DS documentation.

Default: Disabled

property: com.sun.identity.sm.ldap.enableProxy

Notification Pool Size

Specifies the size of the thread pool used to send notifications. A value of 1 causes notifications to be processed sequentially, avoiding any potential out-of-order conditions. In production, where configuration is unlikely to change often, keeping the default of 1 is recommended.

Default: 1

property: com.sun.identity.sm.notification.threadpool.size

Event service

The following properties are available under the Event Service tab:

Number of retries for Event Service connections

Specifies the maximum number of attempts to reestablish event service connections.

Default: 3

property: com.iplanet.am.event.connection.num.retries

Delay between Event Service connection retries

Specifies the time in milliseconds between attempts to reestablish entry service connections.

Default: 3000

property: com.iplanet.am.event.connection.delay.between.retries

Error codes for Event Service connection retries

Specifies the LDAP error codes for which AM retries rather than returning failure.

Default: 80,81,91

property: com.iplanet.am.event.connection.ldap.error.codes.retries

Disabled Event Service Connection

Specifies which persistent search connections AM can disable. Any connection that is not specified as disabled is enabled.

Multiple values should be separated with a comma ,.

Default: aci,um

property: com.sun.am.event.connection.disable.list

Possible values are:

  • aci. Obtain notification changes to the aci attribute.

  • um. Obtain notification changes in AM’s user store. For example, modifying a password.

  • sm. Obtain notification changes in AM’s configuration store. For example, modifying a realm.

LDAP connection

The following properties are available under the LDAP Connection tab:

Number of retries for LDAP Connection

Specifies the maximum number of attempts to reestablish LDAP connections.

Default: 3

property: com.iplanet.am.ldap.connection.num.retries

Delay between LDAP connection retries

Specifies the time, in milliseconds, between attempts to reestablish LDAP connections.

Default: 1000

property: com.iplanet.am.ldap.connection.delay.between.retries

Error Codes for LDAP connection retries

Specifies the LDAP error codes for which AM retries rather than returning failure.

Default: 80,81,91

property: com.iplanet.am.ldap.connection.ldap.error.codes.retries

Caching and replica

The following properties are available under the Caching and Replica tab:

SDK Caching Max. Size

Specifies the cache size used when SDK caching is enabled. The size should be an integer greater than 0, or the default size of 10000 will be used.

Changes to this property clear the contents of the cache. No server restart is necessary.

Default: 10000

property: com.iplanet.am.sdk.cache.maxSize

SDK Replica Retries

Specifies the maximum number of attempts to retry when an entry not found error is returned to the SDK.

Changes to this property take effect immediately. No server restart is necessary.

Default: 0

property: com.iplanet.am.replica.num.retries

Delay between SDK Replica Retries

Specifies the time in milliseconds between attempts to retrieve entries through the SDK.

Changes to this property take effect immediately. No server restart is necessary.

Default: 1000

property: com.iplanet.am.replica.delay.between.retries

Time to live configuration

The following properties are available under the Time to Live Configuration tab:

Cache Entry Expiration Enabled

When disabled, cache entries expire based on the User Entry Expiration Time property.

Default: Disabled

property: com.iplanet.am.sdk.cache.entry.expire.enabled

User Entry Expiration Time

Specifies the time in minutes for which user entries remain valid in cache after their last modification. When AM accesses a user entry that has expired, it reads the entry from the directory server instead of from the cache.

Default: 15

property: com.iplanet.am.sdk.cache.entry.user.expire.time

Default Entry Expiration Time

Specifies the time in minutes for which non-user entries remain valid in cache after their last modification. When AM accesses a non-user entry that has expired, it reads the entry from the directory server instead of from the cache.

Default: 30

property: com.iplanet.am.sdk.cache.entry.default.expire.time

CTS properties

The Core Token Service (CTS) does not need to be configured in the same LDAP storage as the configuration store. The CTS can instead be configured on its own external directory server. There are some specific requirements for indexing and replication which need to be accounted for. In particular, WAN replication is an important consideration which needs to be handled carefully for optimum performance.

You may also choose to set advanced properties related to token size, including com.sun.identity.session.repository.enableEncryption, com.sun.identity.session.repository.enableCompression, and com.sun.identity.session.repository.enableAttributeCompression. For more information about these three properties, see Advanced properties.

CTS token store

The following properties are available under the CTS Token Store tab:

Store Mode

Specifies whether AM stores CTS tokens in the default token store or in an external token store.

CTS tokens are stored in the same data store used for the AM configuration when you specify the Default Token Store option. When specifying this option, you can only configure the properties available under the CTS Token Store tab.

You can separate the CTS store from the AM configuration on different external servers by selecting the External Token Store option. When specifying this option, you can configure the properties available under both the CTS Token Store and the External Store Configuration tabs.

Root Suffix

For either default or external token stores, specifies the base DN for CTS storage information in LDAP format, such as cn=cts,ou=famrecords,ou=openam-session,ou=tokens. The Root Suffix specifies a database that can be maintained and replicated separately from the standard user data store.

Max Connections

Specifies the maximum number of remote connections to the external data store. For affinity deployments, this property specifies the maximum number of remote connections to each directory server in the connection string.

Default: 100

For suggested settings, see Tuning CTS Store LDAP Connections.

Page Size

The number of results per page returned from the underlying CTS datastore.

If the result set is smaller than the page size, the number of results will never be paginated. If larger, the number of pages returned will be the result set size divided by the page size.

Increasing the page size results in fewer round trips to the CTS datastore when retrieving large result sets.

To return all results and disable pagination, set to 0.

Default: 0

VLV Page Size

The number of results per page returned from the underlying CTS datastore when using virtual list views (VLVs). Larger values will result in fewer round trips to the datastore when retrieving large result sets, and VLVs are enabled on the datastore.

For more information on VLVs, see Virtual List View Index in the DS documentation.

Default: 10

External store configuration

AM honors the following properties when External Token Store is selected under the CTS Token Store tab:

SSL/TLS Enabled

When enabled, AM accesses the external directory service using StartTLS or SSL.

Connection String(s)

Specifies the ordered list of connection strings for external DS servers. The format is HOST:PORT[|SERVERID[|SITEID]], where HOST:PORT are the LDAP server and its port. SERVERID and SITEID are optional parameters to specify an AM instance that prioritizes the particular connection. This does not exclude other AM instances from using that connection, although they must have no remaining priority connections available to them before they use it.

When a failed DS server becomes available again, AM instances create new connections to it based on the order specified in the list.

Examples for active/passive deployments:

cts-dj1.example.com:389,cts-dj2.example.com:389

Every AM instance accesses cts-dj1.example.com:389 for all CTS operations. If it goes down, they access cts-dj2.example.com:389.

Every instance will open new connections to cts-dj1.example.com:389 when it becomes available.

cts-dj1.example.com:389|1|1,cts-dj2.example.com:389|2|1

Server 1 site 1 gives priority to cts-dj1.example.com:389. Server 2 site 1 gives priority to cts-dj2.example.com:389. Any server not specified accesses the first server on the list, while it is available.

If cts-dj1.example.com:389 goes down, server 1 site 1 accesses cts-dj2.example.com:389. Any server not specified access the second server on the list.

If cts-dj2.example.com:389 goes down, server 2 site 1 accesses cts-dj1.example.com:389. Any server not specified still accesses the first server on the list.

Server 1 site 1 and any server not specified will open new connections to cts-dj1.example.com:389 when it becomes available. Only server 2 site 1 will open new connections to cts-dj2.example.com:389 when it becomes available.

cts-dj1.example.com:389|1|1,cts-dj2.example.com:389|1|1,cts-dj3.example.com:389|1|2

Server 1 site 1 gives priority to cts-dj1.example.com:389. Any server not specified accesses the first server on the list, while it is available.

If cts-dj1.example.com goes down, server 1 site 1 accesses cts-dj2.example.com:389. Any server not specified accesses the second server on the list.

If both cts-dj1.example.com and cts-dj2.example.com go down, server 1 site 1 accesses cts-dj3.example.com:389 in site 2. Any server not specified accesses the third server on the list.

Server 1 site 1 and any server not specified will open new connections to any server in site 1 when they become available, with cts-dj1.example.com being the preferred server.

Example for affinity deployments:

cts-dj1.example.com:389,cts-dj2.example.com:389,cts-dj3.example.com:389,cts-dj4.example.com:389

Access CTS tokens from one of the four servers listed in the connection string. For any given CTS token, AM determines the token’s affinity for one of the four servers, and always accesses the token from that same server. Tokens are distributed equally across the four servers.

Login Id

Specifies the user, in DN format, needed to authenticate to the external data store. The user needs sufficient privileges to read and write to the root suffix of the external data store.

Password

Specifies the password associated with the login ID.

Heartbeat

Specifies how often AM should send a heartbeat request to the directory server to ensure that the connection does not remain idle, in seconds. Configure the heartbeat to ensure that network hardware, such as routers and firewalls, does not drop the connection between AM and the directory server.

Default: 10

Affinity Enabled

When enabled, specifies whether to access the CTS token store by using multiple directory instances in an affinity deployment rather than a single master directory instance using an active/passive deployment.

When you enable this option, you must ensure that the value of the Connection String(s) property is identical for every server in multi-server deployments.

Default: Disabled

UMA properties

UMA server settings are inherited by default.

UMA resource store

The following settings appear on the UMA Resource Store tab:

Store Mode

Specifies the data store where AM stores UMA tokens. Possible values are:

  • Default Token Store: AM stores UMA tokens in the configuration data store.

  • External Token Store: AM stores UMA tokens in an external data store.

Root Suffix

Specifies the base DN for storage information in LDAP format, such as dc=uma-resources,dc=example,dc=com.

Max Connections

Specifies the maximum number of connections to the data store.

External UMA resource store configuration

AM honors the following properties when External Token Store is selected under the Resource Sets Store tab:

SSL/TLS Enabled

When enabled, AM uses SSL or TLS to connect to the external data store. Make sure AM trusts the data store’s certificate when using this option.

Connection String(s)

Specifies an ordered list of connection strings for external data stores. The format is HOST:PORT[|SERVERID[|SITEID]], where HOST:PORT specify the FQDN and port of the data store, and SERVERID and SITEID are optional parameters that let you prioritize the particular connection when used by the specified node(s).

Multiple connection strings must be comma-separated, for example, uma-ldap1.example.com:389|1|1, uma-ldap2.example.com:389|2|1.

See the entry for Connection String(s) in CTS properties for more syntax examples.

Login Id

Specifies the username AM uses to authenticate to the data store. For example, uid=am-uma-bind-account,ou=admins,dc=uma,dc=example,dc=com. This user must be able to read and write to the root suffix of the data store.

Password

Specifies the password associated with the login ID property.

Heartbeat

Specifies, in seconds, how often AM should send a heartbeat request to the data store to ensure that the connection does not remain idle.

Default: 10

UMA audit store

The following settings appear on the UMA Audit Store tab:

Store Mode

Specifies the data store where AM stores audit information generated when users access UMA resources. Possible values are:

  • Default Token Store: AM stores UMA audit information in the configuration data store.

  • External Token Store: AM stores UMA audit information in an external data store.

Root Suffix

Specifies the base DN for storage information in LDAP format, such as dc=uma-audit,dc=example,dc=com.

Max Connections

Specifies the maximum number of connections to the data store.

External UMA audit store configuration

AM honors the following properties when External Token Store is selected under the UMA Audit Store tab:

SSL/TLS Enabled

When enabled, AM uses SSL or TLS to connect to the external data store. Make sure AM trusts the data store’s certificate when using this option.

Connection String(s)

Specifies an ordered list of connection strings for external data stores. The format is HOST:PORT[|SERVERID[|SITEID]], where HOST:PORT specify the FQDN and port of the data store, and SERVERID and SITEID are optional parameters that let you prioritize the particular connection when used by the specified node(s).

Multiple connection strings must be comma-separated, for example, uma-ldap1.example.com:389|1|1, uma-ldap2.example.com:389|2|1.

See the entry for Connection String(s) in CTS properties for more syntax examples.

Login Id

Specifies the username AM uses to authenticate to the data store. For example, uid=am-uma-bind-account,ou=admins,dc=uma,dc=example,dc=com. This user must be able to read and write to the root suffix of the data store.

Password

Specifies the password associated with the login ID property.

Heartbeat

Specifies, in seconds, how often AM should send a heartbeat request to the data store to ensure that the connection does not remain idle.

Default: 10

Pending requests store

The following settings appear on the Pending Requests Store tab:

Store Mode

Specifies the data store where AM stores pending requests to UMA resources. Possible values are:

  • Default Token Store: AM stores UMA pending requests in the configuration data store.

  • External Token Store: AM stores UMA pending requests in an external data store.

Root Suffix

Specifies the base DN for storage information in LDAP format, such as dc=uma-pending,dc=forgerock,dc=com.

Max Connections

Specifies the maximum number of connections to the data store.

External pending requests store configuration

AM honors the following properties when External Token Store is selected under the Pending Requests Store tab:

SSL/TLS Enabled

When enabled, AM uses SSL or TLS to connect to the external data store. Make sure AM trusts the data store’s certificate when using this option.

Connection String(s)

Specifies an ordered list of connection strings for external data stores. The format is HOST:PORT[|SERVERID[|SITEID]], where HOST:PORT specify the FQDN and port of the data store, and SERVERID and SITEID are optional parameters that let you prioritize the particular connection when used by the specified node(s).

Multiple connection strings must be comma-separated, for example, uma-ldap1.example.com:389|1|1, uma-ldap2.example.com:389|2|1.

See the entry for Connection String(s) in CTS properties for more syntax examples.

Login Id

Specifies the username AM uses to authenticate to the data store. For example, uid=am-uma-bind-account,ou=admins,dc=uma,dc=example,dc=com. This user must be able to read and write to the root suffix of the data store.

Password

Specifies the password associated with the login ID property.

Heartbeat

Specifies, in seconds, how often AM should send a heartbeat request to the data store to ensure that the connection does not remain idle.

Default: 10

UMA resource labels store

The following settings appear on the UMA Resource Labels Store tab:

Store Mode

Specifies the data store where AM stores user-created labels used for organizing UMA resources. Possible values are:

  • Default Token Store: AM stores user-created labels in the configuration data store.

  • External Token Store: AM stores user-created labels in an external data store.

Root Suffix

Specifies the base DN for storage information in LDAP format, such as dc=uma-resources-labels,dc=forgerock,dc=com.

Max Connections

Specifies the maximum number of connections to the data store.

External UMA resource labels store configuration

AM honors the following properties when External Token Store is selected under the UMA Resource Labels Store tab.

SSL/TLS Enabled

When enabled, AM uses SSL or TLS to connect to the external data store. Make sure AM trusts the data store’s certificate when using this option.

Connection String(s)

Specifies an ordered list of connection strings for external data stores. The format is HOST:PORT[|SERVERID[|SITEID]], where HOST:PORT specify the FQDN and port of the data store, and SERVERID and SITEID are optional parameters that let you prioritize the particular connection when used by the specified node(s).

Multiple connection strings must be comma-separated, for example, uma-ldap1.example.com:389|1|1, uma-ldap2.example.com:389|2|1.

See the entry for Connection String(s) in CTS properties for more syntax examples.

Login Id

Specifies the username AM uses to authenticate to the data store. For example, uid=am-uma-bind-account,ou=admins,dc=uma,dc=example,dc=com. This user must be able to read and write to the root suffix of the data store.

Password

Specifies the password associated with the login ID property.

Heartbeat

Specifies, in seconds, how often AM should send a heartbeat request to the data store to ensure that the connection does not remain idle.

Default: 10

Directory configuration properties

Configure connection settings and additional LDAP directory server instances by navigating to Deployment > Servers > Server Name > Directory Configuration.

Directory configuration

The following properties are available under the Directory Configuration tab:

Minimum Connection Pool

Sets the minimum number of connections in the pool.

Changes to this property take effect immediately. No server restart is necessary.

Maximum Connection Pool

Sets the maximum number of connections in the pool.

Changes to this property take effect immediately. No server restart is necessary.

Bind DN

Sets the bind DN of the service account AM uses to connect to the configuration directory servers.

Changes to this property take effect immediately. No server restart is necessary.

Bind Password

Set the bind password to connect to the configuration directory servers.

Changes to this property take effect immediately. No server restart is necessary.

Server

In the LDAP connection table, edit existing LDAP connections by selecting the pen icon to the right of the row you want to modify. To add a new entry, fill the NAME, HOST NAME, PORT NUMBER and CONNECTION TYPE columns using the following hints:

  • NAME. The name of the LDAP connection.

  • HOST NAME. The FQDN of the LDAP server.

  • PORT NUMBER. The port number to connect to the LDAP server.

  • CONNECTION TYPE. Whether the connection between the LDAP server and AM is SIMPLE (unsecured) or SSL (secured).

Advanced properties

Each server has a list of advanced properties that can be modified at Deployment > Servers > Server Name > Advanced. For a list of inherited advanced properties relevant to all servers, go to Configure > Server Defaults > Advanced.

bootstrap.file

File that contains the path to the AM configuration folder. By default, the .openamcfg directory is created in the home directory of the user that runs the web container. For example, /usr/local/.openamcfg/AMConfig_usr_local_apache-tomcat-8.0.35_webapps_openam_.

com.forgerock.openam.dj.backendType

The backend type for the embedded DS server.

Default: je

com.iplanet.am.cookie.c66Encode

Properly URL encode session tokens.

Default: true

com.iplanet.am.daemons

Modules for which to open daemons at AM startup.

Default: securid

com.iplanet.am.directory.ssl.enabled

Whether to connect to the configuration directory server over LDAPS.

Default: false

com.iplanet.am.installdir

AM Configuration and log file location.

Default: ~/openam/, such as ~/openam

com.iplanet.am.jssproxy.checkSubjectAltName

When using JSS or JSSE, check whether the name values in the SubjectAltName certificate match the server FQDN.

Default: false

com.iplanet.am.jssproxy.resolveIPAddress

When using JSS or JSSE, check that the IP address of the server resolves to the host name.

Default: false

com.iplanet.am.jssproxy.SSLTrustHostList

When using JSS or JSSE, comma-separated list of server FQDNs to trust if they match the certificate CN, even if the domain name is not correct.

com.iplanet.am.jssproxy.trustAllServerCerts

When using JSS or JSSE, set to true to trust whatever certificate is presented without checking.

Default: true

com.iplanet.am.lbcookie.name

Used with sticky load balancers that can inspect the cookie value.

Default: amlbcookie

com.iplanet.am.lbcookie.value

Used with sticky load balancers that can inspect the cookie value. The value of this property defaults to the unique AM server ID, although you can set your own unique value.

To improve AM server performance, keep the value of the cookie set to the AM server ID when using Web Agents.

If you have replaced the value of the this property and you need to match the AM server URLs with their corresponding server IDs, query the global-config/servers endpoint. For example:

$ curl \
--header 'Accept: application/json' \
--header "iPlanetDirectoryPro: AQIC5…​NDU1*" \
--header  "Accept-API-Version: resource=1.0, protocol=2.1" \
'https://openam.example.com:8443/openam/json/global-config/servers?_queryFilter=true'
{
    "result": [
        {
            "_id": "01",
            "_rev": "-1541617246",
            "siteName": null,
            "url": "https://openam.example.com:8443/openam"
        }
    ],
    "resultCount": 1,
    "totalPagedResults": -1,
    "totalPagedResultsPolicy": "NONE"
}

In the example above, the server ID for server https://openam.example.com:8443/openam is 01.

Default: 01

com.iplanet.am.pcookie.name

Persistent cookie name.

Default: DProPCookie

com.iplanet.am.profile.host

Not used

Default: server-host, such as openam.example.com

com.iplanet.am.profile.port

Not used

Default: server-port, such as 8080 or 8443

com.iplanet.am.sdk.caching.enabled

Enables caching for configuration data and user data.

Refer to Overall Server Cache Settings for important information about this property.

Changes to this property take effect immediately. No server restart is necessary.

Default: true

com.iplanet.am.session.agentSessionIdleTime

Time in minutes after which a web or Java agent’s server-side session expires. Note that this setting is ignored when AM creates a client-side session for a web or Java agent.

Default: 1440 (session expires after one day). You can set this property to 0 (session never expires), or any integer higher than 30 (no maximum limit).

com.iplanet.am.session.client.polling.enable

Whether client applications such as web or Java agents poll for server-side session changes. If false, then client applications register listeners for notifications about changes to server-side sessions.

Default: false

com.iplanet.am.session.client.polling.period

If client applications poll for changes, number of seconds between polls.

Default: 180

com.iplanet.am.session.httpSession.enabled

Create an HttpSession for users on successful authentication.

Default: true

com.iplanet.security.SSLSocketFactoryImpl

SSL socket factory implementation used by AM.

Default: com.sun.identity.shared.ldap.factory.JSSESocketFactory, uses a pure Java provider

com.sun.embedded.replicationport

Replication port for the embedded DS server.

Default: 8989

com.sun.embedded.sync.servers

This property applies to multi-server AM deployments that use the embedded DS store.

When this property is set to on, AM servers check during startup to determine whether the replication settings for the embedded store are consistent with the number of servers in the site. If they are not consistent, AM reconfigures replication to match the existing number of servers in the site.

Set this property on a per-server basis by navigating to Deployment > Servers > Server Name > Advanced, rather than globally under Configure > Server Defaults.

Default: on

com.sun.identity.am.cookie.check

Whether to check for cookie support in the user agent, and if not to return an error.

Default: false

com.sun.identity.appendSessionCookieInURL

Whether to append the session cookie to URL for a zero page session.

Default: true

com.sun.identity.auth.cookieName

Cookie used by the AM authentication service to handle the authentication process.

Default: AMAuthCookie

com.sun.identity.authentication.client.ipAddressHeader

Set the name of the HTTP header that AM can examine to learn the client IP address when requests go through a proxy or load balancer. (When requests go through an HTTP proxy or load balancer, checking the IP address on the request alone returns the address of the proxy or load balancer rather than that of the client.) AM must be able to trust the proxy or load balancer to set the client IP address correctly in the header specified.

Example: com.sun.identity.authentication.client.ipAddressHeader=X-Forwarded-For

com.sun.identity.authentication.multiple.tabs.used

Whether to allow users to open many browser tabs to the login page at the same time without encountering an error.

Default: false

com.sun.identity.authentication.setCookieToAllDomains

Whether to allow multiple cookie domains.

Default: true

com.sun.identity.authentication.special.users

List of special users always authenticated against the local directory server.

Default: cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org

com.sun.identity.authentication.super.user

Identifies an administrative user that replaces the amAdmin user. For example, uid=superroot,ou=people,dc=example,dc=com.

You must manually create a user account for the new administrative user in the configuration data store that has the same privileges as the uid=admin user.

The amAdmin account is "hard-coded" in the source of several files. The code in these files may affect the functionality of a top-level administrative user with a name other than amAdmin.

Default: uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org

com.sun.identity.authentication.uniqueCookieName

When cookie hijacking protection is configured, name of the cookie holding the URL to the AM server that authenticated the user.

Default: sunIdentityServerAuthNServer

com.sun.identity.client.notification.url

Notification service endpoint for clients such as web and Java agents.

Default: server-protocol://server-host:server-port/server-uri/notificationservice, such as https://openam.example.com:8443/openam/notificationservice

com.sun.identity.common.systemtimerpool.size

Number of threads in the shared system timer pool used to schedule operations such as session timeout.

Default: 3

com.sun.identity.cookie.httponly

When set to true, mark cookies as HTTPOnly to prevent scripts and third-party programs from accessing the cookies.

Note that this configuration option is used only in non-UI deployments. The UI cannot set the HttpOnly name in a cookie.

Default: false

com.sun.identity.cookie.samesite

Configures support for applying SameSite cookie rules, as per internet-draft Cookies:HTTP State Management Mechanism.

Available settings are as follows:

strict

Requests originating from different domains will not have cookies sent with them.

When this mode is enabled, any AM functionality that relies on requests being redirected back to the AM instance may not operate correctly. For example, OAuth 2.0 flows and SAML federation may not operate correctly if AM cannot access the required cookies.

lax

Cookies received from different domains cannot be accessed, unless the request is using a top-level request and uses a "safe" HTTP method, such as GET, HEAD, OPTIONS, and TRACE.

off

No restrictions on the domain of cookies is applied. This is the default setting.

You must disable SameSite support if any of the following is true:

  • You have set Access-Control-Allow-Credentials=true in your CORS configuration.

    For more information on configuring CORS in AM, refer to Configuring CORS Support.

  • You are using SAML HTTP-POST bindings.

    For example, IDP-initiated single logout (SLO) functionality will not operate correctly if SameSite support is enabled, as the iPlanetDirectoryPro cookie would not be accessible in cross-domain POST requests. For more information on SAML single logout, refer to Implement SSO and SLO.

Default: off

com.sun.identity.enableUniqueSSOTokenCookie

If true, then AM is using protection against cookie hijacking.

Default: false

com.sun.identity.jss.donotInstallAtHighestPriority

Whether JSS should take priority over other providers.

Default: true

com.sun.identity.monitoring

Whether monitoring is active for AM.

Default: off

com.sun.identity.monitoring.local.conn.server.url

URL for local connection to the monitoring service.

Default: service:jmx:rmi://

com.sun.identity.password.deploymentDescriptor

Internal property used by AM.

Default: server-uri, such as openam

com.sun.identity.policy.Policy.policy_evaluation_weights

Weights of the cost of evaluating policy subjects, rules, and conditions. Evaluation is in order of heaviest weight to lightest weight.

Default: 10:10:10, meaning evaluation of rules, then conditions, then subjects

com.sun.identity.policy.resultsCacheMaxSize

Maximum number of policy decisions AM caches.

Default: 10000

com.sun.identity.security.checkcaller

Whether to perform a Java security permissions check for AM.

Default: false

com.sun.identity.server.fqdnMap

Enables virtual hosts, partial hostname and IP address. Maps invalid or virtual name keys to valid FQDN values for proper redirection.

To map myserver to myserver.example.com, set com.sun.identity.server.fqdnMap[myserver]=myserver.example.com.

com.sun.identity.session.repository.enableAttributeCompression

For additional compression of CTS token JSON binaries, beyond GZip, if desired.

Default: false

com.sun.identity.session.repository.enableCompression

For GZip-based compression of CTS tokens, if desired.

Default: false

com.sun.identity.session.repository.enableEncryption

Enables tokens to be encrypted when stored.

Multi-instance deployments require consistent use of this property, which should be configured under Configure > Server Defaults > Advanced.

The am.encryption.pwd property must also be the same for all deployed instances. You can set the Password Encryption Key property under Deployment > Servers > Server Name > Security. Verify that all servers have the same setting for this property.

Default: false

com.sun.identity.sm.cache.enabled

Enables service configuration caching.

See Overall Server Cache Settings for important information about this property.

Changes to this property take effect immediately. No server restart is necessary.

Default: true

com.sun.identity.sm.cache.ttl

When service configuration caching time-to-live is enabled, this sets the time to live in minutes.

Changes to this property take effect immediately. No server restart is necessary.

Default: 30

com.sun.identity.sm.cache.ttl.enable

If service configuration caching is enabled, whether to enable a time-to-live for cached configuration.

Changes to this property take effect immediately. No server restart is necessary.

Default: false

com.sun.identity.sm.flatfile.root_dir

File system directory to hold file-based representation of AM configuration.

Default: /path/to/openam/

com.sun.identity.sm.sms_object_class_name

Class used to read and write AM service configuration entries in the directory.

Default: com.sun.identity.sm.ldap.SMSEmbeddedLdapObject

com.sun.identity.url.readTimeout

Used to set the read timeout in milliseconds for HTTP and HTTPS connections to other servers.

Default: 30000

com.sun.identity.urlchecker.dorequest

Whether to perform an HTTP GET on com.sun.identity.urlchecker.targeturl as a health check against another server in the same site.

If set to false, then AM only checks the Socket connection, and does not perform an HTTP GET.

If each AM server runs behind a reverse proxy, then the default setting of true means the health check actually runs against the AM instance, rather than checking only the Socket to the reverse proxy.

Default: true

com.sun.identity.urlchecker.targeturl

URL to monitor when com.sun.identity.urlchecker.dorequest is set to true.

Default: URL to the /openam/namingservice endpoint on the remote server

com.sun.identity.urlconnection.useCache

Whether to cache documents for HTTP and HTTPS connections to other servers.

Default: false

com.sun.identity.webcontainer

Name of the web container to correctly set character encoding, if necessary.

Default: WEB_CONTAINER

console.privileged.users

Used to assigned privileged console access to particular users. Set to a | separated list of users' Universal IDs, such as console.privileged.users=uid=demo,ou=user,dc=openam,dc=forgerock,dc=org|uid=demo2,ou=user,dc=openam,dc=forgerock,dc=org.

openam.auth.destroy_session_after_upgrade

Where to destroy the old session after a session is successfully upgraded.

Default: true

openam.auth.distAuthCookieName

Cookie used by the AM distributed authentication service to handle the authentication process.

Default: AMDistAuthCookie

openam.auth.session_property_upgrader

Class that controls which session properties are copied during session upgrade, where default is to copy all properties to the upgraded session.

Default: org.forgerock.openam.authentication.service.DefaultSessionPropertyUpgrader

openam.auth.version.header.enabled

The X-DSAMEVersion http header provides detailed information about the version of AM currently running on the system, including the build and date/time of the build. AM will need to be restarted once this property is enabled.

Default: false

openam.authentication.ignore_goto_during_logout

Whether to ignore the goto query string parameter on logout, instead displaying the logout page.

Default: false

openam.cdm.default.charset

Character set used for globalization.

Default: UTF-8

openam.forbidden.to.copy.headers

Comma-separated list of HTTP headers not to copy when the distributed authentication server forwards a request to another distributed authentication server.

Default: connection

openam.forbidden.to.copy.request.headers

Comma-separated list of HTTP headers not to copy when the distributed authentication server forwards a request to another distributed authentication server.

Default: connection

openam.private.key.jwt.encryption.algorithm.whitelist

Comma-separated list of encryption algorithms that the OpenID Connect clients of the Social Identity Provider service can configure in the Private Key JWT Encryption Algorithm field.

For a list of algorithms that AM supports, refer to the JSON Web Algorithms (JWA) internet draft.

For more information, refer to the Social Identity Provider service client configuration reference.

Unrecognized or unsupported algorithms will be saved, but not exposed in the Private Key JWT Encryption Algorithm field.

This property is hot-swappable.

Default: RSA-OAEP,RSA-OAEP-256,ECDH-ES

openam.retained.http.headers

Comma-separated list of HTTP headers to copy to the forwarded response when the server forwards a request to another server.

Requests are forwarded when the server receiving the request is not the server that originally initiated authentication. The server that originally initiated authentication is identified by a cookie.

When the distributed authentication service (DAS) is in use, then the cookie is the AMDistAuthCookie that identifies the DAS server by its URL.

When authentication is done directly on AM, then the cookie is the AMAuthCookie that holds a session ID that identifies the AM server.

On subsequent requests the server receiving the request checks the cookie. If the cookie identifies another server, the current server forwards the request to that server.

If a header such as Cache-Control has been included in the list of values for the property openam.retained.http.request.headers and the header must also be copied to the response, then add it to the list of values for this property.

Example: openam.retained.http.headers=X-DSAMEVersion,Cache-Control

Default: X-DSAMEVersion

openam.retained.http.request.headers

Comma-separated list of HTTP headers to copy to the forwarded request when the server forwards a request to another server.

Requests are forwarded when the server receiving the request is not the server that originally initiated authentication. The server that originally initiated authentication is identified by a cookie.

When the distributed authentication service (DAS) is in use, then the cookie is the AMDistAuthCookie that identifies the DAS server by its URL.

When authentication is done directly on AM, then the cookie is the AMAuthCookie that holds a session ID that identifies the AM server.

On subsequent requests the server receiving the request checks the cookie. If the cookie identifies another server, the current server forwards the request to that server.

When configuring the distributed authentication service, or when a reverse proxy is set up to provide the client IP address in the X-Forwarded-For header, if your deployment includes multiple AM servers, then this property must be set to include the header.

Example: openam.retained.http.request.headers=X-DSAMEVersion,X-Forwarded-For

AM copies the header when forwarding a request to the authoritative server where the client originally began the authentication process, so that the authoritative AM server receiving the forwarded request can determine the real client IP address.

In order to retain headers to return in the response to the AM server that forwarded the request, use the property openam.retained.http.headers.

Default: X-DSAMEVersion

openam.session.case.sensitive.uuid

Whether universal user IDs are considered case sensitive when matching them.

Default: false

org.forgerock.allow.http.client.debug

Whether AM can output logging at the Message level for the org.apache.http.wire and org.apache.http.headers logging appenders.

Possible values are:

  • true. The appenders' debug log level can take the same value as AM’s, even Message.

    The appenders can log cleartext passwords or sensitive information related to client interactions. For example, scripted authentication or STS transactions.

    Enable this property for debugging purposes only when required.

  • false. The appender’s debug log level is always warning, unless debug is disabled.

You can also set this property as a JVM option in the container where AM runs.
Default: false

org.forgerock.openam.http.ssl.connection.manager

The class that implements the org.forgerock.openam.http.SslConnectionManager interface, which controls both keystore and truststore settings, as well as hostname verification.

If the container in which AM runs is configured with the java.protocol.handler.pkgs property set, then ensure this property is set to com.sun.identity.protocol.AmSslConnectionManager.

In previous versions of AM, this property was named opensso.protocol.handler.pkgs, and required a value of com.sun.identity.protocol if the java.protocol.handler.pkgs property was set by the container.
org.forgerock.openam.audit.identity.activity.events.blacklist

A comma-separated list of audit events that will not be logged.

The following events can be suppressed:

  • AM-ACCESS-ATTEMPT.

  • AM-IDENTITY-CHANGE.

  • AM-GROUP-CHANGE.

Logging these additional events can impact performance.

Default: AM-ACCESS-ATTEMPT,AM-IDENTITY-CHANGE,AM-GROUP-CHANGE

org.forgerock.openam.authLevel.excludeRequiredOrRequisite

Whether a session’s authentication level is always the highest authentication level of any authentication module that passed, even if requisite or required modules in the authentication chain weren’t executed. For more information, refer to About Authentication Levels for Chains.

Default: false

org.forgerock.embedded.dsadminport

Administration port for the embedded DS server.

Default: 4444

org.forgerock.openam.auth.audit.nodes.enabled

When true, AM generates audit log messages for each authentication node reached during authentication tree flows.

Possible values are true or false.

Default: true

org.forgerock.openam.auth.audit.trees.enabled

When true, AM generates audit log messages with the outcome of authentication tree flows.

Possible values are true or false.

Default: true

org.forgerock.openam.auth.transactionauth.returnErrorOnAuthFailure

Whether AM returns an HTTP 200 or HTTP 401 message when the user fails to complete the required actions to perform session upgrade during transactional authorization. Possible values are:

  • false. AM returns an HTTP 200 message with the original SSO token.

    For example:

    {
        "tokenId": "AQIC5wM...TU3OQ*",
        "successUrl": "http://example.com/index.html",
        "realm": "/"
    }

    In this case, the user is redirected to the success URL and, when trying to access the protected resource, policy evaluation will fail since transactional authorization has failed.

  • true. AM returns an HTTP 401 message.

    For example:

    {
        "code":401,
        "reason":"Unauthorized",
        "message":"Login failure",
        "detail":{
            "failureUrl":"http://example.com/unauthorized.html"
        }
    }

    In this case, the user is redirected to the failure URL.

Default: false

org.forgerock.openam.authentication.accountExpire.days

Days until account expiration set after successful authentication by the account expiration post-authentication plugin.

Default: 30

org.forgerock.openam.authentication.forceAuth.enabled

This property has no effect on authentication trees; it applies to authentication chains only.

Enables or disables the ForceAuth authentication parameter. If this property is set to false, the ForceAuth parameter will always be false, regardless of what the administrator sets. If this property is true, the configured value of the ForceAuth parameter is respected.

In new installations, this property is set to false by default, which means that the value of ForceAuth is always false.

When you upgrade AM, this property is set to true by default, which means that the value of ForceAuth is respected.

If you do not need ForceAuth to be enabled, it is strongly recommended that you set org.forgerock.openam.authentication.forceAuth.enabled to false.

Default: false for new installations, true for upgraded installations

org.forgerock.openam.console.autocomplete.enabled

Specifies whether input forms and password fields can be autocompleted. This property only affects end-user pages in the classic UI. Possible values are true, to enable autocomplete, and false, to disable it.

Default: true

org.forgerock.openam.core.resource.lookup.cache.enabled

Controls whether the results of resource file lookup should be cached.

While you are customizing the UI as described in UI customization, set this property to false to allow AM immediately to pick up changes to the files as you customize them.

Reset this to the default, true, when using AM in production.

Default: true

org.forgerock.openam.core.sms.always.fail.on.invalid.attributes

Specifies whether the server should throw an exception, when it encounters an unknown attribute while parsing file-based configurations. By default, the server ignores any unknown attributes, and does not throw an exception. To override this behavior, set this property to true.

Default: false

org.forgerock.openam.core.sms.placeholder_api_enabled

For file-based configurations, enables property value substitution.

Takes the following values:

  • ON enables property value substitution for all property types.

  • STRING_ONLY enables property value substitution for properties with string values only.

  • OFF disables property value substitution.

Default: OFF

The recommended way to enable property value substitution is through a Java system property, rather than with this advanced server property.

org.forgerock.openam.cts.rest.enabled

Enables access to the CTS REST endpoint /json/tokens.

Even when access to the CTS REST endpoint is enabled, only the AM global administrator has authorization to perform operations against /json/tokens.

Default: false

After changing this property, you must restart AM or the container in which it runs for the change to take effect.

org.forgerock.openam.encryption.key.digest

Determines the digest algorithm used along with PBKDF2 key derivation method for AES Key Wrap encryption. Possible values are SHA1, SHA256, SHA384, or SHA512.

Set this property in AM’s web container’s startup script. For more information, refer to Use stronger encryption algorithms.

Default: SHA1

org.forgerock.openam.encryption.key.iterations

The number of iterations for the key derivation process specified in the org.forgerock.openam.encryption.key.digest advanced property.

Set this property in AM’s web container’s startup script. For more information, refer to Use stronger encryption algorithms.

Default:`10000`

org.forgerock.openam.encryption.key.size

The size of the derived key for the AES Key Wrap encryption operations.

Set this property in AM’s web container’s startup script. For more information, refer to Use stronger encryption algorithms.

Default: 128

org.forgerock.openam.encryption.useextractandexpand

Enables the algorithm introduced in AM 7.1 that reduces the performance cost of AES Key Wrap encryption even when high iteration counts are used. Possible values are true, to enable it, and false to disable it.

If you configure a large iteration count when this property is set to false, AM startup times may refer to a performance impact if there are many agents in your deployment.

Set this property in AM’s web container’s startup script. For more information, refer to Use stronger encryption algorithms.

Default: false

org.forgerock.openam.httpclienthandler.system.clients.connection.timeout

Specifies the time that new client connections using ForgeRock’s ClientHandler code will wait before timing out.

The value is a string specifying a number and a unit of time.

Restart AM or the container in which it runs for the change to take effect.

Default: 10 seconds

org.forgerock.openam.httpclienthandler.system.clients.max.connections

Specifies the maximum number of connections allowed in the pool available for clients using ForgeRock’s ClientHandler code.

Use this property only when the org.forgerock.openam.httpclienthandler.system.clients.reuse.connections.enabled advanced server property is enabled.

Restart AM or the container in which it runs for the change to take effect.

Default: 64

org.forgerock.openam.httpclienthandler.system.clients.pool.ttl

Specifies, in milliseconds, the maximum time-to-live for pooled clients connections using ForgeRock’s ClientHandler code.

Restart AM or the container in which it runs for the change to take effect.

Default: Not set

org.forgerock.openam.httpclienthandler.system.clients.response.timeout

Specifies the time that a client using ForgeRock’s ClientHandler code will wait for a response before timing out.

The value is a string specifying a number and a unit of time.

Restart AM or the container in which it runs for the change to take effect.

Default: 10 seconds

org.forgerock.openam.httpclienthandler.system.clients.retry.failed.requests.enabled

Specifies whether the ForgeRock’s ClientHandler code should retry failed connections. Possible values are true or false.

Restart AM or the container in which it runs for the change to take effect.

Default: true

org.forgerock.openam.httpclienthandler.system.clients.reuse.connections.enabled

Specifies whether the ForgeRock’s ClientHandler code should pool and reuse connections. Possible values are true or false.

Restart AM or the container in which it runs for the change to take effect.

Default: true

org.forgerock.openam.httpclienthandler.system.nonProxyHosts

Lists the target hosts for which requests should not be proxied. Hostnames are separated by commas.

This property supports wildcards at the start and end of any value. For example, *.example.com would result in a match for customers.example.com and staff.example.com, and requests would not be proxied for those target hosts.

Configure alongside the org.forgerock.openam.httpclienthandler.system.proxy.uri, org.forgerock.openam.httpclienthandler.system.proxy.username, and org.forgerock.openam.httpclienthandler.system.proxy.password advanced server properties.

Default: localhost,127.*,[::1],0.0.0.0,[::0]

org.forgerock.openam.httpclienthandler.system.proxy.enabled

When set to true, AM routes outgoing ForgeRock’s ClientHandler code requests through the HTTP proxy defined on the JVM.

Restart AM or the container in which it runs for the change to take effect.

Default: Not set

org.forgerock.openam.httpclienthandler.system.proxy.password

Specifies the password of the proxy that AM will use to route outgoing ForgeRock’s ClientHandler code requests.

Configure alongside the org.forgerock.openam.httpclienthandler.system.proxy.username, org.forgerock.openam.httpclienthandler.system.proxy.uri, and org.forgerock.openam.httpclienthandler.system.nonProxyHosts advanced server properties.

Restart AM or the container in which it runs for the change to take effect.

Default: Not set

org.forgerock.openam.httpclienthandler.system.proxy.uri

Specifies the URI of the proxy that AM will use to route outgoing ForgeRock’s ClientHandler code requests. The URI must be in the format scheme://hostname:port. For example, https://myproxy.example.com:443.

If the proxy requires authentication, also configure the org.forgerock.openam.httpclienthandler.system.proxy.username and org.forgerock.openam.httpclienthandler.system.proxy.password properties, and, optionally, the org.forgerock.openam.httpclienthandler.system.nonProxyHosts property.

This property takes precedence over the org.forgerock.openam.httpclienthandler.system.proxy.enabled advanced server property and its related JVM properties.

For more information, refer to Configuring AM for Outbound Communication.

Restart AM or the container in which it runs for the change to take effect.

Default: Not set

org.forgerock.openam.httpclienthandler.system.proxy.username

Specifies the username of the proxy that AM will use to route outgoing ForgeRock’s ClientHandler code requests.

Configure alongside the org.forgerock.openam.httpclienthandler.system.proxy.password and org.forgerock.openam.httpclienthandler.system.proxy.uri advanced server properties.

Restart AM or the container in which it runs for the change to take effect.

Default: Not set

org.forgerock.openam.idm.attribute.names.lower.case

Specifies whether the fields in JSON responses are always returned in lowercase. When true, AM converts the fields to lowercase.

Default: false

org.forgerock.openam.introspect.token.query.param.allowed

Specifies whether AM allows HTTP GET requests, and the use of token as a query parameter in POST requests, on the oauth2/introspect endpoint.

For security reasons, and in accordance with the OAuth 2.0 Token Introspection specification, AM disallows HTTP GET requests on the introspection endpoint, and requires HTTP POST requests instead. AM also disallows the use of token as a query parameter in a POST request on that endpoint; for example, /oauth2/introspect?token=access-token.

If your clients in an existing deployment need to send a GET request or token as a query parameter to the oauth2/introspect endpoint, you can change this setting to true. However, it is recommended that you adjust your clients to use the more secure setting.

Default: false

org.forgerock.openam.ldap.default.time.limit

Configures the client-side timeout, in milliseconds, applied to LDAP operations performed with the Netscape LDAP SDK.

Default: 0 (no time limit)

org.forgerock.openam.ldap.dncache.expire.time

Sets the DN cache timeout, in milliseconds, after which an entry should be removed from the cache. A value of 0 means that the DN cache will not expire, and entries will not be removed automatically.

Setting this value too low can have a severe performance impact.

Default: 0 (no time limit)

org.forgerock.openam.ldap.heartbeat.timeout

Specifies the number of seconds that AM should wait for a heartbeat operation to the DS server to complete, before considering the connection unavailable.

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.

Default: 10

org.forgerock.openam.ldap.secure.protocol.version

The protocols AM uses to connect to a secure LDAP server.

Specify a single value, for example TLSv1.2, for AM to use only that protocol when connecting to affected external resources. Refer to Secure network communication for a list of these resources.

Specify a comma-separated list with multiple protocols for AM to use the most secure protocol supported by the external resources.

For environments using Java 11 and later, a value of TLSv1.3,TLSv1.2 means that AM attempts to use the TLSv1.3 protocol to connect to external configuration and user data stores, but if a TLSv1.3 connection is not supported, AM uses TLSv1.2.

Upgrading to Java 11 (versions 11.0.11, 1.8.0_291 and later) disables protocol versions TLSv1 and TLSv1.1, which are considered less secure and are now deprecated.

Default: TLSv1.3,TLSv1.2

org.forgerock.openam.notifications.agents.enabled

Controls whether to publish notifications for consumption by web agents and Java agents.

This property does not apply to web or Java agent versions earlier than version 5. If the deployment uses only earlier versions of web and Java agents, you can set this property to false.

Default: true

org.forgerock.openam.oauth2.client.graceperiod.disabled

Lets you override the default maximum refresh token grace period.

By default, you cannot set a grace period that exceeds 120 seconds. Setting this server property to true disables the maximum and lets you set any grace period up to the maximum positive integer value. This value affects the refresh token grace period set in the OAuth2.0 provider configuration or on any OAuth 2.0 clients.

Having a long grace period poses a security risk. You should therefore keep the grace period as small as possible. Exceeding the default maximum of 120 seconds is not recommended.

Default: false

org.forgerock.openam.openidconnect.allow.open.dynamic.registration

Controls whether OpenID Connect clients can register dynamically without providing an access token.

If you set this to true in production, take care to limit or throttle dynamic client registrations.

Default: false

org.forgerock.openam.radius.server.context.cache.size

Maximum number of RADIUS client sessions that can be cached concurrently on the AM server.

Default: 5000

org.forgerock.openam.redirecturlvalidator.maxUrlLength

Specifies the maximum length of redirection URLs validated by AM. The Validation Service and other AM services perform redirection URL validation.

The default value should be adequate in most cases. Increase the default value as needed if messages similar to the following appear in your debug log files with message-level debugging enabled:

RedirectUrlValidator.isRedirectUrlValid: The url was length 2015 which is longer than the allowed maximum of 2000

Default: 2000

org.forgerock.openam.request.max.bytes.entity.size

Specifies the maximum size of the body of any request made to AM. For more information, refer to Limit the size of the request body.

The property is hot-swappable. You do not need to restart AM for the changes to take effect.

Default: 1 MB (1048576 bytes)

org.forgerock.openam.secrets.keystore.keyid.provider

Specifies the name of the KeyStoreKeyIdProvider implementation AM uses to provide key ID (kids) to public keys when AM is configured as an OAuth 2.0 authorization server.

For more information, refer to Customizing Public Key IDs.

Default: org.forgerock.openam.secrets.DefaultKeyStoreKeyIdProvider.

org.forgerock.openam.secrets.googlekms.decryptionkey

Specifies the fully qualified resource ID of the Google Cloud KMS secret used to decrypt secrets as they are read from the filesystem, environment variables, or system properties.

This property may also specify the Google Cloud KMS secret used to decrypt the hash of the password of the amAdmin user, if the value of the org.forgerock.openam.secrets.special.user.passwords.format advanced server property is set to GOOGLE_KMS_ENCRYPTED.

Only one key can be specified at a time.

This property has no default.

org.forgerock.openam.secrets.special.user.passwords.format

Specifies the format used to store the hash of the amAdmin user password.

Possible values are:

  • ENCRYPTED_PLAIN. The hash is encrypted with the AM encryption key.

  • PLAIN. The hash is unencrypted. The password must be randomly generated and high entropy.

  • GOOGLE_KMS_ENCRYPTED. The hash is encrypted with the Google Cloud KMS secret specified in the org.forgerock.openam.secrets.googlekms.decryptionkey advanced server property.

For more information, refer to Changing the amAdmin Password (Secret Stores).
Default: ENCRYPTED_PLAIN

org.forgerock.openam.session.stateless.encryption.method

Sets the encryption method for client-side sessions. Possible values are:

  • A128CBC-HS256. AES 128-bit in CBC mode using HMAC-SHA-256-128 hash (HS256 truncated to 128 bits)

  • A192CBC-HS384. AES 192-bit in CBC mode using HMAC-SHA-384-192 hash (HS384 truncated to 192 bits)

  • A256CBC-HS512. AES 256-bit in CBC mode using HMAC-SHA-512-256 hash (HS512 truncated to 256 bits)

  • A128GCM. AES 128-bit in GCM mode

  • A192GCM. AES 192-bit in GCM mode

  • A256GCM. AES 256-bit in GCM mode

Default: A128CBC-HS256

org.forgerock.openam.session.stateless.logout.cache.expiryCheckIntervalSeconds

The period (in seconds) after which the logout token cache purges expired entries. Changes to this property require a server restart.

Default: 60

For more information, refer to Invalidate all sessions for a user.

org.forgerock.openam.session.stateless.rsa.padding

Sets the padding mode for RSA encryption of client-side sessions. Possible values are:

  • RSA1_5. RSA with PKCS#1 v1.5 padding.

  • RSA-OAEP. RSA with OAEP and SHA-1.

  • RSA-OAEP-256. RSA with OAEP padding and SHA-256.

Default: RSA-OAEP-256

org.forgerock.openam.session.stateless.signing.allownone

Specifies whether signing client-side sessions is enabled. When true, AM allows selecting NONE as the signing algorithm for client-side sessions under Configure > Global Services > Session > Client-Side Sessions.

org.forgerock.openam.smtp.system.connect.timeout

Specifies the amount of time, in milliseconds, that AM waits before considering that an outbound SMTP connection is unavailable.

Default: 10000

org.forgerock.openam.smtp.system.socket.read.timeout

Specifies the amount of time, in milliseconds, that AM waits for an SMTP read request to receive an acknowledgement before returning an error.

Default: 10000

org.forgerock.openam.smtp.system.socket.write.timeout

Specifies the amount of time, in milliseconds, that AM waits for an SMTP write request to receive an acknowledgement before returning an error.

Default: 10000

org.forgerock.openam.slf4j.enableTraceInMessage

Controls whether trace-level logging messages are generated when message-level debug logging is enabled in AM.

Certain components that run in AM’s JVM, such as embedded DS configuration stores, write a large volume of trace-level debug records that are not required for troubleshooting in many cases. With this option set to false, trace-level debug records are not written for these components.

If you set this to true in production, take care to monitor the amount of disk space occupied by the AM debug logs.

Default: false

org.forgerock.openam.sso.providers.list

Specifies an ordered list of SSO providers. AM chooses the first applicable provider depending on the context for the requested SSO operation.

Default: org.forgerock.openidconnect.ssoprovider.OpenIdConnectSSOProvider, org.forgerock.openam.sso.providers.stateless.StatelessSSOProvider

org.forgerock.openam.trees.consumedstatedata.cache.size

Specifies the maximum number of trees in a realm for which to cache the results of "state" scans.

AM recursively scans the nodes and paths in authentication trees to determine the state data that each node consumes. Caching this information for a number of trees in each realm means AM does not have to make multiple calls to get the tree’s structure.

If you have many complex authentication trees and a large number of realms, increasing this value may reduce the impact on performance of the consumed state scans.

Default: 15

org.forgerock.openam.xui.user.session.validation.enabled

Changes the UI’s behavior when a user session expires. Possible values are false, where the user notices that their session has expired when trying to interact with the UI and they are redirected to the login screen, or true, where AM redirects the user to a page with the session expired message when their session expires. This prevents the display of possible sensitive information on the screen after a session expires.

This setting does not apply to those users that are global or realm administrators, for example, amAdmin.

Default: true

org.forgerock.openidconnect.ssoprovider.maxcachesize

Maximum size in entries of the OpenIdConnectSSOProvider provider’s cache. This cache is used to map OIDC tokens to SSO tokens for quick lookup.

Default: 5000

org.forgerock.policy.subject.evaluation.cache.size

Maintains a record of subject IDs matched or not matched in a given session. The cache is keyed on the token ID and the session is cleared when destroyed.

Default: 10000

org.forgerock.security.oauth2.enforce.sub.claim.uniqueness

Specifies the format of the subject (sub) claim of an OAuth 2.0 access token, logout token, and OpenID Connect ID token.

Tokens using the old sub format will still be accepted after the property is enabled. Before enabling this property, ensure that your clients can use the new sub claim format, or a combination of the sub and the subname claims.

About the subname Claim

The value of the subname claim matches the value of the sub claim as it was returned in versions of AM earlier than 7.1, or as returned when the org.forgerock.security.oauth2.enforce.sub.claim.uniqueness advanced server property is disabled.

An example of the value of the subname claim is demo, or myOauth2Client.

This claim was introduced in AM 7.1, and is added by default to access and logout tokens. It is also available to ID tokens, but not included in the OIDC Claims Script. Therefore, AM does not add it to ID tokens by default.

Default: true for new installations, false for upgrades

Possible values are:

  • false.

    The value of the sub claim is the username of the identity, or the name or the client that is the subject of the token.

    For example, demo, or myOauth2Client.

  • true.

    The subject claim is in the format (type!subject), where:

    • subject is the identifier of the user/identity, or the name of the OAuth 2.0/OpenID Connect client that is the subject of the token.

    • type can be one of the following:

      • age. Specifies that the subject is an OAuth 2.0/OpenID Connect-related user-agent or client. For example, an OAuth 2.0 client, a Remote Consent Service agent, and a Web and Java Agent internal client.

      • usr. Specifies that the subject is a user/identity.

For example, (usr!demo), or (age!myOAuth2Client).

org.forgerock.services.cts.reaper.cache.pollFrequencyMilliseconds

How often to poll the reaper cache for tokens that have expired, and delete them.

By default, an AM instance will review its cache for tokens eligible for deletion every 100 milliseconds.

Default: 100 (milliseconds)

For more information, refer to Tune the CTS.]

org.forgerock.services.cts.reaper.cache.size

The number of records an AM instance will store in its CTS reaper cache.

Default: 500000

For more information, refer to Tune the CTS.

org.forgerock.services.cts.reaper.search.gracePeriodMilliseconds

Specifies a grace period used when searching for expired tokens. Any tokens that expired more than the specified duration ago are returned.

Default: 300000 (milliseconds)

For more information, refer to Tune the CTS.

org.forgerock.services.cts.reaper.search.pollFrequencyMilliseconds

How often to perform a search for expired tokens in the CTS persistence store.

Default: 5000 (milliseconds)

For more information, refer to Tune the CTS.

org.forgerock.services.cts.reaper.search.tokenLimit

The maximum number of expired tokens to return to the AM reaper when searching the CTS store.

Default: 5000

For more information, refer to Tune the CTS.

org.forgerock.services.cts.store.ttlsupport.enabled

Specifies whether AM support for the DS entry expiration and deletion feature is enabled. Enabling this setting causes AM to clone the value of the coreTokenExpirationDate attribute to the coreTokenTtlDate attribute during token creation, which allows DS to index tokens using the coreTokenTtlDate attribute for the entry expiration and deletion feature.

This property does not clone the values of tokens that were created before the setting was enabled.

Set this property to true in conjunction with the org.forgerock.services.cts.store.ttlsupport.exclusionlist advanced server property when you need to configure the AM reaper to manage the expiration time for a subset of the tokens in the CTS store only.

For more information, refer to Manage expired CTS tokens.

Default: false

org.forgerock.services.cts.store.reaper.enabled

Specifies whether the AM reaper is enabled.

Do not disable the AM reaper unless you have a system in place to clean up expired tokens, such as the DS entry expiration and deletion feature.

Set this property to true in the following scenarios:

  • When the AM reaper must manage the expiration times for all the tokens in the CTS store.

  • When the AM reaper must manage the expiration time for a subset of the tokens in the CTS store.

For more information, refer to Manage expired CTS tokens.

Default: true

org.forgerock.services.cts.store.ttlsupport.exclusionlist

When the org.forgerock.services.cts.store.ttlsupport.enabled advanced server property is set to true, this property specifies a list of token types which will not have their coreTokenExpirationDate data cloned. For example, SESSION.

The AM reaper will delete the excluded tokens when they expire.

The CTS token store lists the token types in use in your environment.

For more information, refer to Manage expired CTS tokens.
Default: Not set

org.forgerock.services.datalayer.connection.timeout

Timeout in seconds for LDAP connections to the configuration data store.

Default: 10 (seconds)

For suggested settings, see Tuning CTS Store LDAP Connections.

org.forgerock.services.datalayer.connection.timeout.cts.async

Timeout in seconds for LDAP connections used for most CTS operations.

Default: 10 (seconds)

For suggested settings, see Tuning CTS Store LDAP Connections.

org.forgerock.services.datalayer.connection.timeout.cts.reaper

Timeout in seconds for the LDAP connection used for CTS token cleanup.

Default: None (do not time out)

For suggested settings, see Tuning CTS Store LDAP Connections.

securidHelper.ports

Port on which SecurID daemon listens.

Default: 58943

org.forgerock.session.stateless.jwtcache.expiry.time

The maximum time, in seconds, that AM caches client-side session JWTs.

Setting a long cache timeout may be more efficient, but AM will not detect if a client-side session JWT has expired or has become invalid until the cache expires.

The property is hot-swappable. You do not need to restart AM for the changes to take effect.

Default: 10

org.forgerock.session.stateless.jwtcache.size

The size, in bytes, of the cache where AM stores client-side session JWTs.

Default: 10000

org.forgerock.openam.ldap.keepalive.search.base

Defines the search base for:

  • The heartbeat request that checks connections to the LDAP server are alive and prevents idle timeouts (keepalive).

  • The load balancer availability check.

The LDAP server connection pool will be marked as unavailable if the search fails with an error, returns no entries, or if more than one entry is returned.

If the search results in an error, AM fails to start up with an exception such as org.forgerock.opendj.ldap.ConnectionException: Connect Error: No operational connection factories available.

Default: [Empty]

org.forgerock.openam.ldap.keepalive.search.filter

Defines the search filter for:

  • The heartbeat request that checks connections to the LDAP server are alive and prevents idle timeouts (keepalive).

  • The load balancer availability check.

    You can also use the absolute True and False filter (&).

The LDAP server connection pool will be marked as unavailable if the search fails with an error, returns no entries, or if more than one entry is returned.

If the search results in an error, AM fails to start up with an exception such as org.forgerock.opendj.ldap.ConnectionException: Connect Error: No operational connection factories available.

Default: (objectClass=*)

org.forgerock.am.auth.trees.authenticate.identified.identity

During authentication, AM records the type of user identified in an identity store. When this setting is enabled, AM uses these stored identities to decide which user to log in.

This lets the authentication trees engine correctly resolve identities that have the same username.

For more information, refer to the custom node documentation and the scripted decision node API.

Default: true

Configure sites

Sites involve multiple AM servers working together to provide services. You can use sites with load balancers and session high availability to configure pools of servers capable of responding to client requests in highly available fashion.

Name

Sets the name of the site.

Primary URL

Sets the primary entry point to the site, such as the URL, to the load balancer for the site configuration.

Secondary URLs

Sets alternate entry points to the site.

Copyright © 2010-2024 ForgeRock, all rights reserved.