medusa-auth-zitadel
v1.0.0
Published
Zitadel (OIDC) authentication provider for Medusa v2
Maintainers
Readme
medusa-auth-zitadel
Zitadel authentication provider for Medusa v2.
A standalone Auth Module Provider that lets customers, admin users, or custom actor types log in with Zitadel using the OpenID Connect Authorization Code flow.
Zitadel endpoints are resolved through
OIDC Discovery ({issuer}/.well-known/openid-configuration),
so the provider works with Zitadel Cloud and self-hosted instances behind a custom domain. The returned
id_token is verified cryptographically against Zitadel's JWKS.
Requirements
- Medusa v2 (
@medusajs/framework^2.x) - Node.js 20+
- A running Zitadel instance (Cloud or self-hosted)
Installation
npm install medusa-auth-zitadelZitadel setup
- In your Zitadel instance, create (or open) a Project.
- Add a new application:
- Type: Web
- Authentication method: Code — this uses
client_secret_basic, matching the provider's default.
- Set the Redirect URI to exactly the
callbackUrlyou will configure below (e.g.https://your-storefront.com/auth/zitadel/callback). It must match character for character — Zitadel rejects any mismatch during the token exchange. - Copy the generated Client ID and Client Secret.
Configuration
Register the provider in the Auth Module's providers array in medusa-config.ts:
import { defineConfig, Modules } from "@medusajs/framework/utils"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/auth",
options: {
providers: [
// Keep emailpass if you still need email/password login:
// passing `providers` replaces the default list.
{ resolve: "@medusajs/medusa/auth-emailpass", id: "emailpass" },
{
resolve: "medusa-auth-zitadel",
id: "zitadel",
options: {
issuer: process.env.ZITADEL_ISSUER,
clientId: process.env.ZITADEL_CLIENT_ID,
clientSecret: process.env.ZITADEL_CLIENT_SECRET,
callbackUrl: process.env.ZITADEL_CALLBACK_URL,
},
},
],
},
},
],
})The id (zitadel) is the value used in authentication route paths.
Options
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| issuer | string | Yes | — | Zitadel issuer URL, e.g. https://myinstance.zitadel.cloud. Trailing slashes are normalised. |
| clientId | string | Yes | — | OIDC client ID of the Zitadel application. |
| clientSecret | string | Yes | — | OIDC client secret of the Zitadel application. |
| callbackUrl | string | Yes | — | URL Zitadel redirects to after authentication. Can be overridden per request with a callback_url body parameter. |
| scope | string | No | openid profile email | Scopes requested from Zitadel. |
| clientAuthMethod | "client_secret_basic" \| "client_secret_post" | No | client_secret_basic | How the client authenticates at the token endpoint. Must match the Zitadel application's authentication method. |
Environment variables
| Variable | Maps to |
|---|---|
| ZITADEL_ISSUER | issuer |
| ZITADEL_CLIENT_ID | clientId |
| ZITADEL_CLIENT_SECRET | clientSecret |
| ZITADEL_CALLBACK_URL | callbackUrl |
Actor types
By default only the user actor type is restricted to emailpass; other actor types can authenticate with
any installed provider. To control which providers each actor type may use, set
projectConfig.http.authMethodsPerActor. Note that specifying this option overrides the default, so any
actor type you omit can no longer authenticate with any provider:
module.exports = defineConfig({
projectConfig: {
http: {
authMethodsPerActor: {
user: ["emailpass", "zitadel"],
customer: ["emailpass", "zitadel"],
},
},
},
})Authentication flow
The provider implements the standard Medusa third-party authentication flow. Replace customer with your
actor type (user, customer, or a custom actor type).
1. Start the flow. The storefront asks Medusa for the Zitadel authorize URL:
curl -X POST http://localhost:9000/auth/customer/zitadel \
-H 'Content-Type: application/json' \
--data-raw '{ "callback_url": "https://your-storefront.com/auth/zitadel/callback" }'The response contains a location property — the Zitadel authorize URL. Redirect the browser to it.
Omit callback_url to use the configured callbackUrl.
{
"location": "https://myinstance.zitadel.cloud/oauth/v2/authorize?client_id=...&redirect_uri=...&response_type=code&scope=openid+profile+email&state=..."
}2. Zitadel redirects back. After the user authenticates, Zitadel redirects the browser to your
callback_url with ?code=...&state=.... The storefront forwards both to Medusa:
curl -X POST http://localhost:9000/auth/customer/zitadel/callback \
-H 'Content-Type: application/json' \
--data-raw '{ "code": "<code>", "state": "<state>" }'3. Receive the Medusa token. On success, Medusa returns a JWT and the auth identity:
{
"token": "<medusa-jwt>",
"authIdentity": {
"id": "au_zitadel_...",
"provider_metadata": {},
"user_metadata": { "email": "[email protected]", "name": "Jane Doe" }
}
}Use token as the Authorization: Bearer <token> header for authenticated store or admin requests.
If the auth identity does not exist yet, the provider creates it on first successful login.
The provider's state value (containing the callback URL used as redirect_uri) is stored server-side via
the Auth Module and consumed on callback, which protects the flow against CSRF and session replay.
Claim mapping
Zitadel's claims are mapped into Medusa's auth identity as follows.
| Zitadel claim | Medusa field |
|---|---|
| sub | entity_id |
| email | user_metadata.email |
| email_verified | user_metadata.email_verified |
| name | user_metadata.name |
| given_name | user_metadata.given_name |
| family_name | user_metadata.family_name |
| preferred_username | user_metadata.preferred_username |
| picture | user_metadata.picture |
| locale | user_metadata.locale |
Only claims actually returned by Zitadel are stored.
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| Could not fetch Zitadel OIDC discovery document | issuer is wrong or unreachable. It must be the Zitadel base domain, e.g. https://myinstance.zitadel.cloud — not the token or authorize endpoint. |
| ... discovery document issuer "..." does not match configured issuer "..." | The issuer returned by discovery differs from your setting (Zitadel may add or omit a trailing slash, or you are using a different hostname than the one Zitadel self-reports). Use the issuer exactly as Zitadel reports it. |
| Could not exchange token with Zitadel: 400 | Usually a redirect-URI mismatch. The callbackUrl must exactly match a Redirect URI registered on the Zitadel application, including scheme, host, and path. |
| Could not exchange token with Zitadel: 401 | clientAuthMethod does not match the Zitadel application's authentication method. Zitadel Web apps default to client_secret_basic; if you configured Post, set clientAuthMethod: "client_secret_post". |
| Could not verify ... id_token | The id_token audience or issuer did not match. Confirm clientId belongs to the Zitadel application you are authenticating against. |
| Zitadel does not support registration | Expected. Zitadel SSO requires users to be provisioned in Zitadel first; there is no registration route. |
| User can authenticate in Zitadel but gets a Medusa 401 | The actor type is not allowed to use zitadel. Check projectConfig.http.authMethodsPerActor. |
Publishing
For maintainers, from the repository root:
npm login
npm publish --access publicThe prepublishOnly script runs the build automatically. After publishing, submit the package to the
Medusa Integrations directory.
License
MIT
