Pisum.Bff.Shared

Shared models and utilities for the Pisum Backend for Frontend (BFF) security framework.

Overview

Pisum.Bff.Shared is a lightweight library containing shared data models and utilities used across the Pisum BFF framework. This package provides common types that can be used in both server-side and client-side applications.

Features

• Lightweight Claims Model - Serializable claims representation for session storage
• Cross-platform - Targets .NET 8.0 and .NET 9.0
• No Dependencies - Zero external package dependencies for maximum compatibility

Installation

From Pisum NuGet Server

dotnet add package Pisum.Bff.Shared --source https://nuget.pisum.synology.me/v3/index.json

Or via Package Manager:

Install-Package Pisum.Bff.Shared -Source https://nuget.pisum.synology.me/v3/index.json

Configure NuGet Source

Add the Pisum NuGet server to your NuGet configuration:

dotnet nuget add source https://nuget.pisum.synology.me/v3/index.json --name Pisum

Then install normally:

dotnet add package Pisum.Bff.Shared

Components

ClaimLite

A lightweight, serializable representation of a claim.

public sealed record ClaimLite(string Type, string Value);

Usage:

var claim = new ClaimLite("email", "user@example.com");

ClaimsPrincipalLite

A lightweight, serializable representation of a claims principal.

public sealed class ClaimsPrincipalLite
{
    public string? AuthenticationType { get; init; }
    public IEnumerable<ClaimLite> Claims { get; init; } = [];
}

Usage:

var principal = new ClaimsPrincipalLite
{
    AuthenticationType = "OpenIdConnect",
    Claims = new[]
    {
        new ClaimLite("sub", "123456"),
        new ClaimLite("email", "user@example.com"),
        new ClaimLite("name", "John Doe")
    }
};

Extension Methods

ClaimsPrincipalLite Extensions:

// Convert from System.Security.Claims.ClaimsPrincipal
ClaimsPrincipal principal = ...;
ClaimsPrincipalLite lite = principal.ToClaimsPrincipalLite();

// Convert back to System.Security.Claims.ClaimsPrincipal
ClaimsPrincipal original = lite.ToClaimsPrincipal();

Use Cases

1. Session Storage

Store user claims in a serializable format for server-side session management:

public class UserSession
{
    public string SessionId { get; set; }
    public ClaimsPrincipalLite User { get; set; }
    public DateTime CreatedAt { get; set; }
}

2. Client-Server Communication

Share user identity information between BFF server and client applications:

// Server-side API endpoint
[HttpGet("/bff/user")]
public IActionResult GetUser()
{
    var user = HttpContext.User.ToClaimsPrincipalLite();
    return Ok(user);
}

// Client-side consumption
var response = await httpClient.GetFromJsonAsync<ClaimsPrincipalLite>("/bff/user");

3. Cache-Friendly Format

Store authentication state in distributed caches:

// Store in Redis or similar
var lite = principal.ToClaimsPrincipalLite();
await cache.SetAsync($"session:{sessionId}", JsonSerializer.Serialize(lite));

// Retrieve from cache
var json = await cache.GetAsync($"session:{sessionId}");
var principal = JsonSerializer.Deserialize<ClaimsPrincipalLite>(json);

Target Frameworks

• .NET 8.0
• .NET 9.0

Dependencies

None - this is a zero-dependency package.

Related Packages

• Pisum.Bff - Core BFF library with session management and OIDC
• Pisum.Bff.Yarp - YARP integration for API gateway functionality
• Pisum.Bff.Blazor.Client - Blazor WebAssembly client components

Contributing

This is part of the Pisum BFF framework. For contributions and issues, please refer to the main repository.

License

Copyright © 2025 pisum.net

Support

For questions and support, please open an issue in the main repository.