A !policy statement creates a policy resource and a policy role. A policy is a set of Conjur policy statements.


  - !policy
    id: <name>
    owner: !<kind-of-role> <role-name>  
 body: <statements>


Attributes Description


Required. Identifies the policy branch name.
The id specifies either a new branch to create or a previously created branch that you are adding to or replacing.

The following shortcut entry is allowed when no other attributes are used:

- !policy policyname

The id value is used as a prefix to fully qualify all resources declared in the policy. For example, a variable named db-password in a policy named prod-myapp would have a fully-qualified id value of prod-myapp/db-password.

Because of this path-like naming convention, we recommend that you avoid using id values that contain the "/" character.


Optional. Identifies the role that owns the policy. If omitted, the owner defaults to the parent policy owner.

See Examples below for an explanation of ownership for nested policy branches.


A policy organizes a related set of records, such as resource declarations, grants, and permits, into a common database namespace. The namespace name is the policy id.

The policy id is also the policy resource name and the policy role name.

A policy resource represents a branch in a hierarchy of policies. The policy hierarchy that you create using the !policy statement is created under the default root policy.

The policy role is the default owner of all resources declared in the body of the policy. This means that the owner of a policy implicitly owns everything defined in the policy. This nested ownership makes it possible to delegate the management of a complex system to many different teams and groups, each with responsibility over a small set of policies.

Root policy and branches

The policy tree starts at root. The root policy is created by default when the Conjur account is created.

All named policy ids exist under root . The policy statement and id are used to create, add to, or update a namespace under root (a policy branch).

Do not use the !policy statement for statements that are intended as root policy. To add new statements to the root policy, add the statements to a policy file that does not include a !policy statement. To merge those new statements into existing root policy, load the policy file under root using the following command: 

conjur policy load -b root -f my-new-root-objects-file.yml
conjur policy load root my-new-root-objects-file.yml

To replace everything currently loaded under root policy with new root policy, create a file that includes the entire desired root policy (or edit an existing root policy file). Use the following command to erase all current root policy and replace it with your new content: 

conjur policy load replace -b root -f my-replacement-root-policy-file.yml
conjur policy load --replace root my-replacement-root-policy-file.yml



Actions on a policy resource require the following permissions.

To perform these actions... A role needs these privileges...

Declare a new policy namespace directly under root .

create privilege on root policy. The role creating root policy should be a member of a root admin role.

Declare a new policy branch under an already existing policy branch.

create privilege on the parent policy.

Change ownership of a policy.

update privilege on the policy.

Create resources in a policy namespace, such as users, groups, hosts, layers, and webservices.

create privilege on the policy.

Change existing resources, such as add an annotation, or add a host to a layer.

update privilege on the policy or on the applicable resource (such as on a layer ).

Get information about a policy.

read privilege on the policy.

View the policy contents.

read privilege on the policy

Best practices

  1. Maintain one policy file for your root policy. The file should be checked into source control, and changes to it should be controlled.

  2. Make policy ids descriptive. This helps others read and understand policy and makes policy records in the audit logs more meaningful.
  3. Avoid using the "/" character within a policy id. In a hierarchy of parent and child policy, your hierarchy is more clear if each component in a namespace path represents a unique policy.

  4. Enforce least privilege by using policy ids to separate management and ownership into logical and functional branches. A typical example is two branches named dev and prod. Another example is to separate administration of servers into Linux and Windows.