Identity Broker

Run one Convex-hosted OpenID Provider that handles Google and GitHub OAuth for all your apps and preview deployments without per-app OAuth registrations.

Installation

npm install @samebase/identity-broker

Benefits

Use cases

how to share OAuth sign-in across multiple Convex apps without registering OAuth apps each time

The @samebase/identity-broker component lets you mount a single OpenID Provider on one Convex deployment. Each downstream app registers itself as a client at deploy time via registerClient, then points its auth flow at the hub's /authorize and /token endpoints. No per-app GitHub or Google OAuth app registration is needed.

how to add OAuth sign-in to Convex preview deployments

Preview deployments cannot register OAuth callback URLs with upstream providers in an automated way. With @samebase/identity-broker, each preview deployment registers itself as a client on the central hub at deploy time, and the hub holds the single upstream OAuth registration. The preview gets a clientId and clientSecret from the hub and never touches Google or GitHub directly.

how to set up an OpenID Connect provider on Convex

Install @samebase/identity-broker, mount the component in convex.config.ts, and call defineIdentityBroker in convex/http.ts with your issuer URL, signing keys, and connectors such as github() or google(). The broker exposes discovery, JWKS, userinfo, and authorization code flow with PKCE S256 endpoints automatically via broker.addHttpRoutes(http).

how to rotate signing keys for a Convex auth component

The @samebase/identity-broker package ships an npx identity-broker keys CLI command that prints the initial key set for the IDENTITY_BROKER_KEYS environment variable. Running keys --rotate advances the key set with overlap so existing tokens remain valid, and keys --rotate --no-overlap replaces a compromised key immediately. The key set's salt also derives every pairwise subject, so it must be backed up.

Frequently asked questions

Does the identity-broker store user accounts or sessions?

No. The @samebase/identity-broker component keeps no user accounts and no sessions on the hub. Every sign-in proxies through to the upstream provider, and each downstream app creates its own user record from the id_token it receives. The hub is stateless with respect to end users.

Which OAuth and OpenID Connect providers does identity-broker support?

The @samebase/identity-broker package ships built-in connectors for GitHub (github()) and Google (google()). Any OAuth 2.0 provider that publishes RFC 8414 metadata and any OpenID Connect provider can also be configured as a connector, making it provider-agnostic beyond the two included helpers.

How does an app register its deployments with the identity-broker hub?

Each deployment calls the internal registerClient function on the hub using npx convex run or the Convex.HubClient Alchemy v2 resource at deploy time. The registration call returns the issuer, clientId, and clientSecret. The first client for an appId automatically creates the app as a first-party app. When a deployment is removed, deleteClient cleans up its registration.

How does identity-broker integrate with Convex Auth?

A Convex Auth v2 app can point its generic OAuth method at the hub's /authorize and /token endpoints using the issuer, clientId, and clientSecret returned by registerClient. The hub issues RS256 id_tokens with pairwise subjects, and first-party apps additionally receive a connector_account_id claim identifying the upstream account.

What standards does the identity-broker component implement?

The @samebase/identity-broker component implements OAuth 2.0, the OAuth 2.1 draft (authorization code flow, PKCE S256, exact redirect URIs, iss on responses), OpenID Connect Core and Discovery, RFC 8414, RFC 9207, RFC 9700, and the JWT, JWS, and JWK standards. Departures from these standards are documented in the package's docs/design.md file.

Links

Convex
Components

Open-source building blocks for your Convex app

Browse components in this category.

All All

Loading components