Centeva.PrincipalProvider 2.0.0

Centeva.PrincipalProvider

Provides abstractions and implementations for user principal management in .NET applications, including support for web and background task scenarios.

Upgrading from v1? See the 2.0 Upgrade Guide.

Installation

Add the NuGet package to your project:

dotnet add package Centeva.PrincipalProvider

Or via the NuGet Package Manager in Visual Studio:

• Open the NuGet Package Manager
• Search for Centeva.PrincipalProvider
• Click Install

Usage

1. Register Services

services.AddHttpContextAccessor();
services.AddSingleton<TaskRunnerPrincipalProvider>(sp =>
    new TaskRunnerPrincipalProvider(
        authorizationKey: "your-authorization-key",
        authorizedUserName: "TaskRunnerUser",  // display name for background tasks
        email: "jobs@example.com"              // optional, see Background Tasks below
    )
);
services.AddScoped<IPrincipalProvider, WebPrincipalProvider>();

AddHttpContextAccessor() is required — WebPrincipalProvider cannot be constructed without it.

To inject the principal directly, register it as IPrincipal (the type UserPrincipal returns):

services.AddScoped(sp => sp.GetRequiredService<IPrincipalProvider>().UserPrincipal);

2. Accessing the Principal

Inject IPrincipalProvider where needed:

public class MyService(IPrincipalProvider principalProvider)
{
    public void DoSomething()
    {
        var email = principalProvider.Email;
        var principal = principalProvider.UserPrincipal;
    }
}

Claims this interface does not surface — the token's subject among them — are reachable through UserPrincipal. See ADR 0001 for why the subject is deliberately not exposed as a property.

3. Background Tasks

For background jobs, use TaskRunnerPrincipalProvider:

var provider = new TaskRunnerPrincipalProvider("your-authorization-key", "TaskRunnerUser");
var principal = provider.UserPrincipal;

Values passed to the constructor are exposed both as properties and as claims on UserPrincipal, so application code reaches the same answer either way.

They do not affect ASP.NET Core authorization policies, which evaluate HttpContext.User. A background job is not an HTTP request, so no policy runs against this principal.

API

IPrincipalProvider

Interface for principal providers.

Each claim is read under more than one name because the name is not fixed by the token:

• Email — inbound claim mapping is a host-level setting. With mapping on (the framework default) email arrives rewritten to its ClaimTypes.* URI; with it off the raw name survives. Both are accepted so the property does not depend on that setting.
• ApplicationId — azp and appid are the same claim under two token versions. Entra ID emits azp on v2.0 tokens and appid on v1.0; Keycloak emits azp. Accepting both keeps a tenant's token version out of application code.

WebPrincipalProvider

Uses IHttpContextAccessor to provide the current web user's principal and claims. Email and ApplicationId are derived from the same ClaimsPrincipal as UserPrincipal, so no extra extraction is needed in application code.

When AuthorizationKey matches the injected TaskRunnerPrincipalProvider's key, all three members switch to the task runner identity.

TaskRunnerPrincipalProvider

Provides a fixed principal for background tasks. Constructor parameters:

UserPrincipal is a ClaimsPrincipal whose identity has AuthenticationType of "TaskRunner" (the TaskRunnerPrincipalProvider.AuthenticationType constant), so application code can tell a background identity from a signed-in one. It carries ClaimTypes.Name, plus ClaimTypes.Email and azp for whichever values were supplied.

Using with Centeva.Oidc

Centeva.PrincipalProvider is designed to work alongside the Centeva.Oidc package suite, which registers the API, Dashboard and Scalar authorization policies. Both packages read the same claims under the same set of alternative names, so a request that Centeva.Oidc authorizes always resolves to a non-null principal value here.

Example wiring in Program.cs:

builder.Services.AddOidcAuth()
    .WithOptions(options =>
    {
        options.Authority = "https://auth.example.com/realms/my-realm";
        options.Audience = "my-api";
        options.ClientId = "my-client";
        options.DashboardAccessPredicate = email => email.EndsWith("@example.com");
    });

builder.Services.AddHttpContextAccessor();
builder.Services.AddSingleton<TaskRunnerPrincipalProvider>(sp =>
    new TaskRunnerPrincipalProvider("your-authorization-key", email: "jobs@example.com"));
builder.Services.AddScoped<IPrincipalProvider, WebPrincipalProvider>();

Target Frameworks

• .NET 8, 9, 10
• C# 12

License

Distributed under the MIT License.