Variable

The !variable statement creates a resource for storing a secret value in Conjur.

Syntax

  
- !variable
  id: <name>
  kind: <description>
  mime_type:
  annotations: 
    <key>: <value>

Attributes

Attributes Description

id:

Required. The variable name.

The following shortcut syntax is supported when no other attributes are used:

  
- !variable <name>

kind:

Optional. Assigns a descriptive label to the variable, such as password. The values are not predefined; create your own.

mime_type:

 Optional. The expected MIME type of the values. This attribute is used to set the Content-Type header on HTTP responses.

annotations:

Rotators are implemented with annotations. See Rotators for detailed rotator descriptions.

Custom annotations are supported.

Custom annotations provide a way to store meta data about a resource. Annotations are useful for human users and automated processing. Conjur API calls can retrieve annotation values from the Conjur database.

Usage

Use the !variable statement to declare a named resource that will hold a secret value. The variable id is the name used to access and manage the secret. You manage access to the variable in !permit statements. The secret value itself never appears in policy.

A variable provides encrypted, access-controlled storage and retrieval of arbitrary data values. The value is a string. You can store certificates as a variable. You can restrict distribution of important information by storing the information as a secret in Conjur.

Variable values are also versioned. The last 20 historical versions of the variable are available through the API; the latest version is returned by default.

Variable values are encrypted on entry and de-crypted on retrieval. Values are encrypted using aes-256-gcm. The encryption used in Conjur has been independently verified by a professional, paid cryptographic auditor.

Declaring multiple variables as a unit

In a policy with several related variables, it is convenient to group variables together as a unit. The !permit statement can reference all of the variables together rather than listing them separately. To do so, create a node using the "&" character and a label:

  
- &my-variables
  - !variable password
  - !variable username

The !permit statement can now reference the set of variables as a unit in its resource attribute. Use the "*" character and the label name as shown here: 

  
- !permit
  resource: *my-variables
  privileges: [ read, execute ]
  roles: !group secrets-users

Setting variable values

By design, policy does not set the variable value. Use the CLI, or the API to set the value.

The CLI command to set (add) a variable value is:

  
$ conjur variable set -i <policy/path/variable-id> -v <value>
  
$ conjur variable values add <policy/path/variable-id> <value>

Where:

  • <policy/path/variable-id> is the variable name, fully qualified to include the policy namespace where the variable is declared. See Examples for more information.

  • <value> is the secret value.

Automatic rotation of variable value

Conjur supports automatic rotation for some specific infrastructure secrets. The rotator services generate new values, store the new values in Conjur, and also change the values on the target system. Secret values are machine-generated and changed on your specified rotation schedule. Any role with execute privilege on the variable can retrieve the current value.

Rotators are configured using annotations in the variable declaration. For a list of supported rotators and specific configuration information, see Rotators.

Examples

  
- !variable
  id: db-password
  kind: password

This example provides full declarations for each variable and groups them together for readability and convenience.

  
$ - &variables
  - !variable
    id: db-password
    kind: password

  - !variable
    id: db-login
    kind: username

This example declares two variables and assigns privileges to access those variables to a layer named app. All members of the app layer can see information about the variable and fetch the variable value. They cannot change the variable value or delete the variable.

The layer must be declared before this example will load successfully. We assume that the layer was declared elsewhere (in an entitlements file for the policy), along with grant statements that assign members to the layer.

  
$ - &variables
  - !variable
    id: db-password
    kind: password

  - !variable
    id: ssl/private_key
    kind: SSL private key
    mime_type: application/x-pem-file

- !permit
  role: !layer app           # layer declared earlier
  privileges: [read, execute]
  resources: *variables

The following command creates a new variable in an existing policy named mytest. This example loads the policy statements from STDIN:

  
$ conjur policy load -b mytest -
  - !variable
    id: var1
  <EOL>
Loaded policy 'mytest'
{
  "created_roles": {
  },
  "version": 1
}
  
$ conjur policy load mytest -
  - !variable
    id: var1
  <EOL>
Loaded policy 'mytest'
{
  "created_roles": {
  },
  "version": 1
}

The following command sets a value on the new variable. Note the fully qualified variable name.

  
$ conjur variable set -i mytest/var1 -v 001
  
$ conjur variable values add mytest/var1 001
  
Value added

This example shows how to set up rotation using the AWS secret-key rotator. The time-to-live is set to 1 day, which means that the value is rotated every 24 hours.

  
$ - !policy
  id: aws
  body:
    - !variable region
    - !variable access_key_id
    - !variable secret_key_proxy
    - !variable
      id: secret_access_key
      annotations:
        rotation/rotator: aws/secret_key
        rotation/ttl: P1D # 1 day

Permissions

The !permit statement assigns privileges to roles to access a variable. Actions on a variable require the following permissions.

To perform these actions... A role needs these privileges...
Add or change the value of a variable update privilege on the variable
Fetch the variable's current value or any historical value execute privilege on the variable
View the variable's metadata, such as annotations read privilege on the variable

 

 

The read, execute, and update privileges each represent separate privileges that are not always related to each other. For example, having update privileges does not automatically provide execute privileges.

However, having execute privileges on a variable does provide read privileges as well.

Best practices

Rotations are recommended when available for the type of variable because they offer the most robust way to secure variable values.