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" |

Resources

• Auth Providers
• Auth Module