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.

Secrets from SystemAndEnvSecretStore never expire.

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

Usage

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

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.

For information about supported formats for secret-id, see secret-id.

format: SecretKeyPropertyFormat reference, required

The SecretKeyPropertyFormat object that defines the format and algorithm used for the secret.

For more information, see "SecretKeyPropertyFormat". For an example that uses SecretKeyPropertyFormat, see "Packing Data Into a JWT Signed With a Symmetric Key".

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

In the following example an AmService is configured to authenticate with AM, using the IG agent in AM. IG uses the SystemAndEnvSecretStore to retrieve the agent password from an environment variable.

Retrieve a Secret From an Environment Variable

Before you start:

  1. Set up AM:

    1. (For AM 6.5.x and earlier versions) 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:

      • Agent ID: ig_agent

      • Password: password

      Leave all other values as default.

      For AM 6.5.x and earlier versions, set up an agent as described in "Set Up an IG Agent in AM 6.5 and Earlier".

      1. Select Applications > Agents > Java (or J2EE).

      2. Add an agent with the following values:

        • Agent ID: ig_agent

        • Agent URL: http://openig.example.com:8080/agentapp

        • Server URL: http://openam.example.com:8088/openam

        • Password: password

      3. On the Global tab, deselect Agent Configuration Change Notification.

        This option stops IG from being notified about agent configuration changes in AM, because they are not required by IG.

  2. Set up IG:

    1. Set an environment variable for the IG agent password: 

      $ export AGENT_SECRET_ID='password'

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

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

    3. Add the following route to IG: 

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

      Notice the following features of the route:

      • The route matches requests to /home/systemandenvsecret.

      • The agent password for AmService is provided by a SystemAndEnvSecretStore 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.

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

      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 sample app, which returns the profile page.

Read a different version of :