SSO with Google

Firezone supports authenticating users with Google using Firezone's public OAuth client. When a new provider is verified with a Google Workspace administrator, Firezone saves the verified domains and restricts sign-ins to those domains. Verification with a personal Google account creates a provider that accepts personal accounts only. You can configure multiple Google providers with non-overlapping Workspace domains, plus one provider without Workspace domains. A provider can also combine multiple Workspace customers into one sign-in option.

Enable Google authentication

Complete verification with a Google account. For a Workspace account, use an administrator with permission to list the customer's domains. Firezone requests read-only access to this domain list during setup. Personal accounts do not have a Workspace domain list.

To enable Google authentication:

1. Go to Settings → Authentication in your admin portal.
2. Click Add Provider and select Google.
3. Optionally name the provider — this is shown to users on the sign-in page. Use distinct names so users can identify their organization's sign-in option.
4. Select the authentication context:
   • Client Applications and Admin Portal: Users can sign in to both the Firezone client applications and admin portal using Google SSO.
   • Client Applications Only: Users can sign in to the Firezone client applications using Google SSO but not the admin portal.
   • Admin Portal Only: Users can sign in to the admin portal using Google SSO but not the Firezone client applications.
5. Portal session lifetime: (optional) Set a custom session lifetime for users signing in to the admin portal with Google SSO. Leave blank to use the default session lifetime.
6. Client session lifetime: (optional) Set a custom session lifetime for users signing in to the Firezone client applications with Google SSO. Leave blank to use the default session lifetime.
7. Click Verify Now and sign in with Google:
   • Workspace account: Sign in as an administrator and grant read-only access to your organization's domains. Review the Verified domains table. These domains will be required for sign-in when you save.
   • Personal account: Verification succeeds without a domain list, and the provider accepts personal Google accounts only.
8. If domain validation is enabled and users need to sign in from another Workspace customer, click Verify another domain and complete verification as an administrator of that customer.
9. Click Save.

Users will now see this provider as an option on the Firezone sign-in page.

How it works

Firezone uses a public OAuth client to authenticate users with Google. When a user signs in:

1. They're redirected to Google's sign-in page.
2. After authenticating with Google, they're redirected back to Firezone.
3. If the provider has saved Workspace domains, Firezone verifies that the signed ID token's hd claim matches one of them. Tokens with a missing or different hd are rejected, regardless of the user's email address. Providers without a domain list accept personal accounts only, unless they retain the existing unrestricted behavior described below.
4. Firezone matches the user using the iss and sub claims from Google. For users provisioned via directory sync, this identity already exists. For manually created users, Firezone matches by email on first sign-in and saves the Google identity for subsequent sign-ins.

No Google Cloud project or OAuth client setup is required on your end.

Data accessed

Firezone requests the following scopes from Google:

• openid — Required for authentication
• email — Used to match users on first sign-in
• profile — Used for the user's display name
• https://www.googleapis.com/auth/admin.directory.domain.readonly — Requested during provider verification to read the Workspace customer's domains

Firezone saves the verified primary domain, secondary domains, and domain aliases on the account's Google provider. The setup access token is not retained. Normal sign-ins request only the identity scopes above. Firezone does not access your contacts or calendar.

Supported account types

Providers verified with a Workspace administrator accept accounts whose signed hd claim matches a saved domain. Personal Google accounts have no hd claim, even when they use a company email address. See Google's ID token guidance for the distinction.

A new provider verified with a personal Google account has no saved domain list and accepts only Google accounts without a signed hd claim. A personal account can use a custom email address; Firezone uses the signed claim rather than the email domain to distinguish personal and Workspace accounts.

Existing providers with domain validation off keep their unrestricted behavior, including when you edit their name or session lifetimes. They continue to accept both personal and Workspace accounts. No migration automatically enables restrictions. To enable validation on an existing provider, verify it with a Workspace administrator and save the returned domains. Personal accounts will then need a personal Google provider or another authentication method. A failed Workspace domain lookup does not fall back to unrestricted verification.

When you sign up for a new Firezone account with Google, a Workspace account creates a provider restricted to the signed token's hd domain. A personal account creates a personal-only provider. A Workspace administrator can verify additional domains later.

Manage verified domains

To add domains to an existing provider:

1. Go to Settings → Authentication and edit the Google provider.
2. Click Verify another domain. If this provider has no verified domains, click Verify Now instead.
3. Sign in as an administrator of the Workspace customer whose domains you want to add, and grant read-only access to its domain list.
4. Review the new rows in Verified domains, then click Save.

Verification appends the customer's verified primary domain, secondary domains, and domain aliases to the saved list without duplicating existing entries. Repeat verification to add domains from another Workspace customer or to include domains added since setup. All listed domains share one sign-in option.

To remove an additional domain, click the delete button next to its row, then click Save. Users whose signed hd claim matches that domain will no longer be able to sign in through this provider. The first verified domain cannot be removed, so a provider with domain validation enabled always retains at least one verified domain. Verifying with a personal account does not clear an existing domain restriction.

Each Workspace domain can belong to only one Google provider within a Firezone account, including disabled providers. Domains can be reused in other Firezone accounts. At most one provider per account can have no Workspace domains; an existing unrestricted provider occupies that same slot.

The REST API and MCP return workspace_domains as an array of domain strings. An empty array indicates that no Workspace domains are saved. This applies to both new personal-only providers and existing unrestricted providers. Add domains through the portal's verification flow.

Provisioning users

Users must exist in Firezone before they can sign in with Google. You can:

• Create users manually in the admin portal or via the REST API
• Enable Google directory sync (Business and Enterprise plans) to automatically provision users and groups from Google Workspace

Troubleshooting

User not found

If a user sees a "user not found" or similar error when signing in, it means no matching user exists in Firezone. The user must be created manually or provisioned via directory sync before they can sign in.

Access blocked by Workspace admin

Google Workspace admins can restrict which third-party apps users are allowed to sign into. If a user sees "Access blocked" or "This app is blocked", the Workspace admin will need to allow Firezone in the Google Admin console under Security → API controls → App access control.

Workspace verification fails

For Workspace verification, use an administrator who can list the customer's domains and grant the requested domain read permission. A Workspace user without that permission cannot complete domain verification. A personal Google account can verify a new personal-only provider without a Workspace domain list.

User's Workspace domain is not allowed

Check Verified domains in the provider settings. The signed hd claim must match one of these domains; a matching email address alone is insufficient. Click Verify another domain and complete verification for the relevant Workspace customer to add missing domains, then save the provider.

Revoking access

Users can revoke Firezone's access to their Google account from their Google Account security settings. Revoking access does not delete the user from Firezone or end their active sessions, but they will need to re-authorize on their next sign-in.

Need help? See all support options.