A

Auth oidc

Name: Auth oidc
Author: Medusa

Generic OpenID Connect (OIDC) authentication provider for Medusa

Included in @medusajs/medusa, no separate install needed

@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 doesn't fit. It ships with and is registered through the path.

At a glance


Package
Type	Module Provider (Auth Module)
Provider ID
Registered by default	No
Import from

Features

Resolves endpoints from the issuer's discovery document (), 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 .
Optional allowlists for callback URLs and email domains, and an optional verified-email requirement.

Installation

No installation needed. The provider is a dependency of .

Usage

Register the provider in the Auth Module's array in . Passing replaces the default list, so keep if you still need email/password login. You can register the provider more than once with different values to connect several identity providers.

1import { defineConfig } from "@medusajs/framework/utils"
2
3module.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,
          },
        },
      ],
    },
  },
],
28})

The environment variable names above are examples; the provider doesn't read any environment variables itself.

Configuration

Option	Type	Description	Default
		Required. The identity provider's issuer URL. Must be , except outside production.	-
		Required. The OAuth 2 client ID.	-
		The OAuth 2 client secret. Omit it for a public client using PKCE only.	-
		Required. The default redirect URI after authentication.	-
		Exact-match allowlist for callback URLs passed in a request's body field. If unset, any callback URL is accepted.	-
		Scopes to request. Always include .
		Overrides the discovery document's authorization endpoint.	-
		Overrides the discovery document's token endpoint.	-
		Overrides the discovery document's JWKS URI.	-
		Overrides the discovery document's end-session endpoint.	-
		Maps auth identity fields to ID token claims. Extra keys are stored in .
		Require the claim to be true.
		Only allow users whose email domain is in this list.	-
		Allowed clock skew when validating , , and .
		Lifetime of the single-use value.
		The provider's display name.