# Installation

Copy as Markdown[View as Markdown](/docs/plugins/azure-schema-registry/installation.md)

***

**License:** `Dual-license`

Run the command below to install the EventCatalog Azure Schema Registry plugin.

"Don't have an EventCatalog project yet?"

If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation.md) guide.

```
npm i @eventcatalog/generator-azure-schema-registry
```

License Key

The EventCatalog Azure Schema Registry plugin requires a license key to work with EventCatalog.

You can get a trial license key from [EventCatalog Cloud](https://eventcatalog.cloud).

## Configuration[​](#configuration "Direct link to Configuration")

To use the plugin you need to configure it in your `eventcatalog.config.js` file.

Add the plugin to the `generators` array.

* Basic Example
* Advanced Example with Domains and Message Types
* Multiple Schema Registries

In this example we import schemas from an Azure Schema Registry and assign them to a service.

**Note**: Unlike Confluent, Azure Schema Registry doesn't provide an API to list all schemas, so you must explicitly define which schemas to fetch using schema groups and names.

eventcatalog.config.js

```
// ...
generators: [
  [
    '@eventcatalog/generator-azure-schema-registry',
    {
      // The URL of your Azure Schema Registry
      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
      // Define services and the schemas they use
      services: [
        {
          id: 'orders-service',
          name: 'Orders Service',
          version: '1.0.0',
          // The orders service sends the order-created event
          sends: [
            {
              id: 'order-created',
              schemaGroup: 'com.example.orders'
            },
          ],
          // The orders service receives the payment-received event
          receives: [
            {
              id: 'payment-received',
              schemaGroup: 'com.example.payments'
            },
          ],
        },
      ],
    },
  ],
];
```

In this example we document services from Azure Event Hubs, assign schemas to them as different message types (events, commands, queries), and organize them into domains.

eventcatalog.config.js

```
// ...
generators: [
  [
    '@eventcatalog/generator-azure-schema-registry',
    {
      // The URL of your Azure Schema Registry
      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
      // Define the domain for these services
      domain: {
        id: 'orders-domain',
        name: 'Orders Domain',
        version: '1.0.0',
      },
      // The services to assign schemas to
      services: [
        {
          id: 'orders-service',
          name: 'Orders Service',
          version: '1.0.0',
          sends: [
            {
              id: 'order-created',
              schemaGroup: 'com.example.orders',
              name: 'Order Created Event',
              messageType: 'event', // Specify as event
            },
            {
              id: 'create-order',
              schemaGroup: 'com.example.orders',
              name: 'Create Order Command',
              messageType: 'command', // Specify as command
            },
          ],
          receives: [
            {
              id: 'get-order',
              schemaGroup: 'com.example.orders',
              name: 'Get Order Query',
              messageType: 'query', // Specify as query
            },
            {
              id: 'payment-received',
              schemaGroup: 'com.example.payments',
              name: 'Payment Received Event',
            },
          ],
        },
        {
          id: 'inventory-service',
          name: 'Inventory Service',
          version: '1.0.0',
          sends: [
            {
              id: 'inventory-updated',
              schemaGroup: 'com.example.inventory',
              messageType: 'event',
            },
          ],
          receives: [
            {
              id: 'order-created',
              schemaGroup: 'com.example.orders',
              messageType: 'event',
            },
          ],
        },
      ],
    },
  ],
];
```

In this example we fetch schemas from multiple Azure Schema Registries by overriding the registry URL per schema.

eventcatalog.config.js

```
// ...
generators: [
  [
    '@eventcatalog/generator-azure-schema-registry',
    {
      // Default schema registry URL
      schemaRegistryUrl: 'https://primary-namespace.servicebus.windows.net',
      services: [
        {
          id: 'orders-service',
          name: 'Orders Service',
          version: '1.0.0',
          sends: [
            {
              id: 'order-created',
              schemaGroup: 'com.example.orders',
              // Uses default schemaRegistryUrl
            },
            {
              id: 'order-shipped',
              schemaGroup: 'com.example.shipping',
              // Override to fetch from a different registry
              schemaRegistryUrl: 'https://shipping-namespace.servicebus.windows.net',
            },
          ],
        },
      ],
    },
  ],
];
```

### Configure Authentication[​](#configure-authentication "Direct link to Configure Authentication")

The EventCatalog Azure Schema Registry plugin uses Azure's REST API with Bearer token authentication. You need to set the `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable with your Azure access token.

### Configure Azure Schema Registry License Key[​](#configure-azure-schema-registry-license-key "Direct link to Configure Azure Schema Registry License Key")

The EventCatalog Azure Schema Registry plugin requires a license key to work with EventCatalog.

You can get a trial license key from [EventCatalog Cloud](https://eventcatalog.cloud).

***

## Getting an Azure Access Token[​](#getting-an-azure-access-token "Direct link to Getting an Azure Access Token")

### Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before getting a token, ensure you have:

1. **Azure CLI installed** - [Install Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)

2. **Access to an Azure Event Hubs namespace** with Schema Registry enabled

3. **Appropriate permissions** - You need one of these roles on the Event Hubs namespace:

   <!-- -->

   * `Azure Event Hubs Data Owner` (full access)
   * `Azure Event Hubs Data Receiver` (read access)

### Method 1: Quick Setup for Local Development (Recommended)[​](#method-1-quick-setup-for-local-development-recommended "Direct link to Method 1: Quick Setup for Local Development (Recommended)")

This is the fastest way to get started:

**Step 1: Login to Azure**

```
az login
```

This opens your browser for authentication. After logging in, you'll see your subscriptions.

**Step 2: Set Your Subscription (if you have multiple)**

```
# List your subscriptions
az account list --output table

# Set the subscription containing your Event Hubs namespace
az account set --subscription "Your-Subscription-Name-or-ID"
```

**Step 3: Get and Export the Access Token**

```
# Get token for Azure Event Hubs and export it
export AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)

# Verify the token is set
echo $AZURE_SCHEMA_REGISTRY_TOKEN
```

**Step 4: Run the Generator**

```
# Your token is now ready - run the generator
npm run generate
```

Quick Command

You can also set the token and run the generator in one command:

```
AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv) npm run generate
```

### Method 2: Using .env File (Recommended for Projects)[​](#method-2-using-env-file-recommended-for-projects "Direct link to Method 2: Using .env File (Recommended for Projects)")

For a more permanent setup, add the token to your `.env` file:

**Step 1: Get the Token**

```
# Login first
az login

# Get the token
az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv
```

**Step 2: Add to .env File**

Create or update your `.env` file in your EventCatalog project root:

.env

```
# EventCatalog license key
EVENTCATALOG_LICENSE_KEY_AZURE_SCHEMA_REGISTRY=your-license-key

# Azure Schema Registry access token (paste the token from step 1)
AZURE_SCHEMA_REGISTRY_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOi...
```

**Step 3: Run the Generator**

```
npm run generate
```

### Method 3: CI/CD with Service Principal[​](#method-3-cicd-with-service-principal "Direct link to Method 3: CI/CD with Service Principal")

For automated pipelines, use a service principal to obtain tokens programmatically:

**Step 1: Create a Service Principal (one-time setup)**

```
# Create service principal
az ad sp create-for-rbac --name "eventcatalog-generator" --role "Azure Event Hubs Data Receiver" \
  --scopes /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventHub/namespaces/{namespace-name}
```

This outputs credentials like:

```
{
  "appId": "12345678-1234-1234-1234-123456789012",
  "password": "your-secret",
  "tenant": "your-tenant-id"
}
```

**Step 2: Set Environment Variables in CI/CD**

Add these secrets to your CI/CD environment:

```
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-app-id
AZURE_CLIENT_SECRET=your-password
```

**Step 3: Get Token in CI/CD Pipeline**

```
# Login with service principal and get token
export AZURE_SCHEMA_REGISTRY_TOKEN=$(az login --service-principal \
  --username $AZURE_CLIENT_ID \
  --password $AZURE_CLIENT_SECRET \
  --tenant $AZURE_TENANT_ID \
  --output none && \
  az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)

# Run the generator
npm run generate
```

### Verify Your Permissions[​](#verify-your-permissions "Direct link to Verify Your Permissions")

To check if you have the right permissions:

```
# Check your current user
az account show --query user.name

# List role assignments for your Event Hubs namespace
az role assignment list \
  --scope /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventHub/namespaces/{namespace-name} \
  --query "[?principalName=='your-email@domain.com'].{Role:roleDefinitionName}" \
  --output table
```

You should see one of these roles:

* `Azure Event Hubs Data Owner`
* `Azure Event Hubs Data Receiver`

### If You Don't Have Permission[​](#if-you-dont-have-permission "Direct link to If You Don't Have Permission")

Ask your Azure administrator to grant you access:

```
az role assignment create \
  --role "Azure Event Hubs Data Receiver" \
  --assignee "your-email@domain.com" \
  --scope /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventHub/namespaces/{namespace-name}
```

## White listing EventCatalog Domains[​](#white-listing-eventcatalog-domains "Direct link to White listing EventCatalog Domains")

If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.

### Run the plugin[​](#run-the-plugin "Direct link to Run the plugin")

Run the plugin to import your schemas into EventCatalog.

*This command will run the generators in your eventcatalog.config.js file.*

```
npm run generate
```

### View your catalog[​](#view-your-catalog "Direct link to View your catalog")

Run your catalog locally to see the changes

```
npm run dev
```

### Build your catalog for production[​](#build-your-catalog-for-production "Direct link to Build your catalog for production")

```
npm run build
```

## Any questions or need help?[​](#any-questions-or-need-help "Direct link to Any questions or need help?")

If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).

You can also find some examples of the plugin in action in our examples repository: [eventcatalog/examples](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry).