IAM New Docs (#3201)

* IAM docs

* added diagram

* Apply suggestions from code review

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>

* Apply suggestions from code review

* Apply suggestions from code review

* Updates to IAM docs

* Update iam.mdx

* docs: Markdown syntax fixes

* Apply suggestions from code review

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>

---------

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>

website/content/docs/concepts/iam.mdx

@@ -0,0 +1,109 @@
+---
+layout: docs
+page_title: Identity and Access Management (IAM)
+description: |-
+  Identity and Access Management in Boundary
+---
+
+# Identity and access management (IAM)
+## IAM components
+There are 6 key components to Boundary's identity and access management system: **Scopes**, **Auth Methods**, **Accounts**, **Users**, **Groups**, and **Roles**.
+
+### Scopes
+[Scopes](/boundary/docs/concepts/domain-model/scopes) can be considered as containers for resources and permissions. Each scope also has a permissions boundary that is isolated from other scopes on the same level. There are three types of scopes:
+- **Global** - The highest-level scope of Boundary where administrators configure and manage Boundary for the entire company.
+- **Org (Organization)** - Org scopes are contained in the global scope and are typically used to represent business units, organizations, or departments.
+Org scopes can also be used to contain multiple production-level auth methods in separate scopes.
+- **Project** - Project scopes are contained in Org scopes and be used to separate different business workflows. For example, projects can be used to represent different teams, products, or environments (test, dev, prod).
+
+### Auth methods
+[Auth Methods](/boundary/docs/concepts/domain-model/auth-methods) are resources that authenticate users to
+Boundary. Auth methods can only be contained by the global or Org scopes. The available auth methods are:
+- Username/Password
+- [OIDC](/boundary/tutorials/identity-management/oidc-auth)
+- LDAP
+
+### Accounts
+[Accounts](/boundary/docs/concepts/domain-model/accounts) are resources that represent an authenticated user from a trusted identity provider through a Boundary auth method. Accounts must belong to an auth method, and can be associated with a single Boundary user. Boundary accounts can belong to the global or Org Scopes.
+
+### Users
+[Users](/boundary/docs/concepts/domain-model/users) are resources that represent an individual person or entity for the purposes of
+access control. A user can contain multiple accounts from multiple auth methods, and can belong to the global or Org Scopes.
+
+### Groups
+[Groups](/boundary/docs/concepts/domain-model/groups) are resources that represent a collection of users, and can be contained by any
+scope. [Managed groups](/boundary/docs/concepts/domain-model/managed-groups) are a special kind of group that syncs with the auth
+method's identity provider to provide up-to-date information.
+
+### Roles
+[Roles](/boundary/docs/concepts/domain-model/roles) are resources that contain a collection of
+[permissions](/boundary/docs/concepts/security/permissions) which are granted to any principal (user or group) from any scope. Roles
+can be contained by any scope, and the permissions can be applied to the same scope or any child scope.
+
+## Access management
+### Configuring users - username/password
+There are 3 steps to adding new users to Boundary using the password auth method:
+1. Choose the **scope** and the **auth method** that the user will use to authenticate to Boundary. If the desired auth method does not exist, you must create a new one.
+2. After the auth method is selected, you can create an **account** under the auth method.
+3. In the same scope, create a new **user**, and then attach the new account to the new user. The user is now able to authenticate to Boundary.
+
+### Configuring users - OIDC/LDAP
+[OIDC](/boundary/tutorials/identity-management/oidc-auth) and LDAP accounts and users are auto-vivified (automatically generated) in Boundary in the same scope
+as the auth method. The accounts and users are only created once the user authenticates to Boundary for the first time. The same applies to OIDC/LDAP
+[managed groups](/boundary/tutorials/identity-management/oidc-idp-groups).
+
+### Granting permissions
+When setting up access controls for a user, it is important to first consider which scope(s) the user needs access to. **Each scope requires its own set of roles**,
+giving users permission to perform actions through [grants strings](/boundary/docs/concepts/security/permissions/grants).
+It is recommended to add the user to a group, and then add the group to the role(s), instead of adding the user directly to the role(s). This way, you can manage multiple users at the same time, and it is easier to
+change the permissions of the user by adding/removing them from groups. You can manage OIDC/LDAP users and managed groups the same way, directly in the provider.
+
+## Examples
+Here are a few examples of access management for personas, using this sample scope structure. In this structure, there are 7 scopes overall: 1 global, 2 Orgs, and 4
+Projects. To learn more about writing grants, refer to [grants strings](/boundary/docs/concepts/security/permissions/grants).
+
+![IAM Example Structure](/img/iam-example-structure.png)
+
+### Boundary admin
+1. **Each** of the 7 scopes requires a role (ex. “admin”)
+2. Each role needs to have the user/group added as a principal
+3. Each role needs to have the grants of
+
+   -   `id=*;type=*;actions=*`
+
+### Boundary Viewer
+1. **Each** of the 7 scopes requires a role (ex. “viewer”)
+2. Each role needs to have the user/group added as a principal
+3. Each role needs to have the grants of
+
+   -   `id=*;type=*;actions=read,list`
+
+### Org_A admin
+1. The following scopes **each** require a role (ex. “admin”)
+    - Org_A
+    - Project_1
+    - Project_2
+2. Each role needs to have the user/group added as a principal
+3. Each role needs to have the grants of
+
+   -   `id=*;type=*;actions=*`
+
+### Project_1 admin
+1. Project_1 requires a role (ex. “admin”)
+2. The role needs to have the user/group added as a principal
+3. The role needs to have the grants of
+
+   -   `id=*;type=*;actions=*`
+
+### Project_1 target access
+1. Project_1 requires a role (ex. “target_access”)
+2. The role needs to have the user/group added as a principal
+3. The role needs to have the grants of
+
+   -   `id=*;type=target;actions=list,read,authorize-session`
+   -   `id=*;type=session;actions=read:self,cancel:self,list`
+
+<Tip>
+You can use the same roles across “Boundary Admin”, “Org_A Admin”, and “Project_1 Admin” since the scopes and grants are the same. The only difference is
+the users/groups that are added to each role.
+</Tip>

website/data/docs-nav-data.json

@@ -115,6 +115,10 @@
         "title": "Overview",
         "path": "concepts"
       },
+      {
+        "title": "Identity and Access Management",
+        "path": "concepts/iam"
+      },
       {
         "title": "Service Discovery",
         "path": "concepts/service-discovery"