---
title: Filesystem secret stores
description: A filesystem secret store maps to a directory storing an arbitrary number of files that each contain one secret. When filesystem secret stores are used, IDM reads the contents of a file with a name matching the secretId field in the secret store's mapping list.
component: pingidm
version: 8.1
page_id: pingidm:security-guide:secret-stores-filesystem
canonical_url: https://docs.pingidentity.com/pingidm/8.1/security-guide/secret-stores-filesystem.html
section_ids:
  fs-automatic-encryption: Configuring automatic encryption
  fs-create-new-user-example: "Example: Create a new user type"
  fs-configure-purpose-versions: Configuring purpose versions
---

# Filesystem secret stores

A filesystem secret store maps to a directory storing an arbitrary number of files that each contain one secret. When filesystem secret stores are used, IDM reads the contents of a file with a name matching the `secretId` field in the secret store's mapping list.

Filesystem secret stores are useful to provide secrets from third-party secret stores like AWS Secrets Manager or Google Secrets Manager. They can also be used to separate your secrets from your configuration files.

Filesystem secret stores can be encoded with the following encoding schemes:

* PLAIN

* PEM

* BASE64

* BASE64URL

The following configuration is an example of a filesystem secret store which is configured to use the `/secrets` directory and contains a mapping for the `idm.admin.password` secret:

```json
{
    "name":"secretVolume",
    "class": "org.forgerock.openidm.secrets.config.FileSystemStore",
    "config": {
        "format": "PLAIN",
        "directory": "&{idm.install.dir}/secrets",
        "mappings": [
          {
            "secretId": "idm.admin.password",
            "types": [
              "GENERIC"
            ]
          }
        ]
    }
}
```

## Configuring automatic encryption

You can add automatic encryption to the filesystem secret store by adding the `encryptionKey` field. The following example demonstrates encrypting the `idm.admin.password` secret with the `idm.default` encryption key:

```json
{
    "name": "fileSystemStore",
    "class": "org.forgerock.openidm.secrets.config.FileSystemStore",
    "config": {
        "directory": "&{idm.install.dir}/secrets",
        "format": "PLAIN",
        "encryptionKey": "idm.default",
        "mappings": [
            {
                "secretId": "idm.admin.password",
                "types": [
                    "GENERIC"
                ]
            }
        ]
    }
}
```

By default, IDM uses `AES Key Wrap with a 128-bit key` for JSON Web Token (JWT) key management and `AES_128_CBC_HMAC_SHA_256` for content encryption. These can be configured by setting the `encryptionAlgorithm` and `encryptionMethod` fields on the store configuration respectively.

## Example: Create a new user type

The following example creates a new type of static user, `openidm-super`, with the secret, `idm.admin.password`, kept in the filesystem secret store. To configure the user:

1. In `conf/authentication.json`, add the following new user configuration:

   ```json
   {
       "name": "STATIC_USER",
       "properties": {
           "queryOnResource": "internal/user",
           "username": "openidm-super",
           "password": {
               "$purpose": {
                   "name": "idm.admin.password"
               }
           },
           "defaultUserRoles": [
               "internal/role/openidm-authorized",
               "internal/role/openidm-admin"
           ],
           "enabled": true
       }
   }
   ```

2. In `conf/secrets.json`, use the existing mapping for the `idm.admin.password` secret and optionally add the `format` parameter:

   ```json
   {
       "secretId": "idm.admin.password",
       "format": "PLAIN",
       "types": [
           "GENERIC"
       ]
   }
   ```

   |   |                                                                                                                                |
   | - | ------------------------------------------------------------------------------------------------------------------------------ |
   |   | Only use the optional `format` parameter if the secret is encoded using a different scheme than the rest of the secret volume. |

## Configuring purpose versions

The filesystem secret store supports multiple versions of the same purpose. To configure this, specify the `versionSuffix` property in the store's definition in `conf/secrets.json`. The following example adds the `.v` suffix to the `idm.admin.password` purpose:

```json
{
  "name": "pemStore",
  "class": "org.forgerock.openidm.secrets.config.FileSystemStore",
  "config": {
    "format": "PEM",
    "directory": "&{idm.install.dir}/secrets",
    "versionSuffix": ".v",
    "mappings": [
      {
        "secretId": "idm.admin.password",
        "types": [
          "GENERIC"
        ]
      }
    ]
  }
}
```

After `versionSuffix` is defined, you can version your purpose files by adding it to the file name. Following the previous example, the files could be named `idm.admin.password.v1`, `idm.admin.password.v2`, and so on. The latest version number is the active secret.