Policy

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

Syntax

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

Attributes

Attributes Description

id:

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.

owner:

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.

Usage

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

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

Examples

The following example creates a policy branch but does not add any objects into that branch. The branch is ready for others to load policy statements into it, in the future.

  
- !policy
   id: finance

This policy can be even shorter. The following is equivalent to the previous example and is valid when this is the only line in the policy:

  
- !policy finance

To create the finance policy as a new branch directly under root: 

  1. Save the previous example (the !policy finance statement) in a policy file. For example, save the one-line policy in a file named new-policy.yml.

  2. Load the file under root. For example:

      
    conjur policy load -b root -f new-policy.yml

    The new policy now exists, but it is empty.

  3. To add statements into the new policy, create a new file that contains the policy statements you want to add. This file should not include a policy statement, although a comment that references the policy id is a best practice. Save this file with a different name. For example, save it as finance-policy.yml.

  4. Load the file into the new policy (not into root ). For example:

      
    conjur policy load -b finance -f finance-policy.yml

  5. To edit the policy, edit the above file, and reload it using the command in step 4.

This example used two files, one to create the policy and one to load statements into the policy. You may use a single file, but you must manage the !policy statement when you edit and reload the policy (because you can only create a policy once.) You can comment out the policy statement before reloading.

The following example declares a variable in a policy branch named aws.

  
  - !policy
    id: aws
    owner: !group dev  
#assumes the group dev role exists in root
    body:
      - !variable secret_access_key

Each policy has one owner. Ownership is inherited from the parent policy, unless a different owner is explicitly declared. Root policy is owned by the root admin role.

The following example shows a nested policy. Three levels are implied, since root is the parent of all policy. In the example, the dev policy is owned by the group dev-admin. The dev/db sub-policy is owned by the group db-admin, negating any owner inheritance that would have otherwise existed. The group dev-admin can not change anything in dev/db unless an update privilege for the dev/db policy is explicitly given to dev-admin.

  
  - !group dev-admin
  - !group db-admin

  - !policy
    id: dev
    owner: !group /dev-admin
    body:
    - !policy
      id: db
      owner: !group /db-admin

Note the "/" prepended to the group name reference. This is required because the group declaration is outside of the current policy. The "/" character indicates to start at root to locate the resource.

Permissions

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.