npm.io
2.22.7 • Published 4d ago

@medusajs/auth-oidc

Licence
SEE LICENSE IN LICENSE
Version
2.22.7
Deps
2
Size
63 kB
Vulns
0
Weekly
0
Stars
36.4K

Medusa logo

@medusajs/auth-oidc

Documentation | Website

Building blocks for digital commerce

Medusa is released under the MIT license. PRs welcome! Discord Chat Follow @medusajs

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

Keywords