Unchained OpenID Connect Example

December 10, 2025 ยท View on GitHub

This example demonstrates how to integrate Unchained Commerce with OpenID Connect (OIDC) providers like Zitadel and Keycloak.

Prerequisites

  • Node.js >=22
  • An OIDC provider (Zitadel Cloud or Keycloak instance)

Getting Started

  1. Install dependencies:

    npm install

  2. Configure your OIDC provider (see sections below)

  3. Run the development server:

    npm run dev

Zitadel Setup

Zitadel is a modern identity and access management platform that provides secure authentication and authorization.

Step-by-step Configuration

  1. Create a Zitadel Cloud Account

    • Visit zitadel.cloud and sign up for a free account
    • Create a new project or use the default project

  2. Create an Application

    • Navigate to your project settings
    • Click on "Applications" and create a new application
    • Choose "Web Application" as the application type
    • Select "PKCE" (Proof Key for Code Exchange) for enhanced security

  3. Configure Application Settings

    • Set your redirect URIs (e.g., http://localhost:4000/auth/callback)
    • Note down your Client ID

  4. Environment Configuration

    Create a .env file with the following variables:

    UNCHAINED_ZITADEL_CLIENT_ID=your_client_id_here
UNCHAINED_ZITADEL_DISCOVERY_URL=https://your-instance.zitadel.cloud/.well-known/openid-configuration

Resources

Keycloak Setup

Keycloak is an open-source identity and access management solution for modern applications and services.

Local Development Setup

  1. Start Keycloak

    # Using Docker
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

  2. Access Admin Console

  3. Create a Realm

    • Create a new realm (e.g., "myrealm")
    • Or use the master realm for testing

  4. Create a Client

    • Navigate to "Clients" and create a new client
    • Set Client ID to "myclient" (or your preferred name)
    • Configure appropriate redirect URIs

  5. Environment Configuration

    Add to your .env file:

    UNCHAINED_KEYCLOAK_CLIENT_ID=myclient
UNCHAINED_KEYCLOAK_REALM_URL=http://localhost:8080/realms/myrealm

Resources

Advanced: MCP Server Authorization

Our Keycloak example includes advanced support for OAuth 2.1 authentication protecting the Model Context Protocol (MCP) Server of Unchained Engine.

What is MCP?

The Model Context Protocol is a standardized way for AI models to securely access external data sources and tools.

OAuth 2.1 Protection

This example implements OAuth 2.1 authorization as specified in the MCP Authorization Specification.

Usage

Once configured, you can expose your MCP server to compatible MCP clients with proper OAuth 2.1 authentication, ensuring secure access to your Unchained Commerce data and operations.

Learn More

Support

For questions and support: