How authentik provisions Google Workspace users and groups
If your identities already live in authentik and Google Workspace accounts need to follow them, the supported route is the Google Workspace provider. That provider is part of authentik's Enterprise edition, so it is a licensing question to settle before any design work. In plain terms, the provider pushes users and groups from authentik into Google. It does not read Google's directory back into authentik, so Google accounts are created, updated and suspended by authentik's side of the relationship. Confirm the exact provider settings, required Google API access and service account setup against the provider documentation for your authentik release, since those details change between versions.
The first decision is which system is the source of truth for each attribute, especially who exists, who belongs to which group and who should be suspended. If authentik is the source of truth, people who are edited directly in Google Workspace will be overwritten on the next sync, and administrators need to accept that the Google console is no longer where lifecycle changes are made. If Google is the source of truth for some attributes, such as an existing mail address or a manually created admin account, those attributes must be excluded from the mapping or the two systems will fight over them. Write this down per attribute before building anything, because it decides the matching rules, the property mappings and who on your team is allowed to change what.
The same decision sets the risk profile. A mapping or filter mistake in authentik can propagate to every Google account in scope in one sync cycle, so the reader should plan a pilot group, a review of which accounts the provider will touch on first run, and a documented rollback path. Ask who owns the Google super admin role used for the integration, how that credential is stored and rotated, and which accounts are explicitly excluded, such as break-glass administrators. Those answers belong in the design record before the first sync runs.
What you need before you configure the provider
Google Workspace provisioning from authentik depends on five things lining up before any provider is created: a supported authentik version, an Enterprise license, a Google Cloud service account with delegation, a super admin who approves that delegation, and network reachability from the worker. Confirm each one with its owner first, because a gap in any of them usually shows up as a failed first sync rather than a clear error.
Supported authentik version line
Confirm the deployment runs on 2026.5.x or 2026.8.x, the two version lines the authentik security policy lists as receiving security fixes. The platform team owns the upgrade decision. Check the running version in the admin interface and compare it with the release notes before you start, since the provider configuration depends on the features of that line. Older lines will need an upgrade path planned before this integration is built.
Enterprise license for Google Workspace
The Google Workspace provider is an Enterprise-only feature, so the license must cover it before the provider appears in the admin interface. The identity owner or procurement team should confirm the subscription tier and the number of users it covers. Ask the vendor how external users are counted, because the pricing page lists a separate per-user rate for them, and confirm that the license terms match how the organization plans to use the integration.
Google Cloud project and service account
Create or select a Google Cloud project that the Google Workspace admin team approves, then create a service account for authentik with the Admin SDK API enabled. The Google Cloud administrator owns this step. Record the service account key handling process, since the key grants the provider its access. Confirm the exact API scopes and console steps in the current authentik provider documentation, because they change between releases and must match what the provider requests.
Domain-wide delegation authorization
Domain-wide delegation lets the service account act on behalf of users in the Workspace domain, and only a super administrator can approve it in the Google Admin console. Agree on this step with that person before the build starts, and give them the exact client ID and scope list from the authentik documentation. Ask them to record the approval in their change log. Without it, the provider cannot read or write users and groups, and authentication errors often look like a credentials problem.
Worker egress to Google APIs
Provisioning runs as background tasks in the authentik worker container, not in the web server, so the worker must reach Google's API endpoints over HTTPS. The network or security team should confirm that outbound rules, proxies and any TLS inspection allow those calls from the worker's host or cluster. Test egress from the same environment where the worker runs, because a firewall that allows the web server alone will still leave syncs failing silently in the background.
Configure the Google Workspace provider in authentik
This sequence takes a team from a Google-side service account with domain-wide delegation to a working authentik Google Workspace provider that provisions a test user and group, with each step confirmed before the next begins. The result is a verified provisioning path that can be widened to production scope.
Confirm the Enterprise license and edition
Before anything is built, confirm with your authentik account owner or the pricing details that your deployment includes the Enterprise features, because the Google Workspace provider is listed as an Enterprise-only feature on the authentik pricing page. Also confirm that your authentik version is one that receives security fixes, using the security policy's list of supported versions, and that the server and worker containers are both running. Done when the Enterprise license is active in your instance and the Google Workspace provider type is visible in the admin interface. If it is not, stop here and resolve licensing with the vendor.
Create the Google Cloud service account and grant delegation
A Google Cloud project owner or Workspace super administrator creates a service account, enables the Google APIs that the provider needs, and grants the account domain-wide delegation limited to the directory scopes that authentik's documentation specifies for user and group management. Your team should review the scope list in the provider documentation against your own policy before approving it, since delegated scopes give the account broad control over your directory. Done when the service account's JSON key is generated and stored in your secrets manager, and the delegation entry is visible in the Workspace admin console with only the approved scopes.
Verify the delegated account against a test user
Before entering credentials into authentik, confirm that the service account can act on behalf of a designated administrator account in your domain. Use a dedicated test user, not a production administrator, and record which administrator account the provider will impersonate. Done when a read request made with the delegated identity returns the test user's directory record. If the call is refused, check the delegation scopes and the impersonated address before continuing, because authentik will fail in the same way.
Create the Google Workspace provider in authentik
A platform or identity administrator creates a Google Workspace provider in authentik, pasting the service account credentials and the delegated administrator address, and sets the domain it will manage. Keep the provider's default behavior for matching and deletion for now and record each value you set, so the configuration can be reviewed later. Done when the provider saves without validation errors and the admin interface shows it as configured but not yet synced.
Set property mappings and matching rules
Review the user and group property mappings the provider uses, and confirm how existing Google accounts will be matched to authentik users, using primary email and name fields as the documentation describes. Test with one or two accounts whose primary email addresses you know, including one account that already exists in Google, so you can see whether it is matched or duplicated. Done when a dry review of the mapping output for the test accounts shows the expected primary email and name values, with no unexpected fields overwriting existing data.
Assign the provider to a group or application scope
Attach the Google Workspace provider to a limited authentik group or application, so that only a deliberately chosen set of users is provisioned at first. A test group containing one or two test users is the safest starting point. Done when the provider's assignment page lists the test group or application and no other users are in scope.
Run the first sync and confirm the results
Trigger a sync for the provider and check the task status in authentik until it reports success. Then open the Google Admin console and confirm that the test user appears with the expected primary email address and that the test group exists with the right membership. Next, remove the test user from the assigned group in authentik and sync again. Done when the test user is suspended in Google rather than deleted, and the suspension is visible in the admin console. Record this result as your baseline before widening scope.
Document the test results before widening scope
Write down the provider settings, the delegated administrator, the mapping output, and the outcomes of the match, sync and unassignment tests, so the team can reproduce the setup and explain it to auditors or the Google Workspace owner. Share the record with the people who approve production changes. Done when the record has been reviewed and the team agrees on which additional groups will be added in a later change.
How authentik attributes map to Google Workspace fields
This table compares each authentik user and group attribute with the Google Workspace field it feeds during provisioning, the property mapping that controls the value, and what to confirm before the first sync. Read it as a checklist for your own mapping review. The main takeaway is that the defaults in your authentik version decide the result, so verify each row in a test tenant before enabling sync against production users.
| Authentik attribute | Google Workspace field | Controlling property mapping | What to confirm |
|---|---|---|---|
| Username | Primary email local part | Check the provider's default user mapping list in your version | Whether the username is used directly or derived, and how it behaves for users who share a name |
| Primary email address | The user mapping that sets the email value sent to Google | Which domain is used, whether aliases are involved, and how the provider matches an existing Google account by email | |
| Given name | Given name | The user mapping for given name, if one is present in your provider configuration | Whether a blank given name is rejected by Google or replaced with a placeholder |
| Family name | Family name | The user mapping for family name, if one is present in your provider configuration | How names with multiple parts or non-Latin characters are passed through without truncation |
| Active state | Suspended status | Governed by how the provider treats deactivated authentik users, not by a value mapping alone | Whether a deactivated user is suspended rather than deleted, and how long it takes after a sync run |
| Group membership | Group membership in Google Workspace | Group mappings and the membership handling options on the provider | Whether removing a user from an authentik group removes the Google membership on the next sync |
| Group name | Group name and group email address | The group mapping that sets name and email for each synced group | How spaces, case and special characters are normalized, and whether group addresses collide with existing Google groups |
| Service accounts and excluded users | Not provisioned | Filtering on the provider or the groups it syncs from | Which accounts are excluded from sync so that service identities are not created or suspended in Google |
Matching existing accounts and when changes reach Google
When a Google Workspace tenant already has users, the first sync is the riskiest step. The Enterprise Google Workspace provider has to decide whether an authentik user corresponds to an existing Google account, and a wrong match means one person's authentik identity is tied to another person's mailbox or drive. Matching on email address is the usual starting point because email is unique within a Google domain, but names, aliases and secondary addresses can still produce surprises. Decide, before the first run, which system is the source of truth for each attribute and which record wins when the two disagree.
- Match key: Confirm which attribute the provider uses to link an authentik user to a Google account, and test it with aliases and recently renamed users.
- Winning record: Decide whether authentik or the existing Google account supplies name and org unit values on the first sync.
- Duplicates: Find accounts that differ only in case, punctuation or alias before enabling writes, and resolve them in one system.
- Unmatched accounts: Agree on whether unmatched Google accounts are left alone or flagged for review, rather than created or changed silently.
- Dry run: Run the first sync against a test tenant or a restricted group and compare results with the expected user list.
Confirm the matching behavior and any first-sync options in the provider documentation and rehearse the whole onboarding in a test tenant before touching production accounts.
After onboarding, the question becomes how quickly a change made in authentik appears in Google and which changes are pushed at all. Sync may run on a schedule, after an object changes, or only when someone triggers it. Each trigger has a different delay and a different failure mode, and an administrator who assumes the wrong model can believe a removed group membership has been applied when it has not. Treat the timing as a fact to verify, not an assumption to carry into planning.
- Sync triggers: Confirm whether changes are pushed on save, on a schedule, or both, and whether group membership changes follow the same path as user changes.
- Visible delay: Measure how long a name, email or group change takes to appear in the Google Admin console in your own tenant.
- Property mappings: Map only the attributes you own in authentik, so Google-side edits are not overwritten by empty or default values.
- Failed pushes: Check where errors are reported in authentik and who receives them, since a failed push can look like success in the source system.
- Forced sync for testing: Use the provider's manual sync action in a test tenant to confirm a change end to end, and record the steps for the runbook.
Confirm sync triggers, timing and error reporting in the provider documentation and in a test tenant before relying on any change reaching Google.
Offboarding is where the choice between suspension and deletion matters most. Deleting a Google account can remove mailbox content, Drive ownership and license assignments, and in many cases the account cannot be fully recovered on the same terms. Suspending the account blocks sign-in while keeping data in place for review, forwarding or legal hold. Decide the default behavior with HR, legal and the mail owners before the provider is allowed to delete anything.
- Suspension first: Configure the provider to suspend rather than delete, so access stops while data remains available for handover.
- Deletion policy: Document who approves deletion, after what retention period, and how deletion interacts with Google's own data retention rules.
- Group removal: Confirm that removing a user from an authentik group removes the matching Google group membership, not only the login.
- Restoration: Test restoring a suspended account in a test tenant, including re-enabling sign-in, group membership and mailbox access.
- Service accounts: Exclude service and shared accounts from offboarding so automation and shared mailboxes are not suspended by mistake.
Confirm the deletion and suspension behavior, and the restoration steps, in the provider documentation and in a test tenant before the first real offboarding run.
Security settings that limit what the integration can change
A provisioning integration that creates and suspends users across a whole domain holds some of the most sensitive administrative power in your identity estate. The controls below work together: they limit who can use the integration, what it can touch, how its credentials are stored and rotated, and how every change is traced.
Service account key storage
The service account key lets authentik act on Google Workspace without a person signing in, so the key is effectively the integration's password. Store the JSON key in your secrets store rather than in a configuration file or a shared chat thread, and restrict read access to the few administrators who operate authentik. Confirm with your own secrets tooling who can read the key, whether reads are logged, and how the key reaches the authentik deployment at runtime.
Minimal domain-wide delegation scopes
Domain-wide delegation lets the service account act as an administrator across every user in the domain, so each Admin SDK scope you grant widens the blast radius. Grant only the scopes the Google Workspace provider documents for the user and group operations you enable, and review the list against the provider configuration before each change. Ask your own Google Workspace administrator to confirm the scope list in the Admin console matches that review.
Dedicated, MFA-protected admin account
Delegation is authorized by a Google Workspace super administrator, and that account should not be the same one people use for daily work. Use a dedicated administrator account with multi-factor authentication enforced, keep its credentials out of shared password vaults, and document who holds it. Never let it be used interactively for other tasks, because a session compromise on a shared account would expose both the console and the integration.
Test tenant or organizational unit
Before enabling deletion-adjacent behavior such as suspension or group removal, validate the mapping in a separate Google Workspace test tenant or in an organizational unit that holds only test accounts. Confirm that matching by email and name links the right accounts and that suspended users stay suspended after a sync. Keep the test scope out of production groups so a misconfigured filter cannot reach real staff.
Audit logs on both sides
Provisioning changes should be visible in authentik's own event records and in the Google Workspace admin audit logs. Compare the two for each test run, matching the user, the action and the timestamp, so you can tell whether a change came from the integration or from a person. Confirm where each log is retained, who can read it, and whether it is forwarded to your central log platform.
Key rotation and revocation runbook
Keys and delegation grants need a written process that a second administrator can follow during an incident. Define how often the key is rotated, how the new key is deployed to authentik and tested, and how the old key is deleted in Google Cloud. Include the steps to revoke domain-wide delegation immediately if the key is suspected to be exposed, and rehearse that revocation once in a test tenant so the steps are known to work.
Common provisioning failures and how to fix them
This table pairs common Google Workspace provisioning symptoms from authentik with their likely causes and the first checks to run. Work through the rows in order when a sync misbehaves, since the authorization and matching checks catch the most problems before any data changes. Confirm exact setting names and log locations against the authentik provider settings and your Google Admin console, because both change between releases.
| Symptom | Likely cause | Fix |
|---|---|---|
| Sync fails with an authorization error | Domain-wide delegation was not granted for the service account client ID, the OAuth scopes do not match what authentik requests, or the admin subject is not a super administrator in the tenant | Confirm the service account client ID and scopes in the Google Admin console delegation settings, confirm the admin subject email, then check the failing task in the authentik worker logs and the Google Admin audit log for the rejected call |
| Users created with the wrong primary email | Email mapping in the provider property mappings builds a local part or domain that does not match a verified domain in Workspace, or the default domain setting differs from the primary domain | List the verified domains in the Google Admin console, compare them with the domain used in the mapping, correct the mapping, and test with one user before a full sync |
| Duplicate accounts after matching | The matching rule compares a field such as name or username while existing Google accounts use a different primary email, so authentik creates a new user instead of linking the existing one | Review the matching rule against the email addresses already in Workspace, reconcile mismatched accounts in the directory before syncing, and confirm no new accounts were created in the audit log |
| Groups do not update | The group filter excludes the groups in scope, membership mapping is missing for members, or group membership changes were made in Google, which authentik may overwrite depending on the configured direction | Check the group filter on the provider, confirm the authentik group has members in the application assignment, and review the sync task output for group and membership operations |
| Suspended accounts should be active | The user's assignment or group membership was removed in authentik, so the next sync suspends the account, or the user was suspended manually in Google and authentik does not restore it | Confirm the application assignment and group membership in authentik, check the account state in the Google Admin console, and re-run the sync for that user after restoring access |
| Worker cannot reach Google APIs | Outbound network rules block the Google API endpoints from the worker container, a proxy setting is missing, or the service account key or credentials are not loaded into the worker | Test outbound HTTPS from the worker container to Google endpoints, verify proxy variables, confirm the credentials are present and current, and review worker logs for connection or certificate errors |
What the license and the integration work cost
The license line and the effort line are separate, and only the first has a published number. The authentik pricing page lists the Google Workspace integration as an Enterprise feature, priced at $5 per user per month billed annually, plus $0.02 per external user per month. Enterprise Plus starts at $20k annually and adds dedicated support with SLAs. Use the authentik pricing page as the source for these figures, and confirm them on the day you request a quote, because vendor prices can change. Ask your team to count billable users and external users separately, since the two rates recur every year and the external user count often grows faster than staff. Ask whether the Enterprise license is needed for the Google Workspace provider only or for the whole production deployment, and get the answer in writing.
The effort line is a one-time cost, but it is the larger uncertainty. Effort rises with the number of Google Workspace domains, groups and the state of the existing directory. Duplicate or stale accounts, mismatched primary email addresses and groups nobody owns all need decisions before authentik can match users safely. Effort also rises with the number of applications that depend on those accounts, because each one needs its login and group membership retested. The testing and cutover plan adds more: a staging tenant, a pilot group, a rollback path and a decision on how suspended accounts are handled during the first sync. DeployOpen quotes this work from a written scope rather than a price list, so the scope should list the domains, the group count, the applications in scope and the test environments. Ask the quote to show each of these as a separate line.
Questions buyers ask before provisioning Google Workspace from authentik
Does the authentik Google Workspace provider need an Enterprise license?
Yes. The authentik pricing page lists Google Workspace integration as an Enterprise-only feature, so plan for an Enterprise subscription before you design the sync. Most of the authentik repository is under the MIT license, but code in the authentik/enterprise/ directory is under a separate enterprise license defined in that directory. Have your legal team read that license against your intended use, especially if you host authentik for other organizations. The subscription recurs annually and is separate from any implementation fee. Confirm current edition terms with authentik, because the pricing page and license text are the authority for your version.
Can authentik read existing Google Workspace users as a source?
Confirm this in the authentik provider and source documentation before you plan around it. The Google Workspace provider is documented as a provider type that pushes users and groups from authentik into Google, which is the direction this page covers. Reading Google accounts into authentik is a separate source flow, so check whether a Google source exists in your version and what attributes it reads. Do not assume two-way sync. If both directions are needed, decide which system owns each attribute, because two systems writing to the same field produce conflicts. Ask for a written test in a non-production tenant that shows what is created, changed and left alone.
How long does Google Workspace provisioning take, and what drives the duration?
The duration follows the scope agreed in writing, and no timeline applies across all environments. The main drivers are the number of Google domains and organizational units, the number of groups and nested membership rules, and the quality of email and name data in authentik. Matching existing accounts, custom attribute mappings and the number of test cycles also add time, as do Google admin approvals and change windows. Ask any implementation partner for a fixed-scope proposal with named deliverables and milestones. DeployOpen agrees scope, deliverables and timelines in writing before work starts, so the proposal should show each driver as a line item.
What access and inputs does the work need from Google and authentik admins?
The work needs several inputs from both sides before build starts. From Google, a super admin or delegated admin must create a service account for the provider and approve the API scopes it requests. From authentik, an administrator must create the provider, application, group handling, property mappings and sync schedule, which requires the Enterprise license. You also need a non-production authentik instance and a test Google tenant or organizational unit, a list of protected accounts such as break-glass and service accounts, a written decision on the source of truth for each attribute, and an approved change window for first sync. Confirm the exact scopes and service account steps in the provider documentation.
Can an internal team set up Google Workspace provisioning without outside help?
Yes, if the team includes someone who knows both the authentik provider model and Google Workspace administration, and if they can give the work sustained testing time. The hard parts are decisions, not configuration screens: matching rules, attribute mapping, handling existing accounts, and proving offboarding. A bad matching rule can attach a new record to a legacy account, and a poor first sync can change or suspend the wrong people. Internal teams should run a staged rollout with a tested rollback plan, document every mapping, and watch sync results after each run. Outside help is most useful for large directories, formal compliance evidence, or teams without spare capacity for repeated test cycles. DeployOpen plans, implements and documents this work in your infrastructure, and it prepares evidence for compliance assessments, but it does not issue audit reports.
What happens to existing Google accounts at the first sync?
The outcome depends on how matching is configured, so confirm the matching behavior in the provider documentation before first sync. Typical outcomes are that a matched account is updated, an unmatched record is created as a new account, or accounts with no counterpart in authentik are left alone or flagged, depending on your settings. Before the first run, export the current Google user list, check for duplicate primary emails, aliases and letter-case differences, and identify accounts owned by contractors or service processes. Decide whether unmatched accounts may be changed at all. Run the sync against a test tenant first and keep a copy of the directory state. Illustrative example: a person with an alias and a different primary address could be created twice if matching only uses the primary address.
Is suspension or deletion the safer offboarding path for Google accounts?
Suspension is generally the safer default. A suspended account cannot sign in, and its mail, Drive content and audit history remain available for recovery, transfer and legal holds. Deletion is difficult to reverse. Confirm in the provider documentation what authentik does when a user is deactivated and whether the Google side is suspended, deleted, or only removed from groups. Before the first offboarding, define how Drive and mail are transferred, who receives them, and how long the suspended account is kept. Test the full path on a sample account and ask for a written runbook that your team can follow without the original builders.
How DeployOpen scopes and delivers this integration
DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure. For authentik and Google Workspace provisioning, we start from a written scope that defines which Google Workspace users and groups authentik provisions, how existing accounts are matched, and how departures are handled before any configuration changes.
How we scope
- Written scope names the Google Workspace domain, organizational units and groups in the provisioning set
- Matching rules for existing Google accounts by email and name are agreed and documented before build
- Suspension versus deletion behavior for departed users is confirmed with your identity and records owners
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts
How we build
- We configure the Enterprise Google Workspace provider and its property mappings in your authentik deployment
- Test users and groups are provisioned in a non-production tenant to check matching and sync results
- Edge cases such as shared mailboxes, service accounts and name changes are tested against agreed rules
- Configuration is documented so sync timing and filter changes can be reviewed by your team later
How we hand over
- Handover covers configuration records, property mapping decisions and the matching and suspension rules
- Runbooks describe how to check a sync run, read provisioning errors and confirm a suspended account
- Your administrators are walked through the change process for groups, filters and mappings
- Open items, such as Google Workspace admin roles and edition requirements, are listed with owners
How we support
- Ongoing support, authentik upgrades and continuous testing are available as retainers
- Upgrade planning for authentik releases covers provisioning behavior and Google API changes in scope
- Retainer scope and response expectations are written into the agreement before support begins
- Changes to provisioning rules go through the same written scope process as the original build
