entitlements: roles and permissions which span all policies and global records

For more information on policies, and examples covering common use cases, read the policy guide.

Command Line Usage

The policy command has three subcommands: load, import and retire.

load

The load command is used to load a policy file in one shot.
This command's --dry-run option lets you "preview" the
actions that would be taken if the policy were loaded. This is the command you will most often use.

Loading policy as group security_admin is a best practice. That group then owns the policy
and group members can administrate policies as needed. If you don't specify the --as-group
option when loading a policy, you will own the policy and any associated records. Your colleagues
will not be able to see the records you've created. This is probably not what you want.

Setting a namespace during load allows you to use the same policy across different environments.
Any record created in the policy will be prefixed with the namespace. If you would like to reference
global records, prefix them with /, like !group /ops.
The namespace is also available in the policy document as variable $namespace. If no namespace
is provided on policy load, the records will have no prefix (they are global).

import

The import command loads the output of a dry-run plan and executes it.
Note that you cannot import a policy.yml directly; this command's input
must be a plan that has already been generated. You can think of a generated plan
as Conjur policy bytecode. A policy is declarative, a plan imperative.

To create a policy plan, preview the actions to be taken and then
execute them, run:

retire

Policies can be retired like any other role or resource with policy retire.

Reference

Common Attributes

Policy records share the following attributes:

account Records in Conjur can be divided into separate accounts. Each record in Conjur is uniquely identified by account:kind:id.

kindkind is normally implicit in the policy document. For example, the kind of each User record is user. Conjur can be
extended with custom resources, which should specify the kind explicitly. In addition, some Conjur records create internal roles,
which can be identified by the presence of the @ symbol in their kind.

id an identifier which is unique within the account:kind namespace. By convention, Conjur ids are path-based.
For example: prod/webservers. An exception is host ids, which may use the path-based convention, but may also use the
DNS naming convention www-01.mycorp.com. Keep in mind that ids may not be re-used across hosts, so the ids of dynamically
provisioned hosts should be constructed uniquely.

owner The owner of a record is able to fully administer the record. For example, if a group is the owner of a host,
then the group role (and all of its transitive role member), have full permissions on the host, and can also grant and
revoke the host role.

Create

Creating records can be done explicitly using this node type, or
implicitly. Examples of both are given immediately below.

When a record is created explicitly, it's an error if the record already exists.
When a record is created implicitly, the record will be found-or-created, and its
state (owner, fields and annotations) will be updated to match the policy declaration.

Grant

Grant one role to another. When role A is granted to role B,
then role B is said to "have" role A. The set of all memberships of role B
will include A. The set of direct members of role A will include role B.

If the role is granted with admin option, then the grantee (role B),
in addition to having the role, can also grant and revoke the role
to other roles.

The only limitation on role grants is that there cannot be any cycles
in the role graph. For example, if role A is granted to role B, then role B
cannot be granted to role A.

Users, groups, hosts, and layers can all behave as roles, which means they can be granted to and
revoked from each other. For example, when a Group is granted to a User,
the User gains all the privileges of the Group. (Note: "Adding" a User to
a Group is just another way to say that the Group role is granted to the User).

Some grant operations have additional semantics beyond the role grant:

When a Layer is granted to a Host, the automatic roles on the Layer are granted
privileges on the Host. Specifically, the observe role is given read privilege,
use_host is given execute, and admin_host is given update. The admin
option is ignored.

Group

A group of users and other groups.

When a user becomes a member of a
group they are granted the group role, and inherit the group's privileges.
Group members can be added with or without "admin option". With admin option,
the member can add and remove members to/from the group.

Groups can also be members of groups; in this way, groups can be organized and
nested in a hierarchy.

Host

A machine or code; for example, a server, VM, job or container.

Hosts defined in a policy are generally long-lasting hosts, and assigned to a
layer through a !grant entitlement. Assignment to layers is the primary way
for hosts to get privileges, and also the primary way that users obtain access to hosts.

Privileges

Privilege

Description

execute

SSH users should have login privileges to the host without admin privileges.

update

SSH users should have login privileges to the host with admin privileges.

Include

By using this feature, policies for an entire organization can be
defined in one source repository, and then unified by a top-level
"Conjurfile".

Attributes:

file path to the included policy file, relative to the including policy file.
This is the default attribute, so it can be specified in shorthand form as:
- !include the-policy.yml

Included policies inherit the namespace and owner of the enclosing
context. To include a policy with a different namespace and owner,
first define an enclosing policy record with the following attributes:

id the name which is appended to the current namespace

owner the desired owner

Then, within the body of that policy, include the additional
policy files.

Layer

Host are organized into sets called "layers" (sometimes known in some other
systems as "host groups"). Layers map logically to the groups of machines and
code in your infrastructure. For example, a group of servers or VMs can be a layer;
a cluster of containers which are performing the same function (e.g. running the same image)
can also be modeled as a layer. A script which is deployed to a server can be a layer.
And an application which is deployed to a PaaS can also be a layer.

Using layers to model the privileges of code helps to separate the permissions from the
physical implementation of the application. For example, if an application is migrated from a PaaS to a
container cluster, the logical layers that compose the application (web servers, app servers, database tier,
cache, message queue) can remain the same.

Automatic roles

When a layer is created, it automatically creates three additional roles. The name of these
automatic roles are use_host, and admin_host. When a host is added to the layer
(by granting the layer to the host), the layer automatically gives privileges on the host to the
automatic roles:

use_host gets execute privilege on the host

admin_host gets update privilege on the host

If the host is removed from the layer, then these privileges are revoked.

Automatic roles are granted using the !automatic-role tag, described below.

Permit

Give privileges on a resource to a role.

Once a privilege is given, permission checks performed by the role
will return true.

Note that permissions are not "inherited" by any mechanism such as glob
expressions on resource ids; each privilege must be
explicitly given on each resource. Inheritance of privileges only happens through
role grants. Role-based access control
is explicit in this way to avoid unintendend side-effects from the way that
resources are named.

Policy

A policy is used to collect a set of records and permissions grants into a
single scoped namespace with a common owner.

The policy can have the standard attributes such as account, owner, and id.
It's also required to have a body element, which contains:

Records which are owned by the policy.

!permit and !grant elements which apply to policy records.

Like a user or group, a policy is a role. All the records declared in the body of the policy are
owned by the policy role. As a result, any role to whom the policy role is granted inherits
ownership of everything defined in the policy. Typically, this is the policy owner.

Policies should be self-contained; they should avoid making any reference to
records from outside the policy. This way, the policy can be loaded with different
owner and namespace prefix options to serve different functions in the workflow.
For example, a can be loaded into the dev namespace with owner !group developers,
then a "dev" version of the policy is created with full management assigned to the developers group.
It can also be loaded into the prod namespace with owner !group operations, creating
a production version of the same policy.

Any Conjur resource can be annotated with a key-value pair. This
makes organization and discovery easier since annotations can be
searched on and are shown in the Conjur UI. Automation workflows
like rotation and expiration are based on annotations.

Typically, resources are not defined directly.
Rather, records that behave as resources, such as Users, Groups,
Hosts, Layers, Variables and Webservices are used instead.

Retire

Move a Role or Resource to the attic.

When you no longer need a role or resource in Conjur, you retire it.
This is different than deleting it. When you retire an item, all of
its memberships and privileges are revoked and its ownership is
transferred to the attic user. This is a special user in Conjur that
is created when you first bootstrap your Conjur endpoint. By
retiring rather than deleting items, the integrity of the immutable
audit log is preserved.

You can unretire items by logging in as the
'attic' user and transferring their ownership to another role. The
'attic' user's API key is stored as a variable in Conjur at
conjur/users/attic/api-key. It is owned by the 'security_admin'
group.

Example

- !retire
record: !user DoubleOhSeven

Revoke

Some revoke operations have additional semantics beyond the role revocation:

When a Layer is revoked from a Host, the automatic roles on the Layer are denied their
privileges on the Host. Specifically, the observe role is denied read privilege,
use_host is denied execute, and admin_host is denied update.

Webservice

Represents a web service endpoint, typically an HTTP(S) service.

Permission grants are straightforward: an input
HTTP request path is mapped to a webservice resource id. The HTTP
method is mapped to an RBAC privilege. A permission check is
performed, according to the following transaction:

role client incoming role on the HTTP request. The client can be obtained from an Authorization header (e.g. signed
access token), or from the subject name of an SSL client certificate.