Skip to content
IntelliAuth

Sign in with Google

A user clicks "Sign in with Google" in your app. They sign into Google. They come back to your app, already signed in. From your code's perspective, the user is signed in to IntelliAuth — there is no special "Google user" path in your code, just a user record whose primary identity provider is Google.

This is identity federation. IntelliAuth speaks OIDC to Google on your behalf, then issues its own tokens to your application. Your app only needs to know how to sign in with IntelliAuth.

Before you start

Section titled “Before you start”

You need:

  • A Google Cloud project. Free tier is fine.
  • An OAuth consent screen configured in that project.
  • An OAuth 2.0 client ID and client secret for a "Web application".

If you do not yet have a Google Cloud project, create one at console.cloud.google.com. The configuration shape below assumes the consent screen has been published (or you are testing with the consent screen in "Testing" mode and your test users are on the allowlist).

Step 1 — register the redirect URI in Google

Section titled “Step 1 — register the redirect URI in Google”

In the Google Cloud Console:

  1. Open APIs & Services → Credentials.
  2. Edit your OAuth 2.0 client.
  3. Add the IntelliAuth callback as an "Authorised redirect URI":
https://<your-tenant-url>/auth/callback/google

Use the tenant URL the user-facing IntelliAuth tenant runs on — e.g., https://banking-cymmetri.intelliauth.local/auth/callback/google. Google will refuse the sign-in if this URI does not match exactly, character for character.

Step 2 — add the connection in IntelliAuth

Section titled “Step 2 — add the connection in IntelliAuth”

In the tenant admin console:

  1. Navigate to Authentication → Social providers.
  2. Choose Google.
  3. Paste your Google client ID and client secret.
  4. Save.

The connection is live immediately. Test it with the "Try sign-in" button — IntelliAuth opens a popup, sends you to Google, and reports back when the round trip works.

Step 3 — surface the button in your app

Section titled “Step 3 — surface the button in your app”

If you use @intelliauth/react-sdk, the simplest path is to call:

const { loginWithRedirect } = useIntelliAuth()


<button onClick={() => loginWithRedirect({ connection: 'google' })}>
  Sign in with Google
</button>

The connection parameter tells IntelliAuth which provider to send the user to. If your tenant has only one social provider configured, you can omit connection and surface a single "Sign in" button; IntelliAuth will route through Google automatically.

For non-SDK flows, append connection=google to the /oauth2/authorize URL.

What ends up in the user record

Section titled “What ends up in the user record”

When a user signs in with Google for the first time:

  • A user record is created (or matched, if a user with the same email already exists — see "Account linking" below).
  • The Google identity is attached: provider google, subject <google-user-id>, email <the-user's-google-email>.
  • The user's name, picture, and locale come from Google's id token.

On subsequent sign-ins the user record is matched by the Google subject, not by email. This matters: if a Google user later changes their email, IntelliAuth still recognises them — the subject is stable.

Account linking

Section titled “Account linking”

Two flavours, controlled by tenant policy:

  • Strict: a user who signs in with Google gets a user record whose only identity is Google. If the same person later signs in with email/password, that creates a separate user record.
  • Email-matched (default): if the Google identity's email matches an existing user, the Google identity is attached to that user. The user can sign in either way after that.

Email-matched is the friendlier default but assumes the email field can be trusted. Google verifies emails on its end, so trusting them here is reasonable. For other providers (GitHub, for example), the email is not guaranteed to be verified, and strict linking is safer.

Scopes you can ask Google for

Section titled “Scopes you can ask Google for”

By default, IntelliAuth asks Google for openid email profile. You can ask for more by configuring the connection's "Additional scopes" field — https://www.googleapis.com/auth/calendar.readonly to read the user's calendar, for example. Be cautious: Google's consent screen tells the user exactly what they are agreeing to share, and excessive scope is a friction point.

When sign-in fails

Section titled “When sign-in fails”

The most common failure modes:

  • redirect_uri_mismatch — the URI registered in Google does not match what IntelliAuth sent. Re-check character for character; trailing slash matters.
  • Consent screen not published — Google blocks all but the listed test users. Publish the consent screen, or add the user to the test allowlist.
  • Domain restriction (G Suite / Workspace) — if your Google org has restricted who can authorise apps, an admin must approve the IntelliAuth app first.

The audit log in your tenant records every social sign-in attempt with its result; that is the first place to look when something is off.