A

Auth zitadel

Name: Auth zitadel
Author: Orashi

Zitadel (OIDC) authentication provider for Medusa v2

Featured on Medusa

npm install medusa-auth-zitadel

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 (), so the provider works with Zitadel Cloud and self-hosted instances behind a custom domain. The returned is verified cryptographically against Zitadel's JWKS.

Requirements

Medusa v2 ( ^2.x)
Node.js 20+
A running Zitadel instance (Cloud or self-hosted)

Installation

npm install medusa-auth-zitadel

Zitadel setup

In your Zitadel instance, create (or open) a Project.
Add a new application:
- Type: Web
- Authentication method: Code — this uses , matching the provider's default.
Set the Redirect URI to exactly the you will configure below (e.g. ). 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 array in :

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

The () is the value used in authentication route paths.

Options

Required	Default	Description
Yes	—	Zitadel issuer URL, e.g. . Trailing slashes are normalised.
Yes	—	OIDC client ID of the Zitadel application.
Yes	—	OIDC client secret of the Zitadel application.
Yes	—	URL Zitadel redirects to after authentication. Can be overridden per request with a body parameter.
No		Scopes requested from Zitadel.
No		How the client authenticates at the token endpoint. Must match the Zitadel application's authentication method.

Environment variables

Variable	Maps to

Actor types

By default only the actor type is restricted to ; other actor types can authenticate with any installed provider. To control which providers each actor type may use, set . Note that specifying this option overrides the default, so any actor type you omit can no longer authenticate with any provider:

1module.exports = defineConfig({
projectConfig: {
  http: {
    authMethodsPerActor: {
      user: ["emailpass", "zitadel"],
      customer: ["emailpass", "zitadel"],
    },
  },
},
10})

Authentication flow

The provider implements the standard Medusa third-party authentication flow. Replace with your actor type (, , or a custom actor type).

1. Start the flow. The storefront asks Medusa for the Zitadel authorize URL:

1curl -X POST http://localhost:9000/auth/customer/zitadel \
2  -H 'Content-Type: application/json' \
3  --data-raw '{ "callback_url": "https://your-storefront.com/auth/zitadel/callback" }'

The response contains a property — the Zitadel authorize URL. Redirect the browser to it. Omit to use the configured .

1{
2  "location": "https://myinstance.zitadel.cloud/oauth/v2/authorize?client_id=...&redirect_uri=...&response_type=code&scope=openid+profile+email&state=..."
3}

2. Zitadel redirects back. After the user authenticates, Zitadel redirects the browser to your with . The storefront forwards both to Medusa:

1curl -X POST http://localhost:9000/auth/customer/zitadel/callback \
2  -H 'Content-Type: application/json' \
3  --data-raw '{ "code": "<code>", "state": "<state>" }'

3. Receive the Medusa token. On success, Medusa returns a JWT and the auth identity:

1{
"token": "<medusa-jwt>",
"authIdentity": {
  "id": "au_zitadel_...",
  "provider_metadata": {},
  "user_metadata": { "email": "user@example.com", "name": "Jane Doe" }
}
8}

Use as the 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 value (containing the callback URL used as ) 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

Only claims actually returned by Zitadel are stored.

Troubleshooting

Symptom	Cause / fix
	is wrong or unreachable. It must be the Zitadel base domain, e.g. — not the token or authorize endpoint.
	The 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.
	Usually a redirect-URI mismatch. The must exactly match a Redirect URI registered on the Zitadel application, including scheme, host, and path.
	does not match the Zitadel application's authentication method. Zitadel Web apps default to ; if you configured Post, set .
	The audience or issuer did not match. Confirm belongs to the Zitadel application you are authenticating against.
	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 . Check .