Hawcx Docs
DocumentationConsole

Quickstart

Enable Sign in with Google in the Admin Console and add the button to your app in three steps.

Turn on Sign in with Google for a project. This assumes you already have a Hawcx OIDC client integrated (OIDC integration); Social Connect adds a sign-in option to that existing flow — your token exchange and verification code do not change.

Prerequisites

A Google OAuth client (client_id + client_secret). If you don't have one yet, follow Google Cloud setup first — you'll need the redirect URI from Step 1 below to create it.

Build your hosted-login redirect URI

Every provider on a project shares the same callback route. Take your project's hosted-login host and append /oidc/callback:

https://<your-hosted-login-host>/oidc/callback

This is the URL Google redirects back to — it points at Hawcx, not at your app. You'll enter it in both places: as the Authorized redirect URI in Google (Google Cloud setup) and as the Redirect URI field in the Admin Console (Step 2).

Enable the Google provider

In the Admin Console, open your project's Settings → Social Connect tab, then choose Add provider → Google and enter:

FieldWhat to enter
Client IDThe Google OAuth client ID from Google Cloud.
Client secretThe Google OAuth client secret. Stored encrypted; never exposed to your app or the browser.
Redirect URIThe URI you built in Step 1: https://<your-hosted-login-host>/oidc/callback.
Allow email linkingWhether a verified Google email may link to an existing Hawcx user. See account linking.

Save. The provider is now configured but not yet shown to users.

Toggle it into sign-in

Flip Show on sign-in for the Google provider. This adds Continue with Google to your project's hosted sign-in screen for every OIDC client in the project.

Test users before verification

Until your Google consent screen is verified, only Google test users you list can complete the flow. Add yourself as a test user in Google Cloud, or publish and verify the app before rolling out to real users — see consent-screen verification.

Add the button

If you use the Hawcx hosted sign-in screen, you are done — Continue with Google appears automatically once toggled on.

If you render your own sign-in entry point, just start the standard authorization request; the provider choice happens on Hawcx's hosted screen:

<a href="/login">Sign in</a>
// /login — identical to any Hawcx OIDC sign-in; Google is offered on the hosted screen.
import crypto from "node:crypto";

const b64url = (b) => b.toString("base64url");

app.get("/login", (req, res) => {
  const verifier = b64url(crypto.randomBytes(32));
  const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
  const state = b64url(crypto.randomBytes(16));
  const nonce = b64url(crypto.randomBytes(16));
  store.set(state, { verifier, nonce }); // store with the session (CSRF + replay + PKCE)

  const url = new URL("https://api.hawcx.com/authorize");
  url.search = new URLSearchParams({
    response_type: "code",
    client_id: "acme-web",
    redirect_uri: "https://app.acme.com/callback",
    scope: "openid email profile",
    state,
    nonce,
    code_challenge: challenge,
    code_challenge_method: "S256",
  }).toString();
  res.redirect(url.toString());
});

To skip the picker and send the user straight to Google, add login_hint or a provider hint on the authorization request — see the reference.

Verify it works

Sign in through your app and choose Continue with Google. On the callback, decode the Hawcx ID token and confirm:

  • iss is https://api.hawcx.com (Hawcx, not accounts.google.com).
  • sub is a stable Hawcx user_id.
  • email / email_verified reflect the Google account.

If iss is Google's, something is misconfigured — your app should only ever see Hawcx tokens.

Next steps

Sign in with Google

Let users sign in with their Google account while your app only ever consumes Hawcx-issued tokens — Hawcx brokers the login and re-issues its own identity.

Google Cloud Setup

Create a Google OAuth client, register the Hawcx redirect URI and JavaScript origins, and pass consent-screen verification.