Cirreum.Identity.Abstractions 1.0.0

Cirreum.Identity.Abstractions

IdP-agnostic contracts for user provisioning during external identity provider sign-in.

Overview

Cirreum.Identity.Abstractions defines the shared primitives used by Cirreum's identity provider integration packages. It contains no provider-specific code and has no ASP.NET dependency — just the contracts that every provider package implements against.

Consuming packages:

Installation

dotnet add package Cirreum.Identity.Abstractions

You normally don't install this package directly — it arrives as a transitive dependency when you install a provider package. Install it explicitly only if you're authoring a new provider integration.

What's in the box

All types are in the Cirreum.Identity namespace.

Multi-provider applications

A host that serves provisioning callbacks from more than one identity provider can tell them apart via ProvisionContext.Source. Each provider package publishes a well-known constant (EntraExternalIdSource.Name, DescopeSource.Name) that it uses for two things:

1. It stamps ProvisionContext.Source with that value before invoking the provisioner.
2. It registers IUserProvisioner as a keyed DI service under that same name.

An app can therefore register one provisioner per source and have the correct one resolved automatically — or register the same implementation under every key and branch on context.Source internally. Single-IdP apps can simply ignore the field.

Example

using Cirreum.Identity;

public sealed class AppUserProvisioner(AppDbContext db)
    : UserProvisionerBase<AppUser> {

    protected override Task<AppUser?> FindUserAsync(
        string externalUserId, CancellationToken ct) =>
        db.Users.FirstOrDefaultAsync(u => u.ExternalUserId == externalUserId, ct);

    protected override async Task<AppUser?> RedeemInvitationAsync(
        string email, string externalUserId, CancellationToken ct) {
        var invitation = await db.Invitations
            .FirstOrDefaultAsync(i => i.Email == email && !i.IsRedeemed, ct);
        if (invitation is null || invitation.IsExpired) return null;

        var user = new AppUser {
            ExternalUserId = externalUserId,
            Email = email,
            Roles = [invitation.Role]
        };
        db.Users.Add(user);
        invitation.IsRedeemed = true;
        await db.SaveChangesAsync(ct);
        return user;
    }
}

Then register against the provider package of your choice (see that package's README).

Contribution Guidelines

1. Be conservative with new abstractions The API surface must remain stable and meaningful across all provider packages.

2. Limit dependency expansion This package deliberately has zero runtime dependencies. Keep it that way.

3. Favor additive, non-breaking changes Breaking changes ripple through every provider integration.

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

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

Versioning

Cirreum.Identity.Abstractions follows Semantic Versioning:

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

Given its foundational role, 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