MuseHub AWS and Google Workspace Identity Architecture

Status: Current-state architecture and operating runbook
Last updated: 2026-08-23
Primary AWS Region: us-east-1 (US East, N. Virginia)

Purpose

This document explains how MuseHub organizes AWS accounts, authenticates team members through Google Workspace, provisions workforce identities, and separates administrative access from application workloads.

It is intended to help teammates and agents quickly understand the system before changing AWS identity, permissions, billing, DNS, deployment, or production infrastructure.

Security note: This file is intentionally safe to store in the repository. Do not add AWS account IDs, access keys, passwords, MFA seeds, SCIM tokens, private portal URLs, SAML metadata files, or recovery codes.

Architecture at a glance

flowchart TD
    GW["Google Workspace<br/>musehub.ai"]
    IC["AWS IAM Identity Center<br/>MuseHub-Workforce"]
    PS["Permission sets and<br/>account assignments"]
    MA["MuseHub Management<br/>governance account"]
    WA["MuseHub<br/>workload account"]

    GW -->|"SAML authentication<br/>SCIM provisioning"| IC
    IC --> PS
    PS --> MA
    PS --> WA

The important separation is:

• Google Workspace owns workforce identity.
• AWS IAM Identity Center owns AWS authorization.
• MuseHub Management owns organization-level governance and consolidated billing.
• MuseHub owns application workloads, including staging and production.

AWS account topology

AWS account	Root email alias	Responsibility	Workloads allowed?
MuseHub Management	[email protected]	AWS Organizations management, IAM Identity Center, organization policies, permission administration, consolidated billing, and governance	No
MuseHub	[email protected]	Application infrastructure, staging, production, deployment resources, and runtime services	Yes

Both accounts belong to one AWS Organization with all features enabled. MuseHub Management is the management account, and MuseHub is a member account.

Root email aliases

[email protected] and [email protected] are Google Workspace aliases that deliver to the controlled [email protected] mailbox. They are valid AWS root usernames even though they are not separate inboxes.

These aliases exist for account ownership, recovery, and break-glass administration. They are not normal workforce identities.

Identity and access model

Authentication: Google Workspace

The musehub.ai Google Workspace tenant is the external identity provider for AWS.

Google Admin contains an Amazon Web Services SAML application. It provides:

• SAML single sign-on to AWS IAM Identity Center.
• Google-managed authentication and MFA policy.
• SCIM-based user provisioning and deprovisioning.

The AWS application is currently enabled in Google Workspace. Access should ultimately be scoped to a dedicated AWS workforce group or organizational unit rather than every Google user.

Provisioning: SCIM

Google Workspace autoprovisioning is active. Google is the authoritative source for workforce users.

The following users were successfully provisioned into IAM Identity Center during setup:

• [email protected]
• [email protected]
• [email protected]

The presence of these users in IAM Identity Center confirms that SCIM synchronization is working. It does not mean they automatically have access to either AWS account.

Going forward:

• Create, rename, suspend, and delete workforce users in Google Workspace.
• Do not manually create or maintain ordinary workforce users in IAM Identity Center.
• Do not assume Google Groups are mirrored into AWS. The current integration proves user provisioning; AWS authorization remains explicitly managed in IAM Identity Center.
• Do not grant interactive AWS access to shared or service mailboxes such as [email protected].

Authorization: IAM Identity Center

IAM Identity Center is the authorization layer. Access is granted through:

1. A permission set, which defines what a user may do.
2. An account assignment, which links a user or AWS-side group, permission set, and AWS account.

Authentication and authorization are deliberately separate. A person may exist in Google and IAM Identity Center while having no AWS account access.

IAM Identity Center configuration

Setting	Current value
Instance type	AWS Organizations instance
Instance name	MuseHub-Workforce
Primary Region	us-east-1
Deployment	Single Region
Identity source	External identity provider
External IdP	MuseHub Google Workspace
User provisioning	Google SCIM autoprovisioning

The SAML integration uses the instance-specific AWS IAM Identity Center ACS URL and issuer/entity ID. The Google Name ID is the user's primary email address.

The SCIM token and endpoint are stored as secure administrative notes. They must never be committed to the repository or copied into chat, tickets, or general documentation.

User lifecycle

Onboarding a teammate

1. Create the person in the musehub.ai Google Workspace tenant.
2. Require the organization's Google authentication and MFA controls.
3. Add the person to the Google group or organizational unit approved for AWS access.
4. Confirm that SCIM creates the user in IAM Identity Center.
5. Assign the minimum required IAM Identity Center permission set to the appropriate AWS account.
6. Have the user sign in through the AWS access portal.
7. Verify the session identity and permissions before beginning work.

Changing access

Change AWS privileges through IAM Identity Center permission sets and account assignments. Do not solve routine access needs by sharing root credentials, creating additional root MFA devices, or distributing permanent access keys.

Offboarding a teammate

1. Remove the user from the Google AWS-access scope or suspend the Google account.
2. Confirm that SCIM suspends the corresponding IAM Identity Center user.
3. Remove any remaining AWS account assignments.
4. Audit for user-owned access keys, SSH keys, secrets, tokens, or deployment credentials.
5. Rotate any shared secret the departing person could access.

Current Google autoprovisioning behavior is configured to suspend the AWS identity within 24 hours when:

• The AWS app is turned off for the Google user.
• The Google user is suspended.
• The Google user is deleted.

Automatic hard deletion is disabled. This is intentional so offboarding is recoverable and auditable.

Root-user and credential posture

Root users

Root access is break-glass access only. It is reserved for tasks that explicitly require the AWS account root user, such as certain account ownership, recovery, or billing operations.

Current safeguards include:

• The management account root login was tested after creation.
• The workload account root email was migrated to [email protected].
• MFA is enabled on both root accounts.
• An obsolete former-teammate MFA device was removed from the workload account.
• Existing known recovery paths were verified before credential cleanup.

The remaining legacy root MFA devices on the workload account should be reviewed once all human administrators have working IAM Identity Center access. Remove any device that is no longer an approved break-glass factor.

Root access keys

An old, unused root access key in the workload account was deactivated. It was not used by the active deployment CLI configuration.

Root users should have zero active access keys. After an observation period and a final dependency audit, the inactive legacy root key should be deleted.

Existing deployment IAM user

The current local AWS CLI was verified to authenticate as the IAM user musehub-infra, not as root. This explains why deactivating the root key did not interrupt the CLI or current deployment workflow.

musehub-infra and its long-lived credentials are transitional. The target state is:

• Humans use IAM Identity Center and short-lived SSO sessions.
• CI/CD uses an assumable IAM role, ideally through OIDC or another short-lived workload identity.
• EC2 workloads use instance profiles rather than stored access keys.
• No production deployment depends on a root key or a shared human credential.

SSH keys are different from AWS access keys

Do not confuse these credential types:

• AWS access keys authorize AWS API and CLI calls.
• EC2 SSH keys authenticate an operating-system login to a server.

Removing an AWS root access key does not remove an EC2 SSH key. Both types still need separate ownership, rotation, and retirement plans.

Verification commands

Run these before making infrastructure or deployment changes:

aws sts get-caller-identity
aws configure list
aws configure list-profiles

Interpretation:

• An ARN containing user/musehub-infra means the transitional IAM deployment user is active.
• An ARN containing an AWSReservedSSO role means IAM Identity Center/SSO credentials are active.
• A normal working session should never identify as the account root user.
• Confirm the account and Region before running any mutating command.

The existing musehub-infra policy is intentionally limited and cannot perform organization-wide IAM administration. An AccessDenied response to administrative IAM or AWS Organizations commands does not imply that the account relationship or CLI credentials are broken.

Administrative operating rules

Do

• Use MuseHub Management for organization, identity, permission, policy, and consolidated-billing administration.
• Use MuseHub for staging and production workloads.
• Use Google Workspace as the source of truth for human identities.
• Use IAM Identity Center permission sets and account assignments for AWS access.
• Prefer least privilege and short-lived credentials.
• Keep root passwords, MFA recovery material, SCIM credentials, and emergency procedures in the approved password manager.
• Verify the active AWS identity and account before every deployment or infrastructure change.

Do not

• Deploy application resources into MuseHub Management.
• Use an AWS root user for daily work or deployment.
• Create root access keys.
• Commit AWS credentials, SCIM tokens, SAML metadata, private portal URLs, SSH private keys, or account recovery information.
• Treat a provisioned IAM Identity Center user as authorized until an account assignment exists.
• Give shared mailboxes interactive administrator access.
• Manually duplicate Google-managed workforce users in IAM Identity Center.

Current decisions and rationale

Decision	Rationale
Dedicated management account	Isolates governance and billing from workloads and reduces the management account's attack surface
Existing workload account retained	Preserves current staging resources and deployment continuity while improving governance around them
Google Workspace as external IdP	Gives MuseHub one authoritative employee identity lifecycle and central MFA policy
SCIM autoprovisioning	Reduces manual account drift and supports consistent onboarding/offboarding
Single-Region Identity Center in us-east-1	Matches the existing primary AWS Region and avoids unnecessary multi-Region KMS complexity and cost at this stage
Recoverable suspension instead of hard deletion	Makes accidental deprovisioning reversible and supports auditability
Root key deactivated before deletion	Allowed a safe dependency test while preserving a short rollback window

Remaining work

Identity and access

• Create and document IAM Identity Center permission sets.
• Assign [email protected] the administrative access required to complete infrastructure setup.
• Decide and implement the appropriate least-privilege access for [email protected].
• Remove [email protected] from interactive AWS access and restrict the Google AWS app to an approved human-workforce group or organizational unit.
• Test SSO end to end through the AWS access portal for each authorized teammate.
• Document the break-glass root procedure and approved MFA ownership.
• Retire the remaining long-lived human and deployment credentials after role-based replacements are verified.

Infrastructure and deployment

• Inventory the current staging environment before changing it.
• Define staging and production with infrastructure as code rather than relying on an undocumented manual clone.
• Preserve strict staging/production separation for configuration, secrets, databases, storage, and deployment targets.
• Make production deployment as repeatable and observable as staging deployment.
• Configure production DNS in Namecheap using the approved MuseHub hostnames.
• Configure and automatically renew TLS certificates, currently planned with Let's Encrypt.
• Add deployment health checks and a tested rollback path.

Governance and operations

• Enable and review cost budgets and billing alerts.
• Verify organization-level billing and payment configuration.
• Centralize CloudTrail and security logging.
• Review backups, restore tests, encryption, monitoring, and alerting before production launch.
• Define tagging standards for environment, service, owner, and cost allocation.
• Review whether service control policies are needed after the basic permission model is stable.
• Periodically audit root credentials, MFA devices, permission assignments, and dormant users.

Production-readiness sequence

The recommended order for the next phase is:

1. Finish IAM Identity Center permission sets and validate SSO.
2. Inventory the existing workload account and staging deployment path.
3. Convert the environment definition to infrastructure as code or document any unavoidable manual resources.
4. Provision isolated production resources in the MuseHub workload account.
5. Configure production secrets and data services.
6. Configure Namecheap DNS and Let's Encrypt certificate issuance/renewal.
7. Implement a production deployment command or pipeline parallel to staging.
8. Test health checks, rollback, backups, monitoring, and billing alerts.
9. Perform a controlled production launch.
10. Retire transitional credentials only after the replacement paths are proven.

Glossary

Term	Meaning in this architecture
AWS Organizations	The organization boundary connecting the management and workload accounts
Management account	The dedicated account that governs the organization and consolidated billing
Member/workload account	The account that contains MuseHub application infrastructure
IAM Identity Center	AWS service that assigns workforce users permission sets across AWS accounts
SAML	Browser-based authentication federation from Google Workspace to AWS
SCIM	Automated user provisioning and deprovisioning from Google Workspace to IAM Identity Center
Permission set	Reusable AWS permissions assigned to a user or group for a specific AWS account
Account assignment	The link between an identity, a permission set, and an AWS account
Root user	Break-glass owner identity for one AWS account; not a daily administrator
IAM role	Temporary AWS authorization assumed by a person, workload, or CI/CD system

Document maintenance

Update this file whenever any of the following changes:

• An AWS account is added, removed, renamed, or given a new responsibility.
• The Google Workspace SAML/SCIM configuration changes.
• The IAM Identity Center Region, identity source, or workforce scope changes.
• Permission sets or standard onboarding/offboarding procedures change.
• Root credential ownership or break-glass procedures change.
• The production deployment, DNS, TLS, or infrastructure model changes.

Record secrets only in the approved secrets manager or password manager, never in this document.