@medusajs/auth-oidc 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +65 -0
  2. package/README.md +122 -0
  3. package/package.json +7 -3
package/AGENTS.md ADDED
@@ -0,0 +1,65 @@
1
+ # @medusajs/auth-oidc
2
+
3
+ Generic OpenID Connect Auth Module provider (since 2.19.0). Works with any spec-compliant IdP (Okta, Entra ID, Auth0, Keycloak, Google Workspace, ...) via discovery, PKCE (S256), nonce, and full ID-token validation, built on `openid-client` v5.
4
+
5
+ ## Using this package
6
+
7
+ Register one entry per identity provider; each `id` becomes the route segment (`/auth/{actor_type}/{id}`):
8
+
9
+ ```ts
10
+ module.exports = defineConfig({
11
+ modules: [
12
+ {
13
+ resolve: "@medusajs/medusa/auth",
14
+ options: {
15
+ providers: [
16
+ // overriding `providers` drops the default emailpass provider, so re-add it
17
+ {
18
+ resolve: "@medusajs/medusa/auth-emailpass",
19
+ id: "emailpass",
20
+ },
21
+ {
22
+ resolve: "@medusajs/medusa/auth-oidc",
23
+ id: "okta",
24
+ options: {
25
+ issuer: process.env.OKTA_ISSUER,
26
+ client_id: process.env.OKTA_CLIENT_ID,
27
+ client_secret: process.env.OKTA_CLIENT_SECRET,
28
+ callback_url: process.env.OKTA_CALLBACK_URL,
29
+ display_name: "Okta",
30
+ allowed_callback_urls: [process.env.OKTA_CALLBACK_URL],
31
+ allowed_email_domains: ["example.com"],
32
+ },
33
+ },
34
+ ],
35
+ },
36
+ },
37
+ ],
38
+ })
39
+ ```
40
+
41
+ - Required: `issuer`, `client_id`, `callback_url`. `client_secret` is optional (public PKCE clients).
42
+ - Optional (`OidcAuthProviderOptions` in `packages/core/types/src/auth/providers/oidc.ts`): `allowed_callback_urls`, `scopes` (default `["openid", "email", "profile"]`), `authorization_endpoint`, `token_endpoint`, `jwks_uri`, `end_session_endpoint`, `claim_mappings` (default `{ entity_id: "sub", email: "email", name: "name" }`, extra keys copy custom claims into `user_metadata`), `require_verified_email` (default `true`), `allowed_email_domains`, `clock_tolerance_seconds` (default 5), `state_ttl_seconds` (default 600), `display_name`.
43
+ - Flow: `POST /auth/{actor_type}/{id}` returns `{ location }`; the IdP redirects to `callback_url`, which calls `POST /auth/{actor_type}/{id}/callback` forwarding all query params (`code`, `state`, `iss`, ...).
44
+ - Build a custom auth provider: https://docs.medusajs.com/resources/references/auth/provider.md
45
+
46
+ ## Architecture
47
+
48
+ - `src/services/oidc.ts`: `OidcAuthService extends AbstractAuthModuleProvider`, `static identifier = "oidc"`. Implements `validateOptions`, `authenticate`, `validateCallback`; `register` throws `NOT_ALLOWED`. Overrides the `displayName` getter so each registration shows its own `display_name`.
49
+ - `src/engine/engine.ts`: `OidcEngine` (discovery, `buildAuthorizationUrl`, `exchangeCode`, `mapClaims`). Not exported from the package entry point.
50
+ - `src/utils/assert-secure-url.ts`: `issuer` and any endpoint override must be `https`; `http` is allowed only for `localhost`/`127.0.0.1`/`::1` outside production.
51
+ - `nonce` and `code_verifier` are stored in the auth state (`setState`) and replayed on callback.
52
+ - Injects an optional `cache` (`ICacheService`) to share discovery documents; without it, only the per-instance memoized client is used (discovery cache TTL 1 hour).
53
+
54
+ ## Development
55
+
56
+ - `yarn build`, `yarn test`
57
+ - `yarn test:integration`: `integration-tests/__tests__/services.spec.ts` and `engine.spec.ts`.
58
+
59
+ ## Gotchas
60
+
61
+ - Client errors are always the generic `"Authentication failed"`; the real cause is only logged server-side with the `[auth-oidc]` prefix. Check logs when debugging.
62
+ - `require_verified_email` defaults to `true`; IdPs or scope sets that don't return `email_verified: true` fail every login until it's set to `false`.
63
+ - Keep `openid` when overriding `scopes`, or no ID token is returned.
64
+ - `allowed_callback_urls` is opt-in; without it, any body `callback_url` override is accepted and only the IdP validates it.
65
+ - `entity_id` defaults to `sub` (never email). Unlike `auth-google`, `user_metadata` is refreshed from claims on every login.
package/README.md ADDED
@@ -0,0 +1,122 @@
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/auth-oidc
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ 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.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/auth-oidc` |
44
+ | Type | Module Provider (Auth Module) |
45
+ | Provider ID | `oidc` |
46
+ | Registered by default | No |
47
+ | Import from | `@medusajs/medusa/auth-oidc` |
48
+
49
+ ## Features
50
+
51
+ - Resolves endpoints from the issuer's discovery document (`{issuer}/.well-known/openid-configuration`), with optional explicit overrides.
52
+ - Supports confidential clients and public clients using PKCE only (no client secret).
53
+ - Validates ID tokens, with configurable clock tolerance.
54
+ - Maps ID token claims to the auth identity, including custom claims stored in `user_metadata`.
55
+ - Optional allowlists for callback URLs and email domains, and an optional verified-email requirement.
56
+
57
+ ## Installation
58
+
59
+ No installation needed. The provider is a dependency of `@medusajs/medusa`.
60
+
61
+ ## Usage
62
+
63
+ 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.
64
+
65
+ ```ts
66
+ import { defineConfig } from "@medusajs/framework/utils"
67
+
68
+ module.exports = defineConfig({
69
+ // ...
70
+ modules: [
71
+ {
72
+ resolve: "@medusajs/medusa/auth",
73
+ options: {
74
+ providers: [
75
+ {
76
+ resolve: "@medusajs/medusa/auth-emailpass",
77
+ id: "emailpass",
78
+ },
79
+ {
80
+ resolve: "@medusajs/medusa/auth-oidc",
81
+ id: "oidc",
82
+ options: {
83
+ issuer: process.env.OIDC_ISSUER,
84
+ client_id: process.env.OIDC_CLIENT_ID,
85
+ client_secret: process.env.OIDC_CLIENT_SECRET,
86
+ callback_url: process.env.OIDC_CALLBACK_URL,
87
+ },
88
+ },
89
+ ],
90
+ },
91
+ },
92
+ ],
93
+ })
94
+ ```
95
+
96
+ The environment variable names above are examples; the provider doesn't read any environment variables itself.
97
+
98
+ ## Configuration
99
+
100
+ | Option | Type | Description | Default |
101
+ | --- | --- | --- | --- |
102
+ | `issuer` | `string` | Required. The identity provider's issuer URL. Must be `https`, except `localhost` outside production. | - |
103
+ | `client_id` | `string` | Required. The OAuth 2 client ID. | - |
104
+ | `client_secret` | `string` | The OAuth 2 client secret. Omit it for a public client using PKCE only. | - |
105
+ | `callback_url` | `string` | Required. The default redirect URI after authentication. | - |
106
+ | `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. | - |
107
+ | `scopes` | `string[]` | Scopes to request. Always include `openid`. | `["openid", "email", "profile"]` |
108
+ | `authorization_endpoint` | `string` | Overrides the discovery document's authorization endpoint. | - |
109
+ | `token_endpoint` | `string` | Overrides the discovery document's token endpoint. | - |
110
+ | `jwks_uri` | `string` | Overrides the discovery document's JWKS URI. | - |
111
+ | `end_session_endpoint` | `string` | Overrides the discovery document's end-session endpoint. | - |
112
+ | `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" }` |
113
+ | `require_verified_email` | `boolean` | Require the `email_verified` claim to be true. | `true` |
114
+ | `allowed_email_domains` | `string[]` | Only allow users whose email domain is in this list. | - |
115
+ | `clock_tolerance_seconds` | `number` | Allowed clock skew when validating `exp`, `iat`, and `nbf`. | `5` |
116
+ | `state_ttl_seconds` | `number` | Lifetime of the single-use `state` value. | `600` |
117
+ | `display_name` | `string` | The provider's display name. | `"OpenID Connect"` |
118
+
119
+ ## Resources
120
+
121
+ - [Auth Providers](https://docs.medusajs.com/resources/commerce-modules/auth/auth-providers)
122
+ - [Auth Module](https://docs.medusajs.com/resources/commerce-modules/auth)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@medusajs/auth-oidc",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Generic OpenID Connect (OIDC) authentication provider for Medusa",
5
5
  "main": "dist/index.js",
6
6
  "repository": {
@@ -13,10 +13,14 @@
13
13
  },
14
14
  "files": [
15
15
  "dist",
16
+ "AGENTS.md",
16
17
  "!dist/**/__tests__",
17
18
  "!dist/**/__mocks__",
18
19
  "!dist/**/__fixtures__"
19
20
  ],
21
+ "llms": "https://docs.medusajs.com/llms.txt",
22
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
23
+ "mcpServer": "https://docs.medusajs.com/mcp",
20
24
  "engines": {
21
25
  "node": ">=22.22.0"
22
26
  },
@@ -32,10 +36,10 @@
32
36
  "openid-client": "^5.7.1"
33
37
  },
34
38
  "devDependencies": {
35
- "@medusajs/framework": "2.22.0-snapshot-20261020204851"
39
+ "@medusajs/framework": "2.22.0"
36
40
  },
37
41
  "peerDependencies": {
38
- "@medusajs/framework": "2.22.0-snapshot-20261020204851"
42
+ "@medusajs/framework": "2.22.0"
39
43
  },
40
44
  "keywords": [
41
45
  "medusa-provider",