--- title: Secrets description: IG uses the Commons Secrets API to manage secrets, such as passwords and cryptographic keys. component: pinggateway version: 2023.11 page_id: pinggateway:reference:secrets canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/secrets.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2024-09-18T11:50:37Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/secrets.html section_ids: Base64EncodedSecretStore: Base64EncodedSecretStore Base64EncodedSecretStore-usage: Usage Base64EncodedSecretStore-properties: Properties Base64EncodedSecretStore-log: Log level Base64EncodedSecretStore-example: Example Base64EncodedSecretStore-moreinfo: More information FileSystemSecretStore: FileSystemSecretStore FileSystemSecretStore-usage: Usage FileSystemSecretStore-properties: Properties FileSystemSecretStore-log: Log level FileSystemSecretStore-example: Example FileSystemSecretStore-moreinfo: More information HsmSecretStore: HsmSecretStore HsmSecretStore-usage: Usage HsmSecretStore-properties: Properties HsmSecretStore-log: Log level HsmSecretStore-example: Example HsmSecretStore-moreinfo: More information JwkPropertyFormat: JwkPropertyFormat JwkPropertyFormat-usage: Usage JwkPropertyFormat-example: Example JwkPropertyFormat-moreinfo: More information JwkSetSecretStore: JwkSetSecretStore JwkSetSecretStore-usage: Usage JwkSetSecretStore-properties: Properties JwkSetSecretStore-log: Log level JwkSetSecretStore-example: Example JwkSetSecretStore-moreinfo: More information KeyStoreSecretStore: KeyStoreSecretStore KeyStoreSecretStore-usage: Usage KeyStoreSecretStore-properties: Properties KeyStoreSecretStore-log: Log level KeyStoreSecretStore-example: Example KeyStoreSecretStore-moreinfo: More information PemPropertyFormat: PemPropertyFormat PemPropertyFormat-usage: Usage PemPropertyFormat-properties: Properties PemPropertyFormat-example: Example PemPropertyFormat-moreinfo: More information SecretsKeyManager: SecretsKeyManager SecretsKeyManager-usage: Usage SecretsKeyManager-properties: Properties SecretsKeyManager-example: Example SecretsKeyManager-moreinfo: More information SecretKeyPropertyFormat: SecretKeyPropertyFormat SecretKeyPropertyFormat-usage: Usage SecretKeyPropertyFormat-properties: Properties SecretKeyPropertyFormat-example: Example SecretKeyPropertyFormat-moreinfo: More information SecretsProvider: SecretsProvider SecretsProvider-usage: Usage SecretsProvider-properties: Properties SecretsProvider-example: Example SecretsProvider-moreinfo: More information SecretsTrustManager: SecretsTrustManager SecretsTrustManager-usage: Usage SecretsTrustManager-properties: Properties SecretsTrustManager-example: Example SecretsTrustManager-moreinfo: More information SystemAndEnvSecretStore: SystemAndEnvSecretStore SystemAndEnvSecretStore-usage: Usage SystemAndEnvSecretStore-properties: Properties SystemAndEnvSecretStore-log: Log level SystemAndEnvSecretStore-example: Example SystemAndEnvSecretStore-moreinfo: More information TrustManager: TrustManager (deprecated) TrustManager-usage: Usage TrustManager-properties: Properties TrustManager-example: Example TrustManager-moreinfo: More information default-secrets-object: Default secrets object (deprecated) secrets-usage: Usage secrets-properties: Properties secrets-example: Example --- # Secrets IG uses the Commons Secrets API to manage secrets, such as passwords and cryptographic keys. For more information about how IG manages secrets, refer to [About secrets](../security-guide/keys.html#about-secrets). ## Base64EncodedSecretStore Manage a repository of generic secrets, such as passwords or simple shared secrets, whose values are base64-encoded, and hard-coded in the route. This Secret store can only manage the [GenericSecret](../security-guide/keys.html#secret-types) type. The secrets provider queries the Base64EncodedSecretStore for a named secret, identified by the `secret-id` in the `"secret-id": "string"` pair. The Base64EncodedSecretStore returns the matching secret. The secrets provider builds the secret, checking that the secret's constraints are met, and returns a unique secret. If the secret's constraints are not met, the secrets provider cannot build the secret and the secret query fails. Secrets from Base64EncodedSecretStore never expire. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------- | | | Use Base64EncodedSecretStore for testing or evaluation only, to store passwords locally. In production, use an alternative secret store. | For a description of how secrets are managed, refer to [About secrets](../security-guide/keys.html#about-secrets) ### Usage ```json { "name": string, "type": "Base64EncodedSecretStore", "config": { "secrets": map or configuration expression } } ``` ### Properties * `"secrets"`: *[map](preface.html#definition-map) or configuration expression\, required* Map of one or more data pairs with the format `Map`, where: * The key is the ID of a secret used in a route * The value is the base64-encoded value of a secret, or a configuration expression that evaluates to the base64-encoded value of a secret The following formats are allowed: ```json { "secrets": { "secret-id": "configuration expression", ... } } ``` ```json { "secrets": "configuration expression" } ``` In the following example, the property is a map whose values are provided by strings: ```json { "type": "Base64EncodedSecretStore", "config": { "secrets": { "agent.password": "d2VsY29tZQ==", "crypto.header.key": "Y2hhbmdlaXQ=" } } } ``` In the following example, the property is a map whose values are provided by a configuration token and a configuration expression. The values are substituted when the route is loaded: ```json { "type": "Base64EncodedSecretStore", "config": { "secrets": { "agent.password": "&{secret.value|aGVsbG8=}", "crypto.header.key": "${readProperties('file.property')['b64.key.value']}" } } } ``` ### Log level To facilitate debugging secrets for the Base64EncodedSecretStore, in `logback.xml` add a logger defined by the fully qualified package name of the Base64EncodedSecretStore. The following line in `logback.xml` sets the log level to `ALL`: ```xml ``` ### Example For an example that uses Base64EncodedSecretStore, refer to `client-credentials.json` in [Using OAuth 2.0 client credentials](../gateway-guide/oauth2.html#oauth2-clientcredentials). ### More information [Secrets](#) [org.forgerock.openig.secrets.Base64EncodedSecretStore](../_attachments/apidocs/org/forgerock/openig/secrets/Base64EncodedSecretStore.html) ## FileSystemSecretStore Manage a store of secrets held in files, specified as follows: * Each file must contain only one secret. * The file must be in the directory specified by the property `directory`. * The filename must match the `mappings` property `secretId`. * The file content must match the `mappings` property `format`. For example, if the mapping specifies `BASE64`, the file content must be base64-encoded. This Secret store can manage secrets of both [GenericSecret](../security-guide/keys.html#secret-types) and [CryptoKey](../security-guide/keys.html#secret-types) types when used with dedicated formats. Secrets are read lazily from the filesystem. The secrets provider queries the FileSystemSecretStore for a named secret, identified by the name of a file in the specified directory, without the prefix/suffix defined in the store configuration. The FileSystemSecretStore returns the secret that exactly matches the name. The secrets provider builds the secret, checking that the secret's constraints are met, and returns a unique secret. If the secret's constraints are not met, the secrets provider cannot build the secret and the secret query fails. For a description of how secrets are managed, refer to [About secrets](../security-guide/keys.html#about-secrets) ### Usage ```json { "name": string, "type": "FileSystemSecretStore", "config": { "directory": configuration expression, "format": SecretPropertyFormat reference, "suffix": configuration expression, "mappings": [ object, ... ], "leaseExpiry": configuration expression, "autoRefresh": object } } ``` ### Properties * `"directory"`: *configuration expression<[string](preface.html#definition-string)>, required* File path to a directory containing secret files. This object checks the specified directory, but not its subdirectories. * `format`: *SecretPropertyFormat [reference](preface.html#definition-reference), optional* Format in which the secret is stored. Use one of the following values or formats: * `BASE64`: Base64-encoded * `PLAIN`: Plain text * A [JwkPropertyFormat](JwkPropertyFormat.html) * A [PemPropertyFormat](PemPropertyFormat.html) Default: `BASE64` * `"suffix"`: *configuration expression<[string](preface.html#definition-string)>, optional* File suffix. When set, the FileSystemSecretStore will append that suffix to the secret ID and try to find a file with the mapped name. Default: None - `"mappings"`: *array of [objects](preface.html#definition-object), optional* One or more mappings to define a secret: * `secretId`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The ID of the secret used in your configuration. * `format`: *SecretPropertyFormat [reference](preface.html#definition-reference), required* The format and algorithm of the secret. Use [SecretKeyPropertyFormat](SecretKeyPropertyFormat.html) or [PemPropertyFormat](PemPropertyFormat.html). * `"leaseExpiry"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The amount of time that secrets produced by this store can be cached before they must be refreshed. If the duration is `zero` or `unlimited`, IG issues a warning, and uses the default value. Default: 5 minutes * `"autoRefresh"`: *[object](preface.html#definition-object), optional* Automatically reload the FileSystemSecretStore when a file is edited or deleted on the filesystem in the configured directory. ```json { "enabled": configuration expression, "executor": ScheduledExecutorService reference } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Flag to enable or disable automatic reload: * `true`: Enable * `false`: Disable Default: `true` * `"executor"`: *ScheduledExecutorService [reference](preface.html#definition-reference), optional* A [ScheduledExecutorService](MiscellaneousConfigurationObjects.html#ScheduledExecutorService) to monitor the filesystem. Default: The default ScheduledExecutorService in the heap ### Log level To facilitate debugging secrets for the FileSystemSecretStore, in `logback.xml` add a logger defined by the fully qualified package name of the property resolver. The following line in `logback.xml` sets the log level to `ALL`: ```xml ``` ### Example For an example that uses FileSystemSecretStore, refer to [Pass runtime data in a JWT signed with a PEM](../gateway-guide/data-downstream.html#runtime-signed-pem-example). ### More information [Secrets](#) [org.forgerock.openig.secrets.FileSystemSecretStoreHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/FileSystemSecretStoreHeaplet.html) ## HsmSecretStore Manage a store of secrets with a hardware security module (HSM) device or a software emulation of an HSM device, such as SoftHSM. This Secret store can only manage secrets of the [CryptoKey](../security-guide/keys.html#secret-types) type. The secrets provider queries the HsmSecretStore for a named secret, identified by a secret ID and a stable ID, corresponding to the `secret-id`/`aliases` mapping. The HsmSecretStore returns a list of matching secrets. The secrets provider builds the secret, checking that the secret's constraints are met, and returns a unique secret. If the secret's constraints are not met, the secrets provider cannot build the secret and the secret query fails. For a description of how secrets are managed, refer to [About secrets](../security-guide/keys.html#about-secrets) ### Usage ```json { "name": string, "type": "HsmSecretStore", "config": { "providerName": configuration expression, "storePasswordSecretId": configuration expression, "secretsProvider": SecretsProvider reference, "mappings": [ object, ... ], "leaseExpiry": configuration expression, "storePassword": configuration expression //deprecated } } ``` ### Properties * `"providerName"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the pre-installed Java Security Provider supporting an HSM. Use a physical HSM device, or a software emulation of an HSM device, such as SoftHSM. For the SunPKCS11 provider, concatenate `"providerName"` with the prefix `SunPKCS11-`. For example, declare the following for the name `FooAccelerator`: ```json "providerName": "SunPKCS11-FooAccelerator" ``` * `"storePasswordSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* The secret ID of the password to access the HsmSecretStore. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). For information about how IG manages secrets, refer to [About secrets](../security-guide/keys.html#about-secrets). * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The [SecretsProvider](#SecretsProvider) object to query for the `storePassword`. Default: The route's default secret service. For more information, refer to [Default secrets object](#default-secrets-object). - `"mappings"`: *array of [objects](preface.html#definition-object), required* One or more mappings of one secret ID to one or more aliases. ```json "mappings" : { "secretId": configuration expression, "aliases": array of configuration expression, //use aliases or "aliasesMatching": [ string, ... ] //aliasesMatching but not both } ``` * `"secretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The secret ID of the key. * `"aliases"`: *array of configuration expression<[strings](preface.html#definition-string)>, required if `aliasesMatching` is not used* One or more key aliases. Named aliases are mapped to the secret ID. Use `aliases` or `aliasesMatching` but not both. * `"aliasesMatching"`: *array of <[strings](preface.html#definition-string)>, required if `aliases` is not used* One or more regular expressions to match key aliases. Aliases that match the expressions are mapped to the secret ID. Use `aliases` or `aliasesMatching` but not both. Some KeyStores, such as a global Java TrustStore, can contain hundreds of valid certificates. Use this property to map multiple aliases to a secret ID without listing them all in the mapping. The secret store uses the mappings as follows: * When the secret is used to create signatures or encrypt values, the secret store uses the *active secret*, the first alias in the list. * When the secret is used to verify signatures or decrypt data, the secret store tries all of the mapped aliases in the list, starting with the first, and stopping when it finds a secret that can successfully verify signature or decrypt the data. The following example maps the named aliases to the named secret IDs: ```json "mappings": [ { "secretId": "id.key.for.signing.jwt", "aliases": [ "signingkeyalias", "anothersigningkeyalias" ] }, { "secretId": "id.key.for.encrypting.jwt", "aliases": ["encryptionkeyalias"] } ] ``` The following example maps aliases that match the regular expression `.*` to the named secret ID: ```json "mappings": [ { "secretId": "id.key.for.signing.jwt", "aliasesMatching": [".*"] } ] ``` * `secretId`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The ID of the secret used in your configuration. * `aliases`: *array of configuration expression<[strings](preface.html#definition-string)>, required* One or more aliases for the secret ID. :leveloffset: +2 - `"leaseExpiry"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The amount of time that secrets produced by this store can be cached before they must be refreshed. If the duration is `zero` or `unlimited`, IG issues a warning, and uses the default value. Default: 5 minutes * `"storePassword"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required if storePasswordSecretId not set* | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of this property is deprecated. If the KeyStore is password-protected, use `storePasswordSecretId`. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The secret ID of the password to access the HsmSecretStore. \+ For information about how IG manages secrets, refer to [About secrets](../security-guide/keys.html#about-secrets). ### Log level To facilitate debugging secrets for the HsmSecretStore, in `logback.xml` add a logger defined by the fully qualified package name of the HsmSecretStore. The following line in `logback.xml` sets the log level to `ALL`: ```xml ``` ### Example To set up this example: 1. Set up and test the example in [JwtBuilderFilter](Filters.html#JwtBuilderFilter), and then replace the KeyStoreSecretStore in that example with an HsmSecretStore. 2. Set an environment variable for the HsmSecretStore password, `storePassword`, and then restart IG. For example, if the HsmSecretStore password is `password`, set the following environment variable: ```bash export HSM_PIN='cGFzc3dvcmQ=' ``` The password is retrieved by the SystemAndEnvSecretStore, and must be base64-encoded. 3. Create a provider config file, as specified in the [PKCS#11 Reference guide](https://docs.oracle.com/en/java/javase/17/security/pkcs11-reference-guide.html). 4. Depending on your version of Java, create a `java.security.ext` file for the IG instance, with the following content: ```properties security.provider.= ``` or ```properties security.provider.= ``` 5. Start the IG JVM with the following system property that points to the provider config file: ```none -Djava.security.properties=file://path-to-security-extension-file ``` The following example route is based on the examples in [JwtBuilderFilter](Filters.html#JwtBuilderFilter), replacing the KeyStoreSecretStore with an HsmSecretStore: ```json { "name": "hsm-jwt-signature", "condition": "${find(request.uri.path, '/hsm-jwt-signature$')}", "baseURI": "http://app.example.com:8081", "heap": [ { "name": "SystemAndEnvSecretStore-1", "type": "SystemAndEnvSecretStore" }, { "name": "AmService-1", "type": "AmService", "config": { "agent": { "username": "ig_agent", "passwordSecretId": "agent.secret.id" }, "secretsProvider": "SystemAndEnvSecretStore-1", "url": "http://am.example.com:8088/openam" } }, { "name": "HsmSecretStore-1", "type": "HsmSecretStore", "config": { "providerName": "SunPKCS11-SoftHSM", "storePasswordSecretId": "hsm.pin", "secretsProvider": "SystemAndEnvSecretStore-1", "mappings": [{ "secretId": "id.key.for.signing.jwt", "aliases": [ "signature-key" ] }] } } ], "handler": { "type": "Chain", "config": { "filters": [{ "name": "SingleSignOnFilter-1", "type": "SingleSignOnFilter", "config": { "amService": "AmService-1" } }, { "name": "UserProfileFilter-1", "type": "UserProfileFilter", "config": { "username": "${contexts.ssoToken.info.uid}", "userProfileService": { "type": "UserProfileService", "config": { "amService": "AmService-1" } } } }, { "name": "JwtBuilderFilter-1", "type": "JwtBuilderFilter", "config": { "template": { "name": "${contexts.userProfile.commonName}", "email": "${contexts.userProfile.rawInfo.mail[0]}" }, "secretsProvider": "HsmSecretStore-1", "signature": { "secretId": "id.key.for.signing.jwt" } } }, { "name": "HeaderFilter-1", "type": "HeaderFilter", "config": { "messageType": "REQUEST", "add": { "x-openig-user": ["${contexts.jwtBuilder.value}"] } } }], "handler": "ReverseProxyHandler" } } } ``` ### More information [Secrets](#) [org.forgerock.openig.secrets.HsmSecretStoreHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/HsmSecretStoreHeaplet.html) ## JwkPropertyFormat The format of a secret used with [FileSystemSecretStore](FileSystemSecretStore.html) to decode JSON Web Key (JWK) formatted keys into secrets. ### Usage ```json { "name": string, "type": "JwkPropertyFormat" } ``` ### Example ```json { "heap" : [ { "name": "jwkPropertyFormat", "type": "JwkPropertyFormat" }, { "name": "MySecretStore", "type": "FileSystemSecretStore", "config": { "format": "jwkPropertyFormat", "directory": "&{secretsDir}/idcloud", "mappings": [ { "secretId": "my.privateKey.jwk", "format": "jwkPropertyFormat" } ] } } } ``` ### More information [org.forgerock.secrets.propertyresolver.JwkPropertyFormat](../_attachments/apidocs/org/forgerock/secrets/propertyresolver/JwkPropertyFormat.html) ## JwkSetSecretStore A secret store of JSON Web Keys (JWK) from a local or remote JWK Set. This Secret store can only manage secrets of the [CryptoKey](../security-guide/keys.html#secret-types) type. The secrets provider builds the secret, checking that the secret's constraints are met, and returns a unique secret. If the secret's constraints are not met, the secrets provider cannot build the secret and the secret query fails. For a description of how secrets are managed, refer to [About secrets](../security-guide/keys.html#about-secrets). For information about JWKs and JWK Sets, refer to [JSON Web Key (JWK)](https://www.rfc-editor.org/rfc/rfc7517). ### Usage ```json { "name": string, "type": "JwkSetSecretStore", "config": { "jwkUrl": configuration expression, "handler": Handler reference, "cacheTimeout": configuration expression, "cacheMissCacheTime": configuration expression, "leaseExpiry": configuration expression } } ``` ### Properties * `"jwkUrl"`: *configuration expression<[url](preface.html#definition-url)>, required* A URL that contains the client's public keys in JWK format. * `"handler"`: *Handler [reference](preface.html#definition-reference), optional* An HTTP client handler to communicate with the `jwkUrl`. Usually set this property to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler. Default: ClientHandler * `"cacheTimeout"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Delay before the cache is reloaded. The cache contains the `jwkUrl`. The cache cannot be deactivated. If a value lower than 10 seconds is configured, a warning is logged and the default value is used instead. Default: 2 minutes * `"cacheMissCacheTime"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* If the `jwkUrl` is looked up in the cache and is not found, this is the delay before the cache is reloaded. Default: 2 minutes - `"leaseExpiry"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The amount of time that secrets produced by this store can be cached before they must be refreshed. If the duration is `zero` or `unlimited`, IG issues a warning, and uses the default value. Default: 5 minutes ### Log level To facilitate debugging secrets for the JwkSetSecretStore, in `logback.xml` add a logger defined by the fully qualified package name of the JwkSetSecretStore. The following line in `logback.xml` sets the log level to `ALL`: ```xml ``` ### Example For an example of how to set up and use JwkSetSecretStore to validate signed access tokens, refer to [Validate signed access_tokens with the StatelessAccessTokenResolver and JwkSetSecretStore](../gateway-guide/oauth2.html#oauth2-rs-stateless-signed-sat). In the following example, a StatelessAccessTokenResolver validates a signed access token by using a JwkSetSecretStore: ```json "accessTokenResolver": { "type": "StatelessAccessTokenResolver", "config": { "secretsProvider": { "type": "JwkSetSecretStore", "config": { "jwkUrl": "http://am.example.com:8088/openam/oauth2/connect/jwk_uri" }, "issuer": "http://am.example.com:8088/openam/oauth2", "verificationSecretId": "verification.secret.id" } } } ``` The JWT signature is validated as follows: * If the JWT contains a `kid` with a matching secret in the JWK set: * The secrets provider queries the JwkSetSecretStore for a named secret. * The JwkSetSecretStore returns the matching secret, identified by a stable ID. * The StatelessAccessTokenResolver tries to validate the signature with that named secret. If it fails, the token is considered as invalid. In the route, note that the property `verificationSecretId` must be configured but is not used in named secret resolution. * If the JWT contains a `kid` without a matching secret in the JWK set: * The secrets provider queries the JwkSetSecretStore for a named secret. * Because the referenced JWK set doesn't contain a matching secret, named secret resolution fails. IG tries valid secret resolution in the same way as when the JWT doesn't contain a `kid`. * If the JWT doesn't contain a `kid`: * The secrets provider queries the JwkSetSecretStore for list of valid secrets, whose secret ID is `verification.secret.id`. * The JwkSetSecretStore returns all secrets in the JWK set whose purpose is signature verification. For example, signature verification keys can have the following JWK parameters: ```json { "use": "sig" } ``` ```json { "key_opts": [ "verify" ] } ``` Secrets are returned in the order that they are listed in the JWK set. * The StatelessAccessTokenResolver tries to validate the signature with each secret sequentially, starting with the first, and stopping when it succeeds. * If none of the valid secrets can verify the signature, the token is considered as invalid. ### More information [org.forgerock.openig.secrets.JwkSetSecretStoreHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/JwkSetSecretStoreHeaplet.html) [JSON Web Key (JWK)](https://www.rfc-editor.org/rfc/rfc7517) ## KeyStoreSecretStore Manages a secret store for cryptographic keys and certificates, based on a standard Java keystore. | | | | - | ----------------------------------------------------------------------------------------------------------------------- | | | Legacy keystore types such as JKS and JCEKS are supported but are not secure. Consider using the PKCS#12 keystore type. | This Secret store can only manage secrets of the [CryptoKey](../security-guide/keys.html#secret-types) type. The secrets provider queries the KeyStoreSecretStore for a named secret, identified by a secret ID and a stable ID, corresponding to the `secret-id`/`aliases` mapping. The KeyStoreSecretStore returns a secret that exactly matches the name, and whose purpose matches the secret ID and any purpose constraints. The secrets provider builds the secret, checking that the secret's constraints are met, and returns a unique secret. If the secret's constraints are not met, the secrets provider cannot build the secret and the secret query fails. For a description of how secrets are managed, refer to [About secrets](../security-guide/keys.html#about-secrets) ### Usage ```json { "name": string, "type": "KeyStoreSecretStore", "config": { "file": configuration expression, "storeType": configuration expression, "storePasswordSecretId": configuration expression, "entryPasswordSecretId": configuration expression, "secretsProvider": SecretsProvider reference, "mappings": [ object, ... ], "leaseExpiry": configuration expression, "autoRefresh": object, "storePassword": configuration expression, //deprecated "keyEntryPassword": configuration expression //deprecated } } ``` ### Properties * `"file"`: *configuration expression<[string](preface.html#definition-string)>, required* The path to the KeyStore file. * `"storeType"`: *configuration expression<[string](preface.html#definition-string)>, optional* The secret store type. Default: PKCS12 * `"storePasswordSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* The secret ID of the password to access the KeyStore. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). IG searches for the value of the password until it finds it, first locally, then in parent routes, then in `config.json`. To create a store password, add a file containing the password. The filename must corresponds to the secret ID, and the file content must contain only the password, with no trailing spaces or carriage returns. Default: None; the KeyStore is not password-protected * `"entryPasswordSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* The secret ID of the password to access entries in the KeyStore. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). To create an entry password, add a file containing the password. The filename must correspond to the secret ID, and the file content must contain only the password, with no trailing spaces or carriage returns. When this property is used, the password must be the same for all entries in the KeyStore. If the KeyStore uses different passwords for entries, `entryPasswordSecretId` doesn't work. Default: The value of `storePasswordSecretId` * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The SecretsProvider object to query for the keystore password and key entry password. For more information, see [SecretsProvider](#SecretsProvider). Default: The route's default secret service. For more information, see [Default secrets object](#default-secrets-object). - `"mappings"`: *array of [objects](preface.html#definition-object), required* One or more mappings of one secret ID to one or more aliases. ```json "mappings" : { "secretId": configuration expression, "aliases": array of configuration expression, //use aliases or "aliasesMatching": [ string, ... ] //aliasesMatching but not both } ``` * `"secretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The secret ID of the key. * `"aliases"`: *array of configuration expression<[strings](preface.html#definition-string)>, required if `aliasesMatching` is not used* One or more key aliases. Named aliases are mapped to the secret ID. Use `aliases` or `aliasesMatching` but not both. * `"aliasesMatching"`: *array of <[strings](preface.html#definition-string)>, required if `aliases` is not used* One or more regular expressions to match key aliases. Aliases that match the expressions are mapped to the secret ID. Use `aliases` or `aliasesMatching` but not both. Some KeyStores, such as a global Java TrustStore, can contain hundreds of valid certificates. Use this property to map multiple aliases to a secret ID without listing them all in the mapping. The secret store uses the mappings as follows: * When the secret is used to create signatures or encrypt values, the secret store uses the *active secret*, the first alias in the list. * When the secret is used to verify signatures or decrypt data, the secret store tries all of the mapped aliases in the list, starting with the first, and stopping when it finds a secret that can successfully verify signature or decrypt the data. The following example maps the named aliases to the named secret IDs: ```json "mappings": [ { "secretId": "id.key.for.signing.jwt", "aliases": [ "signingkeyalias", "anothersigningkeyalias" ] }, { "secretId": "id.key.for.encrypting.jwt", "aliases": ["encryptionkeyalias"] } ] ``` The following example maps aliases that match the regular expression `.*` to the named secret ID: ```json "mappings": [ { "secretId": "id.key.for.signing.jwt", "aliasesMatching": [".*"] } ] ``` * `secretId`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The ID of the secret used in your configuration. * `aliases`: *array of configuration expression<[strings](preface.html#definition-string)>, required* One or more aliases for the secret ID. :leveloffset: +2 - `"leaseExpiry"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The amount of time that secrets produced by this store can be cached before they must be refreshed. If the duration is `zero` or `unlimited`, IG issues a warning, and uses the default value. Default: 5 minutes * `"autoRefresh"`: *[object](preface.html#definition-object), optional* Automatically reload the KeystoreSecretStore when the keystore is edited or deleted. ```json { "enabled": configuration expression, "executor": ScheduledExecutorService reference } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Flag to enable or disable automatic reload: * `true`: Enable * `false`: Disable Default: `true` * `"executor"`: *ScheduledExecutorService [reference](preface.html#definition-reference), optional* A [ScheduledExecutorService](MiscellaneousConfigurationObjects.html#ScheduledExecutorService) to monitor the keystore. Default: The default ScheduledExecutorService in the heap * `"storePassword"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated. If the KeyStore is password-protected, use `storePasswordSecretId`. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The secret ID of the password to access the KeyStore. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). IG searches for the value of the password until it finds it, first locally, then in parent routes, then in `config.json`. To create a store password, add a file containing the password. The filename must corresponds to the secret ID, and the file content must contain only the password, with no trailing spaces or carriage returns. * `"keyEntryPassword"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This property is deprecated; use the `entryPasswordSecretId` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The secret ID of the password to access entries in the KeyStore. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). To create an entry password, add a file containing the password. The filename must correspond to the secret ID, and the file content must contain only the password, with no trailing spaces or carriage returns. When this property is used, the password must be the same for all entries in the keystore. If the keystore uses different passwords for entries, `keyEntryPassword` doesn't work. Default: The value of `storePassword` ### Log level To facilitate debugging secrets for the KeyStoreSecretStore, in `logback.xml` add a logger defined by the fully qualified package name of the KeyStoreSecretStore. The following line in `logback.xml` sets the log level to `ALL`: ```xml ``` ### Example For examples of routes that use KeyStoreSecretStore, see the examples in [JwtBuilderFilter](Filters.html#JwtBuilderFilter). In the following example, a StatelessAccessTokenResolver validates a signed access token by using a KeyStoreSecretStore: ```json "accessTokenResolver": { "type": "StatelessAccessTokenResolver", "config": { "secretsProvider": { "type": "KeyStoreSecretStore", "config": { "file": "IG_keystore.p12", "storeType": "PKCS12", "storePasswordSecretId": "keystore.secret.id", "entryPasswordSecretId": "keystore.secret.id", "mappings": [{ "secretId": "verification.secret.id", "aliases": [ "verification.key.1", "verification.key.2" ] }] }, "issuer": "http://am.example.com:8088/openam/oauth2", "verificationSecretId": "verification.secret.id" } } } ``` The JWT signature is validated as follows: * If the JWT contains a `kid` with a mapped value, for example `verification.key.1`: * The secrets provider queries the KeyStoreSecretStore for a named secret with the secret ID `verification.secret.id` and the stable ID `verification.key.1`. * Because the KeyStoreSecretStore contains that mapping, the KeyStoreSecretStore returns a named secret. * The StatelessAccessTokenResolver tries to validate the JWT signature with the named secret. If it fails, the token is considered as invalid. * If the JWT contains a `kid` with an unmapped value, for example, `verification.key.3`: * The secrets provider queries the KeyStoreSecretStore for a named secret with the secret ID `verification.secret.id` and the stable ID `verification.key.3`. * Because the KeyStoreSecretStore doesn't contain that mapping, named secret resolution fails. IG tries valid secret resolution in the same way as when the JWT doesn't contain a `kid`. * If the JWT doesn't contain a `kid`: * The secrets provider queries the KeyStoreSecretStore for all valid secrets, whose alias is mapped to the secret ID `verification.secret.id`. There are two valid secrets, with aliases `verification.key.1` and `verification.key.2`. * The StatelessAccessTokenResolver first tries to verify the signature with `verification.key.1`. If that fails, it tries `verification.key.2`. * If neither of the valid secrets can verify the signature, the token is considered as invalid. ### More information [org.forgerock.secrets.keystore.KeyStoreSecretStore](../_attachments/apidocs/org/forgerock/secrets/keystore/KeyStoreSecretStore.html) [org.forgerock.openig.secrets.KeyStoreSecretStoreHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/KeyStoreSecretStoreHeaplet.html) ## PemPropertyFormat The format of a secret used with a mappings configuration in FileSystemSecretStore and SystemAndEnvSecretStore. Privacy-Enhanced Mail (PEM) is a file format for storing and sending cryptographic keys, certificates, and other data, based on standards in [Textual Encodings of PKIX, PKCS, and CMS Structures](https://www.rfc-editor.org/rfc/rfc7468). By default, OpenSSL generates keys using the PEM format. Encryption methods and ciphers used for PEM encryption must be supported by the Java Cryptography Extension. PEM keys have the following format, where the PEM label is associated to the type of stored cryptographic material: ```none -----BEGIN {PEM label}----- Base64-encoded cryptographic material -----END {PEM label}----- ``` | PEM Label | Stored Cryptographic Material | | ----------------------- | ------------------------------------------ | | `CERTIFICATE` | X.509 Certificate | | `PUBLIC KEY` | X.509 SubjectPublicKeyInfo | | `PRIVATE KEY` | PKCS#8 Private Key | | `ENCRYPTED PRIVATE KEY` | Encrypted PKCS#8 Private Key | | `EC PRIVATE KEY` | EC Private Key | | `RSA PRIVATE KEY` | PKCS#1 RSA Private Key | | `RSA PUBLIC KEY` | PKCS#1 RSA Public Keys | | `DSA PRIVATE KEY` | PKCS#1-style DSA Private Key | | `HMAC SECRET KEY` | HMAC Secret Keys | | `AES SECRET KEY` | AES Secret Keys | | `GENERIC SECRET` | Generic Secrets (passwords, API keys, etc) | Note the following points about the key formats: * PKCS#1 is the standard that defines RSA. For more information, refer to [RFC 8017: RSA Public Key Syntax](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.1.1). * PKCS#1-style DSA and EC keys are not defined in any standard, but are adapted from the RSA format. * `HMAC SECRET KEY`, `AES SECRET KEY`, and `GENERIC SECRET` are a ForgeRock extension, and not currently supported by any other tools. The following example is non-standard PEM encoding of an HMAC symmetric secret key. The payload is base64-encoded random bytes that are the key material, with no extra encoding. ```none -----BEGIN HMAC SECRET KEY----- Pj/Vel...thB0U= -----END HMAC SECRET KEY----- ``` Run the following example command to create the key: ```bash cat <, "secretsProvider": SecretsProvider reference } } ``` ### Properties * `"decryptionSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* The secret ID for the secret to decrypt a PKCS#8 private key. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required when `decryptionSecretId` is used* The SecretsProvider object to query for the decryption secret. For more information, see [SecretsProvider](#SecretsProvider). ### Example For examples of use, see [Pass runtime data in a JWT signed with a PEM](../gateway-guide/data-downstream.html#runtime-signed-pem-example) and [Pass runtime data in a JWT signed and encrypted with a PEM](../gateway-guide/data-downstream.html#runtime-encrypted-pem-example). ### More information [org.forgerock.openig.secrets.PemPropertyFormatHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/PemPropertyFormatHeaplet.html) ## SecretsKeyManager Uses the Commons Secrets API to manage keys that authenticate a TLS connection to a peer. The configuration references the keystore that holds the keys. ### Usage ```json { "name": string, "type": "SecretsKeyManager", "config": { "signingSecretId": configuration expression, "secretsProvider": SecretsProvider reference } } ``` ### Properties * `"signingSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The secret ID used to retrieve private signing keys. This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required* The SecretsProvider to query for secrets to resolve the private signing key. For more information, see [SecretsProvider](#SecretsProvider). ### Example The following example uses a private key found from a keystore for TLS handshake. ```json { "type": "SecretsKeyManager", "config": { "signingSecretId": "key.manager.secret.id", "secretsProvider": { "type": "KeyStoreSecretStore", "config": { "file": "path/to/certs/ig.example.com.p12", "storePasswordSecretId": "keystore.pass", "secretsProvider": "SecretsPasswords", "mappings": [{ "secretId": "key.manager.secret.id", "aliases": [ "ig.example.com" ] }] } } } } ``` ### More information [Secrets](#) [org.forgerock.openig.secrets.SecretsKeyManagerHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/SecretsKeyManagerHeaplet.html) ## SecretKeyPropertyFormat The format of a secret used with a secret store. ### Usage ```json { "name": string, "type": "SecretKeyPropertyFormat", "config": { "format": SecretPropertyFormat reference, "algorithm": configuration expression } } ``` ### Properties * `format`: *SecretPropertyFormat [reference](preface.html#definition-reference), optional* Format in which the secret is stored. Use one of the following values, or define a format: * `BASE64`: Base64-encoded * `PLAIN`: Plain text Default: `BASE64` * `"algorithm"`: *configuration expression<[string](preface.html#definition-string)>, required* The algorithm name used for encryption and decryption. Use algorithm names given in [Java Security Standard Algorithm Names](https://docs.oracle.com/en/java/javase/11/docs/specs/security/standard-names.html#algorithmparameters-algorithms). ### Example ```json { "type": "SecretKeyPropertyFormat", "config": { "format": "PLAIN", "algorithm": "AES" } } ``` ### More information [Secrets](#) [org.forgerock.openig.secrets.SecretKeyPropertyFormatHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/SecretKeyPropertyFormatHeaplet.html) ## SecretsProvider Uses the specified secret stores to resolve queried secrets, such as passwords and cryptographic keys. Attempts to resolve the secret with the secret stores in the order that they are declared in the array. ### Usage ```json { "name": string, "type": "SecretsProvider", "config": { "stores": [ SecretStore reference, ... ] } } ``` This object can alternatively be configured in a compact format, without the SecretsProvider declaration, as follows: * With an inline secret store: ```json "secretsProvider": { "type": "secret store type1", "config": {...} } ``` * With multiple inline secret stores: ```json "secretsProvider": [ { "type": "secret store type1", "config": {...} } { "type": "secret store type2", "config": {...} } ] ``` * With a referenced secret store: ```json "secretsProvider": "mySecretStore1" ``` * With multiple referenced secret stores: ```json "secretsProvider": [ "mySecretStore1", "mySecretStore2" ] ``` See [Example](MiscellaneousConfigurationObjects.html#SecretsProvider-example) for more example configurations. ### Properties * `"stores"`: *array of SecretStore [references](preface.html#definition-reference), required* One or more secret stores to provide access to stored secrets. Configure secret stores described in [Secrets](#). ### Example The following SecretsProvider is used in [Discover and dynamically register with OpenID connect providers](../gateway-guide/oidc.html#oidc-discovery). ```json "secretsProvider": { "type": "SecretsProvider", "config": { "stores": [ { "type": "KeyStoreSecretStore", "config": { "file": "/path/to/keystore.p12", "mappings": [ { "aliases": [ "myprivatekeyalias" ], "secretId": "private.key.jwt.signing.key" } ], "storePasswordSecretId": "keystore.secret.id", "storeType": "PKCS12", "secretsProvider": "SystemAndEnvSecretStore-1" } } ] } } ``` The following example shows the equivalent SecretsProvider configuration with an inline compact format: ```json "secretsProvider": { "name": "KeyStoreSecretStore-1", "type": "KeyStoreSecretStore", "config": { "file": "/path/to/keystore.p12", "mappings": [ { "aliases": [ "myprivatekeyalias" ], "secretId": "private.key.jwt.signing.key" } ], "storePasswordSecretId": "keystore.secret.id", "storeType": "PKCS12" } } ``` The following example shows the equivalent SecretsProvider configuration with a compact format, referencing a KeyStoreSecretStore object in the heap: ```json "secretsProvider": "KeyStoreSecretStore-1" ``` ### More information [StatelessAccessTokenResolver](AccessTokenResolvers.html#StatelessAccessTokenResolver) [Secrets](#) [org.forgerock.secrets.SecretsProvider](../_attachments/apidocs/org/forgerock/secrets/SecretsProvider.html) ## SecretsTrustManager Uses the Commons Secrets API to manage trust material that verifies the credentials presented by a peer. Trust material is usually public key certificates. The configuration references the secrets store that holds the trust material. ### Usage ```json { "name": string, "type": "SecretsTrustManager", "config": { "verificationSecretId": configuration expression, "certificateVerificationSecretId": configuration expression, "secretsProvider": SecretsProvider reference, "checkRevocation": configuration expression } } ``` ### Properties * `"verificationSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required if certificateVerificationSecretId isn't used* Either `verificationSecretId` or `certificateVerificationSecretId` is required. The secret ID to retrieve trusted certificates. This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). Consider the following requirements for using certificates with `verificationSecretId`: * Certificates loaded from keystores can be used with the following constraint: * The KeyUsage extension `digitalSignature` must be set **or** no KeyUsage extension must be set * Certificates loaded from JWKs or JWK sets can be used with the following constraints: * The `use` parameter must be set to `sig` **or** the `use` parameter must not be set * The `key_ops` parameter must contain `verify` **or** the `key_ops` parameter must not be set * Certificates loaded from PEM can be used without constraint. * `"certificateVerificationSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required if verificationSecretId isn't used* Either `verificationSecretId` or `certificateVerificationSecretId` is required. The secret ID to retrieve certificates for trusted certificate authorities (CA). Use this property when you trust client certificates **only because** they are signed by a trusted CA. Consider the following requirements: * Certificates loaded from keystores can be used with the following constraint: * The KeyUsage extension `keyCertSign` must be set **or** no KeyUsage extension must be set * Certificates loaded from JWKs or JWK sets can be used with the following constraints: * The `use` parameter must not be set * The `key_ops` parameter must not be set * Certificates loaded from PEM can be used without constraint. * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required* The SecretsProvider to query for secrets to resolve trusted certificates. For more information, refer to [SecretsProvider](#SecretsProvider). * `"checkRevocation"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Specifies whether to check for certificate revocation. Default: `true` ### Example The following example trusts a list of certificates found in a given keystore: ```json { "name": "SecretsTrustManager-1", "type": "SecretsTrustManager", "config": { "verificationSecretId": "trust.manager.secret.id", "secretsProvider": { "type": "KeyStoreSecretStore", "config": { "file": "path/to/certs/truststore.p12", "storePasswordSecretId": "keystore.pass", "secretsProvider": "SecretsPasswords", "mappings": [{ "secretId": "trust.manager.secret.id", "aliases": [ "alias-of-trusted-cert-1", "alias-of-trusted-cert-2" ] }] } } } } ``` The following example trusts a list of CA-signed certificates found in a given keystore: ```json { "type": "SecretsTrustManager", "config": { "certificateVerificationSecretId": [ "ca.secret.id" ], "secretsProvider": { "type": "KeyStoreSecretStore", "config": { "file": "&{ig.instance.dir}/certs/truststore.p12", "storePassword": "keystore.pass", "secretsProvider": "SecretsPasswords", "mappings": [{ "secretId": "ca.secret.id", "aliases": [ "alias-of-trusted-cacert-1", "alias-of-trusted-cacert-2" ] }] } } } } ``` ### More information [Secrets](#) [org.forgerock.openig.secrets.SecretsTrustManagerHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/SecretsTrustManagerHeaplet.html) ## SystemAndEnvSecretStore Manage a store of secrets from system properties and environment variables. This secret store can manage GenericSecret and CryptoKey [secret types](../security-guide/keys.html#secret-types) when used with dedicated formats. A secret ID must conform to the convention described in [secret-id](preface.html#definition-secretid). The reference is then transformed to match the environment variable name, as follows: * Periods (.) are converted to underscores. * Characters are transformed to uppercase. For example, `my.secret.id` is transformed to `MY_SECRET_ID`. The secrets provider queries the SystemAndEnvSecretStore for a named secret, identified by the name of a system property or environment variable. The SystemAndEnvSecretStore returns a secret that exactly matches the name. The secrets provider builds the secret, checking that the secret's constraints are met, and returns a unique secret. If the secret's constraints are not met, the secrets provider cannot build the secret and the secret query fails. For a description of how secrets are managed, refer to [About secrets](../security-guide/keys.html#about-secrets) ### Usage ```json { "name": string, "type": "SystemAndEnvSecretStore", "config": { "format": SecretPropertyFormat reference, "mappings": [ object, ... ], "leaseExpiry": configuration expression } } ``` ### Properties * `format`: *SecretPropertyFormat [reference](preface.html#definition-reference), optional* Format in which the secret is stored. Use one of the following values, or define a format: * `BASE64`: Base64-encoded * `PLAIN`: Plain text Default: `BASE64` - `"mappings"`: *array of [objects](preface.html#definition-object), optional* One or more mappings to define a secret: * `secretId`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The ID of the secret used in your configuration. * `format`: *SecretPropertyFormat [reference](preface.html#definition-reference), required* The format and algorithm of the secret. Use [SecretKeyPropertyFormat](SecretKeyPropertyFormat.html) or [PemPropertyFormat](PemPropertyFormat.html). * `"leaseExpiry"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The amount of time that secrets produced by this store can be cached before they must be refreshed. If the duration is `zero` or `unlimited`, IG issues a warning, and uses the default value. Default: 5 minutes ### Log level To facilitate debugging secrets for the SystemAndEnvSecretStore, in `logback.xml` add a logger defined by the fully qualified package name of the property resolver. The following line in `logback.xml` sets the log level to `ALL`: ```xml ``` ### Example For an example of how to uses a SystemAndEnvSecretStore to manage a password, refer to the example in [Authenticate with SSO through the default authentication service](../gateway-guide/sso-cdsso.html#proc-sso) ### More information [Secrets](#) [org.forgerock.openig.secrets.SystemAndEnvSecretStoreHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/SystemAndEnvSecretStoreHeaplet.html) ## TrustManager (deprecated) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This object is deprecated; use [SecretsTrustManager](SecretsTrustManager.html) instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The configuration of a Java Secure Socket Extension [TrustManager](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/javax/net/ssl/TrustManager.html) to manage trust material (typically X.509 public key certificates) for IG. The configuration references the keystore that holds the trust material. When IG acts as a client, it uses a trust manager to verify that the server is trusted. When IG acts as a server, it uses a trust manager to verify that the client is trusted. ### Usage ```json { "name": string, "type": "TrustManager", "config": { "keystore": KeyStore reference, "alg": configuration expression } } ``` ### Properties * `"keystore"`: *KeyStore [reference](preface.html#definition-reference), required* The [KeyStore (deprecated)](KeyStore.html) object that references the store for key certificates. When `keystore` is used in a KeyManager, it queries for private keys; when `keystore` is used in a TrustManager, it queries for certificates. Provide either the name of the keystore object defined in the heap or an inline keystore configuration object. * `"alg"`: *configuration expression<[string](preface.html#definition-string)>, optional* The certificate algorithm to use. Default: the default for the platform, such as `SunX509`. ### Example The following example configures a trust manager that depends on a KeyStore configuration. This configuration uses the default certificate algorithm: ```json { "name": "MyTrustManager", "type": "TrustManager", "config": { "keystore": { "type": "KeyStore", "config": { "url": "file://${env['HOME']}/keystore.p12", "passwordSecretId": "${system['keypass']}", "secretsProvider": "SystemAndEnvSecretStore" } } } } ``` ### More information [org.forgerock.openig.security.TrustManagerHeaplet](../_attachments/apidocs/org/forgerock/openig/security/TrustManagerHeaplet.html) [JSSE reference guide ](https://docs.oracle.com/en/java/javase/17/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-93DEEE16-0B70-40E5-BBE7-55C3FD432345), [KeyManager](KeyManager.html), [KeyStore](KeyStore.html) ## Default secrets object (deprecated) | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This object is deprecated; use [SecretsProvider](SecretsProvider.html) instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | IG automatically creates a secrets object in each route in the configuration, and in `config.json` and `admin.json`. When the secrets object is not used to declare a secrets store in the configuration, IG creates a default [SystemAndEnvSecretStore](#SystemAndEnvSecretStore) in the local secrets service. When the secrets object is used to declare a secrets store, the default is not installed in the local secrets service. ### Usage ```json { "secrets": { "stores": [ SecretStore reference, ... ] } } ``` ### Properties * `"stores"`: *array of SecretStore [references](preface.html#definition-reference), required* One or more of the following secret stores: * [Base64EncodedSecretStore](#Base64EncodedSecretStore) * [FileSystemSecretStore](#FileSystemSecretStore) * [HsmSecretStore](#HsmSecretStore) * [JwkSetSecretStore](#JwkSetSecretStore) * [KeyStoreSecretStore](#KeyStoreSecretStore) * [SystemAndEnvSecretStore](#SystemAndEnvSecretStore) ### Example The following example configures two secret stores: ```json { "secrets": { "stores": [ { "type": "FileSystemSecretStore", "config": { "directory": "/path/to/secrets", "format": "BASE64" } }, { "type": "SystemAndEnvSecretStore", "config": { "format": "PLAIN" } } ] } } ```