SSO with Google Workspace

Overview

Let members sign in with their Google Workspace accounts, restricted to your Workspace domain. Under the hood this is an OpenID Connect integration against Google, scoped to your organization, with the Google hd (hosted domain) claim validated against the workspace_domains you declare in the configuration — sign-ins from personal Gmail accounts or other Workspace domains are rejected.

Prerequisites:

• Owner role in the organization (sso.edit)
• Access to the Google Cloud Console for your Workspace

That's all — client ID, client secret, and your declared Workspace domain(s) are a complete, working configuration. There is no DNS step: workspace_domains is declared in the configuration, not verified. (Email-routing domain verification is a separate, optional convenience that makes the login page advertise this IdP to anyone typing an email under your domain.)

Step 1 — Create OAuth Credentials in Google Cloud Console

1. In Google Cloud Console, select (or create) a project for your Workspace.
2. Configure the OAuth consent screen: User type Internal (restricts the app to your Workspace users).
3. Create Credentials → OAuth client ID → Web application:
   • Authorized redirect URI: copy the exact value from Organization → Authentication in UptimeHunt — shown as soon as you select Google Workspace, before the configuration is first saved (form: https://auth.uptimehunt.io/accounts/oidc/{org-slug}/login/callback/).
4. Note the client ID and client secret.

The redirect URI is also available programmatically: GET /api/v1/orgs/{slug}/sso/urls?provider_type=google (requires sso.view) computes it from the organization slug alone — no saved configuration required, so automation (Terraform, Ansible, scripts) can create the Google OAuth client before the first PUT:

curl "https://app.uptimehunt.io/api/v1/orgs/acme/sso/urls?provider_type=google" \
  -H "Authorization: Bearer {access_token}"

data.urls.callback is the authorized redirect URI to register; data.urls.login is the direct member sign-in URL.

Step 2 — Configure the Organization

UI: Organization → Authentication → Google Workspace — enter the client ID and secret.

API:

curl -X PUT https://app.uptimehunt.io/api/v1/orgs/acme/sso \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "google",
    "config": {
      "client_id": "1234567890-abc.apps.googleusercontent.com",
      "client_secret": "{client_secret}",
      "workspace_domains": ["acme.com"]
    },
    "jit_provisioning": true,
    "default_role": "member",
    "enabled": true
  }'

The OAuth credentials go inside the config object (Google's issuer is built in — no server_url needed); the top-level fields are the organization-side toggles.

workspace_domains scopes the shared issuer

config.workspace_domains lists the Workspace hosted domain(s) whose accounts belong to your organization. It is required whenever jit_provisioning is on — Google's issuer (accounts.google.com) authenticates every Google account in the world, so the declared list is what scopes sign-ins to your Workspace; the API refuses (400) a JIT-enabled configuration without it. The list is declared here, in the configuration — declaring a domain you don't own admits nobody, because Google only asserts the hd claim for accounts actually in that Workspace.

Step 3 — Test

Validate the stored configuration:

curl -X POST https://app.uptimehunt.io/api/v1/orgs/acme/sso/test \
  -H "Authorization: Bearer {access_token}"

This checks Google's OIDC discovery document (the issuer is built in) — response shape and check details in Testing the Configuration.

Then sign in from a private browser window with a Workspace email: enter the email on the login page and choose the organization route.

How Domain Restriction Works

Two independent gates keep sign-ins inside your Workspace:

1. Google side: an Internal consent screen only allows accounts in your Workspace to authenticate at all.
2. UptimeHunt side: the ID token's hd claim (the account's Workspace domain) must match one of the declared workspace_domains — defense in depth even if the Google-side restriction is misconfigured. Consumer Google accounts carry no hd claim and are always rejected.

The identity anchor is the Google sub claim, scoped to your organization's configuration (identity realm). The same Google account signing in through another organization's Google Workspace integration is a separate UptimeHunt account — organizations never share identities.

Group-Based Role Mapping

Role mapping grants per-group roles from the groups an IdP asserts. With Google there is one important caveat:

Two ways to get group-based roles with Google:

1. A custom Workspace OIDC claim. If your Workspace is configured to emit a custom claim carrying group membership, set the role mapping source to that claim name and add rules as for any other OIDC provider. Advanced Google group sourcing (Admin SDK / Cloud Identity Directory lookups) is not built in yet.

2. Google Workspace SAML (recommended for groups). Configure Google as a SAML 2.0 IdP instead of OIDC and use Google's Group membership attribute mapping:

   • In the Google Admin console → Apps → Web and mobile apps → your SAML app → SAML attribute mapping → add Group membership, choosing the groups to send and an App attribute name (enter groups).
   • Google emits each group as the group's email address (e.g. engineers@acme.com), one <AttributeValue> per group — so your SAML role-mapping rule values must be the full group email addresses, and source must match the App-attribute name you chose.
   • Hard limit: 75 groups configurable per SAML app; groups beyond that are silently dropped — keep your role-granting groups within the configured set.
   • Nested (transitive) membership is included, so a parent group can grant a base role — but adding a user to a subgroup can inadvertently grant the parent's role. Roles re-sync on every login (unless skip_role_sync is set).

Troubleshooting

Related Documentation

• SSO Overview
• OIDC · SAML 2.0 · GitHub
• Email Routing & Auto-Join