Policy Syntax

This section describes YAML syntax as it relates to Conjur policy. For more information about YAML files in general, see the YAML specification.

Conjur policy files are YAML files. They must have a file extension of .yml.

Documents and separation marker lines

Document is a YAML term. In a Conjur policy file, a document consists of a group of policy statements that are related to each other. You can concatenate multiple documents in the same file by using document separation marker lines.

The document separation marker line consists of three dashes beginning in column 1.

If a file contains multiple documents, a document separation marker line is required at the beginning of the file. If a file contains only one document, the document separation marker line is optional. An ending document separation marker line is optional.

---
- !policy
  ...
  ...
---
- !policy
  ...
  ...
---                      

Nodes and indentation (no tabs)

Policy files consist of nodes. The syntax for the start of a node is:

- !tagname

Like this:

- !host

Each node starts with a dash and a space. Nodes can include child nodes. Indentation indicates scope.

Required: The space between the dash and the tag is required.

Required: Each node must be indented further than its parent node. All sibling nodes must use the exact same indentation level. However, the content of each sibling node can be further indented independently.

IMPORTANT: Tabs are not allowed as part of the indentation white space. Tabs can safely be used in other places on a line, just not as part of the beginning indentation.

---
- !policy
  id: my-policy
  body:
    - !layer
    - !host
      owner: !layer
      id: my-host-1
    - !host
      owner: !layer
      id: my-host-2
                  

Tags

A tag is an explicit typing and is indicated with an exclamation mark. For example:

  • !Policy indicates a resource record of kind policy and a role record of kind policy.
  • !User indicates a resource record of kind user and a role record of kind user.
  • !Grant indicates a record of kind grant.

This Policy Statement Reference describes all of the valid tags in Conjur policy.

Required: No space is permitted between the explanation mark and the tag name.

Tags are used at the beginning of a node to define the type of node. Tags are also used within the value part of a key: value pair, to define the type of value being supplied.

- !policy my-policy
  owner: !group admins
                       

Mappings

A node can contain mappings. A mapping is a key: value pair.

Required: The space after the colon in a key: value pair is required.

- !policy
  owner: !group admins
  id: my-host-1
                      

Mapping Node

A mapping node consists of a key followed by a colon, with one or more unordered key: value pairs on separate lines. In the following example, annotations: marks the start of a mapping node. Conjur policy uses a mapping node for the annotations key.

- !user
  id: bob
  annotations:
    name: Bob Green
    email: bgreen@example.com
    dept: Org-2
                     

Required: The key-value pairs in a mapping node must be indented consistently under the mapping node name.

Comments

Use the # character for comments. Comments can appear on the same line as other elements or on a line of their own. A comment line is independent of any indentation levels.

        #admin user
- !user
  id: bob
  annotations:
    name: Bob Green          #admin user
    email: bgreen@example.com
    dept: Org-2
                    

Collections

A collection of nodes of the same type can increase readability of your policy. The tag for a collection node starts with the "&" rather than the "!". The tag itself is plural. The members of the collection are indented under it.

- !policy
  id: frontend
  body:
    - &variables
      - !variable ssl/private_key
      - !variable ssl/certificate