To implement and change policy, you load the policy files into Conjur. You can use the CLI or the API for this task. We use the CLI for examples in this guide.
conjur policy loadcommand loads and updates policy. For more information about policy command, see policy.
Creates new objects. If there are objects that already exist in the database (they were loaded into the branch previously)
but are not specified in the policy file being loaded, those objects are left alone. The loading role needs
create privilege on the policy id.
The options are:
Creates new objects and also implements any !delete statements in the policy being loaded. The loader's role needs
Replaces all previously loaded policy under the named policy id (in root or in a branch). Any policy objects, grants,
and permits that exist in the database from previous loads but are not specified in the new policy file are deleted.
The loader role needs
Other attributes in the command are:
Is either the value
rootor the identifier of a previously created policy branch. The
rootpolicy exists by default. All other policy ids must be explicitly declared in policy statements. They become branches of a policy hierarchy under root. Aside from the root policy, policy ids are not valid until a policy is loaded that declares that policy id.
The first time you load a policy, use the policy-id
root. This is a special policy name that is used to define root-level data. To define policy branches under root, load the first-level policy branches under root to declare the new policy ids (the namespaces for the branches). You can later populate the branch with its own data by loading policy under the branch's policy id.
The file containing Conjur policy statements in YAML format. To read the policy from STDIN, use a single dash (-).
The Rest API uses policy load modes that align with HTTP verbs. The CLI implements the API, using option flags to indicate the load modes.
This requires create privileges. Conjur only creates new data.
If the policy contains deletion statements, such as
!deny, they are treated as errors.
If there are objects that already exist in the database but are not specified in the policy, those objects are left alone.
This requires update privileges. Conjur both creates and deletes data.
Objects and grants that already exist in the database but are not specified in the policy are left alone.
This requires update privileges. Conjur replaces the data in the database with the data specified in the policy file being loaded.
Objects, grants, and privileges that exist in the database but are not specified in the policy file are deleted.
This requires read privileges. Conjur reads the data.
Who can load policy?
Policy statements are loaded into either the Conjur
create for creating new objects and
update for changing existing policy. Privileges are assigned in permit statements for specific roles. A role can be a policy, a user, a group, a host, or a layer.
The default admin can load any policy.
root admin role (if established as we recommend)can update and create privileges on the rootpolicy. You could set this role to have update and create privileges on all policy.
- The policy branch owner can load policy into that policy branch. Owners are named explicitly or are inherited from a parent policy.
- Other roles that have specific create or update privileges on a policy branch can load policy into it.
For details about required permissions, see the Permissions sections in the Policy Statement Reference for the Policy, User, Host, Group, and Layer statements.
Default admin user
The default admin is the user created when Conjur was installed. As part of the installation:
- The installer logged into Conjur for the first time using the admin account.
- The installer was prompted to set a password for the admin account.
Thereafter, you can log on using these credentials:
- User name : admin
- password: API key OR the password
NOTE: admin is the owner of
The policy structure starts at root. The default admin user is initially the owner of root policy.
We recommend that you set up a group role as the owner of root policy. You never want a situation where one user owns important policies and nobody else has access to them. It is also easier to add and remove individuals from role membership than change permissions at the individual user level.
The root admin role has the following characteristics:
- It is the owner of root policy. Therefore, its members can load policy under root.
- It owns all policy unless an explicit owner role is named for a branch of policy off of root.
We call this role the root admin role throughout the documentation. The actual role name can be of your choosing.
The following statements create a root admin group role. You can add statements similar to this to your root policy file.
# add the following to your root policy file # declare two users and a group - !user alice - !user bob - !group conjur-root-admins # add members to the group - !grant role: !group conjur-root-admins members: - !user alice - !user bob # give the group privileges on some resources - !permit role: !group conjur-root-admins privileges: - create - update - read resources: - !policy root
To load this policy into Conjur:
- Add policy similar to the above to your root policy file.
Run the following command:
Root versus Branches
Policy that applies to your entire enterprise would be loaded into
Loading and managing the root policy
Recommended practice is to have only one policy file for root. Maintain all root policy in that file. Also recommended is to create a root admin group role that owns root. See Create a root admin group role.
To load the root policy file the first time:
To load updated versions of the same root policy file:
Creating and managing branches
To create a branch under
Add statements to your
rootpolicy file to create the new branch. The id is the branch name.
- !policy id: aws
Use the following command to load your altered
Branches can contain additional branches. To create a branch off of the
Add statements to an aws policy file to create a new branch.
- !policy id: dev1
Use the following command to load this new file under the aws branch:
conjur policy load -f aws policy-file-name.yml
conjur policy load aws policy-file-name.yml
The fully qualified name of the branch you just created is aws/dev1. To load policy into the aws/dev1 branch, the entire policy path must be supplied in the load command:
Load policy into a branch
To add objects into a branch after the branch is declared:
Altering existing policy: (you are replacing all policy for aws with new policy, which means deleting unwanted objects and adding new objects)
To load policy into a branch two or more levels down from
rootbranch, the entire policy path must be supplied in the load command:
Loading the following policy statements into
root creates two objects in the
- !group dev - !policy aws
Then, load the following statement into the
aws branch to create an object in the
The above two loads are the same as loading the following into
The difference is that when you use the two load commands, the opportunity exists for different roles (different users) to load. Someone who has permission to change the
It is natural and recommended to split up policy for a branch into multiple files.
You can initially load each file separately. However, if you want to make updates to that policy branch using the
--replace option (PUT mode), you need to reload all of the files associated with the branch, even if only some of the files were modified.
The following example illustrates this situation and shows a way to concatenate the files for the purpose of reloading them.
For now, assume that you have a set of files that describes policy for a branch:
Initially, you could load this set of files into a policy branch named
dev as follows:
Over time, you may need to make changes to these files, such as update the entitlements or add or revoke privileges. Because you are replacing the policy, all of the files associated with the policy branch must be loaded together.
The easiest way to do this is to concatenate the associated files before reloading. For example, in a Linux environment, you would run:
When you load policy, the policy YAML is stored in the Conjur database. As you make updates to the policy branch, the subsequent versions of policy for that branch are stored as well.
Previous versions of policy can be useful in case of mistaken policy changes. This policy history is available by fetching the policy resource using the conjur show command.
This policy history is available by fetching the policy resource using the conjur show command:
You can recreate previous policy using the policy_text in the version information, or use the timestamp to retrieve previous versions from your source control system. Then reload your adjusted policy file using the '--replace' (PUT) option.