Skip to content
This repository was archived by the owner on Mar 27, 2022. It is now read-only.

Commit eb474e4

Browse files
mettkemettke
committed
Adding documentation
1 parent 7e0e211 commit eb474e4

File tree

2 files changed

+271
-1
lines changed

2 files changed

+271
-1
lines changed

‎README.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,139 @@
11
# lambda-aws-sso-google-sync
22

3+
This tool syncs Users and Groups from Google Workspace to AWS SSO
4+
5+
## Limitations
6+
7+
AWS SCIM only returns 50 [Users](https://docs.aws.amazon.com/singlesignon/latest/developerguide/listusers.html)
8+
or [Groups](https://docs.aws.amazon.com/singlesignon/latest/developerguide/listgroups.html).
9+
This means:
10+
* For Users: If you have more then 50 Users, the tool will still be able to remove
11+
users added through Google Workspace, but it probably won't be able to remove manually
12+
added users in AWS SSO.
13+
* For Groups: If you have more then 50 Groups, the tool probably won't be able to
14+
remove groups after they were deleted in Google Workspace. The reason for this is
15+
that Google does not provide information about deleted groups. This also means, that
16+
group membership will not be removed, as it is not possible to fetch all groups for
17+
a User in AWS SCIM
18+
19+
## Recommendations
20+
21+
To combat these limitations and to get the best performance, adhere to the following
22+
recommendations:
23+
* Try to keep as few groups as possible (best is below 50) by using
24+
`google_api_query_for_groups`, `ignore_groups_regexes` and/or
25+
`include_groups_regexes`.
26+
* Try to keep as few users as possible (best is below 50) by using
27+
`google_api_query_for_users`, `ignore_users_regexes` and/or
28+
`include_users_regexes`.
29+
* Only sync users which are members of a group that is synced to AWS by using
30+
the sync strategie `GroupMembersOnly`.
31+
32+
## Setup
33+
34+
* Enable `Admin SDK API` in the [Google Console](https://console.cloud.google.com/apis)<br>
35+
(At the top of the Dashboard, there is a `Enable Apis and services` Button. Search for
36+
`Admin SDK API` and click enable)
37+
* Create a [Google Service User](https://developers.google.com/admin-sdk/directory/v1/guides/delegation)<br>
38+
(Keep the credentials.json which is required at a later stage)
39+
* Setup Domain-Wide Delegation Scopes:
40+
* https://www.googleapis.com/auth/admin.directory.group.readonly
41+
* https://www.googleapis.com/auth/admin.directory.group.member.readonly
42+
* https://www.googleapis.com/auth/admin.directory.user.readonly
43+
* Enable Provisining in the AWS SSO Console <br>
44+
(Keep Token and SCIM endpoint which are required at a later stage)
45+
* Create a Secret in AWS Secret Manager with the following content:
46+
```json
47+
{
48+
"endpoint": "<scim_endpoint>",
49+
"access_token": "<token>"
50+
}
51+
```
52+
* Create another Secret in AWS Secret Manager with the following content
53+
```json
54+
{
55+
"mail": "<mail of a google admin user>",
56+
"credential_json": <credentials.json either as String or Object>
57+
}
58+
```
59+
* Create a lambda with the binary from this repository using runtime `provided.al2`
60+
and anything as handler. (More Infos about paramters below)
61+
* Create a CloudWatch Event to trigger the lambda regularly
62+
63+
## Parameters
64+
65+
The lambda function requires a few parameters to correctly work. You can define
66+
them either with the Event that is send to the lambda, or via environment variables.
67+
68+
### Event
69+
70+
```json
71+
{
72+
"security_hub_google_creds": {
73+
"region": "eu-central-1",
74+
"id": "<google_secret_name>"
75+
},
76+
"security_hub_scim_creds": {
77+
"region": "eu-central-1",
78+
"id": "<scim_secret_name>"
79+
},
80+
// Optional, remove if not required. Example: `email:aws-*`
81+
// Query send via Google API to filter users
82+
// More Infos at https://developers.google.com/admin-sdk/directory/v1/guides/search-users
83+
"google_api_query_for_users": "",
84+
// Optional, remove if not required. Example: `email:aws-*`
85+
// Query send via Google API to filter groups
86+
// More Infos at https://developers.google.com/admin-sdk/directory/v1/guides/search-groups
87+
"google_api_query_for_groups": "",
88+
// Optional, remove if not required. Example: `aws-.*@domain.org`
89+
// Ignores a user if one of the regexes matches. Matches on the primary_email
90+
"ignore_users_regexes": [],
91+
// Optional, remove if not required. Example: `aws-.*@domain.org`
92+
// Includes a user if one of the regexes matches. Matches on the primary_email
93+
"include_users_regexes": [],
94+
// Optional, remove if not required. Example: `aws-.*@domain.org`
95+
// Ignores a group if one of the regexes matches. Matches on the email
96+
"ignore_groups_regexes": [],
97+
// Optional, remove if not required. Example: `aws-.*@domain.org`
98+
// Includes a group if one of the regexes matches. Matches on the email
99+
"include_groups_regexes": [],
100+
// Optional, remove if not required. AllUsers | GroupMembersOnly (default)
101+
// Defines the sync strategie
102+
"sync_strategie": [],
103+
}
104+
```
105+
106+
### Environment Variables
107+
```sh
108+
SH_GOOGLE_CREDS="{\"region\": \"eu-central-1\",\"id\": \"<google_secret_name>\"}"
109+
SH_SCIM_CREDS="{\"region\": \"eu-central-1\",\"id\": \"<scim_secret_name>\"}"
110+
# Optional, skip if not required. Example: `email:aws-*`
111+
# Query send via Google API to filter users
112+
# More Infos at https://developers.google.com/admin-sdk/directory/v1/guides/search-users
113+
GOOGLE_API_QUERY_FOR_USERS=""
114+
# Optional, skip if not required. Example: `email:aws-*`
115+
# Query send via Google API to filter groups
116+
# More Infos at https://developers.google.com/admin-sdk/directory/v1/guides/search-groups
117+
GOOGLE_API_QUERY_FOR_GROUPS=""
118+
# Optional, skip if not required. Example: `aws-.*@domain.org`
119+
# Ignores a user if one of the regexes matches. Matches on the primary_email
120+
IGNORE_USERS_REGEXES=""
121+
# Optional, skip if not required. Example: `aws-.*@domain.org`
122+
# Includes a user if one of the regexes matches. Matches on the primary_email
123+
INCLUDE_USERS_REGEXES=""
124+
# Optional, skip if not required. Example: `aws-.*@domain.org`
125+
# Ignores a group if one of the regexes matches. Matches on the email
126+
IGNORE_GROUPS_REGEXES=""
127+
# Optional, skip if not required. Example: `aws-.*@domain.org`
128+
# Includes a group if one of the regexes matches. Matches on the email
129+
INCLUDE_GROUPS_REGEXES=""
130+
# Optional, skip if not required. AllUsers | GroupMembersOnly (default)
131+
# Defines the sync strategie
132+
SYNC_STRATEGIE=""
133+
# Optional, skip if not required. off | error | warn | info (default) | debug | trace
134+
# Defines the log level
135+
LOG_LEVEL=""
136+
```
137+
138+
3139
License: MIT OR Apache-2.0

‎src/main.rs

Lines changed: 135 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,138 @@
1-
//! Syncs Users and Groups from Google Workspace to AWS SSO
1+
//! This tool syncs Users and Groups from Google Workspace to AWS SSO
2+
//!
3+
//! # Limitations
4+
//!
5+
//! AWS SCIM only returns 50 [Users](https://docs.aws.amazon.com/singlesignon/latest/developerguide/listusers.html)
6+
//! or [Groups](https://docs.aws.amazon.com/singlesignon/latest/developerguide/listgroups.html).
7+
//! This means:
8+
//! * For Users: If you have more then 50 Users, the tool will still be able to remove
9+
//! users added through Google Workspace, but it probably won't be able to remove manually
10+
//! added users in AWS SSO.
11+
//! * For Groups: If you have more then 50 Groups, the tool probably won't be able to
12+
//! remove groups after they were deleted in Google Workspace. The reason for this is
13+
//! that Google does not provide information about deleted groups. This also means, that
14+
//! group membership will not be removed, as it is not possible to fetch all groups for
15+
//! a User in AWS SCIM
16+
//!
17+
//! # Recommendations
18+
//!
19+
//! To combat these limitations and to get the best performance, adhere to the following
20+
//! recommendations:
21+
//! * Try to keep as few groups as possible (best is below 50) by using
22+
//! `google_api_query_for_groups`, `ignore_groups_regexes` and/or
23+
//! `include_groups_regexes`.
24+
//! * Try to keep as few users as possible (best is below 50) by using
25+
//! `google_api_query_for_users`, `ignore_users_regexes` and/or
26+
//! `include_users_regexes`.
27+
//! * Only sync users which are members of a group that is synced to AWS by using
28+
//! the sync strategie `GroupMembersOnly`.
29+
//!
30+
//! # Setup
31+
//!
32+
//! * Enable `Admin SDK API` in the [Google Console](https://console.cloud.google.com/apis)<br>
33+
//! (At the top of the Dashboard, there is a `Enable Apis and services` Button. Search for
34+
//! `Admin SDK API` and click enable)
35+
//! * Create a [Google Service User](https://developers.google.com/admin-sdk/directory/v1/guides/delegation)<br>
36+
//! (Keep the credentials.json which is required at a later stage)
37+
//! * Setup Domain-Wide Delegation Scopes:
38+
//! * https://www.googleapis.com/auth/admin.directory.group.readonly
39+
//! * https://www.googleapis.com/auth/admin.directory.group.member.readonly
40+
//! * https://www.googleapis.com/auth/admin.directory.user.readonly
41+
//! * Enable Provisining in the AWS SSO Console <br>
42+
//! (Keep Token and SCIM endpoint which are required at a later stage)
43+
//! * Create a Secret in AWS Secret Manager with the following content:
44+
//! ```json
45+
//! {
46+
//! "endpoint": "<scim_endpoint>",
47+
//! "access_token": "<token>"
48+
//! }
49+
//! ```
50+
//! * Create another Secret in AWS Secret Manager with the following content
51+
//! ```json
52+
//! {
53+
//! "mail": "<mail of a google admin user>",
54+
//! "credential_json": <credentials.json either as String or Object>
55+
//! }
56+
//! ```
57+
//! * Create a lambda with the binary from this repository using runtime `provided.al2`
58+
//! and anything as handler. (More Infos about paramters below)
59+
//! * Create a CloudWatch Event to trigger the lambda regularly
60+
//!
61+
//! # Parameters
62+
//!
63+
//! The lambda function requires a few parameters to correctly work. You can define
64+
//! them either with the Event that is send to the lambda, or via environment variables.
65+
//!
66+
//! ## Event
67+
//!
68+
//! ```json
69+
//! {
70+
//! "security_hub_google_creds": {
71+
//! "region": "<region_of_secret>",
72+
//! "id": "<google_secret_name>"
73+
//! },
74+
//! "security_hub_scim_creds": {
75+
//! "region": "<region_of_secret>",
76+
//! "id": "<scim_secret_name>"
77+
//! },
78+
//! // Optional, remove if not required. Example: `email:aws-*`
79+
//! // Query send via Google API to filter users
80+
//! // More Infos at https://developers.google.com/admin-sdk/directory/v1/guides/search-users
81+
//! "google_api_query_for_users": "",
82+
//! // Optional, remove if not required. Example: `email:aws-*`
83+
//! // Query send via Google API to filter groups
84+
//! // More Infos at https://developers.google.com/admin-sdk/directory/v1/guides/search-groups
85+
//! "google_api_query_for_groups": "",
86+
//! // Optional, remove if not required. Example: `aws-.*@domain.org`
87+
//! // Ignores a user if one of the regexes matches. Matches on the primary_email
88+
//! "ignore_users_regexes": [],
89+
//! // Optional, remove if not required. Example: `aws-.*@domain.org`
90+
//! // Includes a user if one of the regexes matches. Matches on the primary_email
91+
//! "include_users_regexes": [],
92+
//! // Optional, remove if not required. Example: `aws-.*@domain.org`
93+
//! // Ignores a group if one of the regexes matches. Matches on the email
94+
//! "ignore_groups_regexes": [],
95+
//! // Optional, remove if not required. Example: `aws-.*@domain.org`
96+
//! // Includes a group if one of the regexes matches. Matches on the email
97+
//! "include_groups_regexes": [],
98+
//! // Optional, remove if not required. AllUsers | GroupMembersOnly (default)
99+
//! // Defines the sync strategie
100+
//! "sync_strategie": [],
101+
//! }
102+
//! ```
103+
//!
104+
//! ## Environment Variables
105+
//! ```sh
106+
//! SH_GOOGLE_CREDS="{\"region\": \"<region_of_secret>\",\"id\": \"<google_secret_name>\"}"
107+
//! SH_SCIM_CREDS="{\"region\": \"<region_of_secret>\",\"id\": \"<scim_secret_name>\"}"
108+
//! # Optional, skip if not required. Example: `email:aws-*`
109+
//! # Query send via Google API to filter users
110+
//! # More Infos at https://developers.google.com/admin-sdk/directory/v1/guides/search-users
111+
//! GOOGLE_API_QUERY_FOR_USERS=""
112+
//! # Optional, skip if not required. Example: `email:aws-*`
113+
//! # Query send via Google API to filter groups
114+
//! # More Infos at https://developers.google.com/admin-sdk/directory/v1/guides/search-groups
115+
//! GOOGLE_API_QUERY_FOR_GROUPS=""
116+
//! # Optional, skip if not required. Example: `aws-.*@domain.org`
117+
//! # Ignores a user if one of the regexes matches. Matches on the primary_email
118+
//! IGNORE_USERS_REGEXES=""
119+
//! # Optional, skip if not required. Example: `aws-.*@domain.org`
120+
//! # Includes a user if one of the regexes matches. Matches on the primary_email
121+
//! INCLUDE_USERS_REGEXES=""
122+
//! # Optional, skip if not required. Example: `aws-.*@domain.org`
123+
//! # Ignores a group if one of the regexes matches. Matches on the email
124+
//! IGNORE_GROUPS_REGEXES=""
125+
//! # Optional, skip if not required. Example: `aws-.*@domain.org`
126+
//! # Includes a group if one of the regexes matches. Matches on the email
127+
//! INCLUDE_GROUPS_REGEXES=""
128+
//! # Optional, skip if not required. AllUsers | GroupMembersOnly (default)
129+
//! # Defines the sync strategie
130+
//! SYNC_STRATEGIE=""
131+
//! # Optional, skip if not required. off | error | warn | info (default) | debug | trace
132+
//! # Defines the log level
133+
//! LOG_LEVEL=""
134+
//! ```
135+
//!
2136
3137
#![warn(
4138
absolute_paths_not_starting_with_crate,

0 commit comments

Comments
 (0)