--- title: Deployment configuration description: Under Deployment, you can manage different configurations for AM server instances, and site configurations when using multiple AM server instances. component: pingam version: 8 page_id: pingam:am-reference:deployment-configuration-reference canonical_url: https://docs.pingidentity.com/pingam/8/am-reference/deployment-configuration-reference.html keywords: ["Install", "Configuration"] page_aliases: ["reference:deployment-configuration-reference.adoc"] section_ids: servers-configuration: Configure servers server-general: General properties general-site: Site general-system: System general-debugging: Debugging general-mailserver: Mail server server-security: Security properties security-encryption: Encryption security-validation: Validation security-cookie: Cookie security-keystore: Key store security-revocation: Certificate revocation list caching security-protocol: Online certificate status protocol check security-whitelist: Object deserialisation class allowlist server-session: Session properties server-limits: Session limits server-statistics: Statistics server-notification: Notification server-validation: Validation server-sdk: SDK properties sdk-datastore: Data store sdk-event: Event service sdk-ldap: LDAP connection sdk-caching: Caching and replica sdk-timetolive: Time to live configuration server-cts: CTS properties cts-tokenstore: CTS token store cts-external-tokenstore: External store configuration server-uma: UMA properties uma-ref-resource-set-store: UMA resource store uma-ref-external-resource-set-store: External UMA resource store configuration uma-ref-audit-store: UMA audit store uma-ref-external-audit-store: External UMA audit store configuration uma-ref-pending-store: Pending requests store uma-ref-external-pending-store: External pending requests store configuration uma-ref-labels-store: UMA resource labels store uma-ref-external-labels-store: External UMA resource labels store configuration server-directory-configuration: Directory configuration properties directory-directory: Directory configuration sec-directory-config-server: Server server-advanced: Advanced properties sites-configuration: Configure sites --- # 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.](_images/openam-inherited-properties.png)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 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 The directory where AM's configuration data and logs reside. For example, `/path/to/am/`. Property: `com.iplanet.services.configpath` - Default Locale The default locale of the UI pages when the client doesn't request a locale by using the `locale` query string parameter or by setting the `Accept-Language` HTTP header. To set the locale when AM can't find UI files for the requested locale, set the JVM platform locale instead. Default: `en_GB` Property: `com.iplanet.am.locale` - Notification URL The URL of the notification service endpoint. For example, `https://am.example.com:8443/am/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 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 The path where AM writes debug logs. For example, `/path/to/am/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 properties under the Mail Server tab configure the email server AM uses to send notification emails, for example, on account lockout. * Mail Server Host Name The hostname of the SMTP server. Default: `localhost` Property: `com.iplanet.am.smtphost` * Mail Server Port Number The port of the SMTP server. Default: `25` Property: `com.iplanet.am.smtpport` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------- | | | This is a *different* email server to the [Email service](../user-self-service/configuring-email-service.html) you configure for user self-service. | ### Security properties Most security settings are inherited by default. #### Encryption The following properties are available under the Encryption tab: * Password Encryption Key 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 for all servers at Deployment > Servers > *server name* > Security. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For greater security, store the password encryption key in a keystore and rotate the key periodically:1) Set Enable Encryption KeyStore. 2) Configure the keystore by setting the encryption keystore properties on this page. You can either reference an existing keystore file or create a new one for this purpose. 3) Set Encryption Key Alias to the current active key in the keystore.Learn about creating keystores and aliases in [Key aliases and passwords](../security/configuring-keys.html). | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If you set Enable Encryption KeyStore and PingAM finds an encryption key for the mapped alias in the keystore, the Password Encryption Key is ignored. | Example: `TF1Aue9c63bWTTY4mmZJeFYubJbNiSE3` Property: `am.encryption.pwd` * Encryption class The default class used to handle encryption. Default: `com.iplanet.services.util.JCEEncryption` Property: `com.iplanet.security.encryptor` * Secure Random Factory Class 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` * Enable Encryption KeyStore If enabled, AM gets the password encryption key from the keystore defined on this page. Default: false Property: `am.encryption.secret.enabled` * Encryption Key Alias The alias of the current active password encryption key in the keystore. Property: `am.encryption.secret.alias` * Encryption KeyStore File The location of the keystore containing the password encryption key, for example, `/path/to/am/security/keystores/encryption-keystore.jceks`. Property: `am.encryption.secret.keystoreFile` * Encryption KeyStore Type The type of the keystore: `JCEKS`, `PKCS12`, or `BCFKS`. Property: `am.encryption.secret.keystoreType` The specified keystore type must be supported by, and configured in, the local Java runtime environment. Default: `JCEKS` * `BCFKS` keystores require specific configuration. Find more information in [FIPS 140–3 compliance](../security/fips.html). * The encryption key is treated as a generic password. If you're migrating to a BCFKS keystore from other keystore types, you might encounter limitations when migrating the encryption key to BCFKS. This is because BCFKS might not support the algorithm used to store the key in the old keystore (for example, `RAW` or `PBEKey`). Before you migrate the encryption key from an old keystore, change the storage algorithm to one that doesn't enforce length restrictions during storage or retrieval of the key, for example, `HmacSHA512`. Length restrictions on actual usage aren't subject to this issue. * Encryption KeyStore Password File The location of the file containing the keystore password; for example, `/path/to/am/security/secrets/default/.storepass`. Property: `am.encryption.secret.keystorePass` * Encryption Key Password File The location of the file containing the keystore key password; for example, `/path/to/am/security/secrets/default/.keypass`. Property: `am.encryption.secret.keyPass` #### Validation The following properties are available under the Validation tab: * Platform Low Level Comm. Max. Content Length 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` #### Cookie The following properties are available under the Cookie tab: * Cookie Name The name of the cookie 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 The path to the AM keystore file, for example, `/path/to/am/security/keystores/keystore.jceks`. Default: `%BASE_DIR%/%SERVER_URI%/keystore.jceks` Property: `com.sun.identity.saml.xmlsig.keystore` * Keystore Type The keystore type, for example `JKS` or `JCEKS`. 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 The path to the password file for the keystore, for example, `/path/to/am/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 The path to the password file for the private key aliases contained in the keystore, for example, `/path/to/am/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 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 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. AM must trust the certificate from the LDAP server if you enable this option. Default: Disabled Property: `com.sun.identity.crl.cache.directory.ssl` * mTLS Enabled When enabled, AM uses mutual TLS (mTLS) to authenticate to the DS server with trusted certificates. If you enable mTLS, you must also: * Set SSL/TLS Enabled. * Set a secure port in the Connection String(s) property. * Configure the DS server for mTLS. Learn more about configuring datastores for mTLS in [Secure authentication to datastores](../security/secure-data-stores.html). * Map the secret label `am.servers.crl.cache.directory.mtls.cert` to a certificate in the secret store. Learn more about configuring certificates and secret store mappings in [Secret stores](../security/secret-stores.html). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | - If you enable mTLS, AM ignores the values of the LDAP server bind user name and LDAP server bind password properties. - You must restart the server for changes to this setting to take effect. | Default: Disabled property: `com.sun.identity.crl.cache.directory.mtlsenabled` * LDAP server bind user name 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 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 A valid Base DN for the LDAP search, such as `dc=example,dc=com`. Property: `com.sun.identity.crl.cache.directory.searchlocs` * Search Attributes The DN component of the issuer's subject DN 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 The URL for the OCSP responder to contact about the revocation status of certificates. Property: `com.sun.identity.authentication.ocsp.responder.url` * Certificate Nickname 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 A list of classes 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](../am-sessions/cts-based-sessions.html) 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](../am-sessions/cts-based-sessions.html) 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 The path where AM writes statistic files, for example, `/path/to/am/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 datastore 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 PingDS as a directory proxy in front of a number of additional DS instances. For more information, see [Directory Proxy](https://docs.pingidentity.com/pingds/8/install-guide/setup-proxy.html) 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 You can configure the Core Token Service (CTS) to store tokens in the same LDAP directory as the AM configuration or in a separate external directory server. Take note of specific requirements for indexing and replication. In particular, manage WAN replication carefully for optimum performance. Tune advanced properties related to token size correctly, including `com.sun.identity.session.repository.enableEncryption`, `com.sun.identity.session.repository.enableCompression`, and `com.sun.identity.session.repository.enableAttributeCompression`. For more information, refer to [Advanced properties](#server-advanced). #### CTS token store Set the following properties on the CTS Token Store tab: * Store Mode Specifies the datastore where AM stores CTS tokens. Possible values are: * `Default Token Store`: AM stores CTS tokens in the configuration datastore. * `External Token Store`: AM stores CTS tokens in an external datastore. If you specify `Default Token Store`, you can't access the configuration properties on the External Store Configuration tab. * Root Suffix This property sets the base DN for CTS storage. For example, `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 datastore. * Max Connections The maximum number of remote connections to the external datastore. For affinity deployments, this property specifies the maximum number of remote connections to each directory server in the connection string. Default: `100` Find recommended settings in [Tune CTS store LDAP connections](../maintenance/tuning-ldap-settings.html#tuning-ldap-settings-cts). * Page Size The number of results per page returned from the CTS datastore. If the result set is *smaller* than the page size, the number of results is never paginated. If the result set is *larger*, the number of pages returned is 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. Find more information on VLVs in [Virtual List View Index](https://docs.pingidentity.com/pingds/8/config-guide/indexing.html#configure-vlv) in the DS documentation. Default: `10` #### External store configuration The External Store Configuration tab lets you set connection details to one or more external PingDS instances. | | | | - | -------------------------------------------------------------------------------------------------------------------------------- | | | Before you can select `External Token Store` on the CTS Token Store tab, you *must* complete the connection details on this tab. | * SSL/TLS Enabled Enables a secure connection to the directory server. Connections to PingDS *must* be secure. * mTLS Enabled When enabled, AM uses mutual TLS (mTLS) to authenticate to the PingDS using trusted certificates. When you enable mTLS, AM ignores the values of the Login Id and Password properties. You must also: * Set SSL/TLS Enabled. * Set a secure port in the Connection String(s) property. Find information on configuring certificates and keystore mappings in [Secret stores](../security/secret-stores.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You must configure the corresponding secret mapping *before* you enable an mTLS connection to the PingDS. If you try to save an mTLS configuration before configuring the mapping, the UI returns an error. | * Start TLS When enabled, AM uses startTLS to secure the connection to the external directory server. * Connection String(s) An ordered list of connection strings for external DS servers. The format is `HOST:PORT[|SERVERID[|SITEID]]`, where `HOST:PORT` are the DS FQDN and its port. `SERVERID` and `SITEID` are optional parameters to specify an AM instance that prioritizes the particular connection. This doesn't exclude other AM instances from using that connection, although they must have no remaining priority connections available to them before they use it. Multiple connection strings must be comma-separated, for example, `cts1.example.com:1636, cts2.example.com:1636`. AM uses the first connection string in the list unless the server is unreachable. In this case, it tries the next connection strings in the order in which they're defined. In production environments, you should specify more than one connection string for failover purposes. > **Collapse: Examples for active/passive deployments** > > * `cts-ds1.example.com:1636,cts-ds2.example.com:1636` > > Every AM instance accesses `cts-ds1.example.com:1636` for all CTS operations. If that server goes down, they access `cts-ds2.example.com:1636`. > > Each AM opens new connections to `cts-ds1.example.com:1636` when that directory server becomes available. > > * `cts-ds1.example.com:1636|1|1,cts-ds2.example.com:1636|2|1` > > Server 1 site 1 gives priority to `cts-ds1.example.com:1636`. Server 2 site 1 gives priority to `cts-ds2.example.com:1636`. Any server not specified accesses the first server on the list, while it is available. > > If `cts-ds1.example.com:1636` goes down, server 1 site 1 accesses `cts-ds2.example.com:1636`. Any server not specified accesses the second server on the list. > > If `cts-ds2.example.com:1636` goes down, server 2 site 1 accesses `cts-ds1.example.com:1636`. Any server not specified still accesses the first server on the list. > > Server 1 site 1 and any server not specified opens new connections to `cts-ds1.example.com:1636` when it becomes available. Only server 2 site 1 opens new connections to `cts-ds2.example.com:1636` when it becomes available. > > * `cts-ds1.example.com:1636|1|1,cts-ds2.example.com:1636|1|1,cts-ds3.example.com:1636|1|2` > > Server 1 site 1 gives priority to `cts-ds1.example.com:1636`. Any server not specified accesses the first server on the list, while it is available. > > If `cts-ds1.example.com` goes down, server 1 site 1 accesses `cts-ds2.example.com:1636`. Any server not specified accesses the second server on the list. > > If both `cts-ds1.example.com` and `cts-ds2.example.com` go down, server 1 site 1 accesses `cts-ds3.example.com:1636` in site 2. Any server not specified accesses the third server on the list. > > Server 1 site 1 and any server not specified opens new connections to any server in site 1 when they become available, with `cts-ds1.example.com` being the preferred server. > **Collapse: Example for affinity deployments** > > * `cts-ds1.example.com:1636,cts-ds2.example.com:1636,cts-ds3.example.com:1636,cts-ds4.example.com:1636` > > 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 The DN of the user who authenticates to the external datastore. This user needs sufficient privileges to read and write to the root suffix of the external PingDS. * Password The password associated with the login ID. If you enable mTLS, AM ignores the values of the Login Id and Password properties. * Heartbeat The interval, in seconds, that AM should send a heartbeat request to the PingDS to ensure that the connection isn't idle. Configure the heartbeat to ensure that network hardware, such as routers and firewalls, doesn't drop the connection between AM and the directory server. Default: `10` * Affinity Enabled When enabled, AM accesses the CTS token store in multiple DS instances in an affinity deployment rather than a single PingDS instance in an active/passive deployment. If you enable this option, make sure 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 datastore where AM stores UMA tokens. Possible values are: * `Default Token Store`: AM stores UMA tokens in the configuration datastore. * `External Token Store`: AM stores UMA tokens in an external datastore. * 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 datastore. #### 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 datastore. Make sure AM trusts the datastore's certificate when using this option. * Connection String(s) An ordered list of connection strings for external datastores. The format is `HOST:PORT[|SERVERID[|SITEID]]`, where `HOST:PORT` specify the FQDN and port of the datastore, 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:1636|1|1, uma-ldap2.example.com:1636|2|1`. AM uses the first connection string in the list unless the server is unreachable. In this case, it tries the next connection strings in the order in which they're defined. In production environments, you should specify more than one connection string for failover purposes. * Login Id The username AM uses to authenticate to the datastore. 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 datastore. * Password The password associated with the login ID property. * Heartbeat The time period, in seconds, that AM should send a heartbeat request to the datastore 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 datastore 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 datastore. * `External Token Store`: AM stores UMA audit information in an external datastore. * 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 datastore. #### 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 datastore. Make sure AM trusts the datastore's certificate when using this option. * Connection String(s) An ordered list of connection strings for external datastores. The format is `HOST:PORT[|SERVERID[|SITEID]]`, where `HOST:PORT` specify the FQDN and port of the datastore, 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:1636|1|1, uma-ldap2.example.com:1636|2|1`. AM uses the first connection string in the list unless the server is unreachable. In this case, it tries the next connection strings in the order in which they're defined. In production environments, you should specify more than one connection string for failover purposes. * Login Id The username AM uses to authenticate to the datastore. 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 datastore. * Password The password associated with the login ID property. * Heartbeat The time period, in seconds, that AM should send a heartbeat request to the datastore 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 datastore where AM stores pending requests to UMA resources. Possible values are: * `Default Token Store`: AM stores UMA pending requests in the configuration datastore. * `External Token Store`: AM stores UMA pending requests in an external datastore. * Root Suffix Specifies the base DN for storage information in LDAP format, such as `dc=uma-pending,dc=example,dc=com`. * Max Connections Specifies the maximum number of connections to the datastore. #### 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 datastore. Make sure AM trusts the datastore's certificate when using this option. * Connection String(s) An ordered list of connection strings for external datastores. The format is `HOST:PORT[|SERVERID[|SITEID]]`, where `HOST:PORT` specify the FQDN and port of the datastore, 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:1636|1|1, uma-ldap2.example.com:1636|2|1`. AM uses the first connection string in the list unless the server is unreachable. In this case, it tries the next connection strings in the order in which they're defined. In production environments, you should specify more than one connection string for failover purposes. * Login Id The username AM uses to authenticate to the datastore. 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 datastore. * Password The password associated with the login ID property. * Heartbeat The time period, in seconds, that AM should send a heartbeat request to the datastore 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 datastore 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 datastore. * `External Token Store`: AM stores user-created labels in an external datastore. * Root Suffix Specifies the base DN for storage information in LDAP format, such as `dc=uma-resources-labels,dc=example,dc=com`. * Max Connections Specifies the maximum number of connections to the datastore. #### 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 datastore. Make sure AM trusts the datastore's certificate when using this option. * Connection String(s) An ordered list of connection strings for external datastores. The format is `HOST:PORT[|SERVERID[|SITEID]]`, where `HOST:PORT` specify the FQDN and port of the datastore, 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:1636|1|1, uma-ldap2.example.com:1636|2|1`. AM uses the first connection string in the list unless the server is unreachable. In this case, it tries the next connection strings in the order in which they're defined. In production environments, you should specify more than one connection string for failover purposes. * Login Id The username AM uses to authenticate to the datastore. 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 datastore. * Password The password associated with the login ID property. * Heartbeat The time period, in seconds, that AM should send a heartbeat request to the datastore 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. * `am.oauth2.request.object.restrictions.enforced` Aligns AM behavior with the following specifications: * OAuth 2.0 Pushed Authorization Requests (PAR) ([RFC 9126](https://www.rfc-editor.org/rfc/rfc9126.html)) * OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR) ([RFC 9101](https://www.rfc-editor.org/rfc/rfc9101.html#section-5.2)). These specifications indicate the following: * The authorization server should ignore authorize parameters outside the `request_uri`. * When sending a JWT-Secured Authorization Request (JAR), the `request_uri` *must* be an `https` URI. To enforce this behavior in AM, set this property to `true`. Default: `false` * `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_am_`. * `com.iplanet.am.cookie.c66Encode` Properly URL encode session tokens. Default: `true` * `com.iplanet.am.daemons` This property was used only for authentication with modules and chains and is no longer documented. * `com.iplanet.am.directory.ssl.enabled` If `true` AM connects to the configuration directory server over LDAPS. Default: `false` * `com.iplanet.am.installdir` AM Configuration and log file location. Default: `~/openam/`, such as `~/am` * `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 isn't 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 this property and you need to match the AM server URLs with their corresponding server IDs, query the `global-config/servers` endpoint. For example: ```bash $ curl \ --request GET \ --header "Accept: application/json" \ --header "iPlanetDirectoryPro: AQIC5…​NDU1*" \ 'https://am.example.com:8443/am/json/global-config/servers?_queryFilter=true' { "result": [ { "_id": "01", "_rev": "1372703177", "url": "https://am.example.com:8443/am", "siteName": null } ], "resultCount": 1, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 } ``` In the example, the server ID for server `https://am.example.com:8443/am` 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 `am.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. Learn more in the [Overall server cache settings](../maintenance/caching.html#caching-server-settings) section. 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](../am-sessions/cts-based-sessions.html) 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` If `true`, client applications such as web or Java agents poll for [server-side](../am-sessions/cts-based-sessions.html) session changes. If `false`, 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.identity.am.cookie.check` If `true`, AM checks for cookie support in the user agent and returns an error if cookies aren't supported. Default: `false` * `com.sun.identity.appendSessionCookieInURL` If `true`, AM appends the session cookie to the 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` If `true`, users can open many browser tabs to the login page at the same time without encountering an error. Default: `false` * `com.sun.identity.authentication.setCookieToAllDomains` If `true`, AM allows 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,%ROOT_SUFFIX%|cn=amService-UrlAccessAgent,ou=DSAME Users,%ROOT_SUFFIX%` * `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 datastore 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,%ROOT_SUFFIX%` * `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://am.example.com:8443/am/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. This configuration option is used only in non-UI deployments. The UI can't set the HttpOnly name in a cookie. Default: `true` * `com.sun.identity.cookie.samesite` Configures support for applying *SameSite* cookie rules, as per internet-draft [Cookies:HTTP State Management Mechanism](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-02#section-5.3.7). Available settings are as follows: * `strict` Requests originating from different domains won't 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 can't access the required cookies. * `lax` Cookies received from different domains can't be accessed unless the request is a *top-level* request and uses a "safe" HTTP method, such as GET, HEAD, OPTIONS, and TRACE. * `off` AM applies no restrictions on cookie domains. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You must disable *SameSite* support if any of the following is true:- You must set `Access-Control-Allow-Credentials=true` in your CORS configuration. Learn more about configuring CORS in AM in [Configure CORS support](../security/securing-communications.html#enable-cors-support). - You are using SAML HTTP-POST bindings. For example, IdP-initiated single logout (SLO) functionality won't operate correctly if *SameSite* support is enabled, as the `iPlanetDirectoryPro` cookie wouldn't be accessible in cross-domain POST requests. Learn more in [Implement SSO and SLO](../am-saml2/saml2-sso-slo.html). | Default: `off` * `com.sun.identity.enableUniqueSSOTokenCookie` If `true`, AM uses protection against cookie hijacking. Default: `false` * `com.sun.identity.jss.donotInstallAtHighestPriority` If `false`, JSS takes priority over other providers. Default: `true` * `com.sun.identity.monitoring` Activates AM monitoring. 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 `am` * `com.sun.identity.policy.Policy.policy_evaluation_weights` Weights of the cost of evaluating policy subjects, rules, and conditions. Evaluation is in order of the heaviest weight to the lightest. 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` If `true`, AM performs a Java security permissions check. 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. Find important information about this property in [Overall server cache settings](../maintenance/caching.html#caching-server-settings). 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/am/` * `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.SmsWrapperObject` * `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` If `true`, AM sends an HTTP GET request to the `com.sun.identity.urlchecker.targeturl` as a health check against another server in the same site. If `false`, AM only checks the Socket connection and doesn't send an HTTP GET request. 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 `/am/namingservice` endpoint on the remote server * `com.sun.identity.urlconnection.useCache` If `true`, AM caches 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 assign privileged console access to particular users. Set to a `|` separated list of users' Universal IDs, such as `console.privileged.users=uid=bjensen,ou=user,dc=am,dc=example,dc=com|uid=scarter,ou=user,dc=am,dc=example,dc=com`. - `oauth2.provider.request.object.processing.enforced` Forces AM to use the specification set in the [Request Object Processing Specification](services-configuration.html#config-request-object-proc-spec) field of the OAuth 2.0 provider configuration for JWT requests. If set to `true`, this parameter overrides the default behavior, which is for AM to infer the request type from the contents of the request, if possible. Default: `false` - `openam.auth.destroy_session_after_upgrade` Where to destroy the old session after a session is successfully upgraded. Default: `true` - `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` If `true`, AM ignores the `goto` query string parameter on logout and displays the logout page instead. 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. You can find a list of algorithms that AM supports in the [JSON Web Algorithms (JWA)](https://datatracker.ietf.org/doc/html/draft-ietf-jose-json-web-algorithms-11#section-4.1) internet draft. You can find information on the Social Identity Provider service in [Social identity provider client configuration](../am-authentication/social-idp-client-reference.html). 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 isn't the server that originally initiated authentication. The server that originally initiated authentication is identified by a session ID stored in the `AMAuthCookie` cookie. 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 isn't the server that originally initiated authentication. The server that originally initiated authentication is identified by a session ID stored in the `AMAuthCookie` cookie. 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 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. Use the `openam.retained.http.headers` property to retain headers to return in the response to the AM server that forwarded the request. Default: `X-DSAMEVersion` - `openam.session.case.sensitive.uuid` If `true`, universal user IDs are considered case-sensitive when matching them. Default: `false` * `org.forgerock.allow.http.client.debug` 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: * `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](../_attachments/apidocs/org/forgerock/openam/http/SslConnectionManager.html) 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 won't be logged. For example, `AM-ACCESS-ATTEMPT,AM-GROUP-CHANGE`. Logging all events can impact performance. You should log only those events you intend to monitor. Changes to this property require a server restart. Default: `AM-ACCESS-ATTEMPT,AM-IDENTITY-CHANGE,AM-GROUP-CHANGE` * `org.forgerock.openam.authLevel.excludeRequiredOrRequisite` This property was used only for authentication with modules and chains and is no longer documented. * `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` 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: * `false`. AM returns an HTTP 200 message with the original SSO token. For example: ```json { "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: ```json { "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 was used only for authentication with modules and chains and is no longer documented. - `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](../ui-customization/preface.html), 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 doesn't 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](../setup/property-value-substitution.html). 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.httpclienthandler.system.clients.connection.timeout` The time new client connections using the client handler 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` The maximum number of connections allowed in the pool available for clients using the client handler. 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` The maximum time-to-live, in milliseconds, for pooled client connections using the client handler. 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` The time a client using the client handler 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 client handler 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` When `true` the client handler pools and reuses connections. Possible values are `true` or `false`. Restart AM or the container in which it runs for changes to this property to take effect. Default: `true` * `org.forgerock.openam.httpclienthandler.system.nonProxyHosts` Lists the target hosts for which requests shouldn't be proxied. Use commas to separate hostnames. 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 wouldn't be proxied for those target hosts. Configure alongside the `org.forgerock.openam.httpclienthandler.system.proxy.uri` and `org.forgerock.openam.httpclienthandler.system.proxy.username` advanced server properties. Store the proxy password in a [secret store](../security/secret-stores.html), instead of in the configuration. Use the secret label `am.servers.httpclienthandler.proxy.secret` to map an alias for the password. If AM finds a matching secret for the `am.servers.httpclienthandler.proxy.secret` label in a secret store, AM ignores the `org.forgerock.openam.httpclienthandler.system.proxy.password` advanced server property. Default: `localhost,127.*,[::1],0.0.0.0,[::0]` * `org.forgerock.openam.httpclienthandler.system.proxy.enabled` When set to `true`, AM routes outgoing [HttpClientHandler](../_attachments/apidocs/org/forgerock/http/handler/HttpClientHandler.html) 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` The password of the proxy that AM uses to route outgoing client handler requests. For greater security, store the proxy password in a [secret store](../security/secret-stores.html), instead of in the configuration. Use the secret label `am.servers.httpclienthandler.proxy.secret` to map an alias for the password. If AM finds a matching secret for the `am.servers.httpclienthandler.proxy.secret` label in a secret store, AM ignores the `org.forgerock.openam.httpclienthandler.system.proxy.password` advanced server property. 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. If you change this password in the configuration, you must restart AM or the container in which it runs for the change to take effect. If you store the proxy password in a secret store, you can rotate the secret without having to restart AM. Default: Not set * `org.forgerock.openam.httpclienthandler.system.proxy.uri` The URI of the proxy that AM will use to route outgoing client handler 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, optionally, the `org.forgerock.openam.httpclienthandler.system.nonProxyHosts` property. Store the proxy password in a [secret store](../security/secret-stores.html). and use the secret label `am.servers.httpclienthandler.proxy.secret` to map an alias for the password. If AM finds a matching secret for the `am.servers.httpclienthandler.proxy.secret` label in a secret store, AM ignores the `org.forgerock.openam.httpclienthandler.system.proxy.password` advanced server property. This property takes precedence over the `org.forgerock.openam.httpclienthandler.system.proxy.enabled` advanced server property and its related JVM properties. Learn more in [Configure AM for outbound communication](../security/reverse-proxy.html#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` The username of the proxy AM will use to route outgoing client handler 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](../am-oauth2/oauth2-introspect-endpoint.html) endpoint. For security reasons, and in accordance with the [OAuth 2.0 Token Introspection specification](https://www.rfc-editor.org/info/rfc7662), 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](../maintenance/caching.html#caching) timeout, in milliseconds, after which an entry should be removed from the cache. A value of `0` means that the DN cache won't expire, and entries won't 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` The number of 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`. 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. Learn more in [Secure network communication](../security/securing-communications.html). Specify a comma-separated list with multiple protocols for AM to use the most secure protocol supported by the external resources. A value of `TLSv1.3,TLSv1.2` means that AM attempts to use the TLSv1.3 protocol to connect to the configuration and user \*s, but if a TLSv1.3 connection isn't supported, AM uses TLSv1.2. Default: `TLSv1.3,TLSv1.2` * `org.forgerock.openam.notifications.agents.enabled` Controls whether to publish notifications for consumption by web agents and Java agents. Learn more about notifications in the [Web Agents Maintenance Guide](https://docs.pingidentity.com/web-agents/2025.3/maintenance-guide/notifications.html) and the [Java Agents Maintenance Guide](https://docs.pingidentity.com/java-agents/2025.3/maintenance-guide/notifications.html). Default: `true` - `org.forgerock.openam.oauth2.checkIssuerForIdTokenInfo` If set to `true`, a query to the [/oauth2/idtokeninfo](../am-oidc1/rest-api-oidc-idtoken-validation.html) endpoint validates the `iss` (issuer) claim against the AM issuers. If the value of the `iss` claim differs from the AM issuer, AM returns the following error: `bad_request: Invalid id token issuer` Default: `false` * `org.forgerock.openam.oauth2.tokenexpiry.skewAllowance` The period, in seconds, during which an OIDC ID token remains valid *after* its expiry time. This property allows for clock skews between servers. Default: `300` (5 minutes) - `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](services-configuration.html#refresh-token-grace-period-provider) or on any [OAuth 2.0 clients](../am-oauth2/oauth2-register-client.html#refresh-token-grace-period-client). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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.oidc.SocialProvider.sub.claim.is.not.unique` By default, OIDC social authentication flows use the `sub` claim to identify the subject, in accordance with the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes), which mandates that the `sub` claim should uniquely identify the user. However, some identity providers don't provide a unique value for the `sub` claim. In this case, you can set this property to `true`. When set to `true`, AM uses the value of the `Auth ID Key` in the social provider configuration to identify the subject. 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. Learn more in [Configure trusted URLs](../am-authentication/redirection-url-precedence.html#configure_trusted_urls). 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. Learn more in [Limit the size of the request body](../security/limit-request-body-size.html). The property is hot-swappable. You don't 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. Learn more in [Customizing Public Key IDs](../am-oidc1/managing-jwk_uri.html#customizing-kids). 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. Learn more in [Using Google Cloud KMS Secrets to Decrypt AM Secrets](../security/secret-stores.html#KMS-secret-stores-for-encrypting-secrets) and [Store the amAdmin password in a secret store](../security/securing-administration.html#amadmin-password-secret-store). This property has no default. - `org.forgerock.openam.secrets.special.user.passwords.format` 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 have 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. Learn more in [Store the amAdmin password in a secret store](../security/securing-administration.html#amadmin-password-secret-store). Default: `ENCRYPTED_PLAIN` * `org.forgerock.openam.secrets.special.user.secret.refresh.seconds` The period, in seconds, after which the special administrator secret cache expires. Learn more in [Store the amAdmin password in a secret store](../security/securing-administration.html#amadmin-password-secret-store). Default: 900 (15 minutes) * `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` Learn more in [Invalidate all sessions for a user](../am-sessions/managing-sessions-REST.html#invalidate-sessions-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 write a large volume of trace-level debug records that aren't required for troubleshooting in many cases. With this option set to `false`, trace-level debug records aren't 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 doesn't 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 an authenticated 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 doesn't 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.entitlement.enforce.realm` By default, calls to the `subjectattributes` endpoint are enforced per realm. Learn more in [Query subject attributes](../am-authorization/rest-api-authz-policies.html#rest-api-authz-subject-attributes). Default: `true` * `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](../am-oidc1/backchannel-logout.html), and OIDC ID token. AM accepts tokens that use the old `sub` format, even if you enable this property. 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. > **Collapse: About the subname Claim** > > The value of the `subname` claim matches the value of the `sub` claim used in versions of AM earlier than 7.1. It also matches the value of the `sub` claim if you disable the `org.forgerock.security.oauth2.enforce.sub.claim.uniqueness` property. > > An example of the value of the `subname` claim is `bjensen`, or `myOauth2Client`. > > AM adds this claim to access and ID tokens by default. > > If you don't want the `subname` claim added by default, disable the Include subname claim in tokens issued by the OAuth2 Provider property in the OAuth2 Provider service configuration. 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's the subject of the token. For example, `bjensen`, 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`. Indicates 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`. Indicates the *subject* is a user/identity. For example, `(usr!bjensen)`, 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) Learn more in [Tune the CTS](../cts/cts-tuning-considerations.html). * `org.forgerock.services.cts.reaper.cache.size` The number of records an AM instance will store in its CTS reaper cache. Default: `500000` Learn more in [Tune the CTS](../cts/cts-tuning-considerations.html). * `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) Learn more in [Tune the CTS](../cts/cts-tuning-considerations.html). * `org.forgerock.services.cts.reaper.search.pollFrequencyMilliseconds` How often to perform a search for expired tokens in the CTS persistence store. Default: `5000` (milliseconds) Learn more in [Tune the CTS](../cts/cts-tuning-considerations.html). * `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` Learn more in [Tune the CTS](../cts/cts-tuning-considerations.html). * `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 doesn't 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. Learn more in [Manage expired CTS tokens](../cts/cts-reaper.html). Default: `false` * `org.forgerock.services.cts.store.reaper.enabled` Specifies whether the AM reaper is enabled. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------- | | | Don't 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. Learn more in [Manage expired CTS tokens](../cts/cts-reaper.html). 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 won't 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. | Learn more in [Manage expired CTS tokens](../cts/cts-reaper.html).\ Default: Not set * `org.forgerock.services.datalayer.connection.timeout` Timeout in seconds for LDAP connections to the configuration \*. Default: `10` (seconds) Find the suggested settings in [Tuning CTS Store LDAP Connections](../maintenance/tuning-ldap-settings.html#tuning-ldap-settings-cts). * `org.forgerock.services.datalayer.connection.timeout.cts.async` Timeout in seconds for LDAP connections used for most CTS operations. Default: `10` (seconds) Find the suggested settings in [Tuning CTS Store LDAP Connections](../maintenance/tuning-ldap-settings.html#tuning-ldap-settings-cts). * `org.forgerock.services.datalayer.connection.timeout.cts.reaper` Timeout in seconds for the LDAP connection used for CTS token cleanup. Default: None (don't time out) Find the suggested settings in [Tuning CTS Store LDAP Connections](../maintenance/tuning-ldap-settings.html#tuning-ldap-settings-cts). * `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 won't detect if a client-side session JWT has expired or has become invalid until the cache expires. The property is hot-swappable. You don't 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. Learn more in the [custom node documentation](../auth-nodes/core-action.html) and [scripted decision node API](../am-scripting/scripting-api-node.html#action-set-outcome). 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 The name of the site. * Primary URL The primary entry point to the site, such as the URL, to the load balancer for the site configuration. * Secondary URLs Alternative entry points to the site.