@medusajs/auth-oidc
Documentation | Website
Building blocks for digital commerce
OpenID Connect (OIDC) Auth Module Provider for Medusa: lets users and customers log in through any spec-compliant OIDC identity provider, such as Okta, Microsoft Entra ID, Auth0, Keycloak, or Google Workspace. Use it for single sign-on (SSO) when a dedicated provider like auth-google doesn't fit. It ships with @medusajs/medusa and is registered through the @medusajs/medusa/auth-oidc path.
At a glance
| Package | @medusajs/auth-oidc |
| Type | Module Provider (Auth Module) |
| Provider ID | oidc |
| Registered by default | No |
| Import from | @medusajs/medusa/auth-oidc |
Features
- Resolves endpoints from the issuer's discovery document (
{issuer}/.well-known/openid-configuration), with optional explicit overrides. - Supports confidential clients and public clients using PKCE only (no client secret).
- Validates ID tokens, with configurable clock tolerance.
- Maps ID token claims to the auth identity, including custom claims stored in
user_metadata. - Optional allowlists for callback URLs and email domains, and an optional verified-email requirement.
Installation
No installation needed. The provider is a dependency of @medusajs/medusa.
Usage
Register the provider in the Auth Module's providers array in medusa-config.ts. Passing providers replaces the default list, so keep emailpass if you still need email/password login. You can register the provider more than once with different id values to connect several identity providers.
import { defineConfig } from "@medusajs/framework/utils"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/auth",
options: {
providers: [
{
resolve: "@medusajs/medusa/auth-emailpass",
id: "emailpass",
},
{
resolve: "@medusajs/medusa/auth-oidc",
id: "oidc",
options: {
issuer: process.env.OIDC_ISSUER,
client_id: process.env.OIDC_CLIENT_ID,
client_secret: process.env.OIDC_CLIENT_SECRET,
callback_url: process.env.OIDC_CALLBACK_URL,
},
},
],
},
},
],
})
The environment variable names above are examples; the provider doesn't read any environment variables itself.
Configuration
| Option | Type | Description | Default |
|---|---|---|---|
issuer |
string |
Required. The identity provider's issuer URL. Must be https, except localhost outside production. |
- |
client_id |
string |
Required. The OAuth 2 client ID. | - |
client_secret |
string |
The OAuth 2 client secret. Omit it for a public client using PKCE only. | - |
callback_url |
string |
Required. The default redirect URI after authentication. | - |
allowed_callback_urls |
string[] |
Exact-match allowlist for callback URLs passed in a request's callback_url body field. If unset, any callback URL is accepted. |
- |
scopes |
string[] |
Scopes to request. Always include openid. |
["openid", "email", "profile"] |
authorization_endpoint |
string |
Overrides the discovery document's authorization endpoint. | - |
token_endpoint |
string |
Overrides the discovery document's token endpoint. | - |
jwks_uri |
string |
Overrides the discovery document's JWKS URI. | - |
end_session_endpoint |
string |
Overrides the discovery document's end-session endpoint. | - |
claim_mappings |
Record<string, string> |
Maps auth identity fields to ID token claims. Extra keys are stored in user_metadata. |
{ entity_id: "sub", email: "email", name: "name" } |
require_verified_email |
boolean |
Require the email_verified claim to be true. |
true |
allowed_email_domains |
string[] |
Only allow users whose email domain is in this list. | - |
clock_tolerance_seconds |
number |
Allowed clock skew when validating exp, iat, and nbf. |
5 |
state_ttl_seconds |
number |
Lifetime of the single-use state value. |
600 |
display_name |
string |
The provider's display name. | "OpenID Connect" |