Policy syntax

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

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

Nodes and indentation (no tabs!)

Policy files consist of nodes.

  • The syntax for the start of a node is - !tagname, for example, - !host

  • Each node starts with a dash (hyphen) and a space

  • Nodes can include child nodes; indentation indicates scope

 

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

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

 
- !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 type 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.

  • Tags must be used at the beginning of a node to define the type of node.

    • The space between the dash and the exclamation point of the tag is required.

    • There must NOT be a space between the exclamation point and the tag name.

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

Always include a space after the colon in a key: value pair.

- !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: is the key marking the start of the mapping node.

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

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

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