Skip to content

Commit 276ecaa

Browse files
milldraknysh
milldr
and
aknysh
authored
feat: Improve Identity Documentation (#665)
Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com>
1 parent 8790c5d commit 276ecaa

File tree

2 files changed

+340
-99
lines changed

2 files changed

+340
-99
lines changed

‎docs/layers/identity/centralized-terraform-access.mdx

Lines changed: 226 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,9 @@ import KeyPoints from '@site/src/components/KeyPoints';
1111
This is an overview of our approach to centralized access management and the relationships between the components used to implement it. It explains how SAML, SSO, and custom constructs for AWS teams and team roles interact to provide efficient role delegation and authentication across an AWS Organization.
1212
</Intro>
1313

14-
<img
15-
src="https://lucid.app/publicSegments/view/1eac6776-c23f-4b1f-8aec-c7f540470746/image.png"
16-
style={{ width: "100%", minHeight: "480", height: "auto", margin: "10", position: "relative" }}
17-
/>
18-
<br />
14+
## AWS Teams and Team Roles
1915

20-
The following components are designed to provision all primary user and system roles into a centralized identity
21-
account. These components are expected to be used together to provide fine-grained role delegation across the account
22-
hierarchy.
16+
Why do we need Teams and Team Roles when we have the same thing in Identity Center? To explain that, let’s first explain what they do and how we’ve integrated them.
2317

2418
### AWS Teams
2519

@@ -36,21 +30,185 @@ assume the role in any account.
3630

3731
These roles should be identical in all accounts, such that you can always expect `admin` to be `admin`, `poweruser` to
3832
be `poweruser`, and `observer` to be `observer`. The only difference between accounts is which AWS Team is able to
39-
assume the role.
33+
assume the role. We also have a `terraform` role that is used by Terraform to apply changes across all accounts.
4034

41-
### AWS IAM Identity Center (SSO)
35+
### Example
4236

43-
The `aws-sso` component connects AWS IAM Identity Center (Successor to AWS Single Sign-On) Groups to Permission Sets.
44-
Permission Sets grant access to `aws-teams` in the Identity account or (optional) access to an individual account for
45-
convenience.
37+
Consider this example. We want to enable the “DevOps” to assume Administrator in multiple accounts, such as `dev` or `prod`. However, “developers” can only assume admin in `dev`. Here’s how that would work:
4638

47-
Permission Sets other than the Identity Team Access Permission Set are used only for console and cli access to a single
48-
account. These are redundant with AWS Team Roles but are useful for quickly accessing a given account with limited
49-
permission.
39+
```mermaid
40+
flowchart LR
41+
subgraph core_identity["core-identity Teams"]
42+
developers["developers"]
43+
devops["devops"]
44+
end
45+
46+
subgraph dev_account_roles["plat-dev Team Roles"]
47+
admin_dev["admin"]
48+
end
49+
50+
subgraph prod_account_roles["plat-prod Team Roles"]
51+
observer_prod["observer"]
52+
admin_prod["admin"]
53+
end
54+
55+
developers --> admin_dev
56+
developers --> observer_prod
57+
devops --> admin_prod
58+
devops --> admin_dev
59+
```
60+
61+
In the `core-identity` account, we have a `developers` team and a `devops` team. Then in the `plat-dev` account, we have an `admin` team role. And in the `plat-staging` account we have an `admin` and an `observer` team role. With our design, the `developers` team can assume `admin` only in `plat-dev`, but the `devops` team can assume `admin` in both `plat-dev` and `plat-staging`.
62+
63+
## Using AWS Identity Center for Single Sign On
64+
65+
Now how does AWS IAM Identity Center fit in? Let’s see how we can connect AWS Teams and Team roles with Identity Center to complete the picture.
66+
67+
### Connecting a Permission Set to an AWS Team
68+
69+
Identity Center has the concept of Permission Sets. Permission Sets determine what a user can or cannot do. We simply connect those Permission Sets to one of our Teams.
70+
71+
We define a special Permission Set for the `core-identity` account, called the `Identity{X}TeamAccess` Permission Set. This Permission Set has access to assume the related AWS Team. For example, the `IdentityDeveloperTeamAccess` permission set can assume the `developers` team and the `IdentityDevopsTeamAccess` permission set can assume the `devops` team.
72+
73+
From their AWS Team, users can apply Terraform wherever they have access
74+
75+
76+
```mermaid
77+
flowchart LR
78+
subgraph identity_center_permission_sets["Identity Center Permission Sets"]
79+
developer_access["IdentityDeveloperTeamAccess"]
80+
devops_access["IdentityDevopsTeamAccess"]
81+
end
82+
83+
subgraph core_identity_teams["core-identity Teams"]
84+
developers["developers"]
85+
devops["devops"]
86+
end
87+
88+
subgraph plat_sandbox_roles["plat-sandbox Team Roles"]
89+
terraform_sandbox["terraform"]
90+
end
91+
92+
subgraph plat_prod_roles["plat-prod Team Roles"]
93+
terraform_prod["terraform"]
94+
planner_prod["planner"]
95+
end
96+
97+
developer_access --> developers
98+
devops_access --> devops
99+
100+
developers --> terraform_sandbox
101+
developers --> planner_prod
102+
103+
devops --> terraform_sandbox
104+
devops --> terraform_prod
105+
```
106+
107+
### Centrally Manage Users and Groups with an IdP
108+
109+
We still need some method to manage users and groups. AWS Teams and Team roles grant groups of users access, but do not define or manage users. AWS IAM Identity Center ties together Teams and Team roles with a predefined set of users and groups.
110+
111+
Although you may choose to manage users and groups directly in Identity Center, the vast majority of our customers choose to use a SAML IdP as the source of truth for their users and groups. With a SAML IdP, users and groups are not created in AWS. Instead, we connect a third-party Identity Provider, such as GSuite, JumpCloud or Okta. Then we manage all Users and Groups in that IdP
112+
113+
With “automatic provisioning” in AWS, we can synchronize all users and groups from the IdP into AWS. Then we can create Permission Sets in AWS to assign to those groups. We can assign Permission Sets to Groups for any given account. A Permission Set, such as `AdministratorAccess` or `ReadOnlyAccess`, is granted to a given group for some account. This way, we only need to define the Permission Sets once each
114+
115+
```mermaid
116+
flowchart LR
117+
subgraph external_idp["External Identity Provider"]
118+
user1["User 1"]
119+
user2["User 2"]
120+
user3["User 3"]
121+
group1["Group 1"]
122+
user1 --> group1
123+
user2 --> group1
124+
user3 --> group1
125+
end
126+
127+
subgraph aws_iam_identity_center["AWS IAM Identity Center"]
128+
user1_copy["User 1 Copy"]
129+
user2_copy["User 2 Copy"]
130+
user3_copy["User 3 Copy"]
131+
group1_copy["Group 1 Copy"]
132+
permissions["Permission Sets"]
133+
user1_copy -.-> group1_copy
134+
user2_copy -.-> group1_copy
135+
user3_copy -.-> group1_copy
136+
group1_copy --> permissions
137+
end
138+
139+
external_idp -->|Automatic Provisioning| aws_iam_identity_center
140+
```
141+
142+
### Access the AWS Web Console with Identity Center
143+
144+
With Identity Center, it’s very easy to log into the AWS web console. Simply open the Single Sign On Portal link, and select the account and role you want to access.
145+
146+
For example, if I wanted to connect to `plat-prod` with “Read Only” access, then I would select the `ReadOnlyAccess` Permission Set for `plat-prod`. AWS then will launch a new session with the appropriate permissions in production
50147

51-
With AWS IAM Identity Center, you can directly access a specific account from the single sign-on page, which will automatically assume the role with the associated `PermissionSet`. This is great for web console usage but not ideal for locally applying Terraform. With Terraform, we need to apply changes across many accounts, where each account has its own role. We don't want to assume a new role each time we change accounts. To solve this, we have a specific Permission Set that can assume an AWS team role in the identity account. When applying Terraform, we assume that "team" role via SSO, and when accessing the web console, we use the Permission Set directly.
52148

53-
### AWS SAML
149+
### Deploying both AWS IAM Identity Center and AWS SAML
150+
151+
AWS IAM Identity Center and AWS SAML are not mutually exclusive solutions. They can be used together to provide a seamless login experience for users. Cloud Posse frequently deploys both in customer environments - AWS SAML to log in ourselves for the duration of the engagement and AWS IAM Identity Center for the customer to use and support. That way the customer can access AWS via their chosen Identity Provider (IdP), and we can use GSuite SAML to access the Identity account team directly. When an engagement is complete, we can easily decommission our access by removing the SAML connection.
152+
153+
:::tip AWS IAM Identity Center or AWS SAML? Which do I choose?
154+
155+
The vast majority of our customers prefer AWS IAM Identity Center (SSO). The convenience of a web console login is hard to beat. However, some customers prefer SAML for its simplicity and compatibility with existing systems. We support both methods, and you can choose the one that best fits your needs.
156+
157+
:::
158+
159+
160+
```mermaid
161+
flowchart TB
162+
subgraph "Complete Access Architecture"
163+
subgraph "core-root"
164+
subgraph sso["Identity Center"]
165+
developers_team_access["IdentityDevelopersTeamAccess"]
166+
devops_team_access["IdentityDevopsTeamAccess"]
167+
end
168+
end
169+
170+
subgraph "core-identity"
171+
subgraph aws_teams["aws-teams"]
172+
devops_teams["devops"]
173+
developers_teams["developers"]
174+
spacelift_teams["spacelift"]
175+
end
176+
end
177+
178+
subgraph "plat-prod"
179+
subgraph aws_team_roles_prod["aws-team-roles"]
180+
terraform_prod["terraform"]
181+
planner_prod["planner"]
182+
end
183+
end
184+
185+
subgraph "plat-sandbox"
186+
subgraph aws_team_roles_sandbox["aws-team-roles"]
187+
terraform_sandbox["terraform"]
188+
end
189+
end
190+
191+
developers_team["Developer Team"] --> developers_team_access
192+
devops_team["DevOps Team"] --> devops_team_access
193+
developers_team_access --> developers_teams
194+
devops_team_access --> devops_teams
195+
196+
g_suite["G Suite"] -->|SAML Federated Identity| devops_teams
197+
spacelift["Spacelift"] --> spacelift_teams
198+
199+
developers_teams --> planner_prod
200+
devops_teams --> terraform_prod
201+
spacelift_teams --> terraform_prod
202+
203+
developers_teams --> terraform_sandbox
204+
devops_teams --> terraform_sandbox
205+
spacelift_teams --> terraform_sandbox
206+
end
207+
```
208+
209+
## FAQ
210+
211+
### Why use AWS SAML?
54212

55213
The `aws-saml` component provides SAML access for Admin users to connect to the Identity account admin role `aws-teams`
56214
without AWS IAM Identity Center (Successor to AWS Single Sign-On).
@@ -60,8 +218,55 @@ Follow the Identity Providers documentation for adding a SAML login.
60218

61219
With AWS SAML, we create a federated SAML login that connects to the "team" in the identity account, and then users can assume other roles from there. We use the [AWS Extend Switch Roles plugin](https://github.com/tilfinltd/aws-extend-switch-roles) that makes this much easier, but it's not as intuitive as Identity Center.
62220

63-
:::tip AWS IAM Identity Center or AWS SAML? Which do I choose?
221+
```mermaid
222+
flowchart TB
223+
subgraph "Human Access Architecture with AWS SAML"
224+
subgraph "core-identity"
225+
subgraph aws_teams["aws-teams"]
226+
devops_teams["devops"]
227+
developers_teams["developers"]
228+
billing_teams["billing"]
229+
end
230+
end
64231
65-
The vast majority of our customers prefer AWS IAM Identity Center (SSO). The convenience of a web console login is hard to beat. However, some customers prefer SAML for its simplicity and compatibility with existing systems. We support both methods, and you can choose the one that best fits your needs.
232+
subgraph "plat-prod"
233+
subgraph aws_team_roles_prod["aws-team-roles"]
234+
admin_prod["admin"]
235+
billing_prod["billing"]
236+
reader_prod["reader"]
237+
end
238+
end
66239
67-
:::
240+
subgraph "plat-sandbox"
241+
subgraph aws_team_roles_sandbox["aws-team-roles"]
242+
admin_sandbox["admin"]
243+
billing_sandbox["billing"]
244+
reader_sandbox["reader"]
245+
end
246+
end
247+
248+
g_suite["GSuite\nFederated Identity"] -->|SAML| devops_teams
249+
g_suite -->|SAML| developers_teams
250+
g_suite -->|SAML| billing_teams
251+
252+
developers_teams --> reader_prod
253+
devops_teams --> admin_prod
254+
billing_teams --> billing_prod
255+
256+
developers_teams --> admin_sandbox
257+
devops_teams --> admin_sandbox
258+
billing_teams --> billing_sandbox
259+
end
260+
```
261+
262+
### How do I use AWS IAM Identity Center (SSO)?
263+
264+
The `aws-sso` component connects AWS IAM Identity Center (Successor to AWS Single Sign-On) Groups to Permission Sets.
265+
Permission Sets grant access to `aws-teams` in the Identity account or (optional) access to an individual account for
266+
convenience.
267+
268+
Permission Sets other than the Identity Team Access Permission Set are used only for console and CLI access to a single
269+
account. These are redundant with AWS Team Roles but are useful for quickly accessing a given account with limited
270+
permission.
271+
272+
With AWS IAM Identity Center, you can directly access a specific account from the single sign-on page, which will automatically assume the role with the associated `PermissionSet`. This is great for web console usage but not ideal for locally applying Terraform. With Terraform, we need to apply changes across many accounts, where each account has its own role. We don't want to assume a new role each time we change accounts. To solve this, we have a specific Permission Set that can assume an AWS team role in the identity account. When applying Terraform, we assume that "team" role via SSO, and when accessing the web console, we use the Permission Set directly.

0 commit comments

Comments
 (0)