SSO with Google Workspace

ENTERPRISE

Firezone integrates with Google Workspace using a custom connector that supports both authentication and directory sync. Use this guide if you're looking to setup SSO with Google Workspace for your Firezone Enterprise account and want to automatically sync users, groups, and organizational units from Google Workspace to Firezone.

If you're just looking to authenticate users against Google Workspace without automatic directory sync, use our universal OIDC connector instead, available on all plans.

Overview

The Firezone Google Workspace connector integrates with Google's identity APIs to support user authentication and directory sync.

Users, groups, and organizational units are synced every few minutes to ensure that your Firezone account remains up-to-date with the latest identity data from Google Workspace. Read more about how sync works.

Setup

Setting up the Google Workspace connector is similar to the process of setting up a universal OIDC connector. The main difference is the addition of a few extra read-only scopes needed to enable sync.

Follow the steps below to setup the Google Workspace connector.

Step 1: Create a new project in Google Cloud

You may skip this step and proceed directly to Step 2 if you already have a GCP project you'd like to use with Firezone.

Go here to create a new project in your Google Cloud account and fill in the following fields:

  • Project name: Firezone Connector
  • Organization: Select the appropriate organization that contains the users and groups you wish to integrate with Firezone.
  • Location: Select the appropriate organization to place this project under.

Click CREATE after you've filled in the fields above.

Create project in GCP

Step 2: Enable the Admin SDK API

Visit this link to enable the Admin SDK API for the project you just created in Step 1.

Important: Ensure the Firezone Connector project you created in Step 1 is selected before clicking the "ENABLE" button.

Enable Admin SDK API

Click here to configure the OAuth consent screen for the project you created in Step 1.

Important: Select "Internal" for User type. Select "External" may allow external users to login to your Firezone account.

Enable Admin SDK API

Click CREATE.

On the next page, enter the following information:

  • App name: Firezone
  • User support email: Your or your company's IT support email address.
  • App logo (optional): Download the Firezone logo here to use for this consent screen.
  • Application home page: https://www.firezone.dev
  • Application privacy policy link: https://www.firezone.dev/privacy-policy
  • Application terms of service link: https://www.firezone.dev/terms
  • Authorized domains: Click "ADD DOMAIN" and enter firezone.dev
  • Developer contact information: Enter the same email you used above, e.g. it-support@company.com
Add app info

Click SAVE AND CONTINUE.

Step 4: Configure scopes

OAuth scopes determine what information the Firezone connector is allowed to receive when a user authenticates. Firezone requires the following scopes to authenticate users and sync users and groups with your Google Workspace account:

  • openid: Reserved scope required by all OpenID Connect integrations.
  • profile: Provides information such as the user's username, given name, surname, and so forth.
  • email: The user's email address.
  • https://www.googleapis.com/auth/admin.directory.orgunit.readonly: Required to sync Organization Units.
  • https://www.googleapis.com/auth/admin.directory.group.readonly: Required to sync Groups.
  • https://www.googleapis.com/auth/admin.directory.user.readonly: Required to sync Users.
openid
profile
email
https://www.googleapis.com/auth/admin.directory.orgunit.readonly
https://www.googleapis.com/auth/admin.directory.group.readonly
https://www.googleapis.com/auth/admin.directory.user.readonly

Click ADD OR REMOVE SCOPES and copy-paste the above scopes into the Manually add scopes field.

Update scopes

Then click UPDATE to make sure they're applied.

Update scopes Scopes continue

Ensure your Scopes configuration looks like the screenshot above, then click SAVE AND CONTINUE.

Scopes continue

Your OAuth app summary should look similar to the screenshot above.

Step 5: Create client credentials

Next, you'll need to add OAuth credentials to allow Firezone to connect to your Google Workspace account.

Head to the Credentials section and click CREATE CREDENTIALS to create new OAuth credentials. Be sure to select "OAuth client ID" in the dropdown menu.

Create OAuth credentials

On the next screen, select Web application, then use the following information for the remain fields:

  • Name: Firezone OAuth Client
  • Authorized redirect URIs: Click ADD URI, and enter the two redirect URIs shown on the Google Workspace identity provider setup screen in your Firezone admin dashboard (Settings -> Identity Providers -> Add Identity Provider -> Google Workspace -> Configure).
Web application credentials

Click CREATE.

Web application credentials

Important: Make sure to save the Client ID and Client secret fields in a safe place as they won't be shown again.

Step 6: Configure Firezone

Go back to the Firezone admin dashboard, and enter the Client ID and Client secret you copied from the previous step in the appropriate fields in "Create Identity Provider" form.

Finally, click Connect Identity Provider and click Allow when Google prompts you.

Allow admin access

If you get successfully redirected back to your Firezone admin dashboard, you're done! Your Google Workspace connector is now successfully configured. The first sync will occur within about 10 minutes. After that, users will be able to authenticate to Firezone using their Google Workspace accounts.