Environment variables

Axiomatics Policy DevOps (APD) supports environment variables in attribute connectors, test data, and other configurations. You can also define default values for variables where needed.

The following examples show variable substitution with and without default values:

${PIP_URL}
${PIP_URL:-http://ldap.myorganization.com}

You can use variables in the YAML files within your authorization domain and in the deployment.yaml of ADS. Environment variables are particularly useful for configuration that varies across environments (such as Dev and Prod). For instance, to set the logging level to INFO by default but allow enabling debug level in the Dev environment, deployment.yaml contains:

deployment.yaml

logging:
  level:
    root: ${ADS_LOGGER_ROOT_LEVEL:INFO}

:::warning Two ways of declaring a default value The default value is written differently depending on the file:

• In deployment.yaml, write a colon: ${ADS_LOGGER_ROOT_LEVEL:INFO}. ADS reads this file with Spring Boot, which uses this form.
• In all other files, such as attribute connectors, write a colon and a hyphen: ${USER_SERVICE_URL:-http://localhost:8080}. :::

Variable substitution also works in attribute connector configuration files. This is especially useful for secrets such as passwords and API keys, and for URLs that differ between environments:

src/authorizationDomain/attributeConnectors/userHttpService.yaml

className: com.axiomatics.attributeconnector.http.ConnectorModule
providedAttributes:
  - attributeName: user.service.http.body
configuration:
  identifier: userHttpService
  connection:
    url: ${USER_SERVICE_URL:-http://localhost:8080}/users/search
    method: POST
    headers:
      - name: x-api-key
        value: ${USER_SERVICE_API_KEY}
  mappings:
    - attributeName: user.service.http.body
      contentType: application/json
      template:
        payload: true
        value: '{"userId": "@var1"}'
      keys:
        - attributeName: user.identity

In this example USER_SERVICE_URL has a default value suitable for local development. USER_SERVICE_API_KEY has no default and must be supplied as an environment variable — it should never be committed to source control.

Defining variables

APD runs your authorization domain in different processes, and each of them needs its own variables:

• Tests on the embedded policy engine (./gradlew test): APD substitutes the variables in the attribute connectors and in the attribute values of the test requests.
• Tests against a running ADS (a test_… task with ALFA_TEST_REMOTE_URL, see Test against a running ADS): the tests need the address and credentials of ADS. The ADS itself gets its variables where it runs.
• An ADS that APD starts on your machine (runAds, and for Authorization Hub runAdsWith… and test{environment}-{domainName}): ADS substitutes the variables in deployment.yaml and in the authorization domain.

Set the variables for each of them, as described below.

Gradle passes the environment variables of the shell or build server that starts it on to the tests and to the ADS that APD starts. So the simplest way, and the right way for secrets, is to set the variables there, see Set variables in the shell. Set fixed values that are not secret in build.gradle, as below.

• Running tests on the embedded policy engine

  Define variables within the test {} block in your build.gradle file:

  test {
      environment "USER_SERVICE_URL", "http://user-service-dev.myorg.com"
  }

• Running tests against a running ADS

  Define variables within the task definition in your build.gradle file:

  task test_LocalEnv(type: Test) {
      group "verification"
      environment "ALFA_TEST_REMOTE_URL", "http://127.0.0.1:8080/authorize"
      environment "ALFA_TEST_REMOTE_USER", "pdp-user"
      environment "ALFA_TEST_REMOTE_PASSWORD", System.getenv("ADS_PASSWORD")
  }

  See Test against a running ADS.

• Running a local ADS instance

  Define variables when starting a local ADS instance:

  runAds {
      environment "ADS_LOGGER_ROOT_LEVEL", "DEBUG"
  }

  For the ADS that APD starts for an Authorization Hub domain, set the variables with envVariable in the remote, see Authorization Hub integration.

Pass a variable under another name

To give a process a variable of the shell or build server under another name, read it with System.getenv in build.gradle. For example, to pass ADS_PASSWORD to the tests as ALFA_TEST_REMOTE_PASSWORD, as in the task above:

build.gradle

environment "ALFA_TEST_REMOTE_PASSWORD", System.getenv("ADS_PASSWORD")

note

The shell or build server can be your machine or a build server such as Jenkins or Azure DevOps. Store secrets in the secret store of your build server, for example Jenkins credentials or Azure DevOps secret variables, and expose them as environment variables to the build.

Set variables in the shell

You can also specify variables directly from the command line:

• Linux

  USER_SERVICE_API_KEY=abc123 USER_SERVICE_URL=http://user-service.acme.com ./gradlew test

• Windows (PowerShell)

  $env:USER_SERVICE_API_KEY = "abc123"
  $env:USER_SERVICE_URL = "http://user-service.acme.com"
  .\gradlew test

• Windows (Command Prompt)

  set USER_SERVICE_API_KEY=abc123
  set USER_SERVICE_URL=http://user-service.acme.com
  gradlew test

.env file generation

The tasks createEnvFile and stageDeployment list the environment variables that ADS needs. They collect every ${...} variable in deployment.yaml, src/authorizationDomain, and src/extra, also in commented-out lines, and write three files:

File	Content
.env.generated	The variables, without values. Fill in the values for your environment.
.env.generated.defaults	The variables, with their default values where they have one.
.env.generated.info	How to load the .env file, for example with Docker, Kubernetes, or Java.

createEnvFile writes them to build/, and stageDeployment writes them to build/install/deployment/, next to the staged deployment.