diff --git a/docs/layers/identity/centralized-terraform-access.mdx b/docs/layers/identity/centralized-terraform-access.mdx index 43da1dd6e..9ae7ab1aa 100644 --- a/docs/layers/identity/centralized-terraform-access.mdx +++ b/docs/layers/identity/centralized-terraform-access.mdx @@ -11,15 +11,9 @@ import KeyPoints from '@site/src/components/KeyPoints'; 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. - -
+## AWS Teams and Team Roles -The following components are designed to provision all primary user and system roles into a centralized identity -account. These components are expected to be used together to provide fine-grained role delegation across the account -hierarchy. +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. ### AWS Teams @@ -36,21 +30,185 @@ assume the role in any account. These roles should be identical in all accounts, such that you can always expect `admin` to be `admin`, `poweruser` to be `poweruser`, and `observer` to be `observer`. The only difference between accounts is which AWS Team is able to -assume the role. +assume the role. We also have a `terraform` role that is used by Terraform to apply changes across all accounts. -### AWS IAM Identity Center (SSO) +### Example -The `aws-sso` component connects AWS IAM Identity Center (Successor to AWS Single Sign-On) Groups to Permission Sets. -Permission Sets grant access to `aws-teams` in the Identity account or (optional) access to an individual account for -convenience. +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: -Permission Sets other than the Identity Team Access Permission Set are used only for console and cli access to a single -account. These are redundant with AWS Team Roles but are useful for quickly accessing a given account with limited -permission. +```mermaid +flowchart LR + subgraph core_identity["core-identity Teams"] + developers["developers"] + devops["devops"] + end + + subgraph dev_account_roles["plat-dev Team Roles"] + admin_dev["admin"] + end + + subgraph prod_account_roles["plat-prod Team Roles"] + observer_prod["observer"] + admin_prod["admin"] + end + + developers --> admin_dev + developers --> observer_prod + devops --> admin_prod + devops --> admin_dev +``` + +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`. + +## Using AWS Identity Center for Single Sign On + +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. + +### Connecting a Permission Set to an AWS Team + +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. + +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. + +From their AWS Team, users can apply Terraform wherever they have access + + +```mermaid +flowchart LR + subgraph identity_center_permission_sets["Identity Center Permission Sets"] + developer_access["IdentityDeveloperTeamAccess"] + devops_access["IdentityDevopsTeamAccess"] + end + + subgraph core_identity_teams["core-identity Teams"] + developers["developers"] + devops["devops"] + end + + subgraph plat_sandbox_roles["plat-sandbox Team Roles"] + terraform_sandbox["terraform"] + end + + subgraph plat_prod_roles["plat-prod Team Roles"] + terraform_prod["terraform"] + planner_prod["planner"] + end + + developer_access --> developers + devops_access --> devops + + developers --> terraform_sandbox + developers --> planner_prod + + devops --> terraform_sandbox + devops --> terraform_prod +``` + +### Centrally Manage Users and Groups with an IdP + +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. + +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 + +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 + +```mermaid +flowchart LR + subgraph external_idp["External Identity Provider"] + user1["User 1"] + user2["User 2"] + user3["User 3"] + group1["Group 1"] + user1 --> group1 + user2 --> group1 + user3 --> group1 + end + + subgraph aws_iam_identity_center["AWS IAM Identity Center"] + user1_copy["User 1 Copy"] + user2_copy["User 2 Copy"] + user3_copy["User 3 Copy"] + group1_copy["Group 1 Copy"] + permissions["Permission Sets"] + user1_copy -.-> group1_copy + user2_copy -.-> group1_copy + user3_copy -.-> group1_copy + group1_copy --> permissions + end + + external_idp -->|Automatic Provisioning| aws_iam_identity_center +``` + +### Access the AWS Web Console with Identity Center + +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. + +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 -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. -### AWS SAML +### Deploying both AWS IAM Identity Center and AWS SAML + +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. + +:::tip AWS IAM Identity Center or AWS SAML? Which do I choose? + +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. + +::: + + +```mermaid +flowchart TB + subgraph "Complete Access Architecture" + subgraph "core-root" + subgraph sso["Identity Center"] + developers_team_access["IdentityDevelopersTeamAccess"] + devops_team_access["IdentityDevopsTeamAccess"] + end + end + + subgraph "core-identity" + subgraph aws_teams["aws-teams"] + devops_teams["devops"] + developers_teams["developers"] + spacelift_teams["spacelift"] + end + end + + subgraph "plat-prod" + subgraph aws_team_roles_prod["aws-team-roles"] + terraform_prod["terraform"] + planner_prod["planner"] + end + end + + subgraph "plat-sandbox" + subgraph aws_team_roles_sandbox["aws-team-roles"] + terraform_sandbox["terraform"] + end + end + + developers_team["Developer Team"] --> developers_team_access + devops_team["DevOps Team"] --> devops_team_access + developers_team_access --> developers_teams + devops_team_access --> devops_teams + + g_suite["G Suite"] -->|SAML Federated Identity| devops_teams + spacelift["Spacelift"] --> spacelift_teams + + developers_teams --> planner_prod + devops_teams --> terraform_prod + spacelift_teams --> terraform_prod + + developers_teams --> terraform_sandbox + devops_teams --> terraform_sandbox + spacelift_teams --> terraform_sandbox + end +``` + +## FAQ + +### Why use AWS SAML? The `aws-saml` component provides SAML access for Admin users to connect to the Identity account admin role `aws-teams` 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. 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. -:::tip AWS IAM Identity Center or AWS SAML? Which do I choose? +```mermaid +flowchart TB + subgraph "Human Access Architecture with AWS SAML" + subgraph "core-identity" + subgraph aws_teams["aws-teams"] + devops_teams["devops"] + developers_teams["developers"] + billing_teams["billing"] + end + end -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. + subgraph "plat-prod" + subgraph aws_team_roles_prod["aws-team-roles"] + admin_prod["admin"] + billing_prod["billing"] + reader_prod["reader"] + end + end -::: + subgraph "plat-sandbox" + subgraph aws_team_roles_sandbox["aws-team-roles"] + admin_sandbox["admin"] + billing_sandbox["billing"] + reader_sandbox["reader"] + end + end + + g_suite["GSuite\nFederated Identity"] -->|SAML| devops_teams + g_suite -->|SAML| developers_teams + g_suite -->|SAML| billing_teams + + developers_teams --> reader_prod + devops_teams --> admin_prod + billing_teams --> billing_prod + + developers_teams --> admin_sandbox + devops_teams --> admin_sandbox + billing_teams --> billing_sandbox + end +``` + +### How do I use AWS IAM Identity Center (SSO)? + +The `aws-sso` component connects AWS IAM Identity Center (Successor to AWS Single Sign-On) Groups to Permission Sets. +Permission Sets grant access to `aws-teams` in the Identity account or (optional) access to an individual account for +convenience. + +Permission Sets other than the Identity Team Access Permission Set are used only for console and CLI access to a single +account. These are redundant with AWS Team Roles but are useful for quickly accessing a given account with limited +permission. + +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. diff --git a/docs/layers/identity/identity.mdx b/docs/layers/identity/identity.mdx index 79f0bb7a8..b4739bf8e 100644 --- a/docs/layers/identity/identity.mdx +++ b/docs/layers/identity/identity.mdx @@ -4,9 +4,13 @@ sidebar_label: "Identity and Authentication" sidebar_class_name: hidden description: Setup fine-grained access control for an entire organization --- -import Intro from '@site/src/components/Intro'; -import KeyPoints from '@site/src/components/KeyPoints'; import ReactPlayer from "react-player"; +import Steps from '@site/src/components/Steps'; +import Step from '@site/src/components/Step'; +import StepNumber from '@site/src/components/StepNumber'; +import ActionCard from '@site/src/components/ActionCard'; +import PrimaryCTA from '@site/src/components/PrimaryCTA'; +import SecondaryCTA from '@site/src/components/SecondaryCTA'; There are several methods available to sign in to AWS through a browser or terminal, such as AWS SAML or IAM Identity Center (successor to AWS Single Sign-On). Various tooling has been tried to support AWS SAML, like "saml2aws," and @@ -25,110 +29,142 @@ demonstrating how it can be used to establish fine-grained access control for an
AI generated voice
-## The Problem +## Our Requirements -One problem that many organizations face is choosing whether to use **AWS SAML** or **AWS IAM Identity Center (SSO)**. +Let’s start by identifying the minimum requirements for an identity and authentication system. -### The Problem with Pure IAM Identity Center Permission Sets + + + ### Accessing AWS as a human or as a machine user. -While **IAM Identity Center (successor to AWS Single Sign-On)** seems like a best fit for managing a single pane of -glass of users and their groups, often the downsides are not caught until later. Downsides such as the inability to -easily switch accounts and difficulty with tooling to ensure a consistent login for different groups while managing an -AWS configuration file for all these different groups. + First we need to implement a system that is easy for both humans and machines to access securely, following the principle of least privilege + + + ### Centralized management of user permissions -This presents a major problem in Terraform, where we need to be able to access the state bucket in the root account, -then deploy resources to any given AWS Account. AWS SSO Permission Sets does not grant multi account access and would -therefor not support any complex Terraform. + Plus, all users and permissions must be centrally managed and integrated into an identity platform. We don’t want to copy and paste permissions across accounts or rely on any manual processes + + + ### Highly precise control of user groups -### The Problem with Pure AWS SAML Team Access Roles + Next, we need fine grained access control for user groups. Then assign users to one or more groups depending on what they need access to. It needs to be easy to understand for both users and administrators. + + + ### Apply Terraform for many accounts across an Organization -**AWS SAML** on the other hand does not provide a central place for managing users, groups, and permissions. But AWS -SAML does provide an easier login experience via the terminal and allows for multiple Identity Providers (IdP). Users -and groups are managed by the IdP, while permissions are managed with AWS Teams and Team Roles with Terraform. + With Terraform, we need to manage resources concurrently across multiple accounts. We don’t want to put this burden on the operator to constantly switch roles, so Terraform needs to do this for us. + + + ### Switch roles into other accounts easily both in the UI and locally -### The Problem with Tooling + Finally for engineers, we want to quickly jump between accounts, access the “AWS” web console, or run “AWS” “CLI” commands without having to think how to do it every time. + + -Tooling is another issue that plagues the AWS login experience. Switching roles in the UI can be solved via a Google -Chrome plugin called [extend-roles](https://github.com/tilfinltd/aws-extend-switch-roles), but that requires using -Chrome, Firefox, or Microsoft Edge (or plug-in compatible browser like Opera) as a web browser. -[Leapp](https://www.leapp.cloud/) is a great tool for logging in, but can be a bit clumsy for switching roles. +## Problem We've Encountered -Another common issue is granting the proper permission for a user to sign into any account. AWS SAML signs into a single -role in the Identity account, and that Identity role should have access to roles in other accounts. On the other hand, -AWS IAM Identity Center grants a Permission Set for each account requiring the user to sign out and sign in to switch -accounts. +Now you may be asking some questions. There are plenty of existing solutions out there for authentication and identity. How did Cloud Posse arrive at their solution? What’s wrong with the alternatives? + + + + ### AWS Control Tower lacked APIs + + First off, you might notice we don’t use AWS Control Tower. That’s because until recently, Control Tower didn’t have an API available. So we couldn’t programmatically manage it with Terraform. Of course Cloud Posse does everything with infrastructure as code, so that was a hard stop for us. + + We’re planning to add support for Control Tower now that it’s available, once it matures. + + + ### AWS IAM Identity Center is only for humans + + The ideal way to access AWS for humans is with Identity Center, formally called “AWS SSO”, and this is included in our reference architecture. But that doesn’t solve how we provide access to machines. For example, integrating with GitHub Actions or Spacelift. + + With Identity Center, a user assumes a single role for one account. That’s not going to work for us with Terraform if we’re trying to apply Terraform concurrently across accounts. For example, transit gateway architecture requires provisioning resources and connecting them across accounts. Identity Center is also limited because it only works with a single IdP. For larger enterprises, multiple IdPs might be used. + + In addition, for the duration of an engagement, Cloud Posse configures our own IdP to access your infrastructure so that it’s easy for you to revoke our access when we’re done. + + + ### AWS IAM Roles with SAML is cumbersome + + We needed to find a solution for machine access and to apply Terraform across accounts. To do that, we can use IAM roles with a SAML provider and assume them in Terraform or third party integrations such as GitHub Actions. + + The challenge then becomes making it easy for users. AWS SAML provides low level controls and is a little more cumbersome to use, especially when you compare how easy it is for users to use the IAM Identity Center. + + How can we have a consistent solution that works for both? + + +
+ +AWS doesn’t make it easy to log in. Control Tower lacked APIs, until recently. Identity Center doesn’t work with automation. And IAM roles with SAML is cumbersome to use. + +It’s gotten a lot better with Identity Center, which is one of the reasons we recommend it, but it still doesn’t solve the problem of how to distribute configurations to developers to easily log in on their workstations or how to use IAM roles with SAML. ## Our Solution -**Our goals: team oriented, highly accessible, easily configured** +### Integrated with Single Sign On + +```mermaid +flowchart LR + user["User"] --> idp["Identity Provider"] + idp --> identity_center["AWS IAM\nIdentity Center"] + identity_center --> aws_team["AWS Team"] + aws_team --> aws_team_role["AWS\nTeam Role"] +``` + +We use Identity Center to easily manage users and groups. These are connected with your Identity provider, such as Okta or GSuite. -Taking into account all the challenges of using AWS SSO and SAML, let's summarize our requirements: +Users can sign into Identity Center to access any account they have access to with fine grained access controls. Administrators have a single place to manage users and can use Terraform to define those fine grained access controls. Then we’ve bridged the gap between Identity Center and IAM roles -- We need the ability to use AWS SAML or AWS IAM Identity Center -- We need a single tool to manage logins to the AWS Console and CLI -- We need the ability to switch roles into other accounts easily, with team and account specific permissions. -- We need to be able to concurrently assume roles into multiple accounts (E.g. with Terraform) +### Team Oriented -### Team Oriented: Multiple AWS Accounts, One Team, with Exact Permissions +```mermaid +flowchart LR + subgraph identity_teams["identity Teams"] + devops["devops"] + end -We introduce the concept of a **_Team_**. This Team is a group of users with access to a given set of accounts with -varying permissions. If using AWS SSO, our convention is to use a one-to-one mapping with a User Group, but this is not -required. + subgraph dev_team_roles["dev Team Roles"] + terraform_dev["terraform"] + end -Every group of users has an identity Team, which the user immediately logs into. This is the purpose of the `identity` -account. From there, the user has the ability to assume roles, which permit the user to "sign-in" to the different AWS -accounts that the team has access. + subgraph staging_team_roles["staging Team Roles"] + terraform_staging["terraform"] + end -We introduce the idea of a **_Team Role_**. This is a role in a given account (like `plat-dev`) that a Team is able to -assume from a Team. Team Roles provide standardized permission for all accounts. These roles are identical in all -accounts, but the only difference is which Team is able to assume the Team Role in that account. + subgraph prod_team_roles["prod Team Roles"] + terraform_prod["terraform"] + end -For example, the `developers` team might have access to assume the `admin` Team Role in the `plat-sandbox` account but -only access to assume the `observer` role in the `plat-prod` account. + devops --> terraform_dev + devops --> terraform_staging + devops --> terraform_prod +``` -### Highly Accessible: No more chrome plugins, no more bash scripts +To simplify managing IAM access roles, we’ve created two concepts. AWS Teams and AWS Team Roles. -Now that we have the roles created with Teams and Team Roles, lets put it to work. +All access in AWS is “Team” oriented. A “Team” is a group of users that we deploy into a central “identity” account. Then we deploy a number of “Team Roles” into every single account. A “Team” can assume any “Team Role” across the organization. -We need a tool that solves many problems listed above while being Multi-OS compatible and ideally programmable. We have -tried several tools, the one that works very well and appears to be gaining exponential traction is -[Leapp](https://www.leapp.cloud/). +We’ll explain in detail in the following pages. -Leapp is a Desktop Application (and has a CLI) that manages your active sessions for your AWS Config. This means it -handles logging in, and assigning those credentials generated to a given AWS profile. +### Highly Accessible -Before continuing on all the problems Leapp solves, we need to state that the AWS Configuration file (`~/.aws/config`) -is usually highly dependent on your sign-in method. Different sign-in methods use different profile configurations. The -beauty of using Leapp is we can have a single config file regardless of your sign-in method. I will discuss this in the -next section. +Then to make it incredibly easy for users to log in, we recommend using Leapp to manage local AWS sessions. Leap supports all Identity Providers and can automatically refresh credentials when they expire. -So Leapp manages our credentials. It does so in a couple beautiful ways. +Plus, it’s open source and free to use. It also offers paid options that make it easier for administrators to share configurations. Please note, the Cloud Posse solution does not require any subscription. -1. It works with any Identity Provider, and since it's an Electron application, it can prompt for sign-in, in the app or - in the browser of choice. -2. It automatically refreshes your AWS credentials before they expire (No mid-terraform apply failures from expired - credentials) -3. If we are using AWS IAM Identity Center (SSO) it will sync the available `PermissionSets` from your login as - available sessions. -4. It's Open Source +### Pre-Configured for your Team -Since we auto-generate an AWS Configuration file and Leapp can use a CLI to create Sessions that manage Profile -credentials, we can set up automated AWS access for AWS IAM Identity Center or AWS SAML. +Finally, to get everyone up and running on your Team, we pre-configured a single, common AWS config for all users. -### Easily Configured: Identity Provider independent Configuration and Sign-in. +We preinstall the AWS config in the Geodesic toolbox, and users will automatically assume the correct access roles in AWS. Users can quickly apply Terraform across accounts and assume roles directly in the accounts they have access. -AWS Configuration files usually differ from AWS IAM Identity Center to AWS SAML. With Leapp however, we can use the same -configuration file and use Chained Roles in Leapp. **Chained Roles** in Leapp assume another role by configuration with -a single user action. For AWS IAM Identity Center this means we can create a Chained Role from our AWS IAM Identity -Center Permission Sets to our Team Entry Point. In regard to **Teams** this means that we can create a Chained Role -session for our **Team Roles** to access `dev` or `prod`. +## Next Steps -## References + + Next, we'll explain how we've implemented this solution in details. -- [extend-roles](https://github.com/tilfinltd/aws-extend-switch-roles) -- [Leapp](https://docs.leapp.cloud/latest/installation/install-leapp/) -- [`aws-teams` component](https://github.com/cloudposse/terraform-aws-components/tree/master/modules/aws-teams) -- [`aws-sso` component](https://github.com/cloudposse/terraform-aws-components/tree/master/modules/aws-sso) -- [`aws-saml` component](https://github.com/cloudposse/terraform-aws-components/tree/master/modules/aws-saml) -- [`aws-teams` component](https://github.com/cloudposse/terraform-aws-components/tree/master/modules/aws-teams) -- [`aws-team-roles` component](https://github.com/cloudposse/terraform-aws-components/tree/master/modules/aws-team-roles) + If you're curious about the thought that went into this process, please review the design decisions documentation. +
+ Next Step + Review Design Decisions +
+