Skip to main content

Getting Started with Identity Broker

Identity Broker exists to solve a critical limitation in Microsoft Entra External ID that blocks true multi-tenant SaaS authentication.

This page explains why Identity Broker is needed, what problem it solves, and how you can get started quickly.

Why Identity Broker?​

The Microsoft Limitation​

Microsoft Entra External ID currently has a hard limitation that impacts multi-tenant scenarios:

“Configuring other Microsoft Entra tenants as an external identity provider is currently not supported.
So, the microsoftonline.com domain in the issuer URI isn't accepted.”
— Microsoft Learn Documentation

What This Means​

If you are building a SaaS application that must support multiple enterprise customers, each with their own Microsoft Entra ID tenant, this limitation becomes a blocker.

You are prevented from:

  • Federating multiple Entra ID tenants as identity providers
  • Supporting customers with @microsoftonline.com issuer URIs
  • Implementing true multi-tenant B2B authentication using native Entra ID
  • Scaling onboarding without workarounds or tenant consolidation

In short, Microsoft’s native identity flow does not support SaaS-scale multi-tenancy.

How Identity Broker Solves This​

Identity Broker acts as an identity abstraction layer in front of Microsoft Entra ID.

Instead of your application integrating directly with Microsoft, it integrates once with Identity Broker.

Identity Broker then:

  • Supports multiple Entra ID tenants
  • Accepts issuer URIs that Microsoft blocks natively
  • Dynamically routes authentication based on domain or configuration
  • Maintains OAuth 2.0 / OpenID Connect compliance

Your application stays clean, scalable, and enterprise-ready.

Quick Start​

This section guides you through installing Identity Broker, running it locally, configuring tenants, and integrating it with your application.

30-day trial — no license needed to start

Identity Broker begins a 30-day full-feature trial automatically on first boot. After 30 days an un-licensed instance degrades to the FREE tier (sign-in and SSO keep working — only paid features and resource limits are gated). See License & Trial to activate.

1. Download​

Download the latest release WAR. The main tag always points to the most recently published release:

curl -L -o idp-broker.war \
  "https://github.com/adroitts/identix/releases/download/main/idp-broker.war"

Browse all releases at github.com/adroitts/identix/releases. The build stamps the version into the artifact, so the console always shows exactly what you deployed (see About).

Use a supported Java runtime — Java 21 is recommended.

2. Run​

Start Identity Broker from the downloaded WAR:

java -jar idp-broker.war

By default it starts on port 8080.

3. Configure​

Open the Identity Broker Admin Console in your browser:

http://localhost:8080/admin

From the admin interface, complete the following steps:

  • Add your first Microsoft Entra ID tenant
  • Add additional Entra ID tenants, including tenants that Microsoft blocks natively
  • Map customer domains to the appropriate tenants
  • Validate authentication for each configured tenant

Identity Broker uses this configuration to dynamically route authentication requests based on domain and tenant context.

4. Integrate with Your Application​

Update your application’s authentication configuration to use Identity Broker as the identity authority.

Before (Direct Microsoft Integration):

Authority: https://login.microsoftonline.com/{tenant-id}

After (Using Identity Broker):

Authority: https://idp.yourdomain.com

No additional authentication logic changes are required. Identity Broker transparently manages tenant resolution and authentication routing.

What’s Next?​

After completing the Quick Start, you can continue with the following topics:

  • Tenant configuration and advanced routing
  • Identity provider integrations
  • Security and trust model
  • Docker and Kubernetes deployment
  • Production hardening and operational best practices

Continue through the documentation to explore these areas in detail.