ssosync

SSO Sync

Seamlessly synchronize Google Workspace users and groups to AWS IAM Identity Center

SSO Sync is a powerful CLI tool and AWS Lambda function that enables automatic provisioning of Google Workspace (formerly G Suite) users and groups into AWS IAM Identity Center (formerly AWS SSO). Built with Go and powered by AWS SDK v2, it provides reliable, scalable, and secure identity synchronization.

✨ Key Features

• ** Uni-directional Sync**: Supports both groups and users_groups sync methods
• ** Advanced Filtering**: Flexible user and group filtering with Google API query parameters
• ️ Dry-Run Mode: Test synchronization without making actual changes
• ⚡ High Performance: Built with AWS SDK v2 for improved performance and reliability
• ** Multiple Deployment Options**: CLI, AWS Lambda, or AWS SAM deployment
• ** Comprehensive Logging**: Structured logging with configurable levels and formats
• ** Secure**: AWS Secrets Manager integration for credential management
• ** Scalable**: Supports large directories with user caching and pagination

Quick Start

Use one of the quick start templates to simplify the your deployment. Use these templates, with the Sync from Git option, to make updates to your deployment far simpler.

Step-by-Step Guide

Want to dive straight in? Try this hands-on lab from the AWS Control Tower Workshop. The lab guides you through the complete setup process for both AWS and Google Workspace using the recommended Lambda deployment from the AWS Serverless Application Repository.

Installation Options

Why?

As per the AWS SSO Homepage:

AWS Single Sign-On (SSO) makes it easy to centrally manage access to multiple AWS accounts and business applications and provide users with single sign-on access to all their assigned accounts and applications from one place.

Key part further down:

With AWS SSO, you can create and manage user identities in AWS SSO's identity store, or easily connect to your existing identity source including Microsoft Active Directory and Azure Active Directory (Azure AD).

AWS SSO can use other Identity Providers as well... such as Google Apps for Domains. Although AWS SSO supports a subset of the SCIM protocol for populating users, it currently only has support for Azure AD.

This project provides a CLI tool to pull users and groups from Google and push them into AWS SSO. ssosync deals with removing users as well. The heavily commented code provides you with the detail of what it is going to do.

⚠️ Important Notices

[!IMPORTANT] From v2.7.x the behavior when syncing users has changed for the following situation: If a user in the Google Workspace Directory has been deleted and recreated (and therefore its user id has changed but the email address remains the same).

• Since v2.4 the existing IAM Identity Store user would have the ExternalId field updated. However, in the situation where an email address has been re-assigned to a different user this would lead to them inheriting permission assignments made directly to the user.
• From v2.7 the default bahvaiour will be to delete the existing user and create a new one. This behavior can be overriden with --force-externalid-update option.

[!IMPORTANT] Region and IdentityStoreID are no longer configurable parameters. Region is extracted programmatically from the SCIM Endpoint URL, and IdentityStoreID is resolved automatically via the IAM Identity Center ListInstances API. These parameters are still present in template.yaml to avoid breaking deployment tooling for anyone passing a parameter file to the CloudFormation Stack. They will be fully removed in v3.x.

[!CAUTION] When using ssosync with an instance of IAM Identity Center integrated with AWS Control Tower. AWS Control Tower creates a number of groups and users (directly via the Identity Store API), when an external identity provider is configured these users and groups are can not be used to log in. However it is important to remember that because ssosync implemements a uni-directional sync it will make the IAM Identity Store match the subset of your Google Workspaces directory you specify, including removing these groups and users created by AWS Control Tower. There is a PFR #179 Configurable handling of 'manually created' Users/Groups in IAM Identity Center to implement an option to ignore these users and groups, hopefully this will be implemented in version 3.x. However, this has a dependancy on PFR #166 Ensure all groups/user creates in IAM Identity Store are via SCIM api and populate externalId field, to be able to reliably and consistently disinguish between SCIM Provisioned users from Manually Created users

[!WARNING] There are breaking changes for versions >= 0.02

[!WARNING] >= 1.0.0-rc.5 groups to do not get deleted in AWS SSO when deleted in the Google Directory, and groups are synced by their email address

[!WARNING] >= 2.0.0 this makes use of the Identity Store API which means:

• if deploying the lambda from the AWS Serverless Application Repository then it needs to be deployed into the IAM Identity Center delegated administration account. Technically you could deploy in the management account but we would recommend against this.
• if you are running the project as a cli tool, then the environment will need to be using credentials of a user in the IAM Identity Center delegated administration account, with appropriate permissions.

[!WARNING] >= 2.1.0 make use of named IAM resources, so if deploying via CICD or IaC template will require CAPABILITY_NAMED_IAM to be specified.

[!IMPORTANT] >= 2.1.0 switched to using provided.al2 powered by ARM64 instances.

[!IMPORTANT] As of v2.2.0 multiple query patterns are supported for both Group and User matching, simply separate each query with a ,. For full sync of groups and/or users specify '*' in the relevant match field. User match and group match can now be used in combination with the sync method of groups. Nested groups will now be flattened into the top level groups. External users are ignored. Group owners are treated as regular group members. User details are now cached to reduce the number of api calls and improve execution times on large directories.

References

• SCIM Protocol RFC
• AWS SSO - Connect to Your External Identity Provider
• AWS SSO - Automatic Provisioning
• AWS IAM Identity Center - Identity Store API

Installation

The recommended installation is:

• Setup IAM Identity Center, in the management account of your organization
• Created a linked account Identity Account from which to manage IAM Identity Center
• Delegate administration to the Identity account
• Deploy the SSOSync app from the AWS Serverless Application Repository

You can also: You can go get github.com/awslabs/ssosync or grab a Release binary from the release page. The binary can be used from your local computer, or you can deploy to AWS Lambda to run on a CloudWatch Event for regular synchronization.

⚙️ Configuration

SSO Sync requires configuration from both Google Workspace and AWS sides.

Google Workspace Setup

1. Enable Admin SDK API

   • Go to Google Cloud Console
   • Select API & Services > Enable APIs and Services
   • Search for Admin SDK and Enable the API

2. Create Service Account

   • Follow this delegation tutorial
   • Save the JSON credentials file as credentials.json
   • Grant domain-wide delegation with these scopes:
     • https://www.googleapis.com/auth/admin.directory.group.readonly
     • https://www.googleapis.com/auth/admin.directory.group.member.readonly
     • https://www.googleapis.com/auth/admin.directory.user.readonly

3. Specify Admin User

   • You'll need the email address of a Google Workspace admin user

AWS Setup

1. Enable IAM Identity Center

   • Go to AWS IAM Identity Center console
   • Select Settings → Enable automatic provisioning
   • Copy the SCIM Endpoint URL and Access Token

2. AWS Credentials

   • Configure AWS credentials using any standard method:
     • AWS credentials file (~/.aws/credentials)
     • Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
     • IAM roles (for Lambda deployment)
   • The executing role needs permissions for sso:ListInstances to auto-detect the Identity Store ID

Usage

CLI Usage

./ssosync --help

Basic Example

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

Advanced Examples

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

# Sync all users and groups
./ssosync \
  --user-match "*" \
  --group-match "*" \
  --sync-method users_groups

# Ignore specific users/groups
./ssosync \
  --group-match "*" \
  --ignore-users "[email protected],[email protected]" \
  --ignore-groups "[email protected]"

Environment Variables

All CLI flags can be set via environment variables with the SSOSYNC_ prefix:

export SSOSYNC_GOOGLE_ADMIN="[email protected]"
export SSOSYNC_GOOGLE_CREDENTIALS="./credentials.json"
export SSOSYNC_SCIM_ENDPOINT="https://scim.us-east-1.amazonaws.com/..."
export SSOSYNC_SCIM_ACCESS_TOKEN="AQoDYXdzE..."
export SSOSYNC_GROUP_MATCH="name:AWS*"
export SSOSYNC_DRY_RUN="true"

Configuration Options