User

The !user statement creates a user role and a user resource. A user represents a human user.

Syntax

- !user
  id: <name>
  owner: !<kind-of-role> <role-name>
  annotations:
    <key>: <value>
  restricted_to: <network range>

Attributes

Attributes Description

id:

Required. Identifies the user name. This is the Conjur login name. It should not contain special characters such as ":" or "/". It may contain the @ symbol.

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

- !user ben

owner

Optional. If owner is not provided, a resource inherits its owner from its policy.

If owner is provided, the role that is named as owner must already exist. You can declare the owner in the current policy if the declaration appears before any statement that references it.

annotations

Annotations on a user resource are optional and customizable.

Custom annotations provide a way to store meta data about a resource. Annotations are useful for human users and automated processing. Conjur API calls can retrieve annotation values from the Conjur database.

restricted_to:

Restricts authentication from the specified network range. This can include:

one or more IP addresses
one or more CIDR ranges

The restricted_to attribute does not correctly gate access to the Conjur UI based on origin IP address. Applying this attribute to a user results in denying that user any access to the UI, regardless of their origin IP address.

Trusted proxies must be configured before you can use this feature. For more information, see Client IP Address Sourcing.

Usage

A user role can have privileges on Conjur resources. However, the typical and recommended way to manage user privileges is to add users to group roles, and assign privileges to the group.

User identity

When you load policy that creates a new user, Conjur assigns a randomly generated API key to the user.

In the following example, the conjur policy load command uses the dash (-) to load a simple policy statement from STDIN. Notice the API key in the command response.

$conjur policy load -b root -

- !user ben

<EOF>

Loaded policy 'root'
  {
    "created_roles": {
      "my-acct:user:ben": {
        "id": "my-acct:user:ben",
        "api_key": "3n5xab2x5bjqsxrfvsj1nhm8853nmghw3zvrs8a3gzrvw43sdqsm4"
      }
    },
    "version": 21
  }

Save the api_key value. The user needs the API key to authenticate to Conjur the first time, whether logging into the UI or CLI, or authenticating with the API.

User authentication

A user authenticates to Conjur the first time with a user name and the associated API key value. After authenticating successfully with the API key, the user can set a password. The password change command is:

$ conjur user update_password -p <my-new-password>

Thereafter, the user can authenticate using either:

User name and current API key.
User name and password.

The only way a password on a user account can be changed is by the logged in user. Other users cannot change the password, not even admins.

Lost password and API key

To help in the case of a lost password, an authorized administrative user may rotate the API key for other users. An authorized user is one with update privilege on the user resource. The CLI command to rotate an API key is as follows:

$ conjur user rotate-api-key

The user can then immediately log in with the new API key and change the password for the account.

Examples

Minimal user declaration

- !user ben

User declaration with authentication restricted from a single IP address and a CIDR range:

- !user
  id: ben
  restricted_to: [172.17.0.3, 10.0.0.0/24]

When the conjur authn login command prompts for password, use either the API key or the password associated with the user name. For first-time login, a password does not exist. Use the API key that was returned when the user statement was first loaded.

$ conjur login -i ben

Provide your API key, as the password is not set yet.

Set your password.

$ conjur user change-password -p <my-new-password>

Log out from Conjur.

$ conjur logout

Next time you login, you can use either the password or the API key to login to Conjur. You can provide the user API key or password that you set in the steps earlier.

Permissions

Actions on a user resource require the following permissions.

To perform these actions...	A role needs these privileges...
Declare a new user	`create` privilege on the policy in which the user is declared.
Update user information	`update` privilege on the user.
Rotate a user's API key	`update` privilege on the user.
Change a user's password	A logged in user can update the password on that account only. That is, users can change their own password, and no user can change another user's password.
Delete a user	`update` privilege on the user.
Add a user to a group	`update` privilege on the group.

Best practices

Do not assign privileges to individual users. Rather, use grant statements to add users to groups, and assign privileges to the group role.
Consider using the Conjur Directory services to integrate with an existing AD or LDAP directory to create users.
Carefully consider who in your organization needs user accounts in Conjur. Typically, only a subset of your user base needs Conjur access. Conjur users may include administrators, security teams, DevOps and maybe developers.