Policy concepts

This section describes basic concepts about the Conjur role-based access control (RBAC) model and the objects that are defined and managed using policy.

RBAC and delegation

Conjur implements role-based access control (RBAC) to provide role management and permission checking. In RBAC, a permission check is called a “transaction”. Each transaction has three parts:

  • The role is who, or what, is acting. In Conjur, individual entities such as users and hosts are roles, and groups of entities such as groups and layers are roles too.

  • The privilege is the name of an action that the role is attempting to perform. In Conjur, privileges generally follow the Unix pattern of read, update (write) and execute.

  • The resource is the protected thing, such as a secret or a webservice.

RBAC determines whether a transaction is allowed or denied by traversing the roles and permissions in the policies. Transactions are always denied by default, and only allowed if the permission is granted to some role that is held by the current authenticated role.

In Conjur, permissions are defined in two ways:

  • Ownership. Each object in Conjur has an owner, and the owner always has full privileges on the object. For example, the owner of a policy can always create new objects in the policy, update existing objects, and read any metadata about the policy. An object declared within that policy might have a different owner.

  • Privileges in a permit statement. The permit statement includes three attributes. These attributes link roles to resources with explicit privileges for RBAC transactions on the resources.

    Attribute Description Example

    role

    The entity that can perform the transaction a group named db/secrets-users

    privileges

    The type of transactions that are permitted read and execute

    resources

    The resources that are the target of the transactions all variables in the “db” policy

Roles and resources

Policy statements create the roles and resources for your organization. Each role and resource has an id to identify it, which you provide in the policy.

Many of the statements create both role and resource. For example, a group is both a role and a resource. As a role, a group may have permission to fetch a secret. As a resource, a group has attributes that can be changed by authorized roles. Some administrative user may have permission to update the group's membership.

Policy as a resource

One kind of resource in Conjur is a policy. The policy resource provides a way to organize the other resources (hosts, users, and variables) in a logical way. A policy has an identifying id attribute that creates a policy namespace for organizing resources. For example, you can create a set of users, hosts, and variables that belong to a specific policy and not to other policies. Rather than a flat structure of policy, you can organize resources into separate namespaces to create a branching tree of policy.

  • Use different policies to define rules for different situations. For example, you might create a policy for production, and another policy for development. The users, machines, and permissions for the two situations are most likely different.

  • Each application should have its own policy that defines its variables, its host environment, and permissions for access.

  • The Conjur integrations have policy requirements that should be separated from other policy for administration and maintenance.

  • Different policies can be owned by different users.

Root policy and branches

A policy named root exists by default. All policy exists under root .

  • The root policy can contain users, groups, hosts, and variables and other resources that apply to your entire organization.

  • The root policy can contain other policy resources (branches off the root policy). Each new policy has a unique id that defines a namespace for that policy and all of the resources defined under it.

Any policy can contain other policies, creating a hierarchy.

See Understanding Conjur Policy: Policy as Trees for more information and examples for defining and organizing a logical policy tree.

Ownership

Each object has a role that is its owner. The owner has all permissions on the object it is applied to. For example, if a role group:frontend is the owner of a variable, then any member of the group can perform any action on the variable (e.g., read the secret, add a secret value).

The owner of an object can be explicitly stated in policy using the owner: attribute. That attribute is available to every object. If owner is not supplied for an object, the owner role is inherited:

  • The owner of the policy is the default owner for objects in the policy.

  • In the hierarchy of a policy, the owner of a parent policy is the default owner of child policies.

  • The root policy is owned by the default admin user . You may use a permit statement to give other roles privileges on root policy. We recommend creating an administrative group role for this purpose. See Production policy suggestions.

Object Identifiers

Every object in Conjur has a unique identifier. The identifier is a composite of the object's attributes, in the format:

 
account:kind:id

The following table describes the components of the identifier.

Component

Description

account

Every Conjur appliance has an account name, supplied during the installation process. We frequently refer to this as the “organization account”.

kind

The kind of object. Kinds include: user, group, host, layer, variable, webservice, policy.

id

The fully qualified id of the object. This is the id you supplied in the policy statement that created the object, prepended by the id of the policy where the object is declared. Here are identifiers for a policy named test and two objects declared under that policy:

 

"acct2:policy:test"
"acct2:group:test/my-admins"
"acct2:variable:test/password"

In a hierarchy of policy, the policy id itself might have several components in its path. In that case, the id for an object consists first of the entire id of the policy and then the id of the object in the policy. The following identifiers are for objects declared in a policy branch two levels down from root (test/subtest):

 
"acct2:policy:test/subtest"
  "acct2:variable:test/subtest/another-variable"
  "acct2:group:test/subtest/my-subtest-admins"

Identifiers are visible whenever you look at Conjur database records. For example, many CLI commands display object information. The audit records report actions by identifiers. When you load policy, the resulting messages show identifiers of objects affected by the load.

Here are example identifiers from a CLI command:

 
$ conjur list
[
  "acct2:policy:root",
  "acct2:policy:test",
  "acct2:group:test/my-admins",
  "acct2:variable:test/password",
  ...
]