How authentik as SAML identity provider for Google Workspace works
In this integration, authentik acts as the SAML identity provider (IdP) and Google Workspace acts as the service provider (SP). When a user opens Google Workspace, Google redirects them to authentik, authentik authenticates the user with the sign-in and factors your organization has configured, and then returns a SAML assertion that Google accepts. authentik uses its SAML provider type for this, and the Google Workspace configuration is documented in the authentik integrations catalog page for Google Workspace, which is the primary read before you start. The point to hold onto is that Google keeps the account, the mail, the storage and the admin console, while authentik decides who is allowed to sign in.
Two decisions are easy to blur together and should be made separately. SSO sign-in governs how a user proves identity at login, and the SAML provider handles that. User provisioning governs whether authentik creates, updates or removes Google accounts automatically. The guide treats these as different choices: the SAML sign-in path works against users who already exist in Google Workspace, and automatic account creation and changes from authentik require authentik Enterprise. Confirm the current Enterprise provisioning scope with DeployOpen's scoping and with the integration documentation, and decide early whether your team will manage Google accounts by hand or by provisioning.
Plan the sign-in path before you touch the Google admin console. Confirm which authentik components will serve the SAML endpoint in your deployment, which users will be tested first, and how you will roll back SSO if sign-in fails for everyone except super administrators. Super administrators sign in differently and should not be used to test the integration, so keep a separate, documented recovery path for them. Pick the test users from the existing Google accounts and verify that their primary email addresses match the identifiers authentik sends, because a mismatch is the most common reason a user is sent to an unexpected account or cannot sign in.
What you need before connecting Google Workspace to authentik
Connecting Google Workspace to authentik over SAML depends on four things lining up before any configuration starts: a supported authentik version, a Workspace edition that fits your user count, accounts that already exist with matching emails, and a recovery path. Work through the cards in order, since the Enterprise decision affects how much of the setup you plan for.
Supported authentik version
Confirm your deployment runs on the 2026.5.x or 2026.8.x line, the versions the authentik security policy lists as receiving security fixes. The project announces security releases at least 24 hours in advance, so your maintenance window needs room to follow them. Check the running version in the admin interface before you plan the SAML provider, because an unsupported line means upgrading first. Upgrades to a newer line are sequential, so plan the path before the Google work begins.
Google Workspace edition and user count
Confirm the edition you actually hold in the Google Admin console, not the one your contract implies. Business Starter and Business Standard support up to 300 users, while Enterprise editions have no minimum or maximum user limit. If your headcount is near the 300-user boundary or growing, the edition choice affects both licensing and whether your SAML rollout must cover a larger population later. Ask your Google reseller or account team to confirm the edition in writing.
Users created with matching primary emails
Google Workspace does not create users from a SAML sign-in, so every person who will sign in must already exist in the Workspace directory. Their primary email address must match the identifier authentik sends for them. Mismatched addresses, such as an alias used in authentik or a different domain, produce sign-in failures that look like SSO faults. Export the user list from authentik and the Admin console and compare them before you enable the provider.
Recovery super administrator account
Keep at least one super administrator account that signs in directly to Google, not through authentik. Super administrators sign in differently under SSO and should not be used to test the integration. If the SAML provider is misconfigured, this account is how you restore access and correct the settings. Store its credentials and recovery methods in your password vault, and confirm they work before you switch sign-in over.
Test users outside administrators
Pick a small group of ordinary users, not administrators, to validate the flow end to end. Each test user should have a matching primary email, a known role and a clear expected outcome for sign-in. Record which users you tested and which browser and device they used, so the pilot results are repeatable. Testing with administrator accounts hides problems that ordinary users hit, because those accounts follow different sign-in rules.
Enterprise license for provisioning
SAML sign-in works without the Enterprise license, but automatic creation and management of Google Workspace users from authentik requires authentik Enterprise, and the pricing page lists Google Workspace integration as an Enterprise-only feature. Decide now whether you will provision users from authentik or keep manual creation in Google. Ask your authentik provider which license covers your planned user count and what it costs per year, since that decision shapes the scope of the work.
Configure the SAML connection in the order the guide requires
This sequence connects authentik to a Google Workspace domain over SAML in a fixed order, so that each side is ready before the next one depends on it. The result is a tested sign-in path for a standard user, with unassigned and mismatched accounts confirmed to be refused.
Confirm users exist in Google Workspace first
Before touching authentik, the Workspace administrator confirms that each person who will sign in already has a Google Workspace user account. The primary email address on each account must match the email authentik holds for that person, because the SAML login is matched on that value. Check a sample of users against their authentik accounts and note any mismatch to fix in the source directory. The step is complete when every test user has a Workspace account with a matching primary email.
Create the SAML provider and application in authentik
An authentik administrator creates a SAML provider and an application for Google Workspace, using the settings given in the authentik Google Workspace integration guide. Record the entity ID, the ACS URL and the signing configuration that the provider exposes. Keep the provider bound to a clearly named application so that later assignments and audit records are easy to read. The step is complete when the provider saves without errors and its metadata can be downloaded.
Copy the metadata and ACS values from authentik
The administrator exports or copies the SAML metadata from the authentik provider, along with the ACS and entity values the Google side will need. Store these values in a change record so that the same values are used on both sides without retyping. Confirm the values match exactly, including the protocol and host name, since a single character difference will cause the login to fail. The step is complete when the metadata and values are saved and checked against the provider page.
Configure the SAML SSO profile in Google Admin
A Google super administrator opens the Google Admin console and creates or edits the SAML-based single sign-on profile for the organization. Enter the identity provider details from authentik and the sign-in and change URLs the guide specifies. The Google menu labels change over time, so confirm the current names in the Admin console or in Google's own help before clicking through. The step is complete when the profile saves and the console shows the SSO profile as configured but not yet enforced for all users.
Assign the SSO profile to organizational units or groups
The administrator applies the SAML SSO profile only to the organizational units or groups that hold the pilot users, rather than to the whole domain at once. This limits the blast radius if a setting is wrong. Keep the super administrator accounts out of the scope of this assignment, since they sign in through a separate path. The step is complete when the assignment shows the pilot units and the rest of the domain still uses its existing sign-in.
Test sign-in with a standard user
A standard pilot user opens a Google Workspace service in a private browser session and is redirected to authentik for sign-in. After authenticating, the user should land in Workspace with the account that matches the primary email. Check the authentik event log for the login to confirm the expected email claim was sent. The step is complete when the test user signs in successfully and the email in Workspace matches the email in authentik.
Verify that unassigned and super admin accounts behave as expected
Test one user who is not in the assigned organizational units or groups, and confirm that the SAML sign-in is not applied to that user. Then confirm how super administrators sign in, as the guide describes, without using them as the test account. Record the results, including any user whose primary email did not match, so they can be corrected before wider rollout. The step is complete when the unassigned user follows the existing path, the super administrator path is documented, and the pilot results are written down.
How email and user identity map between authentik and Google Workspace
This table compares the identity fields that must line up between authentik and Google Workspace for a SAML sign-in to succeed. Read each row as a rule the two systems must agree on before testing. The main takeaway is that the Google account must already exist and its primary email must match the authentik email the assertion carries.
| Field | In authentik | In Google Workspace |
|---|---|---|
| Login identifier | The user's email address is the value sent to Google in the SAML assertion, so confirm the mapping in the SAML provider configuration. | The sign-in matches the Google user whose primary email equals that address, not a secondary alias. |
| Email format and case | Enter the address exactly as the mail domain is written, and check for stray spaces or uppercase variants before testing. | Confirm the primary email spelling in the Admin console, since a mismatch is a common cause of failed sign-ins. |
| Existing user record | The authentik user must exist with the correct email before the test. Provisioning from authentik to Google is not included in the SAML sign-in. | The Google user account must already exist. The guide states users must exist first, so create accounts before enabling SSO. |
| Email mismatch | If the authentik email differs from the Google primary email, the sign-in does not match a Google user. | Change either the authentik email or the Google primary email so they are identical, then retest the sign-in. |
| Super administrators | A super administrator account should be kept out of the test population, since the guide says these accounts sign in differently. | Super administrators sign in through a different path, so validate SSO with a standard test user instead. |
| Provisioning scope | Creating or updating Google accounts from authentik requires authentik Enterprise, according to the integrations catalog. | Without provisioning, Google accounts are created and managed separately from the authentik user record. |
Why super administrators should not be used to test SSO
Do not use a super administrator account to test authentik SSO. The authentik Google Workspace SAML guide notes that super administrators sign in differently from other users and should not be used to test, because a test that succeeds or fails on that account tells you little about how ordinary staff will sign in. Test with a standard user who has the same organizational unit, group and role as the people you plan to move to SSO. Before cutover, confirm the exact sign-in behavior of super administrators in your own tenant, including whether they are redirected to SSO at all, and record the result.
The risk is lockout. If the SAML configuration, certificate, or the primary email match between Google Workspace and authentik breaks after you enforce SSO, every user who depends on that path is affected, and the accounts that could repair the tenant may be the ones you cannot reach. Plan a break-glass path: a super administrator password sign-in kept outside SSO, with a strong, unique credential stored in your secrets process and a hardware second factor where Google supports it for that account. Keep at least two named super administrators able to use it, and store recovery codes separately from the password.
Test the break-glass path before you need it. In a change window, sign in with the break-glass account from a clean browser, confirm admin console access, then sign out and confirm that the normal SSO route still works for a test user. Document the account names, where the credential is kept, who may use it, the steps to follow, and the review date. Schedule the test again after any change to SAML settings, certificates, or the authentik version. Treat the documented result as evidence for your change record, not as an assumption.
When to add authentik Enterprise provisioning for Google Workspace
In this model, authentik handles sign-in over SAML while user accounts are created and changed outside authentik. The Google Workspace accounts must already exist with primary emails that match the authentik accounts, so an administrator or another process (a manual import, a Google Cloud Directory Sync setup, or a script you maintain) keeps the directory current. Because authentik does not create or remove accounts here, you only need the Open Source edition for the SAML connection itself.
- Lower license cost: The Open Source edition is free, and no per-user Enterprise fee applies to this model.
- Manual lifecycle work: Each new hire, role change and departure needs an admin action in Google Workspace, and it recurs for every change.
- Leaver risk: Disabling a person in authentik does not suspend their Google account, so offboarding must be tracked in two places.
- Fit for stable populations: Small or slow-changing user groups often absorb manual work without strain.
- Verify the upstream process: Confirm which system is the source of truth for accounts and how fast it reaches Google Workspace.
Before choosing this model, check that the process creating accounts is documented and tested, and that someone owns offboarding.
In this model, authentik creates, updates and suspends Google Workspace users from its own records. Provisioning from authentik requires authentik Enterprise, because the Google Workspace integration is listed as an Enterprise-only feature on the authentik pricing page. The published Enterprise price is $5 per user per month billed annually, plus $0.02 per external user per month. Confirm with authentik whether your external user count and billing terms apply to your case.
- Recurring license cost: The Enterprise fee repeats every month and scales with the number of users, so model it against your headcount.
- Automated lifecycle: Account creation and changes follow the authentik user record, which reduces manual steps and lag.
- Consistent offboarding: Deactivation in authentik can flow to Google Workspace, which closes the two-place gap of the SSO-only model.
- Audit visibility: Enhanced audit logging is also an Enterprise feature, which matters if you must show who changed an account and when.
- Support terms: Ticket-based support for subscriptions over $1k is part of the Enterprise tier, so review what it covers.
Ask authentik for a written quote that states the user count basis, billing period and any external user charges before you commit.
Churn is the main driver of the decision. Organizations with frequent hiring, contractor turnover or reorganizations pay the manual cost of the SSO-only model many times a year, while a stable workforce may not. The question is how often accounts change and how quickly each change must take effect in Google Workspace, not only how many users you have.
- Measure change volume: Count joiners, movers and leavers over the last year, including contractors and temporary staff.
- Set a removal deadline: Decide how long a departed user may keep Google access, and whether that deadline is achievable manually.
- Watch shared or service accounts: Accounts that do not map to a single person complicate both models, so list them early.
- Consider growth: A workforce that is expanding will raise the Enterprise fee over time, so project headcount for the contract term.
- Test with a pilot group: A small group lets you observe how provisioning behaves before you apply it to the full organization.
Document your churn numbers, because they are the input that makes the cost comparison meaningful.
The second driver is who performs the work and what evidence you must keep. In the SSO-only model, administrators spend time on account changes and must keep their own records. With provisioning, the authentik record becomes the place where lifecycle actions are visible, which can simplify reviews, but only if the logs are retained and reviewed. DeployOpen can help define the evidence your assessors expect, but it does not issue audit reports or attestations.
- Admin hours: Estimate the recurring time spent on account creation, changes and removal, and who performs it.
- Access reviews: Decide how often you will review Google Workspace accounts and which system produces the list.
- Audit logging: Enhanced audit logging is an Enterprise feature, so check whether your evidence needs depend on it.
- Segregation of duties: Consider whether the people who approve access should be separate from those who administer authentik.
- Log retention: Confirm where authentik and Google Workspace logs are stored and for how long your policy requires.
Bring these answers to your auditor or compliance lead early, since they often shape the choice more than license cost.
Security settings to review for this Google Workspace integration
The authentik side of this integration decides who reaches the Google Workspace sign-in page and how the SAML trust is maintained over time. The controls below cover what authentik enforces before it issues an assertion, how the signing material is handled, and which access paths stay open for recovery. Confirm the Google-side enforcement options available in your edition before you rely on any of them.
MFA enforced before the SAML response
Google Workspace trusts the assertion authentik sends, so authentik's authentication flow is the control point for second factors. Bind an authentication policy to the application so that users must complete MFA in authentik before the SAML response is issued. Test with a standard user account and confirm that a session without MFA is refused. Then confirm in your Google Workspace edition whether any additional Google-side sign-in enforcement is available and how it interacts with SSO.
Signing certificate rotation
The SAML signing certificate and key are the trust anchor between authentik and Google. Record the certificate expiry date, plan a rotation before it lapses, and check that the new certificate is uploaded to Google Workspace before authentik starts signing with it. Store the private key in your secrets management process rather than in exported configuration files. Schedule a test sign-in after each rotation so that an expired or mismatched certificate is found in a window you chose.
Restricting the application to intended groups
Assigning the Google Workspace application to all authentik users widens the sign-in surface beyond the people who need Workspace. Bind the application to a named group or policy so that only that population can start the SAML flow. Review group membership on a set cadence, because access follows authentik group changes and not Workspace seat assignments. Confirm which users have seats in Google Workspace so that the two lists do not drift apart.
Super administrator recovery path
Super administrators sign in differently from regular users, so the SSO path can fail while they are still needed to repair it. Keep at least one super administrator account that you can reach without relying on authentik, and store its credentials and any recovery codes under your break-glass procedure. Test that this path works before the SAML cutover. Do not use a super administrator account to validate the regular user flow.
Enhanced audit logging
Enhanced audit logging is listed as an Enterprise-only feature on the authentik pricing page, so confirm the subscription tier before planning around it. Without it, you may have less detail on sign-in events, configuration changes and policy decisions when you investigate a failed or suspicious login. Decide where authentik logs go, who reviews them, and how long they are kept, and align that with the retention rules that apply to your organization.
Common Google Workspace SAML failures and how to fix them
This table lists the failures most often seen when authentik signs users in to Google Workspace over SAML, with the likely cause and a check you can run for each. Work through the rows in order, since a missing pre-created account or a primary email mismatch will produce symptoms that look like certificate or redirect problems.
| Failure | Likely cause | Check and fix |
|---|---|---|
| User not found at sign-in | The Google Workspace account was never created, so authentik has no matching user on the Google side | Confirm the user exists in the Google Workspace Admin console before first sign-in. Create the account first, then retry the authentik login for that user. |
| Sign-in loop back to authentik | The primary email in Google Workspace differs from the email authentik sends, including letter case or an alias used in place of the primary address | Compare the primary email in the Admin console with the email attribute in the authentik user record. Correct the mismatch so the two match exactly, then clear the browser session and test again. |
| Super administrator cannot sign in | Super administrators follow a different sign-in path than regular users, and an SSO change can remove the only account that could recover the tenant | Keep a super administrator account that is not dependent on SAML and test it before changing settings. Confirm the sign-in path for super administrators in the authentik Google Workspace guide before making changes. |
| Invalid signature or certificate error | The signing certificate in authentik and the certificate uploaded to Google Workspace no longer match after a rotation or re-export | Compare the certificate fingerprint shown in authentik with the one configured in Google Workspace. Upload the current certificate to Google Workspace and retest with a non-admin test user. |
| ACS URL or entity ID mismatch | The Assertion Consumer Service URL or entity ID was edited on one side after a domain, hostname or application change | Check that the ACS URL and entity ID in the Google Workspace SAML profile match the values generated by the authentik provider. Correct both and re-save before testing. |
| Users sent to Google sign-in instead of authentik | The SAML profile is not assigned to the organizational unit or group that contains the user, so Google falls back to its own login | Check which organizational units the SAML profile applies to and confirm the affected user sits inside one of them. Move the user or extend the assignment, then test a user from that unit. |
Questions teams ask before connecting Google Workspace to authentik
Can our team connect Google Workspace to authentik without outside help?
Yes, many teams with an administrator who knows both Google Workspace and authentik can do the SAML setup themselves, but the work depends on your tenant, your user base and your change window. The authentik Google Workspace guide states that users must already exist in Google Workspace with a primary email matching authentik, and that super administrators sign in differently. Teams usually bring in a partner when they need a clean user match across many accounts, a tested rollback path, or a documented handover. Confirm your internal skills against the guide before deciding.
What makes the effort for this integration grow or shrink?
The main drivers are the number of users, the Google Workspace edition, the number of organizational units, and whether you want provisioning. Google Workspace Business Starter and Business Standard support up to 300 users, while Enterprise editions have no minimum or maximum user limit, so your edition sets the size of the tenant you are working with. Each organizational unit adds policy and testing decisions. Provisioning from authentik to Google adds user creation, updates and removal work. Ask for the scope to be listed for each of these items in the written proposal.
Do we need authentik Enterprise just to sign users in with SAML?
The authentik Google Workspace SAML guide ties provisioning from authentik to authentik Enterprise, and it does not present Enterprise as a requirement for SSO alone. Confirm this with the current integrations catalog entry before you buy, because licensing terms can change. The authentik pricing page lists Google Workspace and Microsoft Entra ID integrations as Enterprise-only features, so if you want both sign-in and automated user lifecycle from authentik, plan for Enterprise from the start. Enterprise is priced per user per month, so the user count in your scope directly affects the license cost.
How long does a Google Workspace SAML rollout take?
No duration has been established for this work, so ask for a timeline in the written scope rather than relying on a general estimate. The schedule depends on the number of users, whether a pilot group is used, how many super administrator accounts need separate handling, and how much email matching cleanup is needed before cutover. Ask the provider to split the timeline into discovery, build, pilot, cutover and handover, with the dependencies on your side stated for each phase.
What do we need to provide for the engagement?
You need tenant administrator access to Google Workspace, access to the authentik instance and its administrators, and a review of user email data. The most important check is that every user who signs in already exists in Google Workspace with a primary email matching the one in authentik. Plan for a set of test users across departments, and keep super administrator accounts out of the test group because the guide says they sign in differently and should not be used for testing. Name an owner on your side who can approve changes to users and policies.
If we move off Google Workspace later, how do the Data Export tool and Takeout help?
Google's Data Export tool lets super administrators export organization data, including Gmail, Drive, Chat and Calendar, as zip files into a Cloud Storage bucket. The admin account must be at least 30 days old, exports typically take about 72 hours but can take up to 14 days, and the default bucket is deleted after 60 days, so plan the download before that window closes. Organizations with Assured Controls or an advanced edition can choose which data to export. Google Takeout covers individual user exports, and administrators control whether users can use it. Treat both as inputs to a migration plan, and confirm the scope with Google's current help pages before any identity change.
How DeployOpen scopes the Google Workspace integration
DeployOpen scopes most engagements as fixed scope, with deliverables and timelines agreed in writing before any work starts. For a Google Workspace SAML integration, that written scope normally covers the authentik SAML provider and application setup, the mapping between authentik user identifiers and Google Workspace primary emails, test sign-ins with standard users, the break-glass path for super administrators, and a handover of configuration and runbooks to your team. Each item should appear in the scope document with a named owner, so it is clear which items your team reviews and which DeployOpen delivers. Ask for the identity mapping and break-glass items to be described in enough detail that your Google Workspace administrators can check them against their own tenant before sign-in is switched on.
DeployOpen does not publish a price list. A quote follows from the written scope, so the inputs that move it are the number of Google Workspace organizations and domains in scope, whether provisioning from authentik is included (which needs authentik Enterprise on your side), the state of your existing users and primary emails, and how many environments you need to test in. Ask for the quote to show one-time work and any recurring costs separately, and confirm who holds the authentik Enterprise subscription and the Google Workspace edition you run. The Google Workspace edition should be confirmed against the current Google Workspace pricing page before scoping, since it affects which admin features you can rely on.
Ongoing support, upgrades and continuous testing are available as a retainer, which suits teams that want authentik upgrades, certificate rotation and sign-in checks handled after handover. Confirm with DeployOpen whether a retainer is needed at all, because a stable SAML application often needs little change once it is working. Any retainer terms, response expectations and service levels should be agreed in writing and kept separate from the fixed-scope project.
How DeployOpen delivers authentik SSO for Google Workspace
DeployOpen plans and implements authentik as the SAML identity provider for your Google Workspace domain, running inside infrastructure you control. The work starts with a written scope that settles user readiness, email matching, super administrator handling and whether provisioning from authentik belongs in the first phase.
How we scope
- Confirm which users already exist in Google Workspace and whose primary email matches the authentik account.
- Record the Google Workspace edition in use and the user count it must support before design starts.
- Agree in writing whether Enterprise provisioning from authentik is in scope or planned for a later phase.
How we build
- Deploy authentik on Docker Compose or Kubernetes in your environment, with PostgreSQL chosen to match your production standards.
- Configure the SAML provider, application and attribute mappings for Google Workspace, then test sign-in with ordinary user accounts.
- Keep super administrator sign-in on a separate, documented path and verify it without using those accounts for routine testing.
How we hand over
- Deliver runbooks covering the SAML configuration, certificate handling, login test steps and the recovery path for super administrators.
- Document the authentik version in use, the upgrade approach and the checks to run after each release.
- Walk your identity and Workspace administrators through sign-in, failure scenarios and the open items that remain.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Ask for a written quote that names each deliverable, who operates each component and what your team must provide.
