Connect Google Workspace so your team signs in to ReFresh with their Google accounts. ReFresh connects to Google over SAML 2.0.

Before you start:

Your domain is claimed and verified; see Setting up and managing SSO (Step 1: Claim and verify your domain).
You're a Google Workspace super admin.
In the ReFresh wizard, choose Google Workspace (SAML is selected for you).

In the wizard, select Google Workspace (SAML is selected for you).

1. Get your values from ReFresh

On the wizard's Add ReFresh to your IdP step, ReFresh shows the SAML service-provider values: SP Entity ID (https://auth.refresh.tech/samlv2/sp/<connection-id>), ACS URL (https://auth.refresh.tech/samlv2/acs), NameID format (email address), a Download SP Metadata XML button, and the required attributes (email, given_name, family_name, groups).

ReFresh, the "Add to IdP" SAML step for Google: SP Entity ID, ACS URL, NameID, and Download SP Metadata.

2. Create the SAML app in Google

In the Google Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app.

Google Admin: Web and mobile apps, then Add custom SAML app.

Name it "ReFresh" and continue.

Google Admin: name the custom SAML app.

On the Google IdP details page, download the IdP metadata (or copy the SSO URL, Entity ID, and certificate); you'll give this to ReFresh.

Google Admin: download the IdP metadata (SSO URL, Entity ID, certificate).

On the Service provider details page, paste the ACS URL and SP Entity ID from ReFresh and set Name ID format to EMAIL.

Google Admin, Service provider details (step 3): paste ReFresh's ACS URL and Entity ID, Name ID format = EMAIL.

3. Map attributes (and groups)

On the Attribute mapping page, map Google directory fields to the claims ReFresh needs (Primary email → email, First name → given_name, Last name → family_name). To assign roles from Google groups, also add a Group membership mapping so the app sends a groups attribute.

Google Admin: map email/first/last name, and add a Group membership → Groups mapping.

Match the group attribute name on both sides: Google sends the group attribute under the name you set here (the demo uses Groups). ReFresh reads groups from the claim named in its Groups Claim field (default groups), and the name match is case-sensitive. Make the two identical; either name the Google app attribute exactly what ReFresh expects, or set ReFresh's Groups Claim to match (e.g. Groups). A mismatch silently drops every group → role mapping.

If you don't already have role groups, create them in Directory → Groups (e.g. ReFresh - Admin).

Google Admin: create a group for a ReFresh role.

Then turn the app ON for the right organisational units / groups.

Google Admin: set the app's service status ON for the ReFresh groups.

4. Give ReFresh your IdP details

On the wizard's Paste IdP details step, give ReFresh Google's IdP metadata: a Metadata URL (preferred, so ReFresh can detect certificate rotations) or the Metadata XML you downloaded (must contain an EntityDescriptor; max 256 KB).

ReFresh: paste Google's SAML metadata (URL or XML).

Then set your roles (manual group mappings work best here), test, and activate per the hub.

Assign roles

Google Workspace is the trickiest provider for roles, because it has no easy per-group role attribute. Two workable paths (see Setting up and managing SSO (Roles for SSO users)):

Manual group mappings (recommended): emit the Group membership attribute (step 3) and map each Google group to a ReFresh role in ReFresh. This is the practical way to give users more than one role.
Automatic (role slugs): define a custom user-schema field holding the ReFresh slug, and map it to a roles SAML attribute. Simplest for one role per user.

If you set neither, use a default role so everyone can sign in.

Google-specific notes

Google doesn't send a groups attribute unless you add the Group membership mapping (step 3).
Multi-role via Google is the known weak spot; prefer group mappings where you can emit groups.
SAML has a larger attack surface than OIDC; this is expected for Google Workspace, which only supports SAML for custom apps.