diff --git a/components/automate-chef-io/content/docs/iam-v2-overview.md b/components/automate-chef-io/content/docs/iam-v2-overview.md index 124de2044a4..80954f797a7 100644 --- a/components/automate-chef-io/content/docs/iam-v2-overview.md +++ b/components/automate-chef-io/content/docs/iam-v2-overview.md @@ -10,26 +10,27 @@ toc = true weight = 10 +++ -Chef Automate's Identity and Access Managment (IAM) allows direct management of policy members from Chef Automate in the browser. -IAM supports the projects feature, which allow for filtering and segregation of your data amongst your user base. -IAM policies allow you to use multiple permissions, distinguish policy membership from policy definition for fine-grained control, and include roles for role-based access control. +## Features in IAM v2 -The *policy* exists at the heart of Chef Automate's IAM system. -A policy defines permissions for who may perform what action on which resource and scopes these permissions by project. +IAM v2 policies allow multiple permissions, separating out policy membership from policy definition for fine-grained control, and includes roles for role-based access control. +Additionally, IAM v2 allows policy members to be managed directly from the Automate UI. +Perhaps most significantly, IAM v2 supports projects, which allow for filtering and segregation of your data amongst your user base. + +At the heart of Chef Automate's IAM system is the *policy*. +A policy defines permissions for who may perform what action on which resource scoped by project. The "who" may be a user, a team, or an API token. -The following diagram shows the new policy structure. We detail the specifics in the next sections. +The following diagram shows the policy structure. We will detail the specifics in the next few sections. ![](/images/docs/iam-v2-diagram.png) ## Policy Definition -IAM uses multi-statement policies that support complex permissions. -Each statement in a policy specifies a single permission. -Chef Automate determines a policy's net effect through the evaluation and combinations of permission statements. -If at least one statement allows access, and none denies it, then the policy allows access. Otherwise, access denied. +IAM v2 uses multi-statement policies that support complex permissions in a single policy. +Each statement specifies a single permission. +The net effect (ALLOW or DENY) of a policy is determined by evaluating the effect of each statement and combining them. If there is at least one statement allowing access, and none denying it, then the policy allows access. Otherwise, access is denied. -Access is granted if explicitly allowed in some policy and not explicitly denied in any policy. +Access is granted only if explicitly allowed in some policy and not explicitly denied in any policy. IAM policy evaluation order is: 1. By default, all requests are denied. @@ -38,22 +39,22 @@ IAM policy evaluation order is: ### Net Effect Examples -The following examples illustrate the net effect of a policy and how it grants access to a user: +The following examples illustrate the net effect of a policy and if access is granted to a user: -- User1, or any team that user1 belongs to, does not include a policy with the `iam:users:list` action. - _Net effect_: Access denied to user1 to view the list of users. +- Neither user1, nor any team that user1 belongs to, are included in any policy with the action `iam:users:list`. + _Net effect_: user1 is denied access to view the list of users. This example illustrates the global default DENY condition. - Bob is a member of team alpha and team omega. - Team alpha contains a broad range of permissions, while team omega experiences severe restrictions in what its members may access. - The "major teams" policy has a statement that allows team alpha to access the resource `compliance:reporting:nodes`, while it has another statement that denies Team Omega access to the same resource. - _Net effect_: The policy denies Bob access because at least one statement denies access. + Team alpha has a broad range of permissions while team omega is very restricted in what its members may access. + The "major teams" policy has a statement that allows team alpha to access the resource `compliance:reporting:nodes`, while it has another statement that denies Team Omega access to that very same resource. + _Net effect_: Bob is denied access because there is at least one statement denying access. - Mary is a member of the default viewers team, which allows read access to everything because of the default Viewers policy. Mary is also a member of the deployment team, which has permission to upload and download profiles. - _Net effect_: The policy grants Mary access because membership in both teams effectively allows access. + _Net effect_: Mary is granted both those permissions, which is effectively the union of relevant policies. ### Properties of a Policy -An IAM policy consists of a list of **statements**, where each statement describes a permission. +An IAM v2 policy consists of a list of **statements**, where each statement describes a permission. ### Properties of a Statement @@ -67,36 +68,32 @@ Projects | list of project IDs to constrain the role ### Properties of a Role -An IAM role consists of a list of **actions**. -Some examples of these actions include listing IAM users, getting compliance profiles, or updating node status. -Find more details about roles in [Role-Based Access Control]({{< relref "iam-v2-overview.md#role-based-access-control" >}}). +An IAM v2 role consists of a list of **actions**. Some examples of those actions include listing IAM users, getting compliance profiles, or updating node status. +Roles are discussed in detail in [Role-Based Access Control]({{< relref "iam-v2-overview.md#role-based-access-control" >}}). ## Members and Policies A **member** may be a user, a team, or an API token. -Users and teams may be *local*, meaning their definition exists within Chef Automate only, or managed by an external identity provider, specifically LDAP or SAML. +Users and teams may be *local*, meaning they are defined within Chef Automate, or managed by an external identity provider, specifically LDAP or SAML. IAM v2 policy *membership* is separate and distinct from policy *definition*. (Notice that members were **not** included as part of the [Policy Definition]({{< relref "iam-v2-overview.md#policy-definition" >}}).) -You can edit policy membership for any policy, but you can adjust only the policy definition for *Custom* policies. +You can modify policy membership for any policy, but you can only adjust policy definition for *Custom* policies. ## Policy Types -IAM distinguishes two types of policies: *Chef-managed* and *Custom*. -Chef provides *Chef-managed* policies, which are integral to the operation of Chef Automate. -You cannot change the policy statements in Chef-managed policies. +IAM v2 distinguishes two types of policies: *Chef-managed* and *Custom*. +*Chef-managed* policies are provided by Chef and are integral to the operation of Chef Automate. The policy statements in Chef-managed policies cannot be changed. *Custom* policies are policies that you create for your own needs. You can add, edit, and delete policy statements in your custom policies. -Both types of policies allow for membership modification. +The membership can be modified in both types of policies. ## Role-Based Access Control A role is a named list of actions. -This list provides the benefit of *encapsulation*. -A policy statement only needs the role's name, and the policy is not burdened by all the details. -Also, the list offers *reusability* as you can apply the role to any statement that needs it. +This listing provides the benefits of *encapsulation*, where only the name is needed and is not encumbered by all the details after initial definition, and *reusability*, in applying the role to any statement that needs it. -Chef Automate has five default roles. +Chef Automate has 5 default roles. To see the actions comprising the roles, see [Chef-managed Roles]({{< relref "api/#tag/roles" >}}). Role | Description @@ -107,18 +104,19 @@ Owner | **Do** everything in the system *including* IAM Project Owner | Editor + **view** and **assign** projects Ingest | Ingest data into the system -Just like policies, roles are either *Chef-managed* or *Custom* types. -Default Chef-managed roles cannot change, like Chef-managed policies. -You can use these default Chef-managed roles in your policies, or create your custom roles for more customized permissions. -You can later edit any roles you create. +Just like policies, roles are considered either *Chef-managed* or *Custom*. +These default roles are Chef-managed, so they cannot be changed, like Chef-managed policies. + +You can use these default roles in your own policies, or create your own custom roles for more customized permissions. +Any roles you create can be modified later. -Chef Automate also ships with default policies that leverage these default roles. -The default policies are Viewers, Editors, Administrator, and Ingest. +Chef Automate also has several default policies that leverage these default roles. +The default policies are: Viewers, Editors, Administrator, and Ingest. ## Working with Projects -IAM projects are collections of resources either created in Chef Automate or ingested from external data providers, such as Chef Infra and Chef InSpec. -Projects used in a policy reduce the scope of that policy's permissions to only the resources assigned to the given projects. +IAM v2 projects are collections of resources either created in Chef Automate, or ingested from external data providers, including Chef Infra and Chef InSpec. +Projects are used in a policy to reduce the scope of that policy's permissions to only the resources assigned to the given projects. {{< info >}} Chef Automate limits you to 300 projects. @@ -127,41 +125,38 @@ See [Configuring Project Limit]({{< relref "iam-v2-guide.md#configuring-project- ### Setting Up Projects -Set up IAM projects using the following steps: +IAM v2 projects can be setup using the following steps: -1. Define each project using the browser. +1. Define each project via the UI. Start on the _Projects List_ page to create your projects. -2. Create or edit IAM policy statements to restrict permissions to specific projects as needed. - *Every* statement must either name specific projects, specify the wildcard (`*`), which denotes all projects, or specify as `(unassigned)`, which provides permissions on objects without projects. - By default, any pre-upgrade previous policies are automatically set up with that wildcard, so they apply to all projects. +2. Create or modify IAM policy statements to restrict permissions to specific projects as needed. + *Every* statement must either indicate specific projects, or specify the wildcard (`*`), which denotes all projects. + By default, any previously existing policies are automatically setup with that wildcard so they apply to all projects. 3. [Assign resources to projects]({{< relref "iam-v2-overview.md#assigning-resources-to-projects" >}}). 4. Select the projects to filter in the UI. After creating projects, use the **global project filter** in the top navigation to select one or more projects for viewing. - No selection displays all resources for which you have permission. + No selection means all resources for which you have permission will be displayed. -By default, Chef Automate includes a *project-owner* role, so the global admin may delegate much of these responsibilities for project management to others and share some of the global admin's burden. +By default, Automate includes a *project-owner* role, so the global admin may delegate much of these responsibilities for project management to others and alleviate some of the burden for the global admin. ### Assigning Resources to Projects -Two categories of resources exist for project assignment: +There are two categories of resources that may be assigned to projects: - Ingested client run and compliance nodes - Teams, API Tokens, Policies, and Roles created in Automate -Any of these resources not explicitly assigned to a project is *unassigned*. -After upgrading and before creating projects, all your resources exist as *unassigned*. - -Assign your set of ingested Client Run and Compliance Nodes to projects via the project ingest rules that you create for the project. -An ingest rule specifies one or more conditions, and each condition specifies a set of attribute values that a node must include for assignment to the given project. +Any of these resources that you do not explicitly assign to a project are considered *unassigned* with respect to projects. +After upgrading and before creating projects, all of your resources are considered *unassigned*. +Assigning your set of ingested Client Run and Compliance Nodes to projects is done via the project ingest rules that you create for the project. +An ingest rule specifies one or more conditions, and each condition specifies a set of attribute values that a node must satisfy to be assigned to the given project. Once you define your set of projects with their contained ingest rules and conditions, use the **Update Projects** button on the bottom of any page to apply those definitions. -You can assign teams and API tokens to projects directly in the browser. -You can assign policies and roles only through the command line. -These resources created within Chef Automate do not make use of, nor do they require, any project ingest rules. +Teams and API tokens may be assigned to projects directly in the UI. Policies and roles can only be assigned through the command line. +These resources created within Automate do not make use of, nor do they require, any project ingest rules. -Some resources in Chef Automate respect projects, and will filter when using the project filter. -Resources that do not respect projects will always display and will ignore any applied project filters. +Only some resources in Chef Automate respect projects and only those will be filtered when using the project filter. Resources that do not respect projects will always be displayed and will ignore any applied project filters. #### Resources that respect projects