Partner sign-in handoff

Send people to NBL+ with your redirect_uri (and client_id when required). After they sign in, NBL+ redirects them back to you and appends a short-lived signed JWT that your backend should verify (typically using the public keys at /.well-known/jwks.json).

Operator setup

NBL+ must register your integration before handoff works. The operator adds a client entry (for example in config/auth-oauth-clients.json) and points the deployment at it with AUTH_OAUTH_CLIENTS_PATH or inline AUTH_OAUTH_CLIENTS_JSON. Each client has a client_id, a list of allowed redirectUris, and optionally allowedDomains (any https callback on that host or its subdomains, e.g. nbl.com.au). Only registered targets are accepted.

End-to-end flow

  1. Agree with the NBL+ operator on your HTTPS redirect_uri (listed under redirectUris or on an allowedDomains host). Use client_id for other callbacks (e.g. third-party ticketing).
  2. From your site, send the user to NBL+, for example (NBL property on an allowed domain): https://<nbl-plus-host>/auth?redirect_uri=https%3A%2F%2Fwww.nbl1.com.au%2Fsso%2Fcallback&action=sign-in.
  3. If they are not signed in yet, they complete sign-in (or sign-up) on NBL+. The portal keeps redirect_uri, optional client_id, and optional state across those steps.
  4. Once signed in, NBL+ redirects the browser to your redirect_uri and adds a jwt query parameter (and state if you sent one), merging with any query you already had on the callback URL.
  5. Your server reads jwt, verifies the signature and claims, then establishes the session on your side. Do not trust the token in the browser alone without server-side verification.

Who signs the token?

NBL+ issues and signs the handoff JWT. Your service verifies it—your integration does not mint this token.

Verify the JWT with JWKS

  1. Fetch GET https://<nbl-plus-host>/.well-known/jwks.json. If that document is not available, check with the operator how verification is expected to work for that environment.
  2. Use the JWS header kid to pick the matching key in the JWKS. This deployment publishes rosetta-sso-1 for its usual signing key.
  3. Validate standard claims: issmust be NBL+'s public site origin for that environment; aud must be your callback URL's hostname only, lowercased (for example yoursite.example), not the full URL; enforce exp (lifetime is on the order of minutes).
  4. The payload normally includes sub (user id), email, name, and a provider marker. A Firebase ID token may appear under firebase_user.jwt for backends that need to validate identity with Firebase as well.

← Documentation overview