npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

medusa-auth-zitadel

v1.0.0

Published

Zitadel (OIDC) authentication provider for Medusa v2

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-zitadel

Zitadel setup

  1. In your Zitadel instance, create (or open) a Project.
  2. Add a new application:
    • Type: Web
    • Authentication method: Code — this uses client_secret_basic, matching the provider's default.
  3. Set the Redirect URI to exactly the callbackUrl you 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.
  4. 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 public

The prepublishOnly script runs the build automatically. After publishing, submit the package to the Medusa Integrations directory.

License

MIT

medusa-auth-zitadel