--- title: FileSystemSecretStore description: Manage a store of secrets held in files, specified as follows: component: pinggateway version: 2026 page_id: pinggateway:reference:FileSystemSecretStore canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/FileSystemSecretStore.html revdate: 2025-06-02T18:01:47Z section_ids: FileSystemSecretStore-usage: Usage FileSystemSecretStore-properties: Properties FileSystemSecretStore-log: Log level FileSystemSecretStore-example: Examples FileSystemSecretStore-moreinfo: More information --- # 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 aren't met, the secrets provider cannot build the secret and the secret query fails. Learn how PingGateway manages secrets in [About secrets](../security-guide/keys.html#about-secrets). ## Usage ```json { "name": string, "type": "FileSystemSecretStore", "config": { "directory": configuration expression, "format": SecretPropertyFormat reference, "versionSuffix": configuration expression, "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. The original secret prior to base64-encoding must use UTF-8 encoding. * `PLAIN`: Plain text. The file must use UTF-8 encoding. * A [JwkPropertyFormat](JwkPropertyFormat.html). * A [PemPropertyFormat](PemPropertyFormat.html). * A [SecretKeyPropertyFormat](SecretKeyPropertyFormat.html). Default: `BASE64` * `"versionSuffix"`: *configuration expression<[string](preface.html#definition-string)>, optional* A version suffix, such as `.v`, not including any version numbers. For details, refer to [the examples that follow](#FileSystemSecretStore-example). Default: None * `"suffix"`: *configuration expression<[string](preface.html#definition-string)>, optional* A file suffix or extension, such as `.secret`. For details, refer to [the examples that follow](#FileSystemSecretStore-example). 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`, PingGateway 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 in the directory given by `directory`. When `autoRefresh` is triggered, secrets and keys are refreshed even if the `leaseExpiry` has not expired. When `autoRefresh` is triggered, the `leaseExpiry` is reset. ```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](ScheduledExecutorService.html) 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 ``` ## Examples The following example FileSystemSecretStore matches `example.pem`, `example.v1.pem`, and `example.v2.pem`. The active secret file is the one with the largest version number, `mySecret.v2.pem`: ```json { "name": "FileSystemSecretStore-1", "type": "FileSystemSecretStore", "config": { "directory": "&{secretsDir}", "format": "PLAIN", "versionSuffix": ".v", "suffix": ".pem", "mappings": [ { "secretId": "example", "format": "pemPropertyFormat" } ] } } ``` Also refer to [Pass runtime data in a JWT signed with a PEM](../gateway-guide/data-downstream.html#runtime-signed-pem-example). ## More information [Secrets](secrets.html) [org.forgerock.openig.secrets.FileSystemSecretStoreHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/FileSystemSecretStoreHeaplet.html)