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

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.