Skip to content

0035: Programmatic Organizational Structure Management via AWS CDK

STATUS

Request for comments

CONTEXT

Managing organizational structure (users and groups) for the tech team in AWS Identity Center has historically been a manual process, leading to inconsistencies, lack of visibility, and challenges in auditing or replicating changes. As our team grows and our compliance requirements increase, it is critical to have a version-controlled, programmatically accessible way to manage these resources. This will improve traceability, enable peer review, and allow for automated provisioning and updates.

Considered Options

  • Continue manual management of users and groups in AWS Console
  • Would also mean continual mananual definitions of those users and groups in our code.
  • Use third-party identity management tools
  • Manage users and groups programmatically via AWS CDK (Identity Center constructs)

DECISION

We will adopt AWS CDK to define and manage our tech team's organizational structure, specifically users and groups in AWS Identity Center. All changes to users, groups, and their relationships will be made through CDK code, stored in version control, and deployed via our standard infrastructure pipelines. This approach ensures that our org structure is reproducible, auditable, and can be peer-reviewed like any other code change.

Manual changes in the AWS Console will be strongly discouraged and even locked-down, and, where possible, monitored or reverted to maintain alignment with the CDK source of truth. We will need to figure out a way to use the users and groups defined in this project in GitHub too.

CONSEQUENCES

Positive outcomes:

  • Organizational structure is version-controlled and auditable.
  • Enables code review and approval workflows for org changes.
  • Reduces risk of configuration drift and manual errors.
  • Facilitates onboarding/offboarding and group membership changes via automation.

Negative outcomes:

  • Initial migration effort to codify existing users/groups.
  • Requires team familiarity with AWS CDK and pipeline processes.
  • Potential for deployment errors if not carefully reviewed.

Risks

  • Accidental removal or misconfiguration of users/groups during migration or updates.
  • We should get a list of old and new teams and make a checklist of which ones to remove and which ones to keep to further help facilitate this migration.
  • Pipeline or CDK errors could impact access if not properly tested.
  • Which tests should we create to enable more trust in this feature?
  • Reliance on AWS CDK features for Identity Center, which may evolve over time.

NOTES

Implementation Plan

The implementation will follow a structured approach using AWS CDK with the following components:

Repository Structure

  • Create new repository: aws-identity-center-org-structure-cdk-app
  • Implement CDK App: aws-identity-center-org-structure-cdk-app

Stack Architecture

The CDK application will be organized into the following stacks:

  1. organization Stack - AWS Organizations management
  2. Register delegated administrator account for organization structure management

  3. Enable necessary AWS services

  4. engineers Stack - Identity Center user management

  5. Manage all Identity Center users programmatically

  6. teams Stack - Identity Center group management

  7. Manage all Identity Center groups programmatically

  8. organizational-structure Stack - AWS Organizations OU management

  9. Manage organizational units (OUs) programmatically

  10. accounts Stack - AWS Organizations account management

  11. Manage AWS accounts programmatically
graph TB subgraph "CDK Application: adaction-org-structure-cdk-app" subgraph "organization Stack" OA[Delegated Admin Account] OS[Enable Services] end subgraph "engineers Stack" EU[Identity Center Users] end subgraph "teams Stack" TG[Identity Center Groups] end subgraph "organizational-structure Stack" OU[Organizational Units] end subgraph "accounts Stack" AC[AWS Accounts] end end subgraph "AWS Resources" AWS_ORG[AWS Organizations] AWS_IDC[AWS Identity Center] end OA --> AWS_ORG OS --> AWS_ORG EU --> AWS_IDC TG --> AWS_IDC OU --> AWS_ORG AC --> AWS_ORG style AWS_ORG fill:#ff9800,color:#0d1117 style AWS_IDC fill:#2196f3,color:#0d1117

Deployment Strategy

  • Deploy all stacks initially, even if empty
  • Import existing resources into their respective stacks using CDK Import tool
  • Establish CDK as the single source of truth for organizational structure
flowchart TD A[Start: Empty CDK Stacks] --> B[Deploy organization stack] B --> C[Deploy engineers stack] C --> D[Deploy teams stack] D --> E[Deploy organizational-structure stack] E --> F[Deploy accounts stack] F --> G[Import existing AWS Organizations resources] G --> H[Import existing Identity Center users] H --> I[Import existing Identity Center groups] I --> J[Import existing OUs] J --> K[Import existing accounts] K --> L[Verify CDK as source of truth] L --> M[Lock down manual console changes] style A fill:#e1f5fe,color:#0d1117 style M fill:#c8e6c9,color:#0d1117 style L fill:#fff3e0,color:#0d1117

Future Considerations

  • Remove unused IAM Users and User Groups
  • Ensure Identity Center groups, users, and accounts align with current organizational structure
  • Integrate with GitHub for user and group synchronization

References

Original Author

  • Dakota Washok

Approval date

Approved by

Appendix