Deployment Configuration

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_.

The backend type for the embedded DS server.

Default: je

Properly URL encode session tokens.

Default: true

Modules for which to open daemons at AM startup.

Default: securid

Whether to connect to the configuration directory server over LDAPS.

Default: false

AM Configuration and log file location.

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

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

Default: false

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

Default: false

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.

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

Default: true

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

Default: amlbcookie

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

Persistent cookie name.

Default: DProPCookie

Not used

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

Not used

Default: server-port, such as 8080 or 8443

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

Time in minutes after which a web or Java agent's CTS-based session expires. Note that this setting is ignored when AM creates a client-based 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).

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

Default: false

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

Default: 180

Create an HttpSession for users on successful authentication.

Default: true

SSL socket factory implementation used by AM.

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

Replication port for the embedded DS server.

Default: 8989

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.

Default: on

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

Default: false

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

Default: true

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

Default: AMAuthCookie

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

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

Default: false

Whether to allow multiple cookie domains.

Default: true

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

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

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.

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

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

Default: sunIdentityServerAuthNServer

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

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

Default: 3

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

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

Available settings are as follows:

Default: off

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

Default: false

Whether JSS should take priority over other providers.

Default: true

Whether monitoring is active for AM.

Default: off

URL for local connection to the monitoring service.

Default: service:jmx:rmi://

Internal property used by AM.

Default: server-uri, such as openam

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

Maximum number of policy decisions AM caches.

Default: 10000

Whether to perform a Java security permissions check for AM.

Default: false

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.

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

Default: false

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

Default: false

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

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

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

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

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

Default: /path/to/openam/

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

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

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

Default: 30000

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

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

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

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

Default: false

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

Default: WEB_CONTAINER

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.

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

Default: true

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

Default: AMDistAuthCookie

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

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

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

Default: false

Character set used for globalization.

Default: UTF-8

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

Default: connection

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

Default: connection

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

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

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

Default: false

Specifies 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:

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

Default: false

Specifies 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.

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

The following events can be suppressed:

Logging these additional events may have an impact on performance.

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

Specifies whether a session's authentication level is always the highest authentication level of any authentication module that passed, even if there are requisite or required modules in the authentication chain that were not executed. For more information, see "About Authentication Levels for Chains".

Default: false

Administration port for the embedded DS server.

Default: 4444

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

Possible values are true or false.

Default: true

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

Possible values are true or false.

Default: true

Specifies 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:

Default: false

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

Default: 30

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

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

While you are customizing the UI as described in the UI Customization Guide, 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

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.

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 to the same value specified in AM's web container's startup script. For more information, see "Preparing AES Key Wrap Encryption".

Default: SHA1, which results in the usage of PBKDF2WithHmacSHA1 key derivation algorithm.

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

Set this property to the same value specified in AM's web container's startup script. For more information, see "Preparing AES Key Wrap Encryption".

Default:10000

The size of the derived key for the AES Key Wrap encryption operations. Key sizes greater than 128 bits require JCE Unlimited Strength policy files to be installed in your system. PBKDF2 using SHA256, SHA384, and SHA512 is only available when AM's web container uses JDK 8.

Set this property to the same value specified in AM's web container's startup script. For more information, see "Preparing AES Key Wrap Encryption".

Default: 128

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]

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

For more information about JVM properties, see Tip.

Default: Not set

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

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, configure the org.forgerock.openam.httpclienthandler.system.proxy.username and org.forgerock.openam.httpclienthandler.system.proxy.uri advanced server properties as well.

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

For more information, see "Configuring AM for Outbound Communication".

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

Default: Not set

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, 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

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

Default: false

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

Default: 0 (no time limit)

Specifies the amount of time in seconds 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 or to a negative number.

Default: 3

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

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

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

Default: 5000

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

Specifies the maximum size of the body of any request made to AM. For more information, see "Limiting 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)

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, see "Customizing Public Key IDs".

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

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.

For more information, see "Using Google Cloud KMS Secrets to Decrypt AM Secrets" and "Changing the amAdmin Password (Secret Stores)".

This property has no default.

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

Possible values are:

For more information, see "Changing the amAdmin Password (Secret Stores)".

Default: ENCRYPTED_PLAIN

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

Default: A128CBC-HS256

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

Default: RSA-OAEP-256

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

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—for example, 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

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

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

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

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

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

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, see "Reaper Cache Size".

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

Default: 500000

For more information, see "Reaper Cache Size".

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, see "Reaper Cache Size".

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

Default: 5000 (milliseconds)

For more information, see "Reaper Cache Size".

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

Default: 5000

For more information, see "Reaper Cache Size".

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, see Configuring the CTS Reaper.

Default: false

Specifies whether the AM reaper is enabled.

Set this property to true in the following scenarios:

For more information, see Configuring the CTS Reaper.

Default: true

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.

For more information, see Configuring the CTS Reaper.

Default: Not set

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

Default: 10 (seconds)

For suggested settings, see "Tuning CTS Store LDAP Connections".

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

Default: 10 (seconds)

For suggested settings, see "Tuning CTS Store LDAP Connections".

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".

Port on which SecurID daemon listens.

Default: 58943