gabriel / musehub public
musehub-cloud-identity-and-aws-operating-model.md markdown
391 lines 21.8 KB
Raw
sha256:cd5c2fcb91a44ac9e38e9c36176c27ce079a074586d9852296da628a29fb01ff Merge 'docs/aws-identity-and-deploy-fixes' into 'dev' — pro… Human 3 days ago

MuseHub Cloud Identity and AWS Account Operating Model

Status: Current operating baseline
Last verified: 2026-08-23
Audience: MuseHub engineers, administrators, operators, and AI agents

1. Purpose

This document explains how MuseHub connects Google Workspace, AWS Organizations, and AWS IAM Identity Center. It defines which system owns each kind of identity, how people access AWS, how the AWS accounts are separated, and which security conventions should remain intact as the team grows.

The central operating principle is:

Google Workspace owns workforce identities; AWS IAM Identity Center grants those identities access to specific AWS accounts and roles.

AWS root users are reserved for account-recovery and root-only operations. Routine human access must use the AWS access portal, and routine automation must use dedicated non-root machine identities.

2. Architecture at a glance

flowchart TD
    GW["Google Workspace<br/>Workforce directory"]
    SAML["SAML<br/>Authentication"]
    SCIM["SCIM<br/>Provisioning"]
    IC["AWS IAM Identity Center<br/>MuseHub-Workforce"]
    ORG["AWS Organization"]
    MGMT["MuseHub Management"]
    NONPROD["MuseHub Nonproduction"]
    PROD["MuseHub Production"]

    GW --> SAML --> IC
    GW --> SCIM --> IC
    IC --> ORG
    ORG --> MGMT
    ORG --> NONPROD
    ORG --> PROD

There are two separate identity paths:

  1. People: Google Workspace → SAML/SCIM → IAM Identity Center → permission set → AWS account.
  2. Automation: deployment or service identity → narrowly scoped AWS credentials or roles → workload resources.

These paths must not be collapsed into root credentials or shared personal credentials.

3. System responsibilities

System Responsibility Do not use it for
Google Workspace Creating, suspending, and deleting workforce identities; primary sign-in and MFA policy; AWS SAML application; SCIM provisioning AWS authorization policies or workload credentials
AWS IAM Identity Center Mapping provisioned people and groups to AWS accounts through permission sets Creating the canonical workforce directory
AWS Organizations Account hierarchy, consolidated billing, organization-wide controls, and account lifecycle Day-to-day application deployment
MuseHub Management Governance services and administration of the AWS Organization Hosting staging or production application workloads
Workload accounts Application infrastructure and environment-specific services Organization governance or shared root access
Google Groups root mailboxes Receiving AWS root, recovery, billing, and security mail Interactive workforce sign-in

4. AWS account inventory

The AWS Organization contains three accounts.

AWS account Purpose Root mailbox
MuseHub Management AWS Organizations, IAM Identity Center and governance [email protected]
MuseHub Nonproduction Development and staging workloads [email protected]
MuseHub Production Production workloads only [email protected]

The known account IDs are:

  • MuseHub Nonproduction: 992382692655
  • MuseHub Production: 672469410277

The management account ID remains restricted; keep it wherever you already recorded it securely rather than in this document.

Important boundaries:

  • Do not deploy application workloads into MuseHub Management.
  • Do not treat MuseHub Nonproduction and MuseHub Production as interchangeable.
  • Production access, credentials, secrets, DNS, certificates, and deployment targets must be independent from nonproduction.
  • Do not record the management account ID, organization ID, access keys, portal-specific identifiers, or recovery secrets in this document.

5. Workforce identity authority

Google Workspace is the authoritative source for MuseHub workforce identities.

The Google Security group AWS Workforce ([email protected]) defines the provisioning scope for AWS IAM Identity Center. Only named human users who are members of this group should be provisioned and enabled through SCIM.

AWS workforce users must be created, suspended, restored, and removed through Google Workspace—not directly through IAM Identity Center.

Current AWS workforce identities

Google identity AWS Workforce member IAM Identity Center status Purpose
[email protected] Yes Enabled Named human administrator
[email protected] Yes Enabled Named human administrator
[email protected] No Disabled Shared support mailbox; retained in Google Workspace but not authorized for AWS

Shared mailboxes, aliases, root-account mailboxes, support accounts, and service identities must not be added to the AWS Workforce group.

Workforce provisioning lifecycle

  1. Create or activate the named human user in Google Workspace.
  2. Add the user to the AWS Workforce Google Security group.
  3. Google SCIM provisioning creates or enables the identity in IAM Identity Center.
  4. Assign AWS accounts and permission sets separately in IAM Identity Center.
  5. To revoke AWS workforce access, remove the user from AWS Workforce.
  6. Confirm that SCIM disables the corresponding IAM Identity Center identity.

Membership in AWS Workforce controls whether an identity exists and is enabled in IAM Identity Center. It does not by itself grant access to an AWS account.

Shared mailbox policy

[email protected] remains an active Google Workspace mailbox but is excluded from AWS Workforce. SCIM has disabled its existing IAM Identity Center identity.

Shared mailboxes must never receive interactive AWS permissions. AWS access belongs to attributable, named human identities or purpose-built noninteractive workload roles.

Required rule

Create, rename, suspend, and remove workforce users in Google Workspace. Do not manually create parallel users in IAM Identity Center. Direct AWS-side user creation would produce identity drift and complicate offboarding.

6. Authentication and provisioning

6.1 SAML authentication

The Google Admin console contains a SAML application named Amazon Web Services. Its service-provider configuration uses values supplied by the MuseHub IAM Identity Center instance:

Google SAML setting AWS source
ACS URL IAM Identity Center Assertion Consumer Service (ACS) URL
Entity ID IAM Identity Center issuer URL
Name ID format EMAIL
Name ID Basic Information → Primary email
Signed response Unchecked

The application is enabled for the MuseHub workforce. Google authenticates the person, applies Google security policy, and sends the SAML assertion to IAM Identity Center.

6.2 SCIM provisioning

Google Workspace autoprovisioning is active. SCIM creates and updates IAM Identity Center workforce records from Google Directory data.

The essential mappings include:

  • username / primary email
  • given name
  • family name
  • display name

Optional directory attributes may also be synchronized, but access decisions should not depend on incomplete optional profile data.

6.3 Deprovisioning behavior

Google is configured to suspend the corresponding AWS workforce identity when:

  • the AWS application is turned off for a user;
  • the Google user is suspended; or
  • the Google user is deleted.

Hard deletion in AWS is not enabled. Suspension provides safer and more recoverable offboarding while immediately blocking access after provisioning propagates.

7. IAM Identity Center configuration

IAM Identity Center

  • Instance name: MuseHub-Workforce
  • Primary Region: us-east-1
  • Identity provider: Google Workspace through SAML
  • Provisioning: Google Workspace through SCIM
  • SCIM provisioning scope: AWS Workforce
  • Canonical access method: IAM Identity Center dual-stack access portal URL

The older IPv4-only awsapps.com/start URL failed during testing. The dual-stack portal URL authenticated successfully and should be used and bookmarked.

IAM Identity Center remains the AWS authorization layer even though Google is the authentication and directory authority.

Permission assignments

SCIM provisioning and AWS authorization are separate:

  • Google Workspace determines which named users are provisioned.
  • IAM Identity Center permission sets determine what those users may do.
  • AWS account assignments determine which accounts they may access.

[email protected] currently has the AdministratorAccess permission set in MuseHub Production, and successful federated console access to that account has been verified.

Prefer assigning permission sets to SCIM-provisioned workforce groups instead of individual users once the access-group model is finalized. Direct assignment to Gabriel is acceptable for the initial production bootstrap.

As the team grows:

  • use Google-managed groups where practical;
  • assign permission sets to groups rather than individuals;
  • create environment- and job-specific permission sets;
  • reserve administrator access for a small set of operators;
  • provide read-only or deployment-specific access when full administration is unnecessary.

8. Human AWS access procedure

Routine console access follows this sequence:

  1. Open the dual-stack AWS access portal URL recorded in the approved password manager or internal secure notes.
  2. Sign in through Google with the user’s @musehub.ai identity.
  3. Complete Google’s authentication and MFA requirements.
  4. Select the required AWS account.
  5. Select an assigned permission set, such as AdministratorAccess.
  6. Open the AWS Management Console.
  7. Confirm the account menu shows the intended account name and account ID before making changes.

The dual-stack portal was tested successfully. The legacy IPv4-only awsapps.com/start URL produced failed sign-ins during validation and should not be the default bookmark.

Production safety check

Before any production mutation, visibly confirm all three:

  • account name is MuseHub Production;
  • account ID matches the production account record in the password manager;
  • federated role and user are the expected IAM Identity Center assignment.

Sign-in quick reference

Three genuinely different kinds of AWS access exist. Confusing them is the most common source of lockout incidents in this project — check this table before troubleshooting a sign-in problem.

Type Login Where
Root (Management, Production) Email + password + Authenticator MFA, stored per-account in the approved password manager signin.aws.amazon.com → "Sign in as root user"
SSO ([email protected], [email protected]) The user's existing Google Workspace login — no separate AWS password exists The dual-stack AWS access portal URL (above)
Nonproduction root Does not exist — deleted intentionally via centralized root access management (see §9) Only reachable via a privileged session launched from Management's SSO session (IAM → Root access management)

9. Root mailbox and root-user model

Each AWS account has a unique Google Group address for its root email. These addresses are operational mailboxes, not normal Google user accounts.

Group Purpose
[email protected] Management-account recovery, security, billing, and root notices
[email protected] Nonproduction-account recovery, security, billing, and root notices
[email protected] Production-account recovery, security, billing, and root notices

For the nonproduction and production groups:

  • Gabriel and Aaron are direct members and owners;
  • delivery is set to Each Email;
  • joining is invitation-only;
  • external members are disabled;
  • group membership and conversations are not publicly visible;
  • external email delivery has been tested successfully to Gabriel;
  • Aaron’s receipt should be recorded when independently confirmed.

AWS verification messages may appear in the Google Groups conversation archive without being delivered to a member’s Gmail inbox. If a root-email verification message is visible in the group archive, retrieve its code there and enter the code directly in AWS. No separate Google Groups approval is required.

Root-user rules

  • Use root only for tasks AWS explicitly requires root to perform.
  • Store each root password as a unique secret in the approved password manager.
  • Protect root with MFA.
  • Never create new root access keys.
  • Do not use a root identity for CLI access, deployments, or daily console administration.
  • Periodically test mailbox delivery and documented recovery access.

Centralized root access management

As of 2026-08-26, centralized root access (IAM trusted access, root credentials management, and privileged root actions) is enabled organization-wide from the Management account. This changes root-user rules for member accounts:

  • MuseHub Management and MuseHub Production keep standing root passwords and Authenticator MFA, each stored uniquely in the approved password manager, per the rules above.
  • MuseHub Nonproduction has had its root credentials (password, MFA device, access keys) deliberately and permanently deleted via IAM → Root access management in the Management account. It has no standing root login and cannot use the "Forgot password" recovery flow — this is intentional, not a fault state.
  • Any future root-only action needed on Nonproduction (or any account whose credentials are later deleted the same way) must be performed by an authorized administrator launching a short-lived privileged session from Management: IAM → Root access management → select account → Take privileged action. The available curated actions are limited (e.g. deleting a misconfigured S3 bucket or SQS queue policy, deleting root credentials) and AWS is expected to expand this list over time.
  • This is the preferred long-term direction for every member account: minimize standing root credentials in favor of IAM Identity Center for routine access and centralized privileged sessions for the rare root-only need.

10. Programmatic and deployment access

The development machine’s existing AWS CLI identity was verified as the IAM user musehub-infra in MuseHub Nonproduction. It is not the root user.

An obsolete root access key ending in TMHL was deactivated after confirming that CLI operations continued to work through musehub-infra. The inactive key has intentionally not yet been deleted, providing a short rollback window while the new operating model is stabilized.

Target state for automation

  • separate nonproduction and production deployment identities;
  • no shared human access keys;
  • least-privilege policies tied to deployment requirements;
  • short-lived credentials through IAM Identity Center, role assumption, OIDC, or another approved federation mechanism where feasible;
  • environment-specific profiles and explicit account verification in deployment scripts;
  • no production credential stored in source control, documentation, shell history, or chat.

Before enabling production deployment, inventory the current staging deployment path and reproduce only the required permissions in the production account.

11. Onboarding a teammate

  1. Create the person in the musehub.ai Google Workspace tenant.
  2. Require Google MFA and apply the organization’s authentication policies.
  3. Add the person to the appropriate Google groups.
  4. Confirm SCIM creates the user in IAM Identity Center.
  5. Assign only the required AWS account and permission set, preferably through a group.
  6. Have the user sign in through the dual-stack access portal.
  7. Verify the account and role visible in the resulting AWS console session.
  8. Record the granted access and its business justification.

Do not add a new teammate to AWS root-mail groups merely because they need normal AWS access.

12. Offboarding a teammate

  1. Suspend the Google Workspace user immediately.
  2. Remove the user from AWS-related Google groups, including root-mail groups when applicable.
  3. Confirm SCIM suspends the IAM Identity Center identity.
  4. Remove AWS account and permission-set assignments.
  5. Revoke active sessions and rotate any shared or exposed credentials.
  6. Transfer ownership of operational documentation and alerts.
  7. Review CloudTrail and relevant audit logs if the departure is sensitive.
  8. Delete the Google user only after the organization’s retention and transfer requirements are satisfied.

13. Security work completed

  • Established a dedicated AWS management account and AWS Organization.
  • Separated management, nonproduction, and production into three AWS accounts.
  • Renamed the original workload account to MuseHub Nonproduction.
  • Created MuseHub Production with its own root mailbox.
  • Replaced the ambiguous nonproduction root address with [email protected].
  • Integrated Google Workspace with IAM Identity Center using SAML.
  • Enabled Google-to-AWS SCIM autoprovisioning.
  • Verified Google-managed users appear in IAM Identity Center.
  • Verified dual-stack access-portal authentication as [email protected].
  • Verified federated access into MuseHub Production using AdministratorAccess.
  • Removed a former teammate’s root MFA device.
  • Deactivated the obsolete root access key while confirming non-root CLI continuity.
  • Enabled Authenticator MFA on MuseHub Management and MuseHub Production root, each with a fresh unique password saved to the approved password manager.
  • Enabled centralized root access management (IAM trusted access, root credentials management, privileged root actions) organization-wide from the Management account.
  • Deleted an unrecognized/stuck root MFA device and password on MuseHub Nonproduction via centralized root access management, after confirming (via AWS's own root-password-recovery documentation) that this account had no self-service recovery path and that root sign-in there was permanently blocked. Nonproduction now has no standing root credentials by design.

14. Remaining work

Identity and authorization

  • Create Google groups for AWS roles, separate from the root-mail distribution groups.
  • Define administrator, developer, deployer, billing, and read-only permission sets.
  • Replace individual production assignments with group-based assignments where appropriate.
  • Decide whether Aaron requires production administration, another permission set, or no production access yet.
  • Periodically re-confirm [email protected] remains excluded from AWS Workforce and disabled in IAM Identity Center.

Production infrastructure

  • Inventory the complete nonproduction architecture and deployment dependencies.
  • Implement production infrastructure using reproducible infrastructure-as-code where possible.
  • Create production-specific secrets, roles, logging, monitoring, alarms, and budgets.
  • Configure the production subdomain and DNS in Namecheap.
  • Provision and validate TLS certificates; document whether Let’s Encrypt or an AWS-managed certificate service is used.
  • Build a production deployment path that is as explicit and repeatable as staging.
  • Add safety prompts and account-ID assertions to prevent cross-environment deployment.
  • Test rollback, restore, certificate renewal, and incident access before public launch.

Security follow-up

  • After an observation period, delete the inactive legacy root access key.
  • Configure budgets and cost alerts for all three accounts.
  • Enable and review organization-wide CloudTrail and appropriate security monitoring.
  • Decide whether to eventually delete MuseHub Production's standing root credentials too (in favor of privileged sessions from Management), or keep it as a deliberate exception since Gabriel needs frequent root-adjacent access there during the production launch.

15. Verification checklist

Use this checklist after significant identity, account, or SSO changes.

  • [ ] Google SAML application is enabled for intended users.
  • [ ] SCIM provisioning is active and reports no unresolved errors.
  • [ ] Expected users appear in IAM Identity Center as SCIM-created users.
  • [ ] Suspended Google test identity cannot access AWS.
  • [ ] Dual-stack access portal redirects to Google authentication.
  • [ ] User can see only the AWS accounts and permission sets intentionally assigned.
  • [ ] Opened AWS console displays the intended account name and ID.
  • [ ] Root mailbox test reaches every approved custodian.
  • [ ] No root access key is active.
  • [ ] Deployment tooling resolves to the intended non-root identity and account.
  • [ ] Production and nonproduction secrets and deployment targets remain separate.

16. Sensitive-data handling

The following must be kept in the approved password manager or restricted administrative systems, never in repository documentation:

  • the MuseHub Management account ID and organization identifiers (the Nonproduction and Production account IDs are recorded in Section 4 for operational verification);
  • root passwords and MFA recovery material;
  • access-portal URLs containing instance-specific identifiers;
  • SAML metadata, certificates, issuer identifiers, and ACS URLs;
  • SCIM endpoints and bearer tokens;
  • access-key IDs and secret access keys;
  • private SSH keys, deployment secrets, and recovery codes.

Screenshots should redact account IDs, organization IDs, personal addresses, tokens, keys, URLs containing unique identifiers, and other recovery information before being shared.

17. Change-management rule

Whenever an AWS account, root mailbox, Google identity integration, permission set, or deployment identity changes:

  1. update this document;
  2. verify access using a private browser session;
  3. test the relevant mailbox or deployment path;
  4. record the date and operator;
  5. avoid removing the previous recovery path until the replacement has been independently verified.
File History 1 commit
sha256:cd5c2fcb91a44ac9e38e9c36176c27ce079a074586d9852296da628a29fb01ff Merge 'docs/aws-identity-and-deploy-fixes' into 'dev' — pro… Human 3 days ago