How Google Workspace sign-in works in authentik
An organization that already runs Google Workspace and wants staff to sign in to authentik with those accounts needs an OAuth source in authentik, which hands the login off to Google and returns the user to authentik once Google has confirmed who they are. The Google Workspace integration is listed on the authentik pricing page as an Enterprise-only feature, so confirm the edition and license terms before you design around it. Do not assume that a Google sign-in button comes with the open-source edition.
Keep two features apart during planning. The Google Workspace *provider* type in authentik is a separate feature that lets authentik act as a directory or provisioning target for Google Workspace, while the login source covered here only handles authentication. Many teams need one, the other, or both, and the answer changes the Enterprise scope, the app registration you create in Google and the user records authentik ends up holding. Confirm with authentik which of the two your use case requires before you request a quote or book build time.
This page covers the supported method for a Google login source: how the OAuth exchange is set up, how to restrict sign-in to your own domain, how new Google users enroll and how existing authentik accounts are linked to Google identities. The steps depend on your authentik version and on the Google Cloud project and consent screen settings in your tenant, so check those details against the current authentik providers documentation and your own Google administrator's setup before you begin.
What you need before you configure the source
Google Workspace as a login source depends on four things lining up: the right authentik edition, a supported release line, a Google Cloud OAuth client that your Workspace admins approve, and a public HTTPS address that both users and Google can reach. Settle these before touching the source settings, because a gap in any one of them tends to surface later as a failed sign-in.
Enterprise edition and licence
Google Workspace integrations are listed as an Enterprise-only feature on the authentik pricing page, so the Open Source edition will not give you this source. Confirm the edition with your authentik account contact before planning. The code under the enterprise directory is covered by its own licence, separate from the MIT licence that covers most of the repository, so have your legal team review that licence if your organization restricts which code it runs.
Supported authentik release line
Run a release line that receives security fixes. The authentik security policy lists 2026.5.x and 2026.8.x as supported, and the project announces security releases at least 24 hours in advance. Pick the line you will stay on, record the exact version in your change ticket, and plan your maintenance window around that advance notice.
Google Cloud project and OAuth client
Create a Google Cloud project and an OAuth client for authentik in your own console. Google's consent screen and OAuth requirements change over time, so confirm the current rules in your console before you register the client. Ask a Workspace super administrator or a delegated admin to approve the app and to confirm which user types and scopes your domain allows.
Workspace administrator access
Identify who holds super administrator rights or a delegated role that can manage API access and app approvals in the Workspace admin console. Without that person, the OAuth client may be blocked for internal users. Agree on who owns the Google Cloud project after go-live, since its credentials and consent settings affect every sign-in through this source.
Public HTTPS hostname for redirects
The OAuth redirect URI must point to a public HTTPS hostname you control that routes to authentik. Choose the hostname now, obtain a valid certificate, and confirm the reverse proxy forwards the callback path. Changing the hostname later means updating the Google client and the authentik source together.
Reachable server, worker and PostgreSQL
A deployment has a server container, a worker container for background tasks, and PostgreSQL holding all configuration and data except uploaded files. Users must reach the server through the hostname, and Google must be able to call back to it. Confirm that the worker can run source synchronization and that PostgreSQL is backed up, since the source and its user links live there.
Configuring the Google source step by step
This sequence takes a Google Workspace OAuth client from creation in Google Cloud to a working authentik source that signs in only your domain's users and is bound to the login and enrollment flows. Each step ends with a check you can run before moving on.
Create the OAuth client in Google Cloud
A Google Workspace administrator, working with someone who has access to the Google Cloud project that will hold the credentials, creates or selects a project and opens the OAuth consent configuration. Where your organization allows it, set the user type to Internal so that only accounts in your Workspace domain can authorize the client. Then create an OAuth client ID of the web application type. Confirm the exact menu names in the current Google Cloud console, since Google renames these screens from time to time. The step is done when the client appears in the project's credentials list with a client ID and secret.
Record the client ID and secret securely
Copy the client ID and client secret into your team's secrets store rather than a shared document or a chat thread. Limit who can read the secret to the people who will manage the authentik source. Note which Google Cloud project owns the client so that a future rotation or cleanup does not break sign-in. The step is done when the values are stored in the vault and a second administrator can locate them without asking the person who created the client.
Create the Google source in authentik
In the authentik admin interface, open the directory section and create a new Google Workspace source, selecting the Google Workspace type rather than a generic OAuth source. Paste the client ID and secret, and enter the Google Workspace domain you want to accept. Copy the redirect (callback) URL that authentik displays for the source and keep it open, because the next step needs it exactly. Confirm the field names in your authentik version. The step is done when the source is saved and appears in the source list as enabled.
Register the callback URL and scopes in Google
Return to the OAuth client in Google Cloud and add the callback URL from authentik as an authorized redirect URI. A mismatch in scheme, host or trailing path is the most common cause of a failed redirect, so paste the value rather than retyping it. Confirm that the requested scopes cover email and profile, which authentik needs to identify the user and populate name and address fields. Do not add directory or administrative scopes unless a specific sync requirement calls for them. The step is done when the redirect URI is saved on the client and the scopes listed match the email and profile requirement.
Bind the source to the login and enrollment flows
In the authentik source settings, attach the Google source to the authentication flow that users see at sign-in, so the Google button appears on the login page. Then set the enrollment flow the source uses when a Google user has no matching account, and decide whether that flow creates a new user or asks for confirmation. Keep the existing password and MFA stages in the flow so that Google sign-in does not bypass your second factor policy. The step is done when the login page shows the Google option and the enrollment flow is the one you designed.
Test sign-in with a pilot account
Choose a pilot account in your Workspace domain that is not an administrator and has a known mailbox. Sign in through the Google option on the authentik login page and confirm that the user lands in the expected application or dashboard. Check the user record in authentik and verify that the email address matches the Google account. The step is done when the pilot user exists once, with the expected email, and the sign-in is recorded in the authentik event log.
Confirm rejection of outside accounts
Test that domain restriction works by attempting sign-in with an account outside your Workspace domain, such as a personal Google account, if your policy allows you to test with one. Authentik should refuse the sign-in or stop at the enrollment flow without creating an account in your directory. Also confirm how existing local users with the same email behave, since linking rules decide whether an account is merged. The step is done when the outside account is rejected and no unexpected user has been created.
Confirm the sequence against your authentik version
Before extending the source to other users, compare each setting and menu name in this sequence with the documentation for your installed authentik version and the current Google Cloud console, because both change between releases. Record the client ID owner, the redirect URI, the domain restriction and the flow bindings in your change record. The step is done when a reviewer has signed off on the recorded configuration and the pilot results are kept with it.
Mapping Google identity claims to authentik users
This table compares each Google identity attribute authentik may receive with the authentik user field it feeds, who controls the value, and what happens when it is missing or changes. Confirm the exact attributes your Google source passes in your own test login before you finalize matching rules, because the fields available depend on the source configuration and Google's OpenID Connect claims.
| Google attribute | Maps to in authentik | Who owns the value | Missing or changed |
|---|---|---|---|
| Subject identifier (sub) | External identity link for the source, not the username | Stable per Google account; treat as the primary key for linking and never reassign it manually | |
| Primary email | Email field and candidate username | Google (Workspace admin) | A changed address can create a duplicate user if matching uses email alone; match on subject first |
| Email verified status | Gate for email-based matching and account linking | If false or absent, do not auto-link to an existing account by email | |
| Given and family name | Name fields on the user | Google (user or admin) | Usually optional; update on each login if your mapping allows it |
| Hosted domain (hd) | Policy check that the account belongs to your domain | Missing for personal accounts; deny sign-in when the domain does not match | |
| Group membership | Not assumed to be passed by the source | Google (groups) or authentik (assignments) | Confirm what your source passes; otherwise plan group assignment inside authentik |
| Username rule | Derived from email local part or subject, set in the enrollment flow | authentik (administrator) | Decide before go-live; changing it later affects existing accounts and links |
How authentik links Google logins to existing users
Before you enable the Google Workspace source, decide what a first Google sign-in should do when the account already exists in authentik. There are three options: create a new user through enrollment, attach the Google identity to a user that was already created by another source or by hand, or hold the login until an administrator approves the link. Each option changes who can get in and who ends up with duplicate accounts. Enrollment is the simplest to run but creates new accounts for anyone who signs in, so it works best when authentik is the only place users come from. Attaching to existing users keeps one account per person, but only if the matching rule is correct. Approval-based linking is the safest choice when your directory was populated from LDAP, SCIM or an earlier authentik deployment, because a person's record may already exist under a different username.
The main risk is matching on email address alone. Email is convenient, but it is not a stable identifier: addresses get reassigned, aliases exist, and an account created by another source may carry an email value an administrator typed in by hand. Before you rely on email matching, confirm with Google's admin documentation and your own tenant that the email claim you receive is verified by Google for the accounts in scope, and check how the Google source passes that claim into authentik's property mappings. Also confirm which attribute authentik uses to identify the user on subsequent logins, so that a later change to a name or address does not create a second account. Treat any mismatch between a Google identity and an existing user as a stop condition, not a warning to be skipped.
Run a pilot with a small set of accounts before you open the source to everyone. Choose a few users who already exist in authentik with known records, plus at least one new hire and one person who has changed their name or primary address, and sign each one in through Google. Record which account each login attached to and whether any duplicates appeared. Write down a rule for duplicates and renamed users before the pilot ends: who approves a link, what evidence is required, and how a second account is merged or disabled. Keep that rule in your runbook so the help desk applies it consistently. Expect the rule to change after the pilot, and ask your implementation partner to include the pilot results in the written scope of work.
Restricting sign-in to your Google domain
The first control sits in Google Cloud, where the OAuth consent screen for the client used by authentik determines who can authorize the application. Setting the user type to internal limits authorization to accounts that belong to your Google Workspace organization, so an account from an outside domain cannot complete the Google sign-in at all. Confirm the current consent screen options in the Google Cloud console for your organization, since menu names and availability depend on how the project is set up.
- What it stops: Google accounts outside your Workspace organization cannot authorize the OAuth client, so they never reach authentik.
- What it does not stop: Accounts inside your organization that you have not approved for use, and any user who already has a valid account in your domain.
- What it does not replace: A check inside authentik. If the consent screen is later changed to external, the Google-side control disappears silently.
- How to test: Sign in through the authentik Google source with an account from another domain, or a personal Gmail account. The flow should fail at the Google consent step.
- Record: Save a screenshot of the consent screen configuration and the failed test result as evidence for your change record.
Check this setting after any change to the Google Cloud project, since it is easy to reset when the consent screen is edited.
The second control runs inside authentik, in the source's enrollment or authentication flow, where a policy can inspect the email domain of the returned identity and reject anything that is not allowed. This is the control you can version, review and test alongside the rest of your authentik configuration. Confirm which domain check method your authentik version supports, such as an expression policy against the user's email attribute or a built-in matching option, before you build it, because the supported approach has changed between releases.
- What it stops: Accounts whose email domain is not on your allow list are rejected even if Google authorized them, for example a secondary domain that is not part of your intended scope.
- What it does not stop: Users within the allowed domain who should not have access to a particular application. Use application bindings and group policies for that.
- Placement matters: Bind the check to the flow that the Google source uses, not only to a single application, so every route into authentik is covered.
- How to test: Attempt sign-in with a permitted account, then with an account from a disallowed domain. The second attempt should stop with a denial message and create no active user.
- Watch for aliases: Confirm whether the policy compares against the primary email only, since some organizations use alias domains that also need handling.
After testing, review the audit log to confirm that the rejected attempt was recorded.
The third control decides whether a successful Google sign-in can create a new authentik account at all. Enrollment flows can be configured so that a first-time Google user is either matched to an existing account, or stopped unless an administrator has invited them. Turning off open self-service enrollment means that a valid domain account without a pre-existing link cannot quietly create a user. The exact flow settings depend on your version, so confirm the enrollment and linking options available in your release.
- What it stops: Automatic account creation for any authenticated Google user who has no matching or invited record in authentik.
- What it does not stop: Access by users who are already linked, and users who an administrator has deliberately invited or matched.
- Linking risk: If matching is done on email address alone, check that the match cannot attach a Google identity to the wrong existing account.
- How to test: Use a domain account that has never signed in before. With enrollment restricted, it should be refused or sent to a holding page, and no new user should appear in the directory.
- Invitation test: Create an invitation for a test user, then repeat the sign-in to confirm that only the invited account is admitted.
Record the enrollment setting alongside the Google and domain controls, because the three only give full protection when all are in place.
Security settings to lock down before go-live
A Google sign-in source changes who can enter authentik and how accounts get created and linked. The controls below decide whether a Workspace login is a safe front door or an open one. Confirm each setting in the authentik version you run, since menu names and defaults shift between releases.
Protect the Google client secret
The OAuth client secret for the Google source lets authentik exchange authorization codes with Google, so anyone who reads it can impersonate the application. Keep it out of exported blueprints and plain-text configuration files, and load it from a secrets mechanism your platform team already operates. Then check which authentik roles can view the source's stored values, and remove read access from roles that only need to use sign-in. Rotate the secret in Google and in authentik if it has ever been pasted into a ticket or chat.
Limit who can edit sources and flows
Editing a source, a flow or a policy can change who is allowed in, so these permissions deserve the same review as production firewall rules. Restrict source and flow editing to a small named administrator group, and keep everyday support staff on read-only or user-management roles. Review that group after every staffing change and confirm that changes to the Google source produce an audit entry you can find.
Keep enrollment closed unless intended
Enrollment flows can create new accounts from a successful Google sign-in, which is convenient but means any account that passes Google authentication may gain an authentik user. Decide whether self-enrollment should exist at all for this source. If it should, limit it to your Workspace domain through the source configuration and the enrollment policies, and confirm that a Google account from outside the domain is rejected before it reaches account creation.
Require verified email before linking
Linking a Google login to an existing authentik account usually matches on email address, so an unverified address could attach a login to the wrong person. Confirm that the matching policy only accepts an email claim that Google marks as verified, and test this with a Workspace account and an external account that claims a matching address. Document which attribute authentik uses to match, because changing that attribute later can silently break links for existing users.
Decide what Google sign-in proves
Google can enforce 2-Step Verification for Workspace users, but authentik only inherits that strength if your design says so. Decide whether a Google sign-in meets your MFA requirement for applications, or whether authentik should still prompt for its own second factor on sensitive applications. Write the decision down per application, and test the flow with a user whose Google account has no second factor enrolled.
Enable and forward audit logs
Enhanced audit logging is listed as an enterprise feature on the authentik pricing page, so confirm whether your edition includes it before you plan around it. Whatever edition you run, record sign-ins through the Google source, source edits and linking events, and forward them to the log platform your security team monitors. Test that a failed domain check and a successful linked login both appear in that platform, and set alerts on repeated failures.
Common Google source failures and fixes
This table lists the failures teams most often hit when Google Workspace is added as a login source in authentik, with the likely cause, the fix and the first check to run. Read it top to bottom when a sign-in breaks, or use it as a checklist before go-live. The main takeaway is that most failures trace back to the OAuth client settings, the consent screen audience or the matching rules, so check those before changing users.
| Failure | Likely cause | Fix | First check |
|---|---|---|---|
| Redirect URI mismatch | The callback URL registered in the Google Cloud OAuth client does not match the source callback URL authentik generates, often because the hostname or scheme changed. | Copy the exact callback URL from the authentik source and register it on the OAuth client, then retry sign-in. | Compare the registered redirect URI character by character with the authentik source callback URL. |
| Client secret rotated or copied incorrectly | The secret was regenerated in Google Cloud or pasted with leading or trailing spaces, so token exchange fails. | Enter the current secret in the authentik source, remove stray whitespace and retire the old secret after confirming the new one works. | Check the authentik event log for token exchange errors and confirm which secret is stored in the source. |
| Consent screen set to external | The OAuth consent screen audience allows accounts outside your organization, so non-domain accounts reach the flow or test users are blocked. | Set the consent screen to internal for a Workspace-only source, or confirm the test user list if the app is still in testing. | Check the user type and publishing status on the consent screen in Google Cloud. |
| Domain policy rejects valid accounts | Matching or restriction rules compare the email domain against the primary address only, so valid aliases or secondary domains are refused. | Decide which addresses are valid, then align the domain restriction with the primary domain and the aliases you intend to accept. | Sign in with the failing account and compare its primary and alias addresses with the restriction policy values. |
| Duplicate users after a username rule change | Changing the username source or mapping creates new accounts instead of matching existing ones, so the same person exists twice. | Merge or disable the duplicates, restore the previous mapping and then apply the new rule with an explicit matching step for existing users. | Search users by email address and compare creation dates and linked sources. |
| Users locked out after the source is removed | Accounts created or linked only through the Google source lose their login method when the source is deleted or disabled. | Before removing the source, give affected users a working password or another factor, and confirm recovery access for administrators. | List users linked to the source and confirm each has an alternative login path. |
| Enterprise license not applied | The Google Workspace integration is an Enterprise-only feature, so the source type is unavailable or not usable on an open source build. | Confirm the edition and apply the license in your deployment, or plan the sign-in method with a supported option. | Check the sources menu for the Google Workspace type and the license status in the admin interface. |
Questions buyers ask before setting up Google sign-in
What does Google Workspace sign-in cost in authentik and which license does it need?
Google Workspace and Microsoft Entra ID integrations are Enterprise-only features in authentik. The authentik pricing page lists Enterprise at $5 per user per month billed annually, plus $0.02 per external user per month. Those are the authentik licensing figures to budget against. The Open Source edition does not include the Google Workspace integration. Your cost also includes the services side: the scoped setup work, testing and handover are quoted separately from the license, and DeployOpen quotes them from a written scope. Ask your partner to confirm which users count as internal and which as external under your license terms, since that determines how the per-user and per-external-user charges apply to your directory.
How long does Google sign-in setup take and what makes it longer?
Duration depends on scope rather than on the Google connection itself. A single domain with one clear rule for linking accounts is the simplest case. Duration grows with the number of domains and tenants you connect, the number of existing authentik users that must be linked to Google identities, how many applications have different login flows, and the amount of testing needed for enrollment, recovery and domain restrictions. Decisions made early, such as whether Google is the only login path or sits beside a password, add or remove work. Ask for a fixed-scope timeline that lists these items separately so you can see what each one adds.
Can our own team set up Google Workspace sign-in without a partner?
Yes, a team with authentik administration experience can set up a Google Workspace source for a single domain when the linking rule is already decided. The work involves creating the OAuth client in Google, configuring the source in authentik, restricting sign-in to your domain, and testing enrollment and login flows. A partner adds value where the design has more moving parts: several domains, existing accounts that need careful linking, custom enrollment flows, and a test plan that covers failure cases before users are affected. DeployOpen plans and implements these pieces under a written scope and can hand over documentation so your team can run the setup afterward.
What do we need from the Google administrator and the authentik administrator?
The Google administrator needs to create or approve an OAuth client for authentik in the Google Cloud project your organization controls, and to confirm which Workspace domains are allowed to sign in. The authentik administrator needs access to create the Google source, configure its redirect and domain restrictions, and manage the enrollment and linking flows. Both should agree on who owns the OAuth client secret, how it is stored, and who approves changes. Confirm the exact Google Cloud steps and consent screen settings with Google's current documentation and your own tenant policies, because they change over time.
Do Google Workspace editions or user counts change the authentik setup?
The Google Workspace edition and user count affect the Workspace account, not how authentik is configured as a login source. Google lists Business Starter and Business Standard as supporting up to 300 users, while Enterprise editions have no minimum or maximum user limit. Those are Google's figures and do not change authentik licensing, which is priced per user as described on the authentik pricing page. What matters for setup is that your users sign in with accounts on the domains you connect, so confirm your domain list and whether any users sit outside Workspace before scoping the work.
Does Google Takeout or Workspace data export affect sign-in?
No. Google Takeout and the Workspace Data Export tool move data out of Google accounts and do not change how users authenticate to authentik. Administrator controls over Takeout have no effect on the OAuth sign-in flow.
What should we check before a Google source goes live for all users?
Test with a small pilot group before opening sign-in to everyone. Check that users from an allowed domain can sign in, that accounts from other domains are refused, that existing authentik users link to the right Google identity, and that new users follow the intended enrollment path. Confirm recovery options for users who lose access to their Google account, and keep a local administrator login available. Record the test results so an auditor or security reviewer can see how the controls were verified.
How DeployOpen works on this
DeployOpen treats Google Workspace sign-in as a planned change to how your staff reach authentik, not a single settings page. We scope the domain rules, enrollment behavior and account linking in writing first, then build and test the source in infrastructure you control. Your team receives the configuration, evidence and runbook needed to operate it.
How we scope
- Confirm which Google Workspace edition and tenant your organization uses before any configuration starts.
- Record the allowed domains, the group or organizational unit rules that gate access, and who approves them.
- Document how existing authentik accounts will link to Google identities, including the handling of duplicate emails.
- Agree the written scope, deliverables and timeline with you before work begins, as most engagements are fixed-scope.
How we build
- Configure the Google OAuth source in authentik, with the redirect URI and client credentials held in your secrets store.
- Build enrollment and linking flows so new Google sign-ins match your rules and fail closed on unknown domains.
- Test domain restriction, first login, repeat login and linking with a set of named test accounts in a non-production instance.
- Check the outcome against your planned access model before any change is made to production applications.
How we hand over
- Provide the final source configuration, flow and policy settings, and the list of Google Cloud settings used.
- Write a runbook covering rotation of client secrets, adding domains and handling linking requests from users.
- Walk your administrators through sign-in, lockout recovery and the local fallback account approach you chose.
- Deliver the test results and change record so your security and compliance reviewers can inspect the setup.
How we support
- Offer ongoing support, authentik upgrades and continuous testing as retainers after the initial handover.
- Plan authentik version upgrades against the supported release lines so the Google source keeps working.
- Review Google Workspace changes that affect your rules, such as edition or domain changes, before they reach users.
- Confirm with your team which support scope, response expectations and retainer terms apply before work starts.
