Franz.Common.Http.Identity 2.3.3

Franz.Common.Http.Identity

HTTP, identity, and service integration for the Franz.Common framework on .NET 10.

Overview

The Franz.Common.Http.Identity package provides HTTP, identity, and service integration within Franz.Common. It is designed to compose with the rest of the framework rather than imposing unrelated infrastructure choices on every application.

Installation

dotnet add package Franz.Common.Http.Identity

Design principles

• Explicit composition: register only the capabilities the application needs.
• Clear boundaries: keep domain and application contracts independent from provider-specific infrastructure where the package's role permits it.
• Predictable behavior: make configuration, failure modes, and lifecycle ownership visible rather than relying on hidden conventions.
• Operational readiness: validate security, resilience, diagnostics, and compatibility for the actual deployment environment.

Usage and configuration

Follow the package-specific setup, configuration, and code examples below. Only configure external services when this package requires them, and keep secrets outside source control.

Package-specific guide

A utility library within the Franz Framework that enhances ASP.NET Core identity management for HTTP-based applications. This package provides tools for identity context access, dependency injection, and plug-and-play SSO providers (WS-Fed, OIDC, SAML2, Keycloak).

-Current Version: v2.3.3

• Part of the private Franz Framework ecosystem.

Features

• Identity Context Access

  • IdentityContextAccessor: resolves identity consistently from HttpContext (headers & claims).
  • Unified into FranzIdentityContext (UserId, Email, FullName, Roles, TenantId, DomainId).

• Dependency Injection

  • AddFranzHttpIdentity(): registers identity accessor and supporting services.

• Authentication Providers (config-driven via appsettings.json):

  • AddFranzWsFedIdentity() – WS-Federation.
  • AddFranzOidcIdentity() – OpenID Connect.
  • AddFranzSaml2Identity() – SAML2 (via Sustainsys).
  • AddFranzKeycloakIdentity() – Keycloak (OIDC + role normalization).

• Claims Normalization

  • All providers map claims into the same FranzIdentityContext.
  • Ensures consistent user & tenant resolution across IdPs.

Installation

dotnet add package Franz.Common.Http.Identity

Usage

1. Register Core Identity

builder.Services.AddFranzHttpIdentity();

2. Add a Provider

Identity providers are registered via DI extensions and configured in appsettings.json.

🔹 WS-Federation

builder.Services.AddFranzWsFedIdentity(builder.Configuration);

appsettings.json

"FranzIdentity": {
  "WsFed": {
    "MetadataAddress": "https://login.microsoftonline.com/{tenant}/federationmetadata/2007-06/federationmetadata.xml",
    "Wtrealm": "https://myapp.example.com/"
  }
}

🔹 OpenID Connect (OIDC)

builder.Services.AddFranzOidcIdentity(builder.Configuration);

appsettings.json

"FranzIdentity": {
  "Oidc": {
    "Authority": "https://login.microsoftonline.com/{tenant}/v2.0",
    "ClientId": "my-client-id",
    "ClientSecret": "super-secret",
    "CallbackPath": "/signin-oidc"
  }
}

🔹 SAML2

builder.Services.AddFranzSaml2Identity(builder.Configuration);

appsettings.json

"FranzIdentity": {
  "Saml2": {
    "EntityId": "https://myapp.example.com/",
    "IdpMetadata": "https://idp.example.com/metadata",
    "CallbackPath": "/signin-saml"
  }
}

🔹 Keycloak (via OIDC)

builder.Services.AddFranzKeycloakIdentity(builder.Configuration);

appsettings.json

"FranzIdentity": {
  "Keycloak": {
    "Authority": "https://keycloak.example.com/auth/realms/myrealm",
    "ClientId": "franz-web",
    "ClientSecret": "super-secret",
    "CallbackPath": "/signin-keycloak"
  }
}

3. Access Identity in Your App

app.MapGet("/whoami", (IIdentityContextAccessor ctx) =>
{
    var identity = ctx.GetCurrentIdentity();
    return Results.Ok(new
    {
        identity.UserId,
        identity.Email,
        identity.FullName,
        identity.Roles,
        identity.TenantId,
        identity.DomainId
    });
});

Integration with Franz Framework

The Franz.Common.Http.Identity package integrates seamlessly with:

• Franz.Common.Identity → core identity contracts and models.
• Franz.Common.Http → HTTP utilities and middleware.
• Franz.Common.Headers → standardized header handling for identity propagation.

Contributing

This package is part of a private framework. Contributions are limited to the internal development team.

1. Clone the repository @ Franz.Common
2. Create a feature branch.
3. Submit a pull request for review.

License

Licensed under the MIT License. See the LICENSE file for details.

Changelog

Version 1.6.2

• Added IdentityContextAccessor (HttpContext-based).

• Introduced AddFranzHttpIdentity() DI extension.

• Added provider extensions:

  • WS-Federation (AddFranzWsFedIdentity).
  • OpenID Connect (AddFranzOidcIdentity).
  • SAML2 (AddFranzSaml2Identity).
  • Keycloak (AddFranzKeycloakIdentity).

• Config-driven setup via appsettings.json.

• Unified claims mapping into FranzIdentityContext.

Version 1.3

• Upgraded to .NET 9.0.8
• Added new features and improvements
• Separated business concepts from mediator concepts
• Now compatible with both the in-house mediator and MediatR

Version 1.2.65

• Upgrade version to .NET 9

Version 1.6.20

• Updated to .NET 10.0

v2.0.1 – Internal Modernization

• Messaging and infrastructure refactored for async, thread-safety, and modern .NET 10 patterns.
• All APIs remain fully backward compatible.
• Tests, listeners, and pipeline components modernized.

Dependency maintenance — October 2026

This project's dependency references were reviewed and updated as part of the repository-wide .NET 10 maintenance pass. The intended target framework and public API remain unchanged. Verify the resolved direct and transitive dependency graph through the repository's dependency validation workflow before publishing. See the central dependency upgrade record.