From b0eca61f384e0fb558ed1f3af8b94ac6b605d020 Mon Sep 17 00:00:00 2001 From: ZJ-StratusFort Date: Sat, 8 Mar 2025 13:15:16 -0800 Subject: [PATCH 1/4] adding documentation and example env for Google Workspace --- .env.example.googleworkspace | 82 ++++++++++++++++++++++++++++++++++++ README.md | 17 ++++++++ 2 files changed, 99 insertions(+) create mode 100644 .env.example.googleworkspace diff --git a/.env.example.googleworkspace b/.env.example.googleworkspace new file mode 100644 index 0000000..4748193 --- /dev/null +++ b/.env.example.googleworkspace @@ -0,0 +1,82 @@ +######################### +## GitHub App Settings ## +######################### +## Webhook Secret +WEBHOOK_SECRET=development +## GitHub App ID +APP_ID=12345 +## Private Key Path +PRIVATE_KEY_PATH=.ssh/team-sync.pem +## Uncomment the following line and use your own GitHub Enterprise +## instance if this will not be used on https://github.com +#GHE_HOST=github.example.com +## Uncomment if you are using a self-signed certificate on GitHub Enterprise. +## Defaults to False. +#VERIFY_SSL=False + +## User directory to sync GitHub teams from +## Azure AD = AAD +## Active Directory = LDAP +## OpenLDAP = LDAP +## Okta = OKTA +## OneLogin = ONELOGIN +## Google Workspace = GOOGLE_WORKSPACE +USER_DIRECTORY=GOOGLE_WORKSPACE +## Attribute to compare users with, username or email +## For Google Workspace, the username option will use the specefied custom schema attribute +USER_SYNC_ATTRIBUTE=username + + +############################### +## Google Workspace Settings ## +############################### +## Location of the Google Workspace service account credentials file +GOOGLE_WORKSPACE_SA_CREDS_FILE=googleAuth.json +## Email of a Google Workspace Admin account the service account will impersonate +GOOGLE_WORKSPACE_ADMIN_EMAIL=admin@example.com +## Email attribute to use for syncing users, not required if syncing by username +## Default: primaryEmail +# GOOGLE_WORKSPACE_USER_MAIL_ATTRIBUTE= +## Custom schema name +## Not required if syncing by email +GOOGLE_WORKSPACE_USERNAME_CUSTOM_SCHEMA_NAME=schema-name +## Custom schema attriute field name +## Not required if syncing by email +GOOGLE_WORKSPACE_USERNAME_FIELD=field-name + +######################### +## Additional settings ## +######################### +## Stop if number of changes exceeds this number +## Default: 25 +#CHANGE_THRESHOLD=25 +## Create an issue if the sync fails for any reason +## Default: false +#OPEN_ISSUE_ON_FAILURE=true +## Where to open the issue upon sync failure +#REPO_FOR_ISSUES=github-demo/demo-repo +## Who to assign the issues to +#ISSUE_ASSIGNEE=githubber +## Sync schedule, cron style schedule + +## Default (hourly): 0 * * * * +SYNC_SCHEDULE=0 * * * * +## Show the changes, but do not make any changes +## Default: false +#TEST_MODE=false +## Automatically add users missing from the organization +ADD_MEMBER=false +## Automatically remove users from the organisation that are not part of a team +REMOVE_ORG_MEMBERS_WITHOUT_TEAM=false + +#################### +## Flask Settings ## +#################### +## Default: app +FLASK_APP=app +## Default: production +FLASK_ENV=development +## Default: 5000 +FLASK_RUN_PORT=5000 +## Default: 127.0.0.1 +FLASK_RUN_HOST=0.0.0.0 diff --git a/README.md b/README.md index 190db7d..87cd990 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,14 @@ This app requires the following Azure permissions: If you have `ADMIN_FINE_GRAINED_AUTHZ` enabled, you only need the following permission for the user realm: - `view-users` +#### Google Workspace Permissions +You must delegate domain-wide authority to the service account with the following 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` + +You must provide a Google Workspace Admin account for the service account to impersonate. + ## Getting Started To get started, ensure that you are using **Python 3.9** (or update your `Pipfile` to the version you're running, 3.4+). The following additional libraries are required: @@ -116,6 +124,7 @@ GHE_HOST=github.example.com ## AD/LDAP = LDAP ## Okta = OKTA ## OneLogin = ONELOGIN +## Google Workspace = GOOGLE_WORKSPACE USER_DIRECTORY=LDAP ## Sync users on username or email attribute @@ -203,6 +212,14 @@ ONELOGIN_CLIENT_SECRET='ca3a86f982fjjkjjkfkhls' REGION=US ``` +### Sample `.env` for Google Workspace +```env +GOOGLE_WORKSPACE_SA_CREDS_FILE=googleAuth.json +GOOGLE_WORKSPACE_ADMIN_EMAIL=admin@example.com +GOOGLE_WORKSPACE_USERNAME_CUSTOM_SCHEMA_NAME=schema-name +GOOGLE_WORKSPACE_USERNAME_FIELD=field-name +``` + ### Sample `.env` settings for additional settings ```env ## Additional settings From 2243bff5c1ad58b7c8c3690412a31d97a8996b8f Mon Sep 17 00:00:00 2001 From: ZJ-StratusFort Date: Sat, 8 Mar 2025 13:21:24 -0800 Subject: [PATCH 2/4] typo --- .env.example.googleworkspace | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.env.example.googleworkspace b/.env.example.googleworkspace index 4748193..02047de 100644 --- a/.env.example.googleworkspace +++ b/.env.example.googleworkspace @@ -40,7 +40,7 @@ GOOGLE_WORKSPACE_ADMIN_EMAIL=admin@example.com ## Custom schema name ## Not required if syncing by email GOOGLE_WORKSPACE_USERNAME_CUSTOM_SCHEMA_NAME=schema-name -## Custom schema attriute field name +## Custom schema attribute field name ## Not required if syncing by email GOOGLE_WORKSPACE_USERNAME_FIELD=field-name From 216fd99761bb663dff900de8fffdfcc2c470000a Mon Sep 17 00:00:00 2001 From: ZJ-StratusFort <168620363+ZJ-StratusFort@users.noreply.github.com> Date: Thu, 13 Mar 2025 20:34:39 -0700 Subject: [PATCH 3/4] Update wording for google workspace account --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 87cd990..d3f1c21 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ You must delegate domain-wide authority to the service account with the followin - `https://www.googleapis.com/auth/admin.directory.group.member.readonly` - `https://www.googleapis.com/auth/admin.directory.user.readonly` -You must provide a Google Workspace Admin account for the service account to impersonate. +You must provide a Google Workspace account for the service account to impersonate with API permissions greater or equal to the scopes above. ## Getting Started To get started, ensure that you are using **Python 3.9** (or update your `Pipfile` to the version you're running, 3.4+). The following additional libraries are required: From 020c3b5ccba36cdb7f2f0a8e87c2e9176e125ada Mon Sep 17 00:00:00 2001 From: ZJ-StratusFort <168620363+ZJ-StratusFort@users.noreply.github.com> Date: Thu, 13 Mar 2025 20:39:55 -0700 Subject: [PATCH 4/4] Making wording more clear for google workspace admin account --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d3f1c21..4faf5b9 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,8 @@ You must delegate domain-wide authority to the service account with the followin - `https://www.googleapis.com/auth/admin.directory.group.member.readonly` - `https://www.googleapis.com/auth/admin.directory.user.readonly` -You must provide a Google Workspace account for the service account to impersonate with API permissions greater or equal to the scopes above. +You must provide a Google Workspace Admin account for the service account to impersonate. +It must have Admin API permissions greater or equal to the scopes listed above. ## Getting Started To get started, ensure that you are using **Python 3.9** (or update your `Pipfile` to the version you're running, 3.4+). The following additional libraries are required: