Table of Contents

• Roadmap
• Why UltimateAuth
• Quick Start
• Usage
• Documentation
• Upgrading & Breaking Changes
• Community & Contributing
• Acknowledgements

---

UltimateAuth is an open-source auth framework with platform-level capabilities that unifies secure session, cookie and token based Auth, modern PKCE flows, Blazor/Maui-ready client experiences - eliminating the complexity of traditional Auth systems while providing a clean, lightweight, extensible and developer-first architecture.

---

Roadmap

Phase	Version	Scope	Status	Release Date
First Preview	0.1.0-preview	"Stable" Preview Core	✅ Completed	07.04.2026
First Release*	0.1.0	Documented & Quality Tested (Client Public API Locked)	✅ Completed	12.10.2026
Product Expansion	0.2.0	Full Auth Modes, Rate Limiting	🟡 In Progress	Q4 2026
Security Expansion	0.3.0	MFA, Reauth	🟡 In Progress	Q4 2026
Infrastructure Expansion	0.4.0	Redis, Distributed Cache, Password Hasher	🔜 Planned	Q1 2027
Multi-Tenant Expansion	0.5.0	Multi tenant management	🔜 Planned	Q1 2027
Extensibility Expansion	0.6.0	Audit, events, hooks	🔜 Planned	Q1 2027
Performance Expansion	0.7.0	Benchmarks, caching	🔜 Planned	Q1 2027
Ecosystem Expansion	0.8.0	Migration tools	🔜 Planned	Q2 2027
v1.0	1.0.0	Locked API, align with .NET 11	🔜 Planned	Q2 2027

*v 0.1.0 already provides a skeleton and extensibility points of multi tenancy, MFA, reauth etc. Expansion releases will enhance these areas.

The project roadmap is actively maintained as a GitHub issue:

👉 #8

We keep it up-to-date with current priorities, planned features, and progress. Feel free to follow, comment, or contribute ideas.

---

💜 Join the UltimateAuth Community

UltimateAuth is more than a framework — it's a growing open-source community.

Join our Discord server to connect with developers, ask questions, share ideas, discuss authentication challenges, and help shape the future of UltimateAuth.

Whether you're using UltimateAuth, exploring the project, or interested in contributing, you're always welcome!

---

Why UltimateAuth

The Six-Point Principles

1) Unified Authentication System

One solution, one mental model — across Blazor Server, WASM, MAUI, and APIs. UltimateAuth eliminates fragmentation by handling client differences internally and exposing a single, consistent API.

2) Plug & Play Ready

Built-in capabilities designed for real-world scenarios:

• Automatic client profile detection (blazor server - WASM - MAUI)
• Selectable authentication modes (Session / Token / Hybrid / SemiHybrid)
• Device-aware sessions
• PKCE flows out of the box
• Unified session + token lifecycle
• Event-driven extensibility

No boilerplate. No hidden complexity.

3) Developer-Centric

Clean APIs, predictable behavior, minimal ceremony — designed to make authentication pleasant.

4) Security as a First-Class Concern

Modern security built-in by default:

• PKCE support
• Session reuse detection
• Device tracking
• Hardened auth flows
• Safe defaults

5) Extensible & Lightweight

Start simple, scale infinitely:

• Works out of the box with sensible defaults
• Replace any component when needed
• No forced architecture decisions

6) Built for Modern .NET Applications

Designed specifically for real-world .NET environments:

• Blazor Server
• Blazor WASM
• Blazor Web App
• .NET MAUI & Hybrid Apps
• Backend APIs

Traditional auth solutions struggle here — UltimateAuth embraces it.

---

Quick Start

⏱ Get started in minutes

This Quick Start uses a Blazor Server application with in-memory persistence. It is intentionally designed as the simplest path to a working UltimateAuth application.

For Entity Framework Core, Blazor WebAssembly, Blazor Web App, Resource API, persistent storage, and other real-world configurations, see the Real-World Setup guide.

UltimateAuth also provides ready-to-use login components, authentication state management, session handling, and a unified client API.

This Quick Start provides a simplified integration overview. For a complete, copy-paste-ready Blazor Server application, see the Full Quick Start Guide or GitHub Quick Start Page.

1. Install

dotnet add package CodeBeam.UltimateAuth.Client.Blazor
dotnet add package CodeBeam.UltimateAuth.InMemory.Bundle

2. Register services

builder.Services.AddUltimateAuthServer()
    .AddUltimateAuthInMemory();

builder.Services.AddUltimateAuthClientBlazor();

Usage by application type:

• Blazor Server App / UAuthHub (Auth Server) → Use both Server and Client registrations
• Blazor WASM / MAUI → Use Client only
• Resource API → Use own ResourceApi registration

3. Configure the pipeline

app.UseUltimateAuthWithAspNetCore();
app.UseAntiforgery();
app.MapUltimateAuthEndpoints();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddUltimateAuthRoutes(UAuthAssemblies.BlazorClient());

4. Add UAuthApp

UltimateAuth uses UAuthApp as the root integration point for its client authentication state and Blazor lifecycle.

Replace the default router in your App.razor or Routes.razor with:

@using CodeBeam.UltimateAuth.Client.Blazor

<UAuthApp UseBuiltInRouter="true" AppAssembly="typeof(Program).Assembly" DefaultLayout="typeof(Layout.MainLayout)">
    <ChildContent>
        @* Add application-wide UI providers or other root components here. *@
    </ChildContent>
    
    <NotAuthorized>
        <p>Not authorized.</p>
    </NotAuthorized>
</UAuthApp>

5. Add the UltimateAuth Client Script

Place this in App.razor or index.html in your Blazor client application:

<script src="_content/CodeBeam.UltimateAuth.Client.Blazor/uauth.min.js"></script>

6. Create Your Login Page

Change Components/Pages/Home.razor:

@page "/"
@page "/login"
@attribute [UAuthLoginPage]
@inherits UAuthPageBase

<div class="container mt-5" style="max-width: 400px;">
    <h3>Sign in</h3>
    <UAuthLoginForm Identifier="@_identifier" Secret="@_password" ReturnUrl="/dashboard">
        <div class="d-block mb-3">
            <label>Username</label>
            <input @bind="_identifier" class="form-control w-100" autocomplete="username" />
        </div>

        <div class="d-block mb-3">
            <label>Password</label>
            <input type="password" @bind="_password" class="form-control w-100" autocomplete="current-password" />
        </div>

        <button class="btn btn-primary w-100" type="submit">Sign in</button>
    </UAuthLoginForm>
</div>

@code {
    private string _identifier = "";
    private string _password = "";
}

7. Protect your pages

@page "/dashboard"
@attribute [UAuthAuthorize]
@inherits UAuthPageBase

<h3>Dashboard</h3>
<p>Welcome, @AuthState?.Identity?.DisplayName!</p>

The examples above provide a simplified overview of UltimateAuth integration and are not intended to be a complete, copy-paste-ready application.

For a complete, step-by-step setup with all required configuration, components, and sample data, follow the full Quick Start guide.

⚡ Complete Quick Start — Build a Working Application

---

Usage

One Client. Your Auth Application API.

For most application-level authentication and identity operations, start with IUAuthClient.

IUAuthClient provides a single entry point to UltimateAuth capabilities such as authentication flows, users, sessions, tokens, profiles, credentials, and authorization — without requiring your application code to manage the underlying authentication transport.

UltimateAuth treats authentication and identity as application services. Your application works with explicit operations and structured results while UltimateAuth handles the underlying authentication flow.

Examples

Login

[Inject] IUAuthClient UAuthClient { get; set; } = null!;

private async Task Login()
{
    var request = new LoginRequest
    {
        Identifier = "admin",
        Secret = "admin",
    };
    await UAuthClient.Flows.LoginAsync(request);
}

Register

[Inject] IUAuthClient UAuthClient { get; set; } = null!;

private async Task Register()
{
    var request = new CreateUserRequest
    {
        UserName = "NewUser",
        Password = "NewUserPassword",
        Email = "newuser@example.com",
    };

    var result = await UAuthClient.Users.CreateAsync(request);
    if (result.IsSuccess)
    {
        Console.WriteLine("User created successfully.");
    }
    else
    {
        Console.WriteLine(result.ErrorText ?? "Failed to create user.");
    }
}

LogoutAll But Keep Current Device

[Inject] IUAuthClient UAuthClient { get; set; } = null!;

private async Task LogoutOthersAsync()
{
    var result = await UAuthClient.Flows.LogoutMyOtherDevicesAsync();
    Console.WriteLine(result.IsSuccess);
}

With IUAuthClient, common application code doesn't need to manually orchestrate:

• token handling
• authentication HTTP calls
• session operations
• redirect plumbing
• client-specific authentication flows

Start with the simple API. Drop down to UltimateAuth's extensibility points when your application needs more control.

---

Documentation & Examples

UltimateAuth provides three ways to learn, explore, and experience the framework.

1) Documentation

Comprehensive guides, API references, tutorials, and architectural explanations to help you understand and integrate UltimateAuth.

📖 Explore Documentation

2) Runnable Samples

Go beyond code snippets. UltimateAuth includes multiple complete, ready-to-run sample applications covering different hosting models, authentication flows, and integration scenarios.

Clone the repository, open the solution in your IDE, and run the samples directly. No need to build a demo application from scratch.

💻 Explore Samples

3) Identity Lab — Interactive Sandbox

Experience UltimateAuth directly in your browser through a free, interactive sandbox.

Create test accounts, manage identities and sessions, explore roles and permissions, and experiment with real authentication and authorization flows.

Powered by UltimateAuth, not simulated. The demonstrated identity capabilities use the framework itself, so you can see what UltimateAuth can do before integrating it into your own application.

🧪 Identity Lab — Interactive Sandbox (Link coming soon)

---

Upgrading & Breaking Changes

UltimateAuth aims to keep upgrades straightforward. When a release introduces breaking changes, we provide concise migration guides explaining what needs to be updated.

Upgrading from an earlier version?

Check the Migration Guides for version-specific instructions.

For new features and improvements, see the GitHub Releases.

---

Community & Contributing

UltimateAuth is built by developers, for developers — and everyone is welcome to be part of its journey.

Whether you're reporting a bug, proposing an idea, improving documentation, or submitting code, your contribution matters.

You don't need to be an expert to get involved.

• 💜 Join our Discord — Connect with the community and share ideas.
• 🤝 Contributing Guide — Learn how to contribute.
• 🛡️ Security Policy — Report security vulnerabilities responsibly.
• 📜 Code of Conduct — Our community values.
• 🏛️ Governance — How project decisions are made.

Every great open-source project starts with people willing to build something together.

---

Acknowledgements

UltimateAuth is built with love by CodeBeam and shaped by real-world .NET development —
for teams who want authentication to be secure, predictable, extensible, and a joy to use.

Reimagine how .NET does authentication.
Welcome to UltimateAuth.