Cirreum.Authorization.Entra 1.0.25

Cirreum Authorization Entra

Azure Entra ID authorization provider for the Cirreum framework

Overview

Cirreum.Authorization.Entra is a .NET 10 authorization provider that seamlessly integrates Azure Entra ID (formerly Azure Active Directory) authentication into applications built with the Cirreum framework. It provides a unified configuration approach for both Web API (JWT Bearer) and Web App (OpenID Connect) authentication scenarios.

Features

• Dual Authentication Support: Handles both Web API (JWT Bearer tokens) and Web App (OpenID Connect) authentication flows
• Microsoft Identity Web Integration: Built on top of Microsoft's official Identity Web library for robust Azure Entra ID support
• Configuration-Driven: Uses strongly-typed configuration classes that integrate with .NET's configuration system
• Multi-Instance Support: Configure multiple authentication schemes within a single application
• Cirreum Provider Framework: Follows established patterns from the Cirreum ecosystem for consistency and reliability

When to use this vs. Cirreum.Authorization.Oidc

Entra-specific features (Graph API calls, On-Behalf-Of flows, sovereign clouds, MSAL token cache) require Microsoft.Identity.Web, which this package wraps. If you're validating tokens from an Entra tenant and need any of those features, use this package. Otherwise, prefer the lighter-weight generic OIDC provider:

You can mix providers — for example Cirreum.Authorization.Entra for a Workforce instance and Cirreum.Authorization.Oidc for a Descope instance in the same API. Each instance registers as its own ASP.NET Core authentication scheme, and Cirreum's dynamic scheme selector routes incoming tokens to the correct one based on the aud claim.

Usage

Registration

Entra authentication is automatically registered when you call AddAuthorization() with Entra configured in appsettings:

// Entra (and other providers) are registered automatically from appsettings.json
builder.AddAuthorization();

// Or with additional authentication schemes
builder.AddAuthorization(auth => auth
    .AddExternal<MyTenantResolver>()      // Add BYOID support
    .AddSignedRequest<MyResolver>()       // Add signed request support
);

Configuration

Configure Azure Entra ID settings in your appsettings.json:

{
  "Cirreum": {
    "Authorization": {
      "PrimaryScheme": "Default",
      "Providers": {
        "Entra": {
          "Instances": {
            "Default": {
              "Enabled": true,
              "Instance": "https://login.microsoftonline.com/",
              "TenantId": "your-tenant-id",
              "Audience": "api://your-client-id"
            }
          }
        }
      }
    }
  }
}

Configuration Properties

Multiple Entra Instances

You can configure multiple Entra instances for different audiences:

{
  "Cirreum": {
    "Authorization": {
      "PrimaryScheme": "WorkforceUsers",
      "Providers": {
        "Entra": {
          "Instances": {
            "WorkforceUsers": {
              "Enabled": true,
              "TenantId": "workforce-tenant-id",
              "Audience": "api://workforce-app"
            },
            "ExternalCustomers": {
              "Enabled": true,
              "TenantId": "external-tenant-id",
              "Audience": "api://customer-app"
            }
          }
        }
      }
    }
  }
}

The dynamic scheme selector routes tokens to the correct instance based on the aud claim.

Architecture

The provider follows the Cirreum authorization framework pattern with these key components:

• EntraAuthorizationRegistrar: Main registrar implementing Web API and Web App authentication setup
• EntraAuthorizationSettings: Root configuration settings
• EntraAuthorizationInstanceSettings: Per-instance configuration (extends base authorization settings)

Contribution Guidelines

1. Be conservative with new abstractions
   The API surface must remain stable and meaningful.

2. Limit dependency expansion
   Only add foundational, version-stable dependencies.

3. Favor additive, non-breaking changes
   Breaking changes ripple through the entire ecosystem.

4. Include thorough unit tests
   All primitives and patterns should be independently testable.

5. Document architectural decisions
   Context and reasoning should be clear for future maintainers.

6. Follow .NET conventions
   Use established patterns from Microsoft.Extensions.* libraries.

Versioning

Cirreum.Authorization.Entra follows Semantic Versioning:

• Major - Breaking API changes
• Minor - New features, backward compatible
• Patch - Bug fixes, backward compatible

Given its role as an authorization provider, major version bumps are rare and carefully considered.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Cirreum Foundation Framework
Layered simplicity for modern .NET