# HealthBridge AWS Authentication Architecture

## 1. AWS Organizations Structure

**AWS Organizations** provides central management of multiple AWS accounts. Your management account (087797848983) controls member accounts with different environments and workloads.

graph TB
    subgraph "AWS Organization: o-goyxn88j6m"
        MGMT[("🔵 Management Account<br/>087797848983<br/>ManagementAccount-DevOps-Role")]
        
        MGMT --> OU1["Organizational Unit: HealthBridge"]
        
        OU1 --> PROD[("🔴 Production Account<br/>065532173824<br/>hbf-awsintegrationshub")]
        OU1 --> DEV[("🟡 Development Account<br/>658413592781<br/>hbf-connect-dev")]
        OU1 --> STAGING[("🟠 Staging Account<br/>844077369820<br/>hbf-connect-prod")]
        OU1 --> MIRROR[("🔵 Mirror Account<br/>068217805200<br/>hbf-prod-mirror")]
        OU1 --> TEST[("🟣 Test Account<br/>035966626420<br/>hbf-production")]
        OU1 --> MGMT2[("🟢 Management Account<br/>087797848983<br/>healthbridge-management")]
    end
    
    style MGMT fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000
    style PROD fill:#ffebee,stroke:#b71c1c,stroke-width:2px,color:#000
    style DEV fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style STAGING fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
    style MIRROR fill:#e3f2fd,stroke:#0d47a1,stroke-width:2px,color:#000
    style TEST fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000
    style MGMT2 fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
    style OU1 fill:#f5f5f5,stroke:#424242,stroke-width:2px,color:#000

> **Key Concept:** The Management Account has administrative control over all member accounts and can apply Service Control Policies (SCPs) to set security guardrails.

## 2. Your Current Authentication Flow (Okta → IAM SAML Federation)

This diagram shows the step-by-step process of how you authenticate from Okta to AWS. Each step happens automatically after you click the AWS tile in Okta.

graph LR
    subgraph "Step 1: Login"
        A[Dom logs into<br/>gohbf.okta.com] 
    end
    
    subgraph "Step 2: Select Account"
        A --> B[Click AWS-Management-Account<br/>tile in Okta]
    end
    
    subgraph "Step 3: Okta Processing"
        B --> C[Okta checks your groups<br/>Finds: AWS-ManagementAccount-DevOps]
        C --> D[Okta creates SAML assertion<br/>with role mapping]
    end
    
    subgraph "Step 4: AWS Processing"
        D --> E[AWS receives SAML assertion<br/>at SAML provider endpoint]
        E --> F[AWS validates against<br/>Okta SAML provider]
        F --> G[AWS grants access to<br/>ManagementAccount-DevOps-Role]
    end
    
    subgraph "Step 5: Console Access"
        G --> H[Land in AWS Console as<br/>ManagementAccount-DevOps-Role/<br/>[e-mail]]
    end
    
    style A fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000
    style B fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000
    style C fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000
    style D fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000
    style E fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#000
    style F fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#000
    style G fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#000
    style H fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px,color:#000

### What's happening behind the scenes:
1. **You authenticate once** with Okta (username/password)
2. **Okta knows your group memberships** (e.g., AWS-ManagementAccount-DevOps)
3. **Okta tells AWS** "Dom is authenticated and should get the DevOps role"
4. **AWS trusts Okta** because of the SAML provider configuration
5. **You get direct console access** without any additional authentication

> **Your Session:** `ManagementAccount-DevOps-Role/[e-mail]` indicates IAM SAML federation (not Identity Center)

## 3. Okta Group to IAM Role Mapping

Shows how Okta groups determine which IAM role you receive in each AWS account.

graph LR
    subgraph "Okta Groups"
        G1[AWS-ManagementAccount-DevOps]
        G2[AWS-ManagementAccount-Admins]
        G3[AWS-ManagementAccount-Security]
        G4[AWS-ManagementAccount-ReadOnly]
        G5[AWS-ProductionAccount-DevOps]
    end
    
    subgraph "Management Account Roles"
        R1[ManagementAccount-DevOps-Role]
        R2[ManagementAccount-Admins-Role]
        R3[ManagementAccount-Security-Role]
        R4[ManagementAccount-ReadOnly-Role]
    end
    
    subgraph "Production Account Roles"
        R5[ProductionAccount-DevOps-Role]
    end
    
    G1 -.->|SAML Attribute| R1
    G2 -.->|SAML Attribute| R2
    G3 -.->|SAML Attribute| R3
    G4 -.->|SAML Attribute| R4
    G5 -.->|Different Account| R5
    
    style G1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000
    style R1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000
    style G2 fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#000
    style R2 fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#000
    style G3 fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000
    style R3 fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000
    style G4 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000
    style R4 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000
    style G5 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#000
    style R5 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#000

## 4. Your Hybrid Setup: Active vs Configured

This diagram shows what's actually being used (IAM SAML) versus what's configured but inactive (Identity Center).

graph TB
    subgraph "Okta Identity Provider"
        OKTA[Okta<br/>gohbf.okta.com]
    end
    
    subgraph "Active Path - BEING USED"
        OKTA -->|SAML 2.0| TILES[Multiple AWS Account Tiles]
        TILES -->|Direct SAML| SAMLP[SAML Providers<br/>in Each Account]
        SAMLP -->|AssumeRoleWithSAML| IAMROLES[IAM Roles<br/>ManagementAccount-*-Role]
        IAMROLES -->|Session| CONSOLE1[AWS Console<br/>Direct Access]
    end
    
    subgraph "Configured but NOT USED"
        OKTA -.->|SCIM Provisioning| IDC[AWS Identity Center<br/>ssoins-790720f893d1c6d2]
        IDC -.->|Would Create| PSETS[Permission Sets]
        PSETS -.->|Would Generate| SSORO[SSO Roles<br/>AWSReservedSSO_*]
        SSORO -.->|Would Access| CONSOLE2[AWS Console<br/>Via Portal]
        
        IDC -->|Shows| USERS[11 SCIM Users<br/>Provisioned but Unused]
    end
    
    style TILES fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px,color:#000
    style SAMLP fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px,color:#000
    style IAMROLES fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px,color:#000
    style CONSOLE1 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px,color:#000
    
    style IDC fill:#fff9c4,stroke:#f9a825,stroke-width:2px,stroke-dasharray: 5 5,color:#000
    style PSETS fill:#fff9c4,stroke:#f9a825,stroke-width:2px,stroke-dasharray: 5 5,color:#000
    style SSORO fill:#fff9c4,stroke:#f9a825,stroke-width:2px,stroke-dasharray: 5 5,color:#000
    style CONSOLE2 fill:#fff9c4,stroke:#f9a825,stroke-width:2px,stroke-dasharray: 5 5,color:#000
    style USERS fill:#ffccbc,stroke:#d84315,stroke-width:2px,color:#000

> **Important:** The Identity Center users exist but aren't used for authentication. Your actual login uses the green path (IAM SAML Federation).

## 5. IAM Federation vs Identity Center Comparison

Side-by-side comparison of your current setup versus how Identity Center would work.

### Current: IAM Federation

graph TD
    O1[Okta Login]
    O1 --> T1[Multiple Account Tiles<br/>One per AWS Account]
    T1 --> D1[Direct to Console<br/>No Selection Screen]
    D1 --> S1["Session Format:<br/>RoleName/email"]
    
    style O1 fill:#c8e6c9,stroke:#2e7d32,color:#000
    style T1 fill:#c8e6c9,stroke:#2e7d32,color:#000
    style D1 fill:#c8e6c9,stroke:#2e7d32,color:#000
    style S1 fill:#c8e6c9,stroke:#2e7d32,color:#000

### Potential: Identity Center

graph TD
    O2[Okta Login]
    O2 --> T2[Single SSO Tile]
    T2 --> P2[Account/Role Portal<br/>Choose from List]
    P2 --> S2["Session Format:<br/>AWSReservedSSO_*/email"]
    
    style O2 fill:#e3f2fd,stroke:#1565c0,color:#000
    style T2 fill:#e3f2fd,stroke:#1565c0,color:#000
    style P2 fill:#e3f2fd,stroke:#1565c0,color:#000
    style S2 fill:#e3f2fd,stroke:#1565c0,color:#000

## 6. Trust Relationship Structure

Detailed view of how IAM roles trust the Okta SAML provider (what you found in the trust policy).

graph LR
    subgraph "IAM Role Trust Policy"
        ROLE[ManagementAccount-DevOps-Role]
        TRUST[Trust Relationship<br/>AssumeRolePolicyDocument]
    end
    
    subgraph "Trust Details"
        PRINCIPAL["Principal:<br/>arn:aws:iam::087797848983:<br/>saml-provider/Okta"]
        ACTION["Action:<br/>sts:AssumeRoleWithSAML"]
        CONDITION["Condition:<br/>SAML:aud = signin.aws.amazon.com/saml"]
    end
    
    ROLE --> TRUST
    TRUST --> PRINCIPAL
    TRUST --> ACTION
    TRUST --> CONDITION
    
    PRINCIPAL -->|Validates| OKTA2[Okta SAML Assertion]
    
    style ROLE fill:#fce4ec,stroke:#880e4f,stroke-width:2px,color:#000
    style TRUST fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000
    style PRINCIPAL fill:#e8eaf6,stroke:#283593,stroke-width:2px,color:#000
    style ACTION fill:#e0f2f1,stroke:#004d40,stroke-width:2px,color:#000
    style CONDITION fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
    style OKTA2 fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000

## Summary

Your HealthBridge AWS environment uses:
- **AWS Organizations** for multi-account management
- **Okta SAML Federation** directly to IAM roles (active)
- **AWS Identity Center** configured but not used for authentication
- **Multiple AWS tiles in Okta** each mapping to specific account/role combinations
- **IAM roles with SAML trust relationships** that validate Okta assertions

The key indicator that you're using IAM federation is your session format: `ManagementAccount-DevOps-Role/[e-mail]` rather than `AWSReservedSSO_PermissionSet_*/email`.