AWS federated access

Use AWS IAM Identity Center for human AWS access and IAM roles for workloads. Do not create or store a long-lived AWS access key when federation is available.

This document describes the reusable HCS pattern. Account aliases, account IDs, access-portal URLs, permission-set assignments, and deployment state belong in the consuming scope's private configuration or standard overlay; they are not published in this base document.

Authentication model

Actor	Authentication	Credential location
Human operator	AWS IAM Identity Center through the AWS CLI SSO token provider	Temporary AWS CLI cache only
EC2 Mac	IAM role attached through an instance profile	Instance metadata; no stored key
GitHub Actions	OIDC federation into a least-privilege IAM role	Temporary job credentials
GitLab CI	Approved workload federation into a least-privilege IAM role	Temporary job credentials
ADO Pipelines	Approved workload federation into a least-privilege IAM role	Temporary job credentials

Values needed for first-time setup

• SSO session name: a local, descriptive name for the organization or scope
• AWS access-portal start URL supplied by the organization
• SSO Region: the Region hosting IAM Identity Center
• AWS account assignment and permission set
• default workload Region, which is independent of the SSO Region

None of these values is a password or access key. Do not paste passwords or MFA codes into a terminal, chat, script, or configuration file; enter them only on the organization's identity provider page.

Configure the AWS CLI

Install AWS CLI v2 from the official AWS installer, then run:

aws configure sso --profile <scope-purpose>

Provide the access-portal URL and SSO Region, authenticate in the browser, then select the assigned account and permission set. Use a purpose-specific profile name rather than default so commands cannot silently target the wrong organization.

The resulting local configuration follows this shape:

[sso-session <scope-session>]
sso_start_url = https://<organization>.awsapps.com/start
sso_region = <sso-region>
sso_registration_scopes = sso:account:access

[profile <scope-purpose>]
sso_session = <scope-session>
sso_account_id = <resolved-locally-do-not-commit>
sso_role_name = <permission-set-name>
region = <workload-region>
output = json

The local AWS config may contain the assigned account ID because the CLI requires it. Never copy that local profile into a repository or template.

Daily sign-in and verification

Use the repository helper for the normal HCS workflow:

./scripts/identity/Connect-AwsFederatedSession.ps1 -Profile <scope-purpose>

It reuses a valid cached session, opens the IAM Identity Center browser flow when authentication is missing or expired, verifies that the active account matches the profile's local SSO assignment, and masks the numeric account ID in its output. Use -ForceLogin to deliberately replace an existing session.

The equivalent direct AWS CLI commands are:

aws sso login --profile <scope-purpose>
aws sts get-caller-identity --profile <scope-purpose>

Before a mutating command, verify the profile, account alias, role, and workload Region. Automation must fail closed when the resolved account differs from the approved target. Logs and documentation may show the account alias and role name, but must mask the numeric account ID.

End the local session when the work is complete:

aws sso logout

Workload authentication

Human SSO is not a pipeline credential. Pipelines use a dedicated IAM role whose trust policy is restricted to the approved CI issuer, organization/project, repository, branch or protected ref, and audience. Apply least-privilege permissions to the role and use separate roles for discovery, deployment, and teardown when practical.

The EC2 Mac uses an instance profile for Systems Manager and any approved supporting services. Do not put AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS_SESSION_TOKEN in the AMI, user data, Key Vault, pipeline variables, or shell profiles.

Key Vault boundary

Key Vault stores genuine application/build secrets, not AWS federation state. Examples that may belong in the scope-owned vault are:

• Apple App Store Connect API private key
• Apple distribution signing private key or exported certificate
• certificate-export password
• generated macOS GUI password when Screen Sharing requires one

Do not store the AWS access-portal URL, SSO Region, account alias, permission-set name, SSO token, role credential, or CLI cache in Key Vault. See the Key Vault standard.

Troubleshooting

• Browser opens the Root/IAM page: stop and use aws configure sso; do not create an IAM user.
• No accounts appear: confirm the user has an account assignment and permission set in IAM Identity Center.
• Token expired: run aws sso login --profile <scope-purpose> again.
• Access denied: verify the selected permission set and workload Region; do not work around the error by creating an access key.
• Wrong account: log out, select the correct profile, re-authenticate, and verify identity before retrying. Do not proceed with a mutating command.