Helping you populate AWS SSO directly with your Google Apps users
SSO Sync will run on any platform that Go can build for. It is available in the AWS Serverless Application Repository
⚠️ there are breaking changes for versions>= 0.02
⚠️ >= 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
🤔 we hope to support other providers in the future
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.
- SCIM Protocol RFC
- AWS SSO - Connect to Your External Identity Provider
- AWS SSO - Automatic Provisioning
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.
You need a few items of configuration. One side from AWS, and the other from Google Cloud to allow for API access to each. You should have configured Google as your Identity Provider for AWS SSO already.
You will need the files produced by these steps for AWS Lambda deployment as well as locally running the ssosync tool.
First, you have to setup your API. In the project you want to use go to the Console and select API & Services > Enable APIs and Services. Search for Admin SDK and Enable the API.
You have to perform this tutorial to create a service account that you use to sync your users. Save the JSON file
you create during the process and rename it to credentials.json
.
you can also use the
--google-credentials
parameter to explicitly specify the file with the service credentials. Please, keep this file safe, or store it in the AWS Secrets Manager
In the domain-wide delegation for the Admin API, you have to specify the following scopes for the user.
- 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
Back in the Console go to the Dashboard for the API & Services and select "Enable API and Services".
In the Search box type Admin
and select the Admin SDK
option. Click the Enable
button.
You will have to specify the email address of an admin via --google-admin
to assume this users role in the Directory.
Go to the AWS Single Sign-On console in the region you have set up AWS SSO and select
Settings. Click Enable automatic provisioning
.
A pop up will appear with URL and the Access Token. The Access Token will only appear
at this stage. You want to copy both of these as a parameter to the ssosync
command.
Or you specific these as environment variables.
SSOSYNC_SCIM_ACCESS_TOKEN=<YOUR_TOKEN>
SSOSYNC_SCIM_ENDPOINT=<YOUR_ENDPOINT>
Additionally, authenticate your AWS credentials. Follow this section to create a Shared Credentials File in the home directory or export your Credentials with Environment Variables. Ensure that the default credentials are for the AWS account you intended to be synced.
To obtain your Identity store ID
, go to the AWS Identity Center console and select settings. Under the Identity Source
section, copy the Identity store ID
.
git clone https://github.com/awslabs/ssosync.git
cd ssosync/
make go-build
./ssosync --help
A command line tool to enable you to synchronise your Google
Apps (Google Workspace) users to AWS Single Sign-on (AWS SSO)
Complete documentation is available at https://github.com/awslabs/ssosync
Usage:
ssosync [flags]
Flags:
-t, --access-token string AWS SSO SCIM API Access Token
-d, --debug enable verbose / debug logging
-e, --endpoint string AWS SSO SCIM API Endpoint
-u, --google-admin string Google Workspace admin user email
-c, --google-credentials string path to Google Workspace credentials file (default "credentials.json")
-g, --group-match string Google Workspace Groups filter query parameter, example: 'name:Admin* email:aws-*', see: https://developers.google.com/admin-sdk/directory/v1/guides/search-groups
-h, --help help for ssosync
--ignore-groups strings ignores these Google Workspace groups
--ignore-users strings ignores these Google Workspace users
--include-groups strings include only these Google Workspace groups, NOTE: only works when --sync-method 'users_groups'
--log-format string log format (default "text")
--log-level string log level (default "info")
-s, --sync-method string Sync method to use (users_groups|groups) (default "groups")
-m, --user-match string Google Workspace Users filter query parameter, example: 'name:John* email:admin*', see: https://developers.google.com/admin-sdk/directory/v1/guides/search-users
-v, --version version for ssosync
-r, --region AWS region where identity store exists
-i, --identity-store-id AWS Identity Store ID
The function has two behaviour
and these are controlled by the --sync-method
flag, this behavior could be
groups
: (default) The sync procedure work base on Groups, gets the Google Workspace groups and their members, then creates in AWS SSO the users (members of the Google Workspace groups), then the groups and at the end assign the users to their respective groups.users_groups
: (original behavior, previous versions) The sync procedure is simple, gets the Google Workspace users and creates these in AWS SSO Users; then gets Google Workspace groups and creates these in AWS SSO Groups and assigns users to belong to the AWS SSO Groups.
Flags Notes:
--include-groups
only works when--sync-method
isusers_groups
--ignore-users
works for both--sync-method
values. Example:--ignore-users [email protected],[email protected]
or[email protected],[email protected]
--ignore-groups
works for both--sync-method
values. Example: --ignore-groups [email protected],[email protected]or
SSOSYNC_IGNORE_GROUPS=[email protected],[email protected]`--group-match
works for both--sync-method
values and also in combination with--ignore-groups
and--ignore-users
. This is the filter query passed to the Google Workspace Directory API when search Groups, if the flag is not used, groups are not filtered.--user-match
works for both--sync-method
values and also in combination with--ignore-groups
and--ignore-users
. This is the filter query passed to the Google Workspace Directory API when search Users, if the flag is not used, users are not filtered.
NOTES:
- Depending on the number of users and groups you have, maybe you can get
AWS SSO SCIM API rate limits errors
, and more frequently happens if you execute the sync many times in a short time. - Depending on the number of users and groups you have,
--debug
flag generate too much logs lines in your AWS Lambda function. So test it in locally with the--debug
flag enabled and disable it when you use a AWS Lambda function.
NOTE: Using Lambda may incur costs in your AWS account. Please make sure you have checked the pricing for AWS Lambda and CloudWatch before continuing.
Running ssosync once means that any changes to your Google directory will not appear in AWS SSO. To sync. regularly, you can run ssosync via AWS Lambda.
You can use the AWS Serverless Application Model (SAM) to deploy this to your account.
Please, install the AWS SAM CLI and GoReleaser.
Specify an Amazon S3 Bucket for the upload with export S3_BUCKET=<YOUR_BUCKET>
.
Execute make package
in the console. Which will package and upload the function to the bucket. You can then use the packaged.yaml
to configure and deploy the stack in AWS CloudFormation Console.
Build
aws cloudformation validate-template --template-body file:https://template.yaml 1>/dev/null &&
sam validate &&
sam build
Deploy
sam deploy --guided