idp-scim-sync

README

idp-scim-sync

Keep your AWS IAM Identity Center (Successor to AWS Single Sign-On) in sync with your Google Workspace directory using and AWS Lambda function.

As the image above shows, the AWS Lambda function is triggered by a CloudWatch event rule, the event rule is configured to run every 15 minutes (default in the cfn template), and sync the AWS IAM Identity Center (Successor to AWS Single Sign-On) with Google Workspace directory using their respective APIs. During the first sync, the data of the Groups and Users are stored in the AWS S3 bucket as the State file

The State file is a custom implementation to save time and requests to the AWS SSO SCIM API, also mitigate some limitations of this.

This project is developed using the Go language and AWS SAM, a tool for creating, publishing and deploying AWS Serverless Applications in an easy way.

If you want to know what creates the CloudFormation Template, please check the AWS SAM Template

First time implementing AWS IAM Identity Center (Successor to AWS Single Sign-On)? please read Using SSO

The best way to to deploy and use this is through the AWS Serverless public repository - slashdevops/idp-scim-sync

Compatibility

AWS recently announced AWS Lambda Deprecates Go Runtime 1.x and posted this article Migrating AWS Lambda functions from the Go1.x runtime to the custom runtime on Amazon Linux 2 to help customers with the migration.

This project is already migrated since version v0.0.19 to the provided.al2 runtime and arm64 architecture, so you can use it without any problem.

version	AWS Lambda Runtime	Architecture	Deprecation Date
<= v0.0.18	Go 1.x	amd64 (Intel)	2023-12-31
>= v0.0.19	provided.al2	arm64 (Graviton 2)	----------

Features

• Support extended AWS SSO SCIM API fields described here attributes and the relation between Google Workspace API fields occurred here User Entity
• Efficient data retrieval from Google Workspace API using Partial response
• Supported nested groups in Google Workspace thanks to includeDerivedMembership API Query Parameter
• Could be used or deployed via AWS Serverless repository (Public), Container Image or CLI. See Repositories
• Incremental changes, drastically reduced the number of requests to the AWS SSO SCIM API thanks to the implementation of State file

Important

The documentation is a WIP and you can contribute!

Credentials

• Google Workspace API credentials This application will need Google Workspace Directory API to retrieve Users, Groups and Members data. Configure this is a little bit tricky, but it is well documented by Google. The Authorization/Authorization needed is OAuth 2.0 for Server to Server Applications and this require to:
  1. Create a Service Account on Google Cloud Platform
  2. Delegate domain-wide authority to the service account, the scope needed are:
     1. https://www.googleapis.com/auth/admin.directory.group.readonly
     2. https://www.googleapis.com/auth/admin.directory.user.readonly
     3. https://www.googleapis.com/auth/admin.directory.group.member.readonly
• AWS SSO SCIM API credentials This credentials is configured in the AWS IAM Identity Center (Successor to AWS Single Sign-On) service following the Automatic provisioning guide.

Repositories

• AWS Serverless public repository - slashdevops/idp-scim-sync
• AWS ECR public repository - slashdevops/idp-scim-sync
• GitHub public repository - slashdevops/idp-scim-sync
• Docker Hub public repository - slashdevops/idp-scim-sync

Limitations

Most of the limitations of this project are due to AWS SSO SCIM API Limitations.

• Use less than 50 Groups --> AWS SSO SCIM API (ListGroups) has a limit of 50 Groups per request. I created these tickets in AWS Support site AWS SSO SCIM API pagination for methods and AWS SSO SCIM API ListGroups members, please consider supporting this ticket with your 👍.
• Too much Users and Groups could generate a ThrottlingException of the some AWS SSO SCIM API methods
• Google Workspace API doesn't separate normal and guest users expect for status (guest miss status), so only ACTIVE users are collected to model as group members. Logically all users who are wanted (and capable of) to sign in are ACTIVE.

NOTES:

1. The use of the The State file could mitigate the number 1, but I recommend you be cautious of these limitations as well.
2. The project implements a well-known HTTP Retryable client (/go-retryablehttp) to mitigate the number 2, but I recommend you be cautious of these limitations as well.

Users that come from the project SSO Sync

• This project only implements the --sync-method groups, so if you are using the --sync-method users_groups you can't use it, because this is going to delete and recreate your data in the AWS SSO side.
• This project only implements the filter for the Google Workspace Groups, so if you are using the filter for the Google Workspace Users, you can't use it. Please see Using SSO for more information.
• The flags names of this project are different from the ones of the SSO Sync
• Not "all the features" of the SSO Sync are implemented here, and maybe will not be.

Components

1. idpscim is a program for keeping AWS Single Sign-On (SSO) groups and users synced with Google Workspace directory service using the AWS SSO SCIM API. Details here.
2. idpscimcli is a command-line tool to check and validate some functionalities implemented in idpscim. Details here.

Requirements

• AWS Single Sign-On -> Connect to your external identity provider
• AWS Single Sign-On -> Automatic provisioning

How to use

To use this project you have different options, and depending on your needs you can use the following

In AWS

There are two ways to use this project in AWS and described below.

Using AWS Serverless Repository

This is the easy way, this project is deployed as an AWS Serverless Application in AWS Serverless Application Repository.

The public repository of the project is slashdevops/idp-scim-sync

NOTE: The repository depends on your AWS Region.

Using AWS SAM

This is the way if you want to build and deploy the lambda function from your local machine.

Requirements:

1. git
2. Go
3. AWS SAM Cli

Validate, Build and Deploy:

# your AWS Cli Profile and Region
export AWS_PROFILE=<profile name here>
export AWS_REGION=<region here>

# validate
aws cloudformation validate-template --template-body file://template.yaml 1>/dev/null --profile $AWS_PROFILE
sam validate --profile $AWS_PROFILE

# build
sam build --profile $AWS_PROFILE

# deploy guided
sam deploy --guided  --capabilities CAPABILITY_IAM --capabilities CAPABILITY_NAMED_IAM --profile $AWS_PROFILE

Are you using AWS Cli Profiles?, read AWS-SAM

In Local

You will have two ways to execute the binaries of this project in local, building these or using the pre-built stored in the github repository project.

Building the project

To build the project in local, you will need to have installed and configured at least the following:

1. git
2. Go
3. make

Then you will need to clone the repository in your local machine, and execute the following commands:

• Compile for your Operating System:

make

then the binaries are in build/ folder.

• Cross-compiling the project for Windows, MacOS and Linux (default)

make clean
make test # optional
make build-dist

then the binaries are in dist/ folder.

• Others Operating Systems, see the list of supported platforms in the syslist.go

make clean
GO_OS=<something from goosList in syslist.go> GO_ARCH=<something from goarchList in syslist.go> make test # optional
GO_OS=<something from goosList in syslist.go> GO_ARCH=<something from goarchList in syslist.go> make build-dist

then the binaries are in dist/ folder.

• Execute

./idpscim --help
#or
./idpscimcli --help

Using the pre-built binaries

This is the easy way, just download the binaries you need from the github repository releases

Using the pre-built binaries in local

Example docs/Demo.md

License

This module is released under the Apache License Version 2.0:

• http://www.apache.org/licenses/LICENSE-2.0.html