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

• 🔄 Bi-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
• 🧪 Extensive Testing: 61%+ test coverage with comprehensive test suite
• 🔐 Secure: AWS Secrets Manager integration for credential management
• 📈 Scalable: Supports large directories with user caching and pagination

🚀 Quick Start

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

Method	Best For	Setup Time
AWS Serverless App Repository	Production use	5 minutes
CLI Binary	Local testing, CI/CD	2 minutes
AWS SAM	Custom deployments	10 minutes

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

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. Get Identity Store ID

   • In IAM Identity Center console → Settings
   • Copy the Identity Store ID from the Identity Source section

3. 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)

🚀 Usage

CLI Usage

./ssosync --help

Basic Example

./ssosync \
  --google-admin admin@company.com \
  --google-credentials ./credentials.json \
  --scim-endpoint https://scim.us-east-1.amazonaws.com/... \
  --scim-access-token AQoDYXdzE... \
  --region us-east-1 \
  --identity-store-id d-1234567890 \
  --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 "service@company.com,bot@company.com" \
  --ignore-groups "temp-group@company.com"

Environment Variables

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

export SSOSYNC_GOOGLE_ADMIN="admin@company.com"
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_REGION="us-east-1"
export SSOSYNC_IDENTITY_STORE_ID="d-1234567890"
export SSOSYNC_GROUP_MATCH="name:AWS*"
export SSOSYNC_DRY_RUN="true"

Configuration Options

Flag	Environment Variable	Description	Default
--google-admin	SSOSYNC_GOOGLE_ADMIN	Google Workspace admin email	Required
--google-credentials	SSOSYNC_GOOGLE_CREDENTIALS	Path to Google credentials JSON	credentials.json
--scim-endpoint	SSOSYNC_SCIM_ENDPOINT	AWS SCIM endpoint URL	Required
--scim-access-token	SSOSYNC_SCIM_ACCESS_TOKEN	AWS SCIM access token	Required
--region	SSOSYNC_REGION	AWS region	Required
--identity-store-id	SSOSYNC_IDENTITY_STORE_ID	AWS Identity Store ID	Required
--sync-method	SSOSYNC_SYNC_METHOD	Sync method (groups or users_groups)	groups
--group-match	SSOSYNC_GROUP_MATCH	Google Groups filter query	*
--user-match	SSOSYNC_USER_MATCH	Google Users filter query	""
--ignore-users	SSOSYNC_IGNORE_USERS	Comma-separated list of users to ignore	[]
--ignore-groups	SSOSYNC_IGNORE_GROUPS	Comma-separated list of groups to ignore	[]
--include-groups	SSOSYNC_INCLUDE_GROUPS	Include only these groups (users_groups method only)	[]
--dry-run	SSOSYNC_DRY_RUN	Enable dry-run mode	false
--log-level	SSOSYNC_LOG_LEVEL	Log level (debug, info, warn, error)	info
--log-format	SSOSYNC_LOG_FORMAT	Log format (text, json)	text

Filtering Examples

Group Filtering

# Sync groups starting with "AWS"
--group-match "name:AWS*"

# Sync multiple patterns
--group-match "name:Admin*,email:aws-*"

# Sync specific group
--group-match "name=Administrators"

# Sync all groups
--group-match "*"

User Filtering

# Sync users with specific name pattern
--user-match "name:John*"

# Sync users with email pattern
--user-match "email:admin*"

# Sync all users
--user-match "*"

# Complex query
--user-match "name:John*,email:admin*,orgName=Engineering"

For complete query syntax, see:

• Google Groups Search
• Google Users Search

🔧 Development

Prerequisites

• Go 1.24+
• Make
• AWS CLI (for deployment)

Setup Development Environment

# Clone repository
git clone https://github.com/awslabs/ssosync.git
cd ssosync/

# Install development dependencies
make setup

# Run tests
make test

# Build locally
make go-build

# Run with development configuration
make dev

Available Make Targets

make help                 # Show all available targets
make setup               # Install all dependencies
make test                # Run tests with coverage
make test-verbose        # Run tests with verbose output
make test-coverage       # Generate HTML coverage report
make lint                # Run linters
make fmt                 # Format code
make go-build           # Build application
make clean              # Clean build artifacts
make ci                 # Run CI pipeline (fmt, vet, test)

Testing

The project includes comprehensive tests with 61%+ coverage:

# Run all tests
make test

# Run tests with verbose output
make test-verbose

# Generate coverage report
make test-coverage

# Run integration tests (requires valid credentials)
go test -tags=integration ./internal -v

🚀 AWS Lambda Deployment

Serverless Application Repository (Recommended)

Deploy directly from the AWS Serverless Application Repository.

Deployment Patterns

Pattern	Description	Use Case
App + Secrets	Default mode, creates app and secrets	Single account deployment
App Only	Creates app, expects existing secrets	Shared secrets across environments
Secrets Only	Creates secrets without app	Centralized secret management
Cross-Account	App in one account, secrets in another	Multi-account organizations

Manual SAM Deployment

# Build
sam build

# Deploy with guided setup
sam deploy --guided

# Or deploy with parameters
sam deploy \
  --stack-name ssosync \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    GoogleAdminEmail=admin@company.com \
    ScheduleExpression="rate(15 minutes)"

Lambda Environment Variables

When deployed as Lambda, configuration is managed through environment variables and AWS Secrets Manager:

# Required secrets (stored in Secrets Manager)
GOOGLE_ADMIN=<secret-arn>
GOOGLE_CREDENTIALS=<secret-arn>
SCIM_ENDPOINT=<secret-arn>
SCIM_ACCESS_TOKEN=<secret-arn>
REGION=<secret-arn>
IDENTITY_STORE_ID=<secret-arn>

# Optional environment variables
LOG_LEVEL=info
LOG_FORMAT=json
SYNC_METHOD=groups
GROUP_MATCH=*
USER_MATCH=
IGNORE_USERS=
IGNORE_GROUPS=
DRY_RUN=false

📊 Monitoring & Troubleshooting

CloudWatch Logs

When deployed as Lambda, logs are automatically sent to CloudWatch:

# View logs
aws logs describe-log-groups --log-group-name-prefix /aws/lambda/ssosync

# Tail logs
aws logs tail /aws/lambda/ssosync-function --follow

Common Issues

Rate Limiting

Error: AWS SSO SCIM API rate limits errors

Solution: Reduce sync frequency or implement exponential backoff

Authentication Errors

Error: cannot read secret: <secret-name>

Solution: Verify IAM permissions for Secrets Manager access

Google API Errors

Error: Error Getting Deleted Users

Solution: Verify Google service account permissions and domain-wide delegation

Performance Optimization

• User Caching: Enable user caching for large directories
• Filtering: Use specific group/user filters to reduce API calls
• Batch Size: Adjust batch sizes for large sync operations
• Scheduling: Set appropriate sync intervals based on directory size

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: make ci
6. Submit a pull request

Code Standards

• Follow Go best practices
• Maintain test coverage above 60%
• Use structured logging
• Document public APIs
• Follow semantic versioning

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• AWS Labs team for the original implementation
• Google Workspace Directory API team
• AWS IAM Identity Center team
• All contributors and community members

---

Need help? Check out our Issues page or start a Discussion.