IG 7.1.2

Secrets

IG uses the ForgeRock Commons Secrets Service to manage secrets, such as passwords and cryptographic keys.

For more information about how IG manages secrets, see Secrets.

Default Secrets Object

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

{
  "secrets": {
    "stores": [ inline secret store declaration, ... ]
  }
}

Properties

"stores": array of secret store declarations, required

One or more inline declarations of the following secret stores:

Example

The following example configures two secret stores:

{
  "secrets": {
    "stores": [
       {
        "type": "FileSystemSecretStore",
        "config": {
          "directory": "/path/to/secrets",
          "format": "BASE64"
        }
      },
      {
        "type": "SystemAndEnvSecretStore",
        "config": {
          "format": "PLAIN"
        }
      }
    ]
  }
}

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.

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, see About Secrets.

Usage

{
  "name": string,
  "type": "Base64EncodedSecretStore",
  "config": {
    "secrets": map
  }
}

Properties

"secrets": map, required

A list of one or more secret ID/string pairs:

{
  "secrets": {
    "secret-id": "string",
    ...
  }
}

Each pair has the form "secret-id": "string", where:

  • secret-id is the ID of a secret used in a route

  • string is the base64-encoded value of the secret

In the following example, Base64EncodedSecretStore configures two base64-encoded secrets:

{
  "type": "Base64EncodedSecretStore",
  "config": {
    "secrets": {
      "agent.password": "d2VsY29tZQ==",
      "crypto.header.key": "Y2hhbmdlaXQ="
    }
  }
}

In the following example, the values of the secrets are provided by a configuration token and a configuration expression, whose values are substituted when the route is loaded:

{
  "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:

<logger name="org.forgerock.openig.secrets.Base64EncodedSecretStore" level="ALL">

Example

In the following example, an AmService acts on behalf of IG to authenticate with AM. IG uses the Base64EncodedSecretStore to retrieve the password for the AmService.

Retrieve a Secret From a Route

Before you start:

  • Prepare IG as described in the Getting Started.

  • Install and configure AM on http://openam.example.com:8088/openam, with the default configuration.

    1. Set up AM

      1. (From AM 6.5.x) Select Identities > demo, and set the demo user password to Ch4ng31t.

      2. (For AM 6.5.3 and later versions) Select Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources :

        • http://openig.example.com:8080/*

        • http://openig.example.com:8080/*?*

      3. Select Applications > Agents > Identity Gateway, add an agent with the following values:

    2. Set up IG:

      1. Add the following route to IG, to serve .css and other static resources for the sample application:

        • Linux

        • Windows

        $HOME/.openig/config/routes/static-resources.json
        appdata\OpenIG\config\routes\static-resources.json
        {
  "name" : "sampleapp-resources",
  "baseURI" : "http://app.example.com:8081",
  "condition": "${find(request.uri.path,'^/css')}",
  "handler": "ReverseProxyHandler"
}

      2. Add the following route to IG:

        • Linux

        • Windows

        $HOME/.openig/config/routes/base64encodedsecret.json
        appdata\OpenIG\config\routes\base64encodedsecret.json
        {
  "heap": [
    {
      "name": "Base64EncodedSecretStore-1",
      "type": "Base64EncodedSecretStore",
      "config":  {
        "secrets": {
          "agent.secret.id": "cGFzc3dvcmQ="
        }
      }
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "http://openam.example.com:8088/openam",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "Base64EncodedSecretStore-1",
        "version": "7.1",
        "notifications": {
          "enabled": true
        }
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "SingleSignOnFilter",
          "config": {
            "amService": "AmService-1"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  },
  "condition": "${find(request.uri.path, '/home/base64encodedsecret')}",
  "baseURI": "http://app.example.com:8081"
}

        Notice the following features of the route:

        • The route matches requests to /home/base64encodedsecret.

        • The agent password for AmService is provided by the Base64EncodedSecretStore in the heap.

        • The SingleSignOnFilter manages redirects to AM for authentication, using the IG agent in AmService-1.

    3. Test the setup:

      1. If you are logged in to AM, log out and clear any cookies.

      2. Go to http://openig.example.com:8080/home/base64encodedsecret.

        The SingleSignOnFilter redirects the request to AM for authentication.

      3. Log in to AM as user demo, password Ch4ng31t.

        When you have authenticated, the SingleSignOnFilter passes the request to the sample app, which returns the profile page.

More Information

Secrets

org.forgerock.openig.secrets.Base64EncodedSecretStore

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.

Secrets are read lazily from the filesystem.

For a description of how secrets are managed, see About Secrets.

Usage

{
  "name": string,
  "type": "FileSystemSecretStore",
  "config": {
    "directory": configuration expression<string>,
    "format": configuration expression<enumeration>,
    "suffix": configuration expression<string>,
    "mappings": [ configuration object, ... ],
    "leaseExpiry": configuration expression<duration>
  }
}

Properties

"directory": configuration expression<string>, required

File path to a directory containing secret files. This object checks the specified directory, but not its subdirectories.

"format": configuration expression<enumeration>, optional

Format in which the secret is stored. Use one of the following values:

  • BASE64: Base64-encoded

  • PLAIN: Plain text

Default: BASE64

"suffix": configuration expression<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, optional

One or more mappings to define a secret:

secretId: configuration expression<secret-id>, required

The ID of the secret used in your configuration.

format: SecretPropertyFormat reference, required

The format and algorithm of the secret. Use SecretKeyPropertyFormat or PemPropertyFormat.

"leaseExpiry": configuration expression<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 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:

<logger name="org.forgerock.secrets.propertyresolver" level="ALL">

Example

The example in Pass Runtime Data in a JWT Signed With a PEM uses a FileSystemSecretStore to manage a private key as PEM file. The PEM file is generated in the directory /path/to/secrets, with the filename id.key.for.signing.jwt. The properties of the FileSystemSecretStore in the route refer to the PEM file.

More Information

Secrets

org.forgerock.openig.secrets.FileSystemSecretStoreHeaplet

HsmSecretStore

Manage a store of secrets with a hardware security module (HSM) device or a software emulation of an HSM device, such as SoftHSM.

For a description of how secrets are managed, see About Secrets.

Usage

{
  "name": string,
  "type": "HsmSecretStore",
  "config": {
    "providerName": configuration expression<string>,
    "storePassword": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference,
    "mappings": [ configuration object, ... ],
    "leaseExpiry": configuration expression<duration>
   }
}

Properties

"providerName": configuration expression<enumeration>, 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:

"providerName": "SunPKCS11-FooAccelerator"
"storePassword": configuration expression<secret-id>, required

The secret ID of the password to access the HsmSecretStore.

For information about how IG manages secrets, see Secrets.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the storePassword. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, see Default Secrets Object.

"mappings": array of objects, required

One or more mappings of one secret ID to one or more aliases. 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 a secret ID to two aliases:

"mappings": [
  {
    "secretId": "global.pcookie.crypt",
    "aliases": [ "rsapair72-1", "rsapair72-2" ]
  }
]
secretId: configuration expression<secret-id>, required

The ID of the secret used in your configuration.

aliases: array of configuration expression<string>, required

One or more aliases for the secret ID.

"leaseExpiry": configuration expression<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 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:

<logger name="org.forgerock.secrets.keystore" level="ALL">

Example

To set up this example:

  1. Set up and test the example in 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:

    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.

  4. Depending on your version of Java, create a java.security.ext file for the IG instance, with the following content:

    security.provider.<number>=<provider-name> <path-to-provider-cfg-file>

    or

    security.provider.<number>=<class-name> <path-to-provider-cfg-file>

  5. Start the IG JVM with the following system property that points to the provider config file:

    -Djava.security.properties=file://path-to-security-extension-file

The following example route is based on the examples in JwtBuilderFilter, replacing the KeyStoreSecretStore with an HsmSecretStore:

{
  "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://openam.example.com:8088/openam",
        "version": "7.1"
      }
    },
    {
      "name": "HsmSecretStore-1",
      "type": "HsmSecretStore",
      "config": {
        "providerName": "SunPKCS11-SoftHSM",
        "storePassword": "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

JwkSetSecretStore

Manages a secret store for JSON Web Keys (JWK) from a local or remote JWK Set.

For a description of how secrets are managed, see Secrets.

For information about JWKs and JWK Sets, see RFC-7517, JSON Web Key (JWK).

Usage

{
  "name": string,
  "type": "JwkSetSecretStore",
  "config": {
    "jwkUrl": configuration expression<url>,
    "handler": Handler reference or inline handler declaration,
    "cacheTimeout": configuration expression<duration>,
    "cacheMissCacheTime": configuration expression<duration>,
    "leaseExpiry": configuration expression<duration>
  }
}

Properties

"jwkUrl": configuration expression<url>, required

A URL that contains the client’s public keys in JWK format.

"handler": Handler 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>, 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>, 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>, 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:

<logger name="org.forgerock.secrets.jwkset" level="ALL">

Example

For an example of how to set up and use JwkSetSecretStore to validate signed access_tokens, see Validate Signed Access_Tokens With the StatelessAccessTokenResolver and JwkSetSecretStore.

More Information

org.forgerock.openig.secrets.JwkSetSecretStoreHeaplet

RFC-7517, JSON Web Key (JWK)

KeyStoreSecretStore

Manages a secret store for cryptographic keys and certificates, based on a standard Java KeyStore.

The KeyStore is typically file-based PKCS12 KeyStore. Legacy proprietary formats such as JKS and JCEKS are supported, but implement weak encryption and integrity protection mechanisms. Consider not using them for new functionality.

For a description of how secrets are managed, see About Secrets.

Usage

{
  "name": string,
  "type": "KeyStoreSecretStore",
  "config": {
    "file": configuration expression<string>,
    "storeType": configuration expression<string>,
    "storePassword": configuration expression<string>,
    "keyEntryPassword": configuration expression<string>,
    "secretsProvider": SecretsProvider reference,
    "mappings": [ configuration object, ... ],
    "leaseExpiry": configuration expression<duration>
   }
}

Properties

"file": configuration expression<string>, required

The path to the KeyStore file.

"storeType": storeType reference, optional

The secret store type.

"storePassword": configuration expression<secret-id>, required

The secret ID of the password to access the KeyStore.

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

The secret ID of the password to access entries in the KeyStore.

To create an entry 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.

When this property is used, the password must be the same for all entries in the KeyStore. If JKS uses different password for entries, keyEntryPassword doesn’t work.

Default: The value of storePassword

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the keystore password and key entry password. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, see Default Secrets Object.

"mappings": array of objects, required

One or more mappings of one secret ID to one or more aliases. 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.

    "mappings": [
  {
    "secretId": "id.key.for.signing.jwt",
    "aliases": [ "SigningKeyAlias", "AnotherSigningKeyAlias" ]
  },
  {
    "secretId": "id.key.for.encrypting.jwt",
    "aliases": ["EncryptionKeyAlias"]
  }
]
secretId: configuration expression<secret-id>, required

The ID of the secret used in your configuration.

aliases: array of configuration expression<string>, required

One or more aliases for the secret ID.

"leaseExpiry": configuration expression<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 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:

<logger name="org.forgerock.secrets.keystore" level="ALL">

Example

For examples of routes that use KeyStoreSecretStore, see the examples in JwtBuilderFilter.

More Information

org.forgerock.secrets.keystore.KeyStoreSecretStore

org.forgerock.openig.secrets.KeyStoreSecretStoreHeaplet

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 RFC 7468. 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:

-----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, see RSA Public Key Syntax.

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

    -----BEGIN HMAC SECRET KEY-----
Pj/Vel...thB0U=
-----END HMAC SECRET KEY-----

    Run the following example command to create the key:

    cat <<EOF
-----BEGIN HMAC SECRET KEY-----
$(head -c32 /dev/urandom | base64)
-----END HMAC SECRET KEY-----
EOF

Usage

{
  "name": string,
  "type": "PemPropertyFormat",
  "config": {
   "decryptionSecretId": configuration expression<secret-id>,
   "secretsProvider": SecretsProvider reference
  }
}

Properties

"decryptionSecretId": configuration expression<secret-id>, optional

The secret ID for the secret to decrypt a PKCS#8 private key.

"secretsProvider": SecretsProvider reference, required if decryptionSecretId is used

The SecretsProvider object to query for the decryption secret. For more information, see SecretsProvider.

Example

For examples of use, see Pass Runtime Data in a JWT Signed With a PEM and Pass Runtime Data in a JWT Signed and Encrypted With a PEM.

More Information

org.forgerock.openig.secrets.PemPropertyFormatHeaplet

SecretsKeyManager

Uses the Commons Secrets Service to manage keys that authenticate a TLS connection to a peer. The configuration references the keystore that holds the keys.

Usage

{
   "name": string,
   "type": "SecretsKeyManager",
   "config": {
     "signingSecretId": configuration expression<secret-id>,
     "secretsProvider": SecretsProvider reference
 }
}

Properties

"signingSecretId": configuration expression<secret-id>, required

The secret ID used to retrieve private signing keys.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider to query for secrets to resolve the private signing key. For more information, see SecretsProvider.

Example

The following example uses a private key found from a keystore for TLS handshake.

{
  "type": "SecretsKeyManager",
  "config": {
    "signingSecretId": "key.manager.secret.id",
    "secretsProvider": {
      "type": "KeyStoreSecretStore",
      "config": {
        "file": "path/to/certs/openig.example.com.p12",
        "storePassword": "keystore.pass",
        "secretsProvider": "SecretsPasswords",
        "mappings": [{
          "secretId": "key.manager.secret.id",
          "aliases": [ "openig.example.com" ]
        }]
      }
    }
  }
}

More Information

Secrets

org.forgerock.openig.secrets.SecretsKeyManagerHeaplet

SecretKeyPropertyFormat

The format of a secret used with a secret store.

Usage

{
  "name": string,
  "type": "SecretKeyPropertyFormat",
  "config": {
    "format": SecretPropertyFormat reference,
    "algorithm": configuration expression<string>
  }
}

Properties

"format": SecretPropertyFormat reference, optional

Format in which the secret is stored. Use one of the following values:

  • BASE64: Base64-encoded

  • PLAIN: Plain text

Default: BASE64

"algorithm": configuration expression<string>, required

The algorithm name used for encryption and decryption. Use algorithm names given in Java Security Standard Algorithm Names.

Example

For examples that use SecretKeyPropertyFormat, see Pass Runtime Data in a JWT Signed With a Symmetric Key.

{
  "type": "SecretKeyPropertyFormat",
  "config": {
    "format": "PLAIN",
    "algorithm": "AES"
  }
}

More Information

Secrets

org.forgerock.openig.secrets.SecretKeyPropertyFormatHeaplet

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

{
  "name": string,
  "type": "SecretsProvider",
  "config": {
    "stores": [ secret store declaration, ... ]
  }
}

This object can alternatively be configured in a compact format, without the SecretsProvider declaration, as follows:

  • With an inline secret store:

    "secretsProvider": {
  "type": "secret store type1",
  "config": {...}
}

  • With multiple inline secret stores:

    "secretsProvider": [
  {
    "type": "secret store type1",
    "config": {...}
  }
  {
    "type": "secret store type2",
    "config": {...}
  }
]

  • With a referenced secret store:

    "secretsProvider": "mySecretStore1"

  • With multiple referenced secret stores:

    "secretsProvider": [
  "mySecretStore1", "mySecretStore2"
]

See Example for more example configurations.

Properties

"stores": array of secret store declarations, 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.

"secretsProvider": {
  "type": "SecretsProvider",
  "config": {
    "stores": [
      {
        "type": "KeyStoreSecretStore",
        "config": {
          "file": "/path/to/keystore.jks",
          "mappings": [
            {
              "aliases": [ "myprivatekeyalias" ],
              "secretId": "private.key.jwt.signing.key"
            }
          ],
          "storePassword": "keystore.secret.id",
          "storeType": "JKS",
          "secretsProvider": "SystemAndEnvSecretStore-1"
        }
      }
    ]
  }
}

The following example shows the equivalent SecretsProvider configuration with an inline compact format:

"secretsProvider": {
  "name": "KeyStoreSecretStore-1",
  "type": "KeyStoreSecretStore",
  "config": {
    "file": "/path/to/keystore.jks",
    "mappings": [
      {
        "aliases": [ "myprivatekeyalias" ],
        "secretId": "private.key.jwt.signing.key"
      }
    ],
    "storePassword": "keystore.secret.id",
    "storeType": "JKS"
  }
}

The following example shows the equivalent SecretsProvider configuration with a compact format, referencing a KeyStoreSecretStore object in the heap:

"secretsProvider": "KeyStoreSecretStore-1"

More Information

StatelessAccessTokenResolver

Secrets

org.forgerock.secrets.SecretsProvider

SecretsTrustManager

Uses the Commons Secrets Service 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

{
  "name": string,
  "type": "SecretsTrustManager",
  "config": {
    "verificationSecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference,
    "checkRevocation": configuration expression<boolean>
  }
}

Properties

"verificationSecretId": configuration expression<secret-id>, required

The secret ID to retrieve trusted certificates.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for secrets to resolve trusted certificates. For more information, see SecretsProvider.

"checkRevocation": configuration expression<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:

{
  "type": "SecretsTrustManager",
  "config": {
    "verificationSecretId": "trust.manager.secret.id",
    "secretsProvider": {
      "type": "KeyStoreSecretStore",
      "config": {
        "file": "path/to/certs/truststore.p12",
        "storePassword": "keystore.pass",
        "secretsProvider": "SecretsPasswords",
        "mappings": [{
          "secretId": "trust.manager.secret.id",
          "aliases": [ "alias-of-trusted-cert-1", "alias-of-trusted-cert-2" ]
        }]
      }
    }
  }
}

More Information

Secrets

org.forgerock.openig.secrets.SecretsTrustManagerHeaplet

SystemAndEnvSecretStore

Manage a store of secrets from system properties and environment variables.

A secret ID must conform to the convention described in secret-id. 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.

For a description of how secrets are managed, see About Secrets.

Usage

{
  "name": string,
  "type": "SystemAndEnvSecretStore",
  "config": {
    "format": configuration expression<enumeration>,
    "mappings": [ configuration object, ... ],
    "leaseExpiry": configuration expression<duration>
    }
}

Properties

"format": configuration expression<enumeration>, optional

Format in which the secret is stored. Use one of the following values:

  • BASE64: Base64-encoded

  • PLAIN: Plain text

Default: BASE64

"mappings": array of objects, optional

One or more mappings to define a secret:

secretId: configuration expression<secret-id>, required

The ID of the secret used in your configuration.

format: SecretPropertyFormat reference, required

The format and algorithm of the secret. Use SecretKeyPropertyFormat or PemPropertyFormat.

"leaseExpiry": configuration expression<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:

<logger name="org.forgerock.secrets.propertyresolver" level="ALL">

Example

For an example of how to uses a SystemAndEnvSecretStore to manage a password, see the example in Authenticate With SSO Through the Default Authentication Service

More Information

Secrets

org.forgerock.openig.secrets.SystemAndEnvSecretStoreHeaplet

Copyright © 2010-2023 ForgeRock, all rights reserved.