website/docs: update gws provider docs (#18286)

* Update filenames, sidebar and redirect. Rework overview doc

* WIP

* Spelling

* Move info box

* WIP

* Update create-gws-provider.md

Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Small tweaks

* Add note about key creation

* Update website/docs/add-secure-apps/providers/gws/configure-gws.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Add delegated user permissions

* Update configure-gws.md

Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Fix link and section naming

* Apply suggestions from code review

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Update configure-gws.md

Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Update website/docs/add-secure-apps/providers/gws/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Update website/docs/add-secure-apps/providers/gws/index.md

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Headers

---------

Signed-off-by: Dewi Roberts <dewi@goauthentik.io>
Co-authored-by: Dominic R <dominic@sdko.org>
Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
This commit is contained in:
Dewi Roberts
2026-01-14 11:17:52 +00:00
committed by GitHub
parent a72c04b885
commit 6ba41daca0
7 changed files with 181 additions and 146 deletions
@@ -1,56 +0,0 @@
---
title: Create a Google Workspace provider
authentik_enterprise: true
---
For more information about using a Google Workspace provider, see the [Overview](./index.md) documentation.
## Prerequisites
To create a Google Workspace provider in authentik, you must have already [configured Google Workspace](./setup-gws.md) to integrate with authentik.
:::info
When adding the Google Workspace provider in authentik, you must define the **Backchannel provider** using the name of the Google Workspace provider that you created in authentik. If you have also configured Google Workspace to log in using authentik following [these](/integrations/services/google/), then this configuration can be done on the same app.
:::
### Create the Google Workspace provider in authentik
1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Applications > Providers**.
3. Click **Create**, and select **Google Workspace Provider**, and in the **New provider** box, define the following fields:
- **Name**: define a descriptive name, such as "GWS provider".
- **Protocol settings**
- **Credentials**: paste the contents of the JSON file you downloaded earlier.
- **Delegated Subject**: enter the email address of the user all of authentik's actions should be delegated to
- **Default group email domain**: enter a default domain which will be used to generate the domain for groups synced from authentik.
- **User deletion action**: determines what authentik will do when a user is deleted from authentik.
- **Group deletion action**: determines what authentik will do when a group is deleted from authentik.
- **User filtering**
- **Exclude service accounts**: set whether to include or exclude service accounts.
- **Group**: select any specific groups to enforce that filtering (for all actions) is done only for the selected groups.
- **Attribute mapping**
- **User Property Mappings**: select any applicable mappings, or use the default.
- **Group Property Mappings**: select any applicable mappings, or use the default.
:::info Skipping certain users or groups
The `SkipObject` exception can be used within a property mapping to prevent specific objects from being synced. Refer to the [Provider property mappings documentation](../property-mappings/index.md#skip-objects-during-synchronization) for more information.
4. Click **Finish**.
### Create a Google Workspace application in authentik
1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Applications > Applications**.
:::info
If you have also configured Google Workspace to log in using authentik following this [integration guide](/integrations/cloud-providers/google), then this configuration can be done on the same app by adding this new provider as a backchannel provider on the existing app instead of creating a new app.
:::
3. Click **Create**, and in the **New provider** box, and define the following fields:
- **Slug**: enter the name of the app as you want it to appear in the URL.
- **Provider**: when _not_ used in conjunction with the Google SAML configuration should be left empty.
- **Backchannel Providers**: this field is required for Google Workspace. Select the name of the Google Workspace provider that you created in the steps above.
- **UI settings**: leave these fields empty for Google Workspace.
4. Click **Finish**.
@@ -0,0 +1,90 @@
---
title: Configure Google Workspace
authentik_enterprise: true
---
For more information about using a Google Workspace provider, see the [Overview](./index.md) documentation.
Your Google Workspace organization must be configured before you [create a Google Workspace provider](./create-gws-provider.md).
## Configure your Google Workspace Organization
The main steps to configure your Google Workspace organization are:
1. [Create a Google Cloud project](#create-a-google-cloud-project)
2. [Create a service account](#create-a-service-account)
3. [Configure service account key and scopes](#configure-service-account-key-and-scopes)
4. [Select a user for the Delegated Subject](#select-a-user-for-the-delegated-subject)
### Create a Google Cloud project
1. Open the [Google Cloud console](https://cloud.google.com/cloud-console).
2. In the upper left, click the drop-down box to open the **Select a project** box, then select **New Project**.
3. Create a new project and provide a name (e.g. `authentik GWS`).
4. Use the search bar at the top of your new project page to search for `API Library`.
5. On the **API Library** page, use the search bar again to find `Admin SDK API`.
6. On the **Admin SDK API** page, click **Enable**.
### Create a service account
1. After the new Admin SDK API is enabled (it might take a few minutes), return to the Google Cloud console home page by clicking on **Google Cloud** in the upper left.
2. Use the search bar to find and navigate to the **IAM** page.
3. On the **IAM** page, click **Service Accounts** in the left navigation pane.
4. At the top of the **Service Accounts** page, click **Create Service Account**.
- Under **Service account details** page, define the **Name** and **Description** for the new service account, then click **Create and Continue**.
- Under **Grant this service account access to project** you do not need to define a role, so click **Continue**.
- Under **Grant users access to project** you do not need to define a role, so click **Done** to complete the creation of the service account.
### Configure service account key and scopes
1. On the **Service accounts** page, click the account that you just created.
2. Click the **Keys** tab at top of the page, then click **Add Key** > **Create new key**.
3. Select **JSON** as the key type, then click **Create**.
A pop-up displays with the private key. The key can be saved to your computer as a JSON file. This key will be required when creating the Google Workspace provider in authentik.
:::info Allow key creation
By default, the Google Cloud organization policy `iam.disableSerivceAccountKeyCreation` prevents creating service account keys. To allow key creation:
1. Navigate to **IAM & Admin** > **Organization Policies** and select the **Disable service account key creation** policy.
2. Click **Manage policy** and disable the policy.
3. Click **Set policy** to save your changes.
:::
4. On the service account page, click the **Details** tab, and expand the **Advanced settings** area.
5. Copy the **Client ID** (under **Domain-wide delegation**), and then click **View Google Workspace Admin Console**.
6. Log in to the Admin Console, and then navigate to **Security** > **Access and data control** > **API controls**.
7. On the **API controls** page, click **Manage Domain Wide Delegation**.
8. On the **Domain Wide Delegation** page, click **Add new**.
9. In the **Add a new client ID** box, paste in the Client ID that you copied from the Admin console earlier (the value from the downloaded JSON file) and paste in the following scope documents:
- `https://www.googleapis.com/auth/admin.directory.user`
- `https://www.googleapis.com/auth/admin.directory.group`
- `https://www.googleapis.com/auth/admin.directory.group.member`
- `https://www.googleapis.com/auth/admin.directory.domain.readonly`
### Select a user for the Delegated Subject
**Delegated Subject** is a required field when creating the Google Workspace provider in authentik. This field must be populated with the email address of a Google Workspace user with [suitable permissions](#delegated-subject-permissions).
1. In the sidebar navigate to **Directory** > **Users**.
2. Either select an existing user's email address or **Add new user** and define the user and email address to use as the Delegated Subject.
3. Take note of this email address as it will be required when creating the Google Workspace provider in authentik.
#### Delegated Subject permissions
:::warning
We do not recommend using an administrator account for the Delegated Subject user. A custom role should be used instead, see the [Google Admin console documentation](https://support.google.com/a/answer/2406043?hl=en) for more details.
:::
The Delagated Subject user requires the following permissions:
##### Admin console privilieges
- Users
- Groups
##### Admin API privileges
- Domain management
- Users
- Groups
Now that you have configured your Google Workspace organization, you are ready to [create a Google Workspace provider](./create-gws-provider.md).
@@ -0,0 +1,52 @@
---
title: Create a Google Workspace provider
authentik_enterprise: true
---
For more information about using a Google Workspace provider, see the [Overview](./index.md) documentation.
## Prerequisites
To create a Google Workspace provider in authentik, you must have already [configured Google Workspace](./configure-gws.md).
## Create a Google Workspace provider in authentik
1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Applications** > **Providers** and click **Create**.
3. Select **Google Workspace Provider** as the provider type, then click **Next**.
4. On the **Create Google Workspace Provider** page, set the following configurations:
- **Name**: provide a descriptive name (e.g. `GWS provider`)
- Under **Protocol settings**:
- **Credentials**: paste the contents of the JSON file that you downloaded when [configuring Google Workspace](./configure-gws.md)
- **Delegated Subject**: enter the email address of the Google Workspace user that all authentik actions will be delegated to
- **Default group email domain**: enter a domain which will be used to generate the email address for groups synced from authentik to Google Workspace
- **User deletion action**: determines what authentik will do when a user is deleted from authentik
- **Group deletion action**: determines what authentik will do when a group is deleted from authentik
- Under **User filtering**:
- **Exclude service accounts**: choose whether to include or exclude service accounts
- **Group**: select a group and only users within that group will be synced to Google Workspace
- Under **Attribute mapping**:
- **User Property Mappings**: select any property mappings, or use the default
- **Group Property Mappings**: select any property mappings, or use the default
:::info Skipping certain users or groups
The `SkipObject` exception can be used within a property mapping to prevent specific objects from being synced. Refer to the [Provider property mappings documentation](../property-mappings/index.md#skip-objects-during-synchronization) for more details.
:::
5. Click **Finish**.
## Create a Google Workspace application in authentik
:::info Backchannel Provider
If you have configured the [Google Workspace SAML integration](/integrations/services/google/) to enable authenticating to Google Workspace with authentik, you can add the provider created in the previous section as a backchannel provider to the existing application, instead of creating a new one.
:::
1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Applications** > **Applications**, click **Create**, and set the following configurations:
- **Name**: provide a name for the application (e.g. `GWS`)
- **Slug**: enter the name that you want to appear in the URL
- **Provider**: when _not_ used in conjunction with the [Google SAML configuration](/integrations/cloud-providers/google), this should be left empty.
- **Backchannel Providers**: this field is required for Google Workspace. Select the name of the Google Workspace provider that you created in the previous section.
- **UI settings**: leave these fields empty for Google Workspace.
3. Click **Create**.
@@ -3,44 +3,57 @@ title: Google Workspace provider
authentik_enterprise: true
---
With the Google Workspace provider, authentik serves as the single source of truth for all users and groups, when using Google products like Gmail.
The Google Workspace provider allows you to integrate with your Google Workspace organization. It supports syncing users and groups from authentik to Google Workspace, allowing authentik to act as a source of truth for all users and groups.
- For instructions to configure your Google Workspace to integrate with authentik, refer to [Configure Google Workspace](./setup-gws.md).
- For instructions to add Google Workspace as a provider, refer to [Create a Google Workspace provider](./add-gws-provider.md).
- For instructions on configuring your Google Workspace organization in prepation for creating a Google Workspace provider, refer to the [Configure Google Workspace](./configure-gws.md) documentation.
- For instructions on creating a Google Workspace provider, refer to the [Create a Google Workspace provider](./create-gws-provider.md) documentation.
## About using Google Workspace with authentik
## Discovery
The following sections discuss how Google Workspace operates with authentik.
Upon creating the Google Workspace provider, it will run a discovery task to query your google workspace for all users and groups, and attempt to match them with their respective counterparts in authentik.
### Discovery
Users are matched on their email address. Groups are matched based on their names.
When first creating the provider and setting it up correctly, the provider will run a discovery and query your google workspace for all users and groups, and attempt to match them with their respective counterparts in authentik.
This discovery also takes into consideration any **User filtering** options configured in the provider, such as only linking to authentik users in a specific group or excluding service accounts. This discovery process occurs each time a full sync is initiated.
This matching is done by email address for users as google uses that as their primary identifier, and using group names for groups. This discovery also takes into consideration any **User filtering** options configured in the provider, such as only linking to authentik users in a specific group or excluding service accounts. This discovery happens every time before a full sync is started.
## Synchronization
### Synchronization
There are two types of synchronization: direct sync and full sync.
There are two types of synchronization: a direct sync and a full sync.
### Direct sync
A _direct sync_ happens when a user or group is created, updated or deleted in authentik, or when a user is added to or removed from a group. When one of these events happens, the direct sync automatically forwards those changes to Google Workspace.
A direct sync occurs when a user or group is created, updated or deleted in authentik, or when a user is added to or removed from a group. When any of these events occur, the direct sync automatically syncs those changes to Google Workspace.
The _full sync_ happens when the provider is initially created and when it is saved. The full sync goes through all users and groups matching the **User filtering** options set and will create/update them in Google Workspace. After the initial sync, authentik will run a full sync every four hours to ensure the consistency of users and groups.
### Full sync
During the full sync, if a user or group was created in authentik and a matching user/group exists in Google Workspace, authentik will automatically link them together. Furthermore, users and groups present in authentik but not in Google Workspace will be created and and linked.
A full sync occurs when the provider is initially created and when it is saved. During a full sync, all users and groups that match the **User filtering** settings are processed and created or updated in Google Workspace. After the initial sync, authentik automatically performs a full sync every four hours to maintain consistency between users and groups.
When a property mapping has an invalid expression, it will cause the sync to stop to prevent errors from being spammed. To handle any kind of network interruptions, authentik will detect transient request failures and retry any sync tasks.
During the full sync, if a user or group exists in both authentik and Google Workspace, authentik will automatically link them.
### Customization for data mapping
Additionally, any users or groups present in authentik but absent in Google Workspace will be created and linked.
There are a couple of considerations in regard to how authentik data is mapped to google workspace user/group data by default.
## Error handling
- For users, authentik only saves the full display name, while Google requires given/family name separately, and as such authentik attempts to separate the full name automatically with the default User property mapping.
When a property mapping has an invalid expression, it will cause a sync to stop to prevent excessive error messages.
- For groups, Google groups require an email address. Thus in authentik the provider configuration has an option **Default group email domain**, which will be used in conjunction with the groups name to generate an email address. This can be customized with a property mapping.
To handle network interruptions, authentik detects transient request failures and retries sync tasks.
- By default, authentik maps a users email, a users name, and their active status. For groups, the name is synced.
## Property mapping
Refer to Google documentation for further details on which fields data can be mapped to:
There are several considerations regarding how authentik data is mapped to Google Workspace user and group data.
- https://developers.google.com/admin-sdk/directory/reference/rest/v1/users#User
- https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups#Group
### Users
For users, authentik only saves the full display name, while Google requires the first (given) name and the family name separately, and as such authentik attempts to separate the full name automatically with the `authentik default Google Workspace Mapping: User` property mapping.
By default, authentik maps a users email address, name, and active status.
Refer to Google documentation for further details on which attributes can be mapped: [Google Workspace Reference - Resource: User](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users#User)
### Groups
For groups, Google Workspace groups require an email address. Therefore the Google Workspace provider has an **Default group email domain** setting, which will be used in conjunction with the groups name to generate an email address. This can be customized with a property mapping.
By default, authentik only maps a group's name.
Refer to Google documentation for further details on which attributes can be mapped: [Google Workspace Reference - Resource: Group](https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups#Group)
@@ -1,66 +0,0 @@
---
title: Configure Google Workspace
authentik_enterprise: true
---
The configuration and set up of your Google Workspace must be completed before you [add the new provider](./add-gws-provider.md) in authentik.
## Overview of steps
The main steps to set up your Google workspace are as follows:
1. [Create your Google Cloud Project](#create-a-google-cloud-project)
2. [Create a service account](#create-a-service-account)
3. [Set credentials for the service account](#set-credentials-for-the-service-account)
4. [Define access and scope in the Admin Console](#set-credentials-for-the-service-account)
5. [Select email address for the Delegated Subject](#select-email-address-for-the-delegated-subject)
For detailed instructions, refer to Google documentation.
### Create a Google cloud project
1. Open the Google Cloud Console (https://cloud.google.com/cloud-console).
2. In upper left, click the drop-down box to open the **Select a project** box, and then select **New Project**.
3. Create a new project and give it a name like "authentik GWS"
4. Use the search bar at the top of your new project page to search for "API Library".
5. On the **API Library** page, use the search bar again to find "Admin SDK API".
6. On the **Admin SDK API** page, click **Enable**.
### Create a service account
1. After the new Admin SDK API is enabled (it might take a few minutes), return to the Google Cloud console home page (click on **Google Cloud** in upper left).
2. Use the search bar to find and navigate to the **IAM** page.
3. On the **IAM** page, click **Service Accounts** in the left navigation pane.
4. At the top of the **Service Accounts** page, click **Create Service Account**.
- Under **Service account details** page, define the **Name** and **Description** for the new service account, and then click **Create and Continue**.
- Under **Grant this service account access to project** you do not need to define a role, so click **Continue**.
- Under **Grant users access to project** you do not need to define a role, so click **Done** to complete the creation of the service account.
### Set credentials for the service account
1. On the **Service accounts** page, click the account that you just created.
2. Click the **Keys** tab at top of the page, the click **Add Key > Create new key**.
3. In the Create box, select JSON as the key type, and then click **Create**.
A pop-up displays with the private key, and the key is saved to your computer as a JSON file.
Later, when you create your authentik provider for Google Workspace, you will add this key in the **Credentials** field.
4. On the service account page, click the **Details** tab, and expand the **Advanced settings** area.
5. Copy the **Client ID** (under **Domain-wide delegation**), and then click **View Google Workspace Admin Console**.
6. Log in to the Admin Console, and then navigate to **Security > Access and data control > API controls**.
7. On the **API controls** page, click **Manage Domain Wide Delegation**.
8. On the **Domain Wide Delegation** page, click **Add new**.
9. In the **Add a new client ID** box, paste in the Client ID that you copied from the Admin console earlier (the value from the downloaded JSON file) and paste in the following scope documents:
- `https://www.googleapis.com/auth/admin.directory.user`
- `https://www.googleapis.com/auth/admin.directory.group`
- `https://www.googleapis.com/auth/admin.directory.group.member`
- `https://www.googleapis.com/auth/admin.directory.domain.readonly`
### Select email address for the Delegated Subject
The Delegated Subject email address is a required field when creating the provider in authentik.
1. Open to the main Admin console page, and navigate to **Directory > Users**.
2. You can either select an existing user's email address or **Add new user** and define the user and email address to use as the Delegated Subject.
3. Save this email address to enter into authentik when you are creating the Google Workspace provider.
Now that you have configured your Google Workspace, you are ready to [add it as a provider in authentik](./add-gws-provider.md).
+2 -2
View File
@@ -155,8 +155,8 @@ const items = [
id: "add-secure-apps/providers/gws/index",
},
items: [
"add-secure-apps/providers/gws/setup-gws",
"add-secure-apps/providers/gws/add-gws-provider",
"add-secure-apps/providers/gws/configure-gws",
"add-secure-apps/providers/gws/create-gws-provider",
],
},
{
+2
View File
@@ -22,6 +22,8 @@
/add-secure-apps/flows-stages/flow/layouts /add-secure-apps/flows-stages/flow/executors/if-flow/ 301!
/core/applications /add-secure-apps/applications/ 301!
/applications/* /add-secure-apps/applications/:splat 301!
/add-secure-apps/providers/gws/add-gws-provider/ /add-secure-apps/providers/gws/create-gws-provider/ 301!
/add-secure-apps/providers/gws/setup-gws/ /add-secure-apps/providers/gws/configure-gws/ 301!
/add-secure-apps/providers/oauth2/client_credentials /add-secure-apps/providers/oauth2/machine_to_machine 301!
/add-secure-apps/providers/entra/setup-entra/ /add-secure-apps/providers/entra/configure-entra/ 301!
/add-secure-apps/providers/entra/add-entra-provider/ /add-secure-apps/providers/entra/create-entra-provider/ 301!