idp-scim-sync

README

🆔 idp-scim-sync

Keep your AWS IAM Identity Center (formerly AWS SSO) in sync with your Google Workspace directory using an AWS Lambda function. 🚀

✨ Features

• ✅ Extended Attribute Support: Syncs extended AWS SSO SCIM API fields as described in the official documentation.
• ✅ Efficient Data Retrieval: Uses partial responses from the Google Workspace API to fetch only the data you need.
• ✅ Nested Groups Support: Supports nested groups in Google Workspace thanks to the includeDerivedMembership API query parameter.
• ✅ Multiple Deployment Options: Can be deployed via the AWS Serverless Application Repository, as a Container Image, or as a CLI.
• ✅ Incremental Sync: Drastically reduces the number of requests to the AWS SSO SCIM API by using a state file to track changes.

Compatibility

This project is compatible with the latest AWS Lambda runtimes. Since version v0.0.19, it uses the provided.al2 runtime and arm64 architecture.

Version Range	AWS Lambda Runtime	Architecture	Deprecation Date
<= v0.0.18	Go 1.x	amd64 (Intel)	2023-12-31
>= v0.0.19 < v0.31.0	provided.al2	arm64 (Graviton 2)	2026-06-30
>= v0.31.0	provided.al2023	arm64 (Graviton 2)	2029-06-30

⚙️ How It Works

The AWS Lambda function is triggered by a CloudWatch event rule (every 15 minutes by default). It syncs your AWS IAM Identity Center with your Google Workspace directory using their respective APIs.

During the first sync, the data of your Groups and Users is stored in an AWS S3 bucket as a state file. This state file is a custom implementation to save time and requests to the AWS SSO SCIM API, and to mitigate some of its limitations.

This project is developed using the Go language and AWS SAM.

For more details on the resources created by the CloudFormation template, please check the AWS SAM Template documentation.

Note: If this is your first time implementing AWS IAM Identity Center, please read Using SSO.

🚀 Getting Started

The easiest way to deploy and use this project is through the AWS Serverless Application Repository.

Credentials

You will need to configure credentials for both Google Workspace and AWS.

• Google Workspace API Credentials

  • Follow the Google Workspace documentation to create credentials.
  • You will need to create a Service Account and delegate domain-wide authority to it with the following scopes:
    • https://www.googleapis.com/auth/admin.directory.group.readonly
    • https://www.googleapis.com/auth/admin.directory.user.readonly
    • https://www.googleapis.com/auth/admin.directory.group.member.readonly

• AWS SSO SCIM API Credentials

  • Configure these credentials in the AWS IAM Identity Center service by following the Automatic provisioning guide.

🛠️ Usage

You have several options to use this project:

In AWS

• AWS Serverless Application Repository (Recommended)

  • Deploy the application directly from the AWS Serverless Application Repository.

• AWS SAM

  • Build and deploy the Lambda function from your local machine.

  • Requirements:

    • Git
    • Go
    • AWS SAM CLI

  • Commands:

    ```bash
    # Set your AWS CLI profile and region
    export AWS_PROFILE=<profile_name>
    export AWS_REGION=<region>
    
    # Validate the template
    sam validate
    
    # Build the project
    sam build
    
    # Deploy with a guided process
    sam deploy --guided --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM
    ```
    

Locally

• Build from Source

  • Requirements:

    • Git
    • Go
    • Make

  • Commands:

    ```bash
    # Compile for your operating system
    make
    
    # Cross-compile for Windows, macOS, and Linux
    make build-dist
    ```
    

• Pre-built Binaries

  • Download the binaries from the GitHub Releases.

• Docker Image

  • Pull the image from one of the public repositories.

📦 Repositories

• 📦 AWS Serverless Application Repository
• 📦 AWS ECR Public Gallery
• 📦 GitHub Packages
• 📦 Docker Hub

⚠️ Limitations

• Group Limit: The AWS SSO SCIM API has a limit of 50 groups per request. Please support the feature request on the AWS Support site to help get this limit increased.
• Throttling: With a large number of users and groups, you may encounter a ThrottlingException from the AWS SSO SCIM API. This project uses a retryable HTTP client to mitigate this, but it's still a possibility.
• User Status: The Google Workspace API doesn't differentiate between normal and guest users except for their status. This project only syncs ACTIVE users.

For ssosync Users

If you are coming from the awslabs/ssosync project, please note the following:

• This project only implements the --sync-method groups.
• This project only implements filtering for Google Workspace Groups, not Users.
• The flag names are different.
• Not all features of ssosync are implemented here, and they may not be in the future.

🧩 Components

• idpscim: A program for keeping AWS IAM Identity Center groups and users synced with your Google Workspace directory. See the idpscim documentation for more details.
• idpscimcli: A command-line tool to check and validate some of the functionalities implemented in idpscim. See the idpscimcli documentation for more details.

📄 License

This project is released under the Apache License 2.0. See the LICENSE file for more details.