Users and Teams

This guide will show you how to manage Chef Automate users and teams. Import existing users into Chef Automate with Microsoft AD (LDAP), generic LDAP or SAML.

You can create local Chef Automate users that can log in and interact with the system independent of LDAP or SAML. Group users into teams for policy-based authorization.

Prerequisites

Before you follow these instructions, we recommend you install the JSON processor jq to ensure readable output. Without it, some commands may need to be modified.

You will need administrative access to interact with the user and team APIs. An existing administrative user can provide that access. If you are already an administrative user, you can create users in the UI by logging into Chef Automate with your admin credentials.

To interact with either the users or teams API using cURL, fetch an admin API token available from the chef-automate CLI, and set it to a usable variable:

export TOK=`chef-automate admin-token`

Users

Creating Users

Create a User in Chef Automate

As an administrative user, you can create a user in the UI from the Admin tab. Select Local Users from the left side of the window to open the User Management screen.

Add Local User

To add a local user, click on Create User , which opens a helper window for entering the user’s full name, a unique username, password and confirm password. Once you’ve filled in the information, select Save and Close at the bottom of the helper window. Using an email address for the username automatically retrieves the user’s gravatar. Otherwise, the user’s avatar appears as a generic image.

Create User

Create a User from the Command Line with cURL

To create a Chef Automate user, you’ll need a name, username, and password. The username must be unique.

curl -H "api-token: $TOK" -H "Content-Type: application/json" -d '{"name":"Your Name", "username":"username001rulez", "password":"password"}' https://automate.example.com/api/v0/auth/users | jq

Fetching Users

You can fetch a single user by username. Keep in mind that certain characters in a username (such as a space) may need to be escaped in the URL.

curl -H "api-token: $TOK" https://automate.example.com/api/v0/auth/users/username001rulez | jq

More generally, here is the format showing a {username} placeholder:

curl -H "api-token: $TOK" https://automate.example.com/api/v0/auth/users/{username} | jq

You can also fetch a list of all users by omitting the final username segment of the URL:

curl -H "api-token: $TOK" https://automate.example.com/api/v0/auth/users | jq

Updating Users

You can update a user’s full name (name property) and/or password (password property). To identify the proper user record, supply the username in the URL and the user’s id in the payload. Then, also in the payload, you must specify the full name–even if you do not want to change it! Finally, include the password in the payload, but only if you do want to change it.

curl -X PUT -H "api-token: $TOK" -H "Content-Type: application/json" -d '{"name":"Revised Full Name", "id": "userID", "password": "another_pwd"}' https://automate.example.com/api/v0/auth/users/{username} | jq

A non-admin user is also able to change their own password through the UI. For completeness, here is the API call to perform the same action.

curl -X PUT -H "api-token: $TOK" -H "Content-Type: application/json" -XPUT -d'{"id":"userID","name":"Revised Full Name","username":"username001rulez","password":"another_pwd","previous_password":"password"}' https://automate.example.com/api/v0/users/{username} | jq

Deleting Users

To delete a user, just supply the username:

curl -X DELETE -H "api-token: $TOK" -H "Content-Type: application/json" https://automate.example.com/api/v0/auth/users/{username} | jq

User Self-Maintenance

Local Automate users can manage their own name and password through the Chef Automate user interface. Select your full name at the right end of the top navigation bar, then select Your Profile from the drop-down.

Navigate to user profile

The sidebar should reflect Your Profile as the active panel, and you should see your user name, your avatar (if your username is your email address), and your full name. Off to the right the Edit button allows you to edit your full name, while the lower portion of the page allows you to update your password.

View user details

Teams

Creating Teams

Create a Team from Chef Automate

As an administrative user, you can create a team in the UI from the Admin tab. Select Local Teams in the sidebar then use the Add Local Team button:

Add Local Team

First, enter a unique name and description for the team. Save your new team.

Create Team

Upon creating the team, you’ll be taken to the new team’s details page.

Team Details

Add users to the new team.

Add Users

Now, you can create a new policy for your team. All members will now have additional access based on that new policy.

Create a team using the Command Line with cURL

To create a Chef Automate team, you’ll need to provide a name and description. Team names must be unique.

curl -H "api-token: $TOK" -H "Content-Type: application/json" -d '{"name":"Team Name", "description":"My Chef Team"}' https://automate.example.com/api/v0/auth/teams | jq

Fetching Teams

You can fetch a team by its ID:

curl -H  "api-token: $TOK" https://automate.example.com/api/v0/auth/teams/{id} | jq

You can also fetch all teams, collectively:

curl -H "api-token: $TOK" https://automate.example.com/api/v0/auth/teams | jq

Updating Teams

To update a team, you must supply its name and description:

curl -X PUT -H "api-token: $TOK" -H "Content-Type: application/json" -d '{"name":"An Updated Team Name", "description": "An updated description"}' https://automate.example.com/api/v0/auth/teams/{ID} | jq

Deleting Teams

To delete a team, you must supply its ID:

curl -X DELETE -H "api-token: $TOK" -H "Content-Type: application/json" https://automate.example.com/api/v0/auth/teams/{ID}

Managing Chef Automate User and Team Associations

Viewing a User’s Teams

To view a user’s teams, you will need the user’s ID:

curl -H "api-token: $TOK" https://automate.example.com/api/v0/auth/users/{user_ID}/teams | jq

Viewing a Team’s Users

To view a team’s users, you will need the team’s ID. This returns JSON that contains an array of user IDs associated with the team:

curl -H "api-token: $TOK" https://automate.example.com/api/v0/auth/teams/{team_ID}/users | jq

Adding Users to Team

To add users to a team, you will need both the team ID and the IDs of the users you will add:

curl -H "api-token: $TOK" -H "Content-Type: application/json" -d '{"user_ids":["userID", "secondUserID"]}' https://automate.example.com/api/v0/auth/teams/{team_ID}/users | jq

Removing Users from a Team

To remove users from a team, you will need both the team ID and the IDs of the users you will remove:

curl -X PUT -H "api-token: $TOK" -H "Content-Type: application/json" -d '{"id":"teamID", "user_ids":["userID", "secondUserID"]}' https://automate.example.com/api/v0/auth/teams/{team_ID}/users

Common Use Cases

Adding Users to the Admin Team

Adding users to the default admins team will give them full access to all endpoints in Chef Automate; they will be able to manage policies, users, and teams.

You may add users on the admins Team Details page.

Add Users to Admins

You may also complete this operation from the command line.

  1. Fetch an admin API token available from the chef-automate CLI and set it to a usable variable:

    export TOK=`chef-automate admin-token`
  2. Get the admins team ID and set it to a usable variable:

    export ID=`curl -H "api-token: $TOK" https://automate.example.com/api/v0/auth/teams | jq -r '.teams[] | select(.name =="admins").id'`
  3. Confirm the user IDs for the user(s) you want to add to the admins team.

    ID of a single user:

    curl -H "api-token: $TOK" https://automate.example.com/api/v0/auth/users/{username} | jq .id

    Fetch all users (with IDs):

    curl -H "api-token: $TOK" -H "Content-Type: application/json" https://automate.example.com/api/v0/auth/users | jq
  4. Add the user(s) to the admins team:

    curl -H "api-token: $TOK" -H "Content-Type: application/json" -d '{"user_ids":["userID", "secondUserID]}' https://automate.example.com/api/v0/auth/teams/$ID/users | jq
  5. Verify that the user is a member of the team by listing all members of the admins team:

    curl -H "api-token: $TOK" -H "Content-Type: application/json" https://automate.example.com/api/v0/auth/teams/$ID/users | jq