website/docs: add docs about Google Workspace (#9669)
* stub files * tweaks * add to sidebar * tweaks * steps to set up gws * first drafts * link * unsaved * formatting * typos * add Ent badge * backchannel and otehr edits * tweaks * tweaks * rewrite stuff Signed-off-by: Jens Langhammer <jens@goauthentik.io> * em one word Signed-off-by: Jens Langhammer <jens@goauthentik.io> --------- Signed-off-by: Jens Langhammer <jens@goauthentik.io> Co-authored-by: Tana M Berry <tana@goauthentik.com> Co-authored-by: Jens Langhammer <jens@goauthentik.io>
This commit is contained in:
Tana M Berry
67
website/docs/providers/gws/add-gws-provider.md
Normal file
67
website/docs/providers/gws/add-gws-provider.md
Normal file
@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Create a Google Workspace provider
|
||||
---
|
||||
|
||||
<span class="badge badge--primary">Enterprise</span>
|
||||
|
||||
---
|
||||
|
||||
:::info
|
||||
This feature is in technical preview, so please report any bugs on [GitHub](https://github.com/goauthentik/authentik/issues).
|
||||
:::
|
||||
|
||||
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 as an admin to authentik, and go to the Admin interface.
|
||||
|
||||
2. In the Admin interface, navigate to **Applications -> Providers**.
|
||||
|
||||
3. Click **Create**, and select **Google Workspace Provider**, and in the **New provider** modal 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.
|
||||
|
||||
4. Click **Finish**.
|
||||
|
||||
### Create a Google Workspace application in authentik
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
2. In the Admin interface, navigate to **Applications -> Applications**.
|
||||
:::info
|
||||
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 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** modal 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**.
|
||||
53
website/docs/providers/gws/index.md
Normal file
53
website/docs/providers/gws/index.md
Normal file
@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Google Workspace provider
|
||||
---
|
||||
|
||||
<span class="badge badge--primary">Enterprise</span>
|
||||
|
||||
---
|
||||
|
||||
:::info
|
||||
This feature is in technical preview, so please report any bugs on [GitHub](https://github.com/goauthentik/authentik/issues).
|
||||
:::
|
||||
|
||||
With the Google Workspace provider, authentik serves as the single source of truth for all users and groups, when using Google products like Gmail.
|
||||
|
||||
- For instructions to configure your Google Workspace to integrate with authentik, refer to [Configure Google Workspace](./setup-gws).
|
||||
- For instructions to add Google Workspace as a provider, refer to [Create a Google Workspace provider](./add-gws-provider).
|
||||
|
||||
## About using Google Workspace with authentik
|
||||
|
||||
The following sections discuss how Google Workspace operates with authentik.
|
||||
|
||||
### Discovery
|
||||
|
||||
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 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
|
||||
|
||||
There are two types of synchronization: a direct sync and a full 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.
|
||||
|
||||
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.
|
||||
|
||||
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 present in authentik but not in Google Workspace will be created and and linked.
|
||||
|
||||
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.
|
||||
|
||||
### Customization for data mapping
|
||||
|
||||
There are a couple of considerations in regard to how authentik data is mapped to google workspace user/group data by default.
|
||||
|
||||
- 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.
|
||||
|
||||
- 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 group’s name to generate an email address. This can be customized with a property mapping.
|
||||
|
||||
- By default, authentik maps a user’s email, a user’s name, and their active status. For groups, the name is synced.
|
||||
|
||||
Refer to Google documentation for further details on which fields data can be mapped to:
|
||||
|
||||
- https://developers.google.com/admin-sdk/directory/reference/rest/v1/users#User
|
||||
- https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups#Group
|
||||
69
website/docs/providers/gws/setup-gws.md
Normal file
69
website/docs/providers/gws/setup-gws.md
Normal file
@ -0,0 +1,69 @@
|
||||
---
|
||||
title: Configure Google Workspace
|
||||
---
|
||||
|
||||
<span class="badge badge--primary">Enterprise</span>
|
||||
|
||||
---
|
||||
|
||||
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** modal 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 modal 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** modal 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).
|
||||
@ -12,6 +12,10 @@ When configuring SCIM, you'll get an endpoint and a token from the application t
|
||||
|
||||
The token given by the application will be sent with all outgoing SCIM requests to authenticate them.
|
||||
|
||||
:::info
|
||||
When adding the SCIM provider, you must define the **Backchannel provider using the name of the SCIM provider that you created in authentik. Do NOT add any value in the **Provider** field (doing so will cause the provider to display as an application on the user interface, under **My apps\*\*, which is not supported for SCIM).
|
||||
:::
|
||||
|
||||
### Syncing
|
||||
|
||||
Data is synchronized in multiple ways:
|
||||
|
||||
@ -74,6 +74,27 @@ const docsSidebar = {
|
||||
id: "providers/index",
|
||||
},
|
||||
items: [
|
||||
{
|
||||
type: "category",
|
||||
label: "Google Workspace Provider",
|
||||
link: {
|
||||
type: "doc",
|
||||
id: "providers/gws/index",
|
||||
},
|
||||
items: [
|
||||
"providers/gws/setup-gws",
|
||||
"providers/gws/add-gws-provider",
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "LDAP Provider",
|
||||
link: {
|
||||
type: "doc",
|
||||
id: "providers/ldap/index",
|
||||
},
|
||||
items: ["providers/ldap/generic_setup"],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "OAuth2 Provider",
|
||||
@ -114,15 +135,6 @@ const docsSidebar = {
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "LDAP Provider",
|
||||
link: {
|
||||
type: "doc",
|
||||
id: "providers/ldap/index",
|
||||
},
|
||||
items: ["providers/ldap/generic_setup"],
|
||||
},
|
||||
"providers/scim/index",
|
||||
{
|
||||
type: "category",
|
||||
|
||||
Reference in New Issue
Block a user