feat(DEV-2500): Identity Docs Improvements (#670)

.github/actions/build-website/action.yml

@@ -30,11 +30,6 @@ runs:
         role-to-assume: ${{ inputs.iam_role_arn }}
         role-session-name: ${{ inputs.iam_role_session_name }}
 
-    - name: Checkout Repository
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-
     - name: Setup Node
       uses: actions/setup-node@v4
       with:

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

@@ -115,20 +115,20 @@ With “automatic provisioning” in AWS, we can synchronize all users and group
 ```mermaid
 flowchart LR
     subgraph external_idp["External Identity Provider"]
-        user1["User 1"]
-        user2["User 2"]
-        user3["User 3"]
-        group1["Group 1"]
+        user1["IdP User: Homer"]
+        user2["IdP User: Lisa"]
+        user3["IdP User: Bart"]
+        group1["IdP Group: DevOps"]
         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"]
+        user1_copy["Identity Center User: Homer"]
+        user2_copy["Identity Center User: Lisa"]
+        user3_copy["Identity Center User: Bart"]
+        group1_copy["Identity Center Group: DevOps"]
         permissions["Permission Sets"]
         user1_copy -.-> group1_copy
         user2_copy -.-> group1_copy
@@ -210,14 +210,19 @@ flowchart TB
 
 ### 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).
+SAML offers granular control over identity management with your IdP in AWS. With our `aws-saml` component, you can integrate multiple IdPs, and we explicitly provision every role, policy, and trust relationship needed. The `aws-saml` component allows users to assume any number of roles to access AWS accounts that are associated with their IdP groups.
 
 This component creates an Identity Provider (IdP) in the Identity account to allow federated access to an identity role.
 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.
 
+:::info What is a federated login?
+
+A federated login means that instead of managing separate credentials for each AWS account, users authenticate through a centralized identity provider (IdP). This allows them to access multiple AWS accounts or services using a single set of credentials, based on trust relationships established between the IdP and AWS.
+
+:::
+
 ```mermaid
 flowchart TB
     subgraph "Human Access Architecture with AWS SAML"
@@ -261,7 +266,9 @@ flowchart TB
 
 ### 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.
+AWS IAM Identity Center (SSO) is natively integrated with the AWS Web Console and the AWS CLI. You don't need to do anything special to get started with it once it's been properly configured.
+
+Specifically, 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.
 

docs/layers/identity/identity.mdx

@@ -45,7 +45,7 @@ Let’s start by identifying the minimum requirements for an identity and authen
     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
   </Step>
   <Step>
-    ### <StepNumber/> Highly precise control of user groups
+    ### <StepNumber/> Tight control over user groups
 
     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.
   </Step>
@@ -94,9 +94,7 @@ Now you may be asking some questions. There are plenty of existing solutions out
 </Steps>
 <br/>
 
-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.
+Ultimately, AWS does not provide a single solution that meets all our requirements. We need to combine the best of both worlds. Identity Center is great for human access, but it doesn’t work well for machines. On the other hand, AWS SAML is great for machines but is cumbersome for users to navigate the AWS web console without a third party tool.
 
 ## Our Solution
 
@@ -118,19 +116,19 @@ Users can sign into Identity Center to access any account they have access to wi
 
 ```mermaid
 flowchart LR
-    subgraph identity_teams["identity Teams"]
+    subgraph identity_teams["Identity Teams"]
         devops["devops"]
     end
 
-    subgraph dev_team_roles["dev Team Roles"]
+    subgraph dev_team_roles["Dev Team Roles"]
         terraform_dev["terraform"]
     end
 
-    subgraph staging_team_roles["staging Team Roles"]
+    subgraph staging_team_roles["Staging Team Roles"]
         terraform_staging["terraform"]
     end
 
-    subgraph prod_team_roles["prod Team Roles"]
+    subgraph prod_team_roles["Prod Team Roles"]
         terraform_prod["terraform"]
     end
 
@@ -149,18 +147,24 @@ We’ll explain in detail in the following pages.
 
 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.
 
-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.
+Plus, it’s open source and free to use.
 
 ### Pre-Configured for your Team
 
-Finally, to get everyone up and running on your Team, we pre-configured a single, common AWS config for all users.
+Finally, to get everyone up and running on your Team, we preconfigured a single, common AWS config for all users.
+
+All users connect to AWS using the same AWS profile name. Then we can use the same AWS config to assume any other role from that given AWS profile if their team has permission. This way, users can quickly apply Terraform across accounts and assume roles directly in the accounts they have access.
+
+:::tip Using Dynamic Terraform Roles
+
+With dynamic Terraform roles, we can choose to deploy a `terraform` and a `planner` role into any given account. The `terraform` role is used to apply changes, and the `planner` role is used to plan changes. For more on dynamic Terraform roles, see the [Dynamic Terraform Roles](/layers/identity/docs/dynamic-terraform-roles/) documentation.
 
-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.
+:::
 
 ## Next Steps
 
 <ActionCard title="How is this implemented?">
-  Next, we'll explain how we've implemented this solution in details.
+  Next, we'll explain how we've implemented this solution in detail.
 
   If you're curious about the thought that went into this process, please review the design decisions documentation.
   <div>