SSO Sync

When deploying or running SSO Sync, be aware of the following critical requirements and behaviors:

IAM Identity Center Delegation

• Lambda Deployment: If deploying via the AWS Serverless Application Repository, the Lambda must be deployed into the IAM Identity Center delegated administration account.
• CLI Usage: If running as a CLI tool, your environment must use credentials from a user in the IAM Identity Center delegated administration account with appropriate permissions.

AWS Control Tower Warning

• Caution: If using IAM Identity Center integrated with AWS Control Tower, ssosync will attempt to make the IAM Identity Store match your Google Workspace directory. This includes removing groups and users created by AWS Control Tower. A feature to ignore these manually created entities is planned for v3.x.

Version-Specific Notes

• v2.1.0+: Uses named IAM resources. If deploying via CI/CD or IaC, you must specify CAPABILITY_NAMED_IAM in your CloudFormation stack.
• v2.1.0+: Uses provided.al2 powered by ARM64 instances.
• v2.2.0+: Supports multiple query patterns for Group and User matching by separating queries with a comma (e.g., query1,query2). Use * for full sync.

SSO Sync uses query strings to filter which users and groups are synchronized.

Group Filtering

Use --group-match with patterns:

• name:AWS* (Prefix match)
• name:Admin*,email:aws-* (Multiple patterns)
• name=Administrators (Exact match)
• * (All groups)

User Filtering

The --user-match parameter supports the following fields and operators:

Syntax Rules:

• Use : for prefix/wildcard matching (e.g., name:John*).
• Use = for exact matching (e.g., email=john@company.com).
• Use " for exact values containing spaces (e.g., orgName="My Department").
• Combine multiple patterns with , or a space.
• Use * to sync all users.

# Sync users by department and cost center
--user-match "orgDepartment:Sales*,orgCostCenter=CC-1234"

# Sync users managed by a specific person
--user-match "manager=boss@company.com"

A production-ready environment requires two AWS accounts: a production account and a staging account. This setup involves a multi-step deployment process across management, delegated, and non-delegated accounts.

1. Prepare the Management Account

• Set up AWS Organizations.
• Create two linked accounts: one delegated and one non-delegated.
• Set up IAM Identity Center.
• Delegate administration to the delegated account.

2. Deploy to Staging Accounts

Deploy the following stacks into each staging account (the management account, the delegated IAM Identity Center admin account, and the non-delegated account). Note the output values from these deployments.

• secrets.yaml: Creates secrets for GSuite and IAM Identity Center credentials.
• testing.yaml: Creates the pipeline to deploy and test the application prior to raising a pull request.

3. Setup the Production Account

• Manually create your AWS CodeStar connection.
• Deploy release.yaml: This creates the pipeline that builds the application, triggers the test pipeline in the staging environment, and publishes the app where appropriate.

The SSO Sync CLI allows you to run synchronization tasks from your terminal. You can provide configuration via command-line flags or environment variables prefixed with SSOSYNC_.

Basic Usage

Run a basic sync by providing the required Google and AWS credentials:

./ssosync \
  --google-admin admin@company.com \
  --google-credentials ./credentials.json \
  --endpoint https://scim.us-east-1.amazonaws.com/... \
  --access-token AQoDYXdzE... \
  --group-match "name:AWS*"

Advanced Sync Patterns

Dry Run with Debugging: Test your filters without making changes to AWS:

./ssosync \
  --group-match "name:Engineering*,email:aws-*" \
  --sync-method groups \
  --dry-run \
  --log-level debug

Full Sync (Users and Groups):

./ssosync \
  --user-match "*" \
  --group-match "*" \
  --sync-method users_groups

Excluding Specific Entities:

./ssosync \
  --group-match "*" \
  --ignore-users "service@company.com,bot@company.com" \
  --ignore-groups "temp-group@company.com"