Google Workspace provider
Enterprise
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 on configuring your Google Workspace organization in prepation for creating a Google Workspace provider, refer to the Configure Google Workspace documentation.
- For instructions on creating a Google Workspace provider, refer to the Create a Google Workspace provider documentation.
Discovery
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.
Users are matched on their email address. Groups are matched based on their names.
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.
Synchronization
There are two types of synchronization: direct sync and full sync.
Direct sync
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.
Full sync
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.
During the full sync, if a user or group exists in both authentik and Google Workspace, authentik will automatically link them.
Additionally, any users or groups present in authentik but absent in Google Workspace will be created and linked.
Deletion and offboarding
The provider's User deletion action and Group deletion action control what happens to the linked Google Workspace object when you delete its counterpart in authentik. Both settings default to Delete. Deletion is processed by a background sync task and requires the provider to remain assigned to an application. Dry-run mode prevents changes to the remote directory.
| Action | When an authentik user is deleted | When an authentik group is deleted |
|---|---|---|
Delete (delete, default) | Deletes the linked Google Workspace user account. | Deletes the linked Google Workspace group. |
Suspend (suspend) | Keeps the Google Workspace account and disables sign-in by setting suspended to true. | Unsupported. Treated as Do Nothing, leaving the remote group unchanged. |
Do Nothing (do_nothing) | Leaves the Google Workspace account unchanged, including its enabled or suspended status. | Leaves the Google Workspace group unchanged. |
All three actions remove authentik's connection record for the deleted user or group. Suspend retains the remote user account; it does not retain the deleted authentik user. Do Nothing does not revoke access to the remote account.
In the Admin interface, User deletion action offers Delete, Suspend, and Do Nothing. Suspension applies only to users, so Group deletion action offers Delete and Do Nothing.
Deactivate a user without deleting the account
Marking an authentik user inactive is an update, so it does not use User deletion action. With the default user property mapping, authentik sets suspended to true in Google Workspace. The authentik user and its connection record remain, and reactivating the user allows the default mapping to enable the remote account again.
This requires the user to remain included in synchronization. Custom property mappings can change whether active status is synchronized.
Offboard users and groups
- To retain a user's accounts while disabling sign-in, mark the authentik user inactive and verify that synchronization has disabled the Google Workspace account before removing the user from synchronization filters.
- To delete an authentik user while retaining the remote account, select Suspend for User deletion action before deleting the user. Use Do Nothing only if you intend to manage the remote account's access separately.
- To delete the remote user or group as well, use Delete. Complete any required data retention or ownership transfers in Google Workspace before deleting the authentik object.
- After offboarding, check the provider's sync tasks for errors and verify the account or group state in Google Workspace.
Removing a user from the provider's filtering group, changing User filtering to exclude the user, or skipping a user with SkipObject does not itself delete or suspend the remote account. These changes exclude the user from provisioning updates. Removing group membership can also remove that membership in Google Workspace, but it does not disable the account.
Do not rely on filtering alone to revoke access. If you later delete a previously linked authentik user, its retained connection record still allows the configured deletion action to run.
Error handling
Property mappings are evaluated in name order. If a property mapping fails to evaluate, authentik stops the synchronization and does not evaluate the remaining mappings.
To handle network interruptions, authentik detects transient request failures and retries sync tasks.
Property mapping
There are several considerations regarding how authentik data is mapped to Google Workspace user and group data.
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 user’s email address, name, and active status.
Refer to Google documentation for further details on which attributes can be mapped: Google Workspace Reference - Resource: 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 group’s 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
Skip objects during synchronization
To exclude specific users or groups from Google Workspace synchronization, you can create a property mapping that raises the SkipObject exception. When this exception is raised during the evaluation of a property mapping, the object is skipped and the sync continues with the next object.
For more information, refer to Skip objects during synchronization.