Prerequisites

This AWS integration relies on IAM Identity Center to manage access. An Identity Store must be set up before the integration can be added to Hyphen.

Setup

1. Create or sign into your Amazon Web Services account

Sign in to the AWS console
or
Create a new AWS account

2. Create an Organization in your AWS account

If your account is not already part of an AWS Organization, create one here.

3. Launch the CloudFormation Stack

Click the button in the integration setup guide to open the pre-filled CloudFormation stack creation page.

The stack will automatically provision the required IAM Role, permissions, SSO Instance ID, and Administrator permission set for Hyphen.

4. Confirm IAM Resource Creation

On the AWS CloudFormation page:

• Scroll down to the Capabilities section.
• Check the following box:
  “I acknowledge that AWS CloudFormation might create IAM resources with custom names.”

Then click Create stack.

5. What Resources Will Be Created?

When you launch the integration stack, Hyphen automatically provisions the following resources in your AWS account via CloudFormation:

✅ IAM Role: hyphen

• Grants Hyphen access to perform specific actions in your AWS Organization and SSO.
• Can only be assumed by Hyphen service principals:
  • arn:aws:iam::640168453690:user/hyphen
  • arn:aws:iam::640168453690:role/hyphen-integration-role-prod

✅ Attached IAM Policy

• Grants only the minimum required permissions to:
  • Manage AWS Organizations (list/move/create accounts and OUs)
  • Access AWS SSO (list and assign permission sets)
  • Interact with AWS Identity Store (groups and memberships)

⚠️

Note: All permissions are scoped to the minimum necessary for the integration to work securely.

✅ Administrator SSO Permission Set

• Creates a new AdministratorAccess permission set in your AWS SSO instance.
• Grants full admin access using AWS’s managed AdministratorAccess policy.
• Used to assign roles to users through Hyphen.

✅ SSO Instance Auto-Detection

• If multiple SSO instances exist, the oldest one is selected automatically.

✅ Integration Registration

• The stack reports back to Hyphen with integration metadata:
  • AWS Account ID and Region
  • IAM Role ARN
  • SSO Instance ID
  • Admin Permission Set ARN

Why Are These Resources Needed?

Hyphen uses these resources to securely automate user, account, and permission management in your AWS environment — without requiring you to set things up manually.

6. Wait for Completion

Once the stack is launched, the setup will run automatically in the background.

Please wait a moment — Hyphen will redirect you to the integration details page as soon as the setup is complete.

Configuration

Connections

Permission Group

Permission Group connections link to AWS Groups in AWS IAM Identity Center. Hyphen will automatically create a new group if a connection input is not provided.

When creating a new group, Hyphen will use the Team name.

Configuration

Connection Input

Provide the AWS Group name to connect to an existing Group.

Verification

A verification email will be sent to the AWS Management Account email to verify existing groups.

Access

A User connection will be added as a member when added to the group.

Folder

Folder connections link to existing Organization Units in AWS or create a new one if none is provided.

When creating a new organization unit, the Hyphen Project name will be used as the folder name, adjusted to contain only alphanumeric characters.

Configuration

Connection Input

Provide the AWS organization unit ID to connect to an existing Organization Unit.

Cloud Workspace

Cloud Workspace connections link to existing AWS Accounts or create a new one if none is provided.

An AWS account relies on a Folder connection. If no Folder connection exists for the Hyphen project environment, a new Folder will be created.

A Cloud Workspace connection requires a Google Workspace or Office 365 Distribution List. If neither exists, a new one will be created.

When creating a new account, the account name will combine the Hyphen project name and environment name.

Configuration

Connection Input

Provide the AWS account ID to connect to an existing Account.

Verification

A verification email will be sent to the AWS account email to verify existing accounts.

Smart Access

A Team connection will be added as a group when added to the account.

User

User connections link to AWS Users in AWS IAM Identity Center. Hyphen will not automatically create Users in AWS. If no connection input is provided, the Hyphen Member's email address will be used to look up the AWS User.

Configuration

Connection Input

Provide the username of the AWS User account to connect to an existing User.

Test Connect