IAM v2 Users Guide

This guide shows you how to upgrade Chef Automate to IAM v2, perform important administrative operations, and revert back to IAM v1. After upgrading to IAM v2, you will add members to Chef-managed v2 policies, delete a legacy policy, and write a Team Admin v2 policy that lets a Team Admin manage their users and teams.

Upgrade to IAM v2

To get the best possible IAM v2 experience, Chef Automate should be running the latest version before upgrading to IAM v2.

Perform the upgrade to IAM v2 with chef-automate iam upgrade-to-v2. The response from your terminal should look something like:

Upgrading to IAM v2.1
Migrating v1 policies...
Creating default teams Editors and Viewers...

Migrating existing teams...

Success: Enabled IAM v2.1

To upgrade without porting existing policies, use the command: chef-automate iam upgrade-to-v2 --skip-policy-migration.

View Policies

After you have signed in to Chef Automate, select the Settings tab in the top navigation bar, and then select and locate the Policies section in the left navigation.

In this section, you can view all of your v2 policies. If you have upgraded without using the --skip-policy-migration flag, you will also see v1 policies.

This policy display includes the following:

  • New default, Chef-managed policies: Administrator, Ingest, Editors, and Viewers.
  • Imported v1 default policies–now called legacy policies–in the new v2 policy format and marked with the [Legacy] prefix.
  • Imported v1 custom policies that you created, which are marked with the [Legacy] prefix and a (custom) suffix.

Policy Conversion

After upgrading, we recommend that you reconstitute your v1 policies as v2 policies. Once this policy conversion is done, delete the old legacy v1 policies and you will have an up-to-date system.

To delete a legacy policy, open the menu on any custom policy, which is located at the end of the policy row, and select Delete Policy from the menu. You will not have this option for Chef-managed policies.

A warning appears if members are still attached to the policy because deleting that policy disrupts access for all of its members. However, you will still be able to delete the policy.

In the rare situation that you include the command --skip-policy-migration when upgrading, no existing v1 policies will be migrated. You will still need to create new v2 policies to preserve any IAM behavior from v1.

Note: Several legacy policies, including Compliance Profile Access and Ingest Access, have API tokens that will stop working if not ported.

The next few sections explain how to use Chef-managed policies and how to create custom policies.

Using Chef-Managed Policies

In this example conversion, you will create two local users and add them to default teams that are automatically included in default policies. Note that you could also add users directly to policies without the intermediate teams, but using teams can make managing your system more flexible.

Create Users

Follow the instructions on Creating Users to:

  • Create a local user with the username test_viewer.
  • Create a local user with the username test_editor.

Add Users to Teams

Select Teams from the left navigation of the Settings tab. Three teams are provided by default: admins, viewers, and editors.

Follow the instructions for Adding Users to a Team to:

  • Add the user test_viewer to the Chef-managed viewers team.
  • Add the user test_editor to the Chef-managed editors team.

After upgrading, those teams will be part of the Viewers and Editors policies, respectively. The default Viewers policy is provided, so you can quickly grant read-only access to everything in Chef Automate, except for admin resources. Similarly, the default Editors policy is provided, so you can quickly grant complete access to everything in Chef Automate, except for admin resources. Once this step is done, the test_viewer and test_editor users may log in with appropriate system access.

Creating Custom Policies

The Chef-managed default policies give you a starting-point for permissions. You may want to write more fine-grained policies, tailored to the demands of your organization. Defining your own policies must be done from the command line.

As an example, let us say that you, the admin, want to delegate a portion of your tasks to a colleague, but without granting them full admin access. In this case, you could create a policy called Team Devops Managers, which grants its members some–but not all–administrative privileges. Create a JSON file in the editor of your choice. Following JSON syntax, begin with the name property.

See the end of this section for a complete JSON policy example

  "name": "Team Devops Managers",

The name field is for human consumption. When you want to refer to the policy in commands, you will need to know the policy’s ID. So let us give this policy the ID value: team-managers-devops.

  "id": "team-managers-devops",

Additionally, we can permission actions on this policy just like any other IAM resource by assigning it to one or more projects. If we leave the projects array empty, then we indicate the policy is unassigned. For example, anyone with permission to view unassigned policies can view this policy.

  "projects": [],

Let us further assume you want user Bob as well as anyone on team gamma to be authorized by this policy. This grouping comprises the members array, as seen below.

  "members": [
    "user:local:bob",
    "team:local:gamma",
  ],

Next, you will specify the permissions themselves–which in IAM v2 are the statements– declared as an array. The statement allows us to specify the actions a user is permitted to take upon resources that have been assigned to a project. The projects field on a statement is an array that may contain more than one existing project, a wildcard * to indicate permission to resources in any project, or (unassigned) to indicate permission to resources that have not been assigned to a project.

Note that the projects property in statements designates permission for the resources within the statement (here, that is iam:users and iam:teams), not for the policy itself, and cannot be left empty. For more about projects, please see Projects or Projects Property documentation.

In this case, we only need a single statement providing access to the get, list, and update actions for users and teams that have been assigned to the project project-devops.

    {
      "effect": "ALLOW",
      "actions": [
        "iam:users:update",
        "iam:users:list",
        "iam:users:get",
        "iam:teams:update",
        "iam:teams:list",
        "iam:teams:get"
      ],
      "projects": ["project-devops"],
    },

Complete JSON Policy Example

{
  "name": "Team Devops Managers",
  "id": "team-managers-devops",
  "projects": [],
  "members": [
    "user:local:bob",
    "team:local:gamma"
  ],
  "statements": [
    {
      "effect": "ALLOW",
      "actions": [
        "iam:users:update",
        "iam:users:list",
        "iam:users:get",
        "iam:teams:update",
        "iam:teams:list",
        "iam:teams:get"
      ],
      "projects": ["project-devops"]
    }
  ]
}

Save your JSON file and follow the steps in Creating a Policy to send that policy data to Chef Automate.

Policy Membership

Users, teams, and API tokens can all be policy members. Both users and teams can be either locally or externally managed with LDAP or SAML.

Local Users and Teams

Local users and teams are managed directly by Chef Automate.

To add or delete members, navigate to the Policies list in the Settings tab, and then select a policy in the list to open its details. Select Members to view the current membership. Use the Add Members button to open a list of candidate members. This lists all those local members (both users and teams) that are not members of this policy. If all of the local members are already included in the policy, then this list will be empty. Select any members you wish to add to the policy. Use the Add Members button to complete the operation. This takes you back to the policy details, showing the revised membership list.

Member Expressions

Member expressions are required for externally managed users, and teams, as well as API tokens.

LDAP and SAML users’ information is saved outside of Chef Automate. You will need to manually enter the provider-qualified user or team. To do this, open any policy from the Policies list, then select Members. Select Add Members to open the list of candidate local users and teams. Near the bottom of the page, select the Add Member Expression button.

Enter a member expression using the format team:<type>:<name> or user:<type>:<name>. Note that these expressions are case-sensitive.

  • The <type> expression is either ldap or saml.
  • The <name> expression is the name of the user or team that the external identity provider knows. For example, this is a valid member expression team:ldap:editors_team_1, assuming the editors_team_1 team is known by your identity provider.

Alternately, you may add all teams to a policy using a wildcard as the last term in the member expression: team:ldap:* or team:saml:*.

The member expression dialog also supports tokens. You enter a token using the expression token:<id>. In order to find a token’s ID, visit the API Tokens page.

Projects

Projects are used to group and permission Chef Automate resources as well as ingested data, specifically Compliance reports, Chef Server and Compliance events, and Infrastructure nodes.

Projects can be managed via the Projects list under the Settings tab and consist of an ID, a name, and a collection of ingest rules. Project ingest rules are lists of conditions used only when assigning ingested resources to projects, so they are not relevant when assigning IAM resources such as teams or roles.

Creating a Project

To create a project, navigate to the Projects list under the Settings tab and select Create Project. You will need to provide a name and can optionally edit the ID. You must create a project before you can assign any resources to it.

Assigning Resources to Projects

Projects can be assigned to Automate-created resources on creation or update.

To assign a team to projects, select a team from the Teams list, then select Details. Likewise, to assign a token to projects, select a token from the API tokens list, then select Details. In either case, you can select projects from the projects dropdown to assign.

You may also assign teams and tokens to projects on creation. In the creation modal, select any projects to which the new resource should belong.

Presently, policies and roles can only be assigned to projects using the command line, not the browser. Users cannot be assigned to projects from the browser or the command line.

If you would like to delegate ownership of a project to another user so that they may assign resources, you will want to make that user a Project Owner of that project.

Assigning Ingested Resources to Projects

While Automate’s local teams and tokens can be directly assigned to a project, ingested resources must be assigned to projects using ingest rules.

Project ingest rules are used to associate ingested resources with projects within Automate. An ingest rule contains conditions that determine if an ingested resource should be moved into the rule’s project. Each condition contains an attribute, operator, and value. See Project Rules for details on how to manage project rules.

In this example, after creating a project with the ID project-devops, you will add an ingest rule to this new project. You will update projects to apply this new project rule, causing all matching ingested resources to be associated with project-devops. You will then use the global project filter to filter your ingested data by project-devops.

First, determine which ingested resources should belong to the project. In this example, we want to add the following ingested resources to project-devops:

  • Compliance reports with Chef Organization devops
  • Infrastructure nodes with Environment dev and Chef Tag devops-123
  • actions on Chef Servers devops.pizza or devops.dog

You may want to verify that those filters work as expected on the Event Feed, Client Runs, and Reports pages.

Navigate to the project details page of project-devops, by selecting the project name on the project list page.

Select the Create Rule button to create a new project rule. Choose the resource type Node, then fill in the first condition’s fields. Feel free to create fake ingest data that corresponds to the example json below, or come up with a condition that matches your existing data set.

Compliance reports must be using audit cookbook 7.5+ in order to make use of all of the available project rule attributes. Older reports will only have Environment and Chef Role available as attributes.
{
  "id": "devops-rule",
  "name": "devops rule",
  "type": "NODE",
  "project_id": "project-devops",
  "conditions": [
    {
      "operator": "EQUALS",
      "attribute": "CHEF_ORGANIZATION",
      "values": [
        "devops"
      ]
    }
  ]
}

Save the rule. If you later need to change the name or the conditions, select the project rule name on the project details page.

You should see a message that says Edits are pending: update projects to apply edits. Select the projects link in the message to go back to the project list page.

On the project list page, the button Update Projects should be enabled since a new rule has been added to a project. You should also see Edits pending in the Ingest Rules column of project-devops in the projects table. Select Update Projects and confirm the action in the modal that pops up.

Updating a project begins an operation that applies all pending rule edits and then moves ingested resources into the correct projects according to those latest changes. An ingested resource is moved into a project if it matches at least one of the project’s rules. In this example, upon successful update, all ingested resources whose Chef Organization matches devops will be considered a part of the project project-devops. Only these resources will appear in Automate’s dashboards when the project-devops project has been selected in the global project filter.

As the operation takes place, you should see a percentage count up within the Update Projects button. You may cancel the update at any time by selecting Stop Updating Projects and confirming the cancel in the modal that pops up.

Avoid stopping an update unless absolutely necessary. It will leave your system in an unknown state where only some resources have been moved into their projects while others still remain in old projects. Only another successful update will restore the system to an up-to-date state.

Once rules have been successfully applied, the update button will change to Projects Up-to-Date and be disabled until the next time there are pending edits to any project.

To verify that the ingested resources have been moved into the correct projects, select project-devops in the global projects filter, which is on the top navigation. The data in Automate will now be filtered by the selected project. In this example, the effect is revealed by navigating to the Compliance Reports’ Nodes tab, which only features nodes that belong to the devops Chef Organization.

Now that we have the first set of our ingested data associated with our new project, let us add another condition and a new rule to add more data to project-devops.

Compliance and Infrastructure ingested resources are not the exact same nodes, so their properties may not be the same. Separate conditions governing said resources may need to be used if their properties do not match exactly.
Ingested events require conditions of Event type to be associated with the correct project. A condition of type Node will not match an event, even if the condition’s operator, attribute, and value all match exactly (and vice versa with Event project rules and nodes).

Return again to the project detail page and create two new ingest rules by selecting Create Rule. Creating new rules will expand the data set under project-devops, because an ingested resource need only match one rule to be placed in the project.

The first rule should contain two conditions. Fill in the first condition with attribute Environment, operator equals, and value dev, or any value matching your data set. Select Add Condition to add another condition with attribute Chef Tag, operator equals, and devops-123. Save the rule.

Adding conditions further restricts the ingested data because every condition must be true for an ingested resource to be placed in the project.

For the second rule, choose resource type Event. Fill in the first condition with attribute Chef Server, operator member of, and value devops.pizza, devops.dog, or any values matching your data set.

Setting the project rule Resource Type determines what condition attributes are available to select. Event rule conditions can only have the attributes Chef Organization or Chef Server.

Rules of type Node can have conditions with attributes Chef Organization, Chef Server, Environment, Chef Role, Chef Tag, Chef Policy Name, Chef Policy Group.

Navigate to the project list page once more. Select Update Projects. Upon completion of the update, you should be able to filter by project-devops across Automate’s dashboards and see only the ingested data that you expect.

Project Owners

The role Project Owner allows admin users to delegate management of project membership to another user without granting that user access to other admin actions in Chef Automate. Project Owners have the following permissions on resources assigned to their project:

"infra:*",
"compliance:*",
"system:*",
"event:*",
"ingest:*",
"secrets:*",
"telemetry:*",
"iam:projects:list",
"iam:projects:get",
"iam:projects:assign",
"iam:policies:list",
"iam:policies:get",
"iam:policyMembers:*",
"iam:teams:list",
"iam:teams:get",
"iam:teamUsers:*",
"iam:users:get",
"iam:users:list"

In order to create a Project Owner, you can use an existing user, or create a user with username test_project_owner by following Creating Users.

Next, you will create a policy that gives test_project_owner the role of project-owner for your new project. The policy will look like the JSON below:

{
  "name": "Project Devops Policy",
  "id": "project-devops-policy",
  "projects": ["project-devops"],
  "members": [ "user:local:test_project_owner"],
  "statements": [
    {
      "effect": "ALLOW",
      "role": "project-owner",
      "projects": ["project-devops"]
    }
  ]
}

By adding project-devops to the policy’s top-level projects field, we ensure that the Project Owner has access to this policy.

Save as a JSON file and follow the steps in Creating a Policy to send that data to Chef Automate.

Editor and Viewer Policies for Projects

You may additionally choose to create a Project Devops Editors policy and a Project Devops Viewers policy. Once those are in place, you or your project-devops Owner can add members to each policy to give them privileges to view or edit resources assigned to Project Devops. To create those policies, use the JSON below for Project Viewers Policy and Project Editors Policy, respectively:

Project Viewers Policy
{
  "name": "Project Devops Viewers",
  "id": "project-devops-viewer-policy",
  "projects": ["project-devops"],
  "members": [],
  "statements": [
    {
      "effect": "ALLOW",
      "role": "viewer",
      "projects": ["project-devops"]
    }
  ]
}
Project Editors Policy
{
  "name": "Project Devops Editors",
  "id": "project-devops-editor-policy",
  "projects": ["project-devops"],
  "members": [],
  "statements": [
    {
      "effect": "ALLOW",
      "role": "editor",
      "projects": ["project-devops"]
    }
  ]
}

Now, if you would like Terry, a user, to be able to view Project Devops and Kelly, another user, to be able to edit Project Devops, you will add them as members to the relevant policies. You can do that directly in the above JSON when creating the policy, or in the browser by selecting Settings, then Policies, and lastly Project Devops Policy. Under the Details tab, you will find the option to select new policy members.

Assuming Terry is not a member of any other policy, once you make Terry a member of the Project Devops Viewers policy, they will only be able to see resources assigned to Project Devops. They will not be able to update or delete them. Kelly, however, will be able to do both.

See Policy Membership for more information on policy membership.

Restoring Admin Access

While we have safeguards to prevent it, it is possible to lock yourself out of Chef Automate. If you have root access to the node where Chef Automate is installed, use the following commands to restore admin access:

This command, which is also available on IAM v1, resets the local admin user’s password and ensures that user is a member of the local admins team, which is a permanent member of the Chef-managed Administrator policy.

  chef-automate iam admin-access restore <your new password here>

Generate a new token and add that token as a new member of the Chef-managed Administrator policy. This command is the equivalent of the v1 command chef-automate admin-token.

  chef-automate iam token create <your token name here> --admin

Reverting to IAM v1

Reverting to IAM v1 discards your IAM v2 policies, roles, and projects, and re-configures Chef Automate to use your v1 policies again.

To revert back to IAM v1, use:

$ chef-automate iam reset-to-v1