Skip to Content

OpenID Connect

Use an OIDC provider that issues signed ID tokens and publishes discovery metadata. In Projects → your project → General → Authentication, add an OpenID Connect connection with:

SettingValue
Issuer URLThe issuer that appears in your ID tokens
AudiencesThe client IDs or audiences Modem should accept

A project can connect multiple OIDC issuers. The connected issuer is read-only in the editor; accepted audiences can be updated. To move to another issuer, plan the identity transition using provider lifecycle, rather than treating it as a URL rename.

Provider requirements

The issuer must serve /.well-known/openid-configuration. Its issuer must match the configured canonical issuer, and its jwks_uri must be an HTTPS URL, except supported local development URLs. Modem uses the discovered signing keys and accepts RS256 and ES256 ID tokens.

Tokens must contain exp, iat, iss and sub; the audience must match a configured accepted audience. Issued-at and optional authentication times cannot lie in the future beyond the verifier’s clock tolerance. Keep clocks synchronized rather than depending on tolerance to compensate for an incorrect device time.

Connect your app

Complete the provider’s normal sign-in flow, then supply its ID token:

const client = createCustomerClient({ environment: 'production', projectId: 'YOUR_PROJECT_ID', authentication: { type: 'identity-token-provider', getIdentityToken: async () => await yourOidcClient.getIdToken() } })

yourOidcClient.getIdToken() represents your provider library’s token retrieval method, not a Modem API. Import createCustomerClient from @preternatural-js/client-sdk. Do not substitute an OAuth access token unless it also satisfies this configured ID-token flow.

Troubleshooting

  • A token for the wrong client needs an audience configuration or sign-in correction, not a retry of the same token.
  • A discovery or JWKS outage is a temporary verification problem. Confirm that Modem can reach the provider’s metadata and keys.
  • An issuer mismatch requires correcting the connection or choosing the intended provider instance. Do not weaken verification to match tokens by email.

After identification, Modem sessions have their own persistence and renewal lifecycle.

Last updated on