From 5fdc72f471c9d182167432e59c13aa1df30f771b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mehmet=20Can=20Karag=C3=B6z?= <78308169+mckaragoz@users.noreply.github.com> Date: Thu, 24 Sep 2026 19:35:59 +0300 Subject: [PATCH] Docs Improvement With CI (#57) * Docs Improvement With CI * Add Ecosystem Page to Docs --- .dockerignore | 24 + .github/PULL_REQUEST_TEMPLATE.md | 3 +- .github/workflows/deploy.yml | 12 +- docs/content/getting-started/ecosystem.md | 841 ++++++++++++++++++ docs/content/getting-started/quickstart.md | 5 +- .../getting-started/real-world-setup.md | 2 +- .../Pages/DocsSidebar.razor | 2 +- .../wwwroot/docs/docs-index.json | 11 +- .../docs/getting-started/ecosystem.json | 152 ++++ .../docs/getting-started/quickstart.json | 2 +- .../Program.cs | 24 +- 11 files changed, 1055 insertions(+), 23 deletions(-) create mode 100644 .dockerignore create mode 100644 docs/content/getting-started/ecosystem.md create mode 100644 docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/getting-started/ecosystem.json diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..57e342f5 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,24 @@ +# Git +.git +.gitignore + +# IDE +.vs +.vscode +.idea +**/*.user +**/*.suo + +# .NET build artifacts +**/bin +**/obj + +# Test / coverage artifacts +**/TestResults +**/coverage +**/coverage.* +**/*.trx + +# OS files +.DS_Store +Thumbs.db \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index dc07c26c..25c396c5 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -20,8 +20,9 @@ Link any related issues: ## 🛠 Changes - [ ] New feature - [ ] Bug fix +- [ ] Refactoring - Improvement - [ ] Documentation -- [ ] Refactoring +- [ ] Samples - [ ] Breaking change --- diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index ff7915fd..b2c15184 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -18,9 +18,17 @@ jobs: username: ${{ secrets.SERVER_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} script: | + set -e + cd ~/apps/UltimateAuth - git pull origin master + + git fetch origin master + git reset --hard origin/master + + echo "Deploying commit:" + git log -1 --oneline + cd .docker + docker compose down docker compose up -d --build - diff --git a/docs/content/getting-started/ecosystem.md b/docs/content/getting-started/ecosystem.md new file mode 100644 index 00000000..3e1d1aae --- /dev/null +++ b/docs/content/getting-started/ecosystem.md @@ -0,0 +1,841 @@ +--- +title: UltimateAuth Ecosystem +order: 2 +group: getting-started +--- + +# UltimateAuth Ecosystem + +UltimateAuth is designed as a modular authentication and identity platform for .NET. + +The platform has three primary foundations: + +```text + UltimateAuth + | + Core + | + +------------+------------+ + | | + Server Client + | | + Server composition Client integration + through bundles for the application +``` + +**Core** defines the common language and foundational abstractions of the platform. + +**Server** hosts and executes authentication and identity capabilities. + +**Client** provides the application-facing model used by applications to interact with those capabilities. + +An application does not necessarily need both Server and Client. Depending on its role, it may use: + +- Server only +- Client only +- Server and Client together + +This separation is intentional. UltimateAuth is designed so that application topology does not dictate a monolithic package structure. + +--- + +## Platform at a Glance + +A useful way to think about UltimateAuth is: + +```text +UltimateAuth +| ++-- Core +| ++-- Server +| | +| +-- Essential server capabilities +| | +-- Authentication +| | +-- Sessions +| | +-- Tokens +| | +-- Policies +| | +| +-- Plugin Domains +| | +-- Users +| | +-- Credentials +| | +-- Authorization +| | +| +-- Implementations +| +-- Reference +| +-- InMemory +| +-- Entity Framework Core +| ++-- Client + | + +-- Client.Blazor + +-- Client.AspNetCore compatibility + +-- Future client integrations +``` + +The important distinction is that these packages are not intended to make installation complicated. + +The internal architecture is modular, while the installation experience is deliberately composed around **server bundles** and **client-specific packages**. + +--- + +# Core + +## `CodeBeam.UltimateAuth.Core` + +Core is the foundation of the entire UltimateAuth platform. + +It contains the shared primitives, domain concepts, contracts, abstractions, value objects, configuration foundations, and common infrastructure required by the rest of UltimateAuth. + +Concepts such as UltimateAuth's identity and session model originate from this layer. + +Core is intentionally independent from a particular application type or persistence technology. + +```text + Core + | + +--------+--------+ + | | + Server Client +``` + +Server and Client share the same platform vocabulary because both are built on Core. + +Most application developers do not need to install Core directly. It is normally brought into the application through the appropriate Server bundle or Client integration package. + +--- + +# Server + +The Server side is the authority that executes UltimateAuth authentication and identity behavior. + +It is responsible for the server-side runtime, including authentication flows, security decisions, orchestration, endpoints, middleware integration, and the coordination of server capabilities. + +At source level, `CodeBeam.UltimateAuth.Server` is the central server project and depends on major server domains such as: + +```text +CodeBeam.UltimateAuth.Server +| ++-- Core ++-- Authorization ++-- Credentials ++-- Users ++-- Policies +``` + +Other essential server capabilities, including authentication, sessions, and tokens, are kept in focused projects rather than being merged into one oversized server assembly. + +This gives UltimateAuth a modular internal architecture without forcing that complexity onto application developers. + +## Do I install `CodeBeam.UltimateAuth.Server` directly? + +For normal application setup, **no**. + +The recommended server installation unit is a **Bundle**. + +A bundle represents a complete server composition for a particular infrastructure strategy. + +Instead of manually selecting all server packages and implementations, choose the bundle that matches your application. + +```text + Your Server + | + Bundle + | + +---------------+---------------+ + | | | + Server Domains Infrastructure + | | | + Runtime Reference Persistence + behavior providers +``` + +This is an important part of the UltimateAuth design: + +> The framework remains modular internally, while common server configurations remain simple to install. + +--- + +# Server Bundles + +Bundles are server-side composition packages. + +They collect the UltimateAuth server capabilities and the implementations required for a particular configuration into a single installation unit. + +You normally choose **one server bundle**. + +## Reference Bundle + +### `CodeBeam.UltimateAuth.Reference.Bundle` + +The Reference Bundle provides the recommended UltimateAuth server composition without selecting a persistence implementation for your application. + +Use it when you want UltimateAuth's reference behavior but provide your own persistence infrastructure. + +Conceptually: + +```text +Reference.Bundle +| ++-- Server ++-- UltimateAuth reference implementations ++-- Required server capabilities +| ++-- Persistence: supplied by your application +``` + +This is the lowest-level recommended server composition for applications that want to own their storage implementation. + +It is also an important extensibility point: UltimateAuth provides a recommended architecture without requiring applications to use one particular persistence technology. + +## InMemory Bundle + +### `CodeBeam.UltimateAuth.InMemory.Bundle` + +The InMemory Bundle provides a complete server setup backed by UltimateAuth's in-memory implementations. + +It is primarily intended for: + +- development +- Quick Start +- samples +- automated tests +- evaluation +- prototypes + +```text +InMemory.Bundle +| ++-- Server ++-- Reference implementations ++-- InMemory persistence implementations +``` + +This is the easiest way to start an UltimateAuth server. + +## Entity Framework Core Bundle + +### `CodeBeam.UltimateAuth.EntityFrameworkCore.Bundle` + +The Entity Framework Core Bundle provides the complete server composition using UltimateAuth's EF Core persistence implementations. + +```text +EntityFrameworkCore.Bundle +| ++-- Server ++-- Reference implementations ++-- EF Core persistence implementations +``` + +For applications that use EF Core for persistent UltimateAuth data, this is normally the server package to install. + +The developer does not need to manually assemble the individual Users, Credentials, Authorization, Sessions, Tokens, and other persistence packages. + +The bundle performs that composition. + +--- + +# Why Bundles Matter + +A highly modular framework can easily make the developer experience worse if every application has to understand and install its internal package graph. + +UltimateAuth deliberately separates **architecture modularity** from **installation complexity**. + +Internally: + +```text +Server + + Users + + Credentials + + Authorization + + Authentication + + Sessions + + Tokens + + Policies + + persistence implementations + + reference implementations +``` + +From the application: + +```bash +dotnet add package CodeBeam.UltimateAuth.EntityFrameworkCore.Bundle +``` + +This gives UltimateAuth two useful properties at the same time: + +1. individual capabilities remain independently replaceable and evolvable; +2. the common path remains simple. + +You should not need to understand the complete internal dependency graph before building your first application. + +--- + +# Client + +The Client side has a different packaging model. + +There are **no Client bundles**. + +Instead, applications install the client package designed for their application model. + +```text + Client Foundation + | + +-------------+-------------+ + | | | + Blazor MAUI Future +``` + +For example, a Blazor application installs: + +```bash +dotnet add package CodeBeam.UltimateAuth.Client.Blazor +``` + +A future MAUI integration can follow the same model without changing the underlying UltimateAuth Client architecture. + +## `CodeBeam.UltimateAuth.Client` + +`CodeBeam.UltimateAuth.Client` is the shared client foundation. + +It contains common client contracts, abstractions, flow APIs, state concepts, and runtime-independent client behavior. + +It should be thought of as the foundation on which concrete UltimateAuth client integrations are built. + +Most applications should therefore install their platform-specific client package rather than installing `CodeBeam.UltimateAuth.Client` directly. + +--- + +## `CodeBeam.UltimateAuth.Client.Blazor` + +`CodeBeam.UltimateAuth.Client.Blazor` is the concrete UltimateAuth client integration for Blazor. + +It builds on the Client foundation and adds the Blazor-specific runtime and UI integration required by Blazor applications. + +This includes capabilities such as: + +- `UAuthApp` +- `UAuthLoginForm` +- `UAuthStateView` +- authentication state integration +- Blazor authorization integration +- routing integration +- authentication flow components +- JavaScript transport integration +- client lifecycle coordination + +Conceptually: + +```text +Core + | +Client + | +Client.Blazor + | +Your Blazor Application +``` + +This model keeps the shared Client architecture independent from Blazor while still giving Blazor developers one natural package to install. + +--- + +# Client Compatibility Packages + +Not every client-side package represents a complete client implementation. + +Some packages exist to bridge UltimateAuth with a host framework. + +## `CodeBeam.UltimateAuth.Client.AspNetCore` + +`CodeBeam.UltimateAuth.Client.AspNetCore` is a lightweight ASP.NET Core compatibility layer for UltimateAuth client applications. + +It allows client-oriented applications to integrate with ASP.NET Core authentication and authorization infrastructure without introducing the full UltimateAuth Server runtime. + +This is particularly useful for hosting models such as Blazor Web App with Interactive WebAssembly. + +It can enable compatibility with ASP.NET Core features such as `[Authorize]`, but it does **not** implement authentication itself and does not turn the application into an UltimateAuth Server. + +--- + +# Application Composition + +Because Server and Client are independent platform sides, different applications can compose UltimateAuth differently. + +## Server Only + +Typical examples include: + +- dedicated authentication servers +- backend services hosting UltimateAuth +- server-side identity infrastructure + +```text +Application +| ++-- Server Bundle +``` + +## Client Only + +Typical examples include: + +- standalone Blazor WebAssembly +- future MAUI applications +- applications using a remote UAuthHub + +```text +Application +| ++-- Client.Blazor + | + +---- remote UltimateAuth Server / UAuthHub +``` + +## Server + Client + +Some applications host UltimateAuth and consume its client API in the same application. + +Blazor Server is a common example. + +```text +Blazor Server Application +| ++-- Server Bundle +| ++-- Client.Blazor +``` + +The two sides remain architecturally distinct even when deployed in the same process. + +--- + +# Plugin Domains + +UltimateAuth extends its identity platform through **Plugin Domains**. + +The current primary Plugin Domains are: + +- Users +- Credentials +- Authorization + +A Plugin Domain is more than a single assembly. It is a capability area with contracts, runtime behavior, recommended implementations, and infrastructure implementations. + +This structure allows a domain to remain replaceable without requiring applications to redesign the rest of UltimateAuth. + +## Anatomy of a Plugin Domain + +A typical Plugin Domain follows this model: + +```text +Plugin Domain +| ++-- Contracts +| ++-- Domain / Runtime +| ++-- Reference +| ++-- Persistence + | + +-- InMemory + +-- EntityFrameworkCore +``` + +Each layer has a distinct purpose. + +--- + +## Contracts + +Example: + +```text +CodeBeam.UltimateAuth.Users.Contracts +``` + +Contracts define the public boundary of the domain. Server and Client can communicate through same contracts without requiring one to depend on the other. + +They are intentionally kept close to Core and represent the smallest dependency surface for applications or extensions that only need to interact with the domain contract. + +Depending on the domain, contracts can contain concepts such as: + +- requests +- results +- public models +- abstractions +- domain-facing contracts + +This allows another implementation to integrate with UltimateAuth without depending on the entire built-in implementation. + +--- + +## Domain / Runtime + +Example: + +```text +CodeBeam.UltimateAuth.Users +``` + +The main domain project provides the runtime and application behavior of that Plugin Domain. + +It operates against abstractions rather than requiring one persistence implementation. + +--- + +## Reference Implementations + +Example: + +```text +CodeBeam.UltimateAuth.Users.Reference +``` + +Reference packages contain the implementation UltimateAuth recommends as the standard baseline for the domain. + +The distinction between **contract** and **reference implementation** is intentional. + +UltimateAuth does not leave extensibility points empty and require every developer to design critical identity behavior from scratch. + +Instead, the platform provides: + +```text +Contract + | + +---- UltimateAuth Reference Implementation + | + +---- Your Custom Implementation +``` + +For the common path, use the UltimateAuth reference implementation. + +For specialized requirements, replace the appropriate implementation while preserving the surrounding platform contract and security boundaries. + +This pattern gives advanced applications extensibility without making simple applications incomplete. + +--- + +## Persistence Implementations + +Plugin Domains can provide persistence-specific packages independently. + +For example: + +```text +Users +| ++-- Users.Contracts ++-- Users ++-- Users.Reference ++-- Users.InMemory ++-- Users.EntityFrameworkCore +``` + +The same pattern applies to other Plugin Domains where appropriate. + +A developer using a server bundle normally does not need to install these packages individually. The selected bundle composes the appropriate persistence strategy. + +Their separation exists primarily to preserve architectural modularity and replaceability. + +--- + +# Current Plugin Domains + +## Users + +The Users domain owns user lifecycle and user-management capabilities. + +Its package family includes: + +```text +CodeBeam.UltimateAuth.Users.Contracts +CodeBeam.UltimateAuth.Users +CodeBeam.UltimateAuth.Users.Reference +CodeBeam.UltimateAuth.Users.InMemory +CodeBeam.UltimateAuth.Users.EntityFrameworkCore +``` + +## Credentials + +The Credentials domain owns credential-related capabilities and credential management. + +Its package family includes: + +```text +CodeBeam.UltimateAuth.Credentials.Contracts +CodeBeam.UltimateAuth.Credentials +CodeBeam.UltimateAuth.Credentials.Reference +CodeBeam.UltimateAuth.Credentials.InMemory +CodeBeam.UltimateAuth.Credentials.EntityFrameworkCore +``` + +## Authorization + +The Authorization domain provides UltimateAuth authorization capabilities. + +Its package family includes: + +```text +CodeBeam.UltimateAuth.Authorization.Contracts +CodeBeam.UltimateAuth.Authorization +CodeBeam.UltimateAuth.Authorization.Reference +CodeBeam.UltimateAuth.Authorization.InMemory +CodeBeam.UltimateAuth.Authorization.EntityFrameworkCore +``` + +The same architectural pattern makes these capabilities independently evolvable while keeping their public boundaries explicit. + +--- + +# Essential Server Capabilities + +Authentication, Sessions, and Tokens are slightly different from Plugin Domains. + +They are fundamental parts of an UltimateAuth Server and are not treated as optional identity plugins in the same sense as Users, Credentials, or Authorization. + +However, they are still separated into focused projects. + +Conceptually: + +```text + UltimateAuth Server + | + +--------------------+--------------------+ + | | | + Authentication Sessions Tokens +``` + +Why separate them if the Server needs them? + +Because **required does not have to mean monolithic**. + +Keeping these capabilities isolated: + +- prevents the central Server project from becoming an oversized implementation assembly; +- keeps responsibilities and dependency boundaries explicit; +- allows implementations to evolve independently; +- makes persistence providers independently composable; +- keeps replacement and testing boundaries smaller. + +They can be thought of as **modular server subsystems** rather than full Plugin Domains. + +For example, persistence implementations can still exist independently: + +```text +Authentication ++-- Authentication.InMemory ++-- Authentication.EntityFrameworkCore + +Sessions ++-- Sessions.InMemory ++-- Sessions.EntityFrameworkCore + +Tokens ++-- Tokens.InMemory ++-- Tokens.EntityFrameworkCore +``` + +The selected Server bundle composes the required implementations for the application. + +--- + +# Policies and Security + +Some capabilities are deliberately isolated even though they support multiple areas of the platform. + +## Policies + +`CodeBeam.UltimateAuth.Policies` contains policy infrastructure used to keep security and application decisions explicit and extensible. + +Policies are part of the server architecture rather than application-specific transport logic. + +## Security Implementations + +Security algorithms can also live behind focused implementations. + +For example: + +```text +CodeBeam.UltimateAuth.Security.Argon2 +``` + +Keeping security implementations separate avoids coupling the entire platform to one concrete algorithm or provider. + +--- + +# Modularity Without an Incomplete Framework + +UltimateAuth's modularity has an important design goal: + +> Extensibility should not require developers to build the missing half of the framework themselves. + +Every major extensibility boundary should have a practical UltimateAuth-provided path. + +The common model is: + +```text + UltimateAuth Contract + | + +-----------+-----------+ + | | + Reference Path Custom Path + | | + Works out of the box Replace when needed +``` + +This means the platform can provide strong defaults and reference implementations while still allowing advanced applications to replace individual capabilities. + +A customization should be local to the capability being replaced rather than requiring the authentication architecture to be rewritten. + +--- + +# Replaceability by Design + +UltimateAuth is intentionally built from small architectural boundaries. + +The goal is not modularity for its own sake. + +The goal is to reduce the cost of change. + +An application may start with: + +```text +EntityFrameworkCore.Bundle +``` + +while still having clearly separated domains and infrastructure underneath. + +If a specialized application later needs a custom implementation for one capability, the architecture already has a boundary for it. + +This provides a different model from choosing between two extremes: + +```text +Simple but monolithic + OR +Flexible but difficult to configure +``` + +UltimateAuth aims for: + +```text + Simple installation + + + Modular internals + + + Reference implementations + + + Explicit contracts + = + Low-cost customization +``` + +Security-sensitive extension points still remain subject to UltimateAuth's security invariants and authority boundaries. Replaceability is intended to enable integration and specialization, not to bypass required security decisions. + +--- + +# Choosing Packages + +For most developers, package selection should be simple. + +## Blazor Server with InMemory persistence + +```bash +dotnet add package CodeBeam.UltimateAuth.InMemory.Bundle +dotnet add package CodeBeam.UltimateAuth.Client.Blazor +``` + +The application both hosts UltimateAuth and consumes the Blazor client integration. + +## Blazor Server with Entity Framework Core + +```bash +dotnet add package CodeBeam.UltimateAuth.EntityFrameworkCore.Bundle +dotnet add package CodeBeam.UltimateAuth.Client.Blazor +``` + +## Custom persistence + +Start from: + +```bash +dotnet add package CodeBeam.UltimateAuth.Reference.Bundle +``` + +and provide the required persistence implementations for your architecture. + +## Standalone Blazor WebAssembly + +Install the client integration: + +```bash +dotnet add package CodeBeam.UltimateAuth.Client.Blazor +``` + +The authentication authority lives in a remote UltimateAuth Server or UAuthHub. + +--- + +# The Rule of Thumb + +You generally do not need to assemble UltimateAuth package-by-package. + +For the **Server**: + +> Choose the Bundle that matches your infrastructure. + +For the **Client**: + +> Choose the Client package that matches your application platform. + +```text +SERVER +"What infrastructure do I use?" + | + +-- Reference.Bundle + +-- InMemory.Bundle + +-- EntityFrameworkCore.Bundle + + +CLIENT +"What kind of application am I building?" + | + +-- Client.Blazor + +-- Client.Maui (future) + +-- ... +``` + +The detailed package graph exists so that UltimateAuth remains extensible. + +The bundles and client integrations exist so that you do not have to manage that graph for ordinary applications. + +--- + +# Next + +You now have the mental model needed to understand the rest of the UltimateAuth documentation: + +```text +Core + | + +-- Server --> choose a Bundle + | + +-- Client --> choose your platform integration + +Server + | + +-- Essential server subsystems + | + +-- Plugin Domains + | + +-- Contracts + +-- Runtime + +-- Reference implementations + +-- Persistence implementations +``` + +Continue with the [Quick Start](./quickstart.md) to build your first UltimateAuth application. + +For persistent storage, UAuthHub, standalone WebAssembly, Resource API, and other deployment models, continue with the [Real-World Setup](./real-world-setup.md). diff --git a/docs/content/getting-started/quickstart.md b/docs/content/getting-started/quickstart.md index 77853bb1..ea2b7c47 100644 --- a/docs/content/getting-started/quickstart.md +++ b/docs/content/getting-started/quickstart.md @@ -1,6 +1,6 @@ --- title: QuickStart -order: 2 +order: 3 group: getting-started --- @@ -24,7 +24,6 @@ cd UltimateAuthDemo Install the required UltimateAuth packages: ```csharp -dotnet add package CodeBeam.UltimateAuth.Server dotnet add package CodeBeam.UltimateAuth.Client.Blazor dotnet add package CodeBeam.UltimateAuth.InMemory.Bundle ``` @@ -84,7 +83,7 @@ For protected pages For any page that you use UltimateAuth features like AuthState etc. ```csharp -@inherits UAuthFlowPageBase +@inherits UAuthPageBase ``` ## 9. Seed Data For QuickStart (Optional) diff --git a/docs/content/getting-started/real-world-setup.md b/docs/content/getting-started/real-world-setup.md index 27f9e35c..695b8e5a 100644 --- a/docs/content/getting-started/real-world-setup.md +++ b/docs/content/getting-started/real-world-setup.md @@ -1,6 +1,6 @@ --- title: Real World Setup -order: 3 +order: 4 group: getting-started --- diff --git a/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/Pages/DocsSidebar.razor b/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/Pages/DocsSidebar.razor index 8743c5d6..3d4e23a9 100644 --- a/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/Pages/DocsSidebar.razor +++ b/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/Pages/DocsSidebar.razor @@ -35,7 +35,7 @@ @code { private Dictionary>? _groups; - private bool _expanded = true; + private bool _expanded = false; [Parameter] public bool Inline { get; set; } diff --git a/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/docs-index.json b/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/docs-index.json index ae4a7783..1eac283f 100644 --- a/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/docs-index.json +++ b/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/docs-index.json @@ -6,17 +6,24 @@ "Group": "getting-started", "GroupOrder": 1 }, + { + "Title": "UltimateAuth Ecosystem", + "Slug": "getting-started/ecosystem", + "Order": 2, + "Group": "getting-started", + "GroupOrder": 1 + }, { "Title": "QuickStart", "Slug": "getting-started/quickstart", - "Order": 2, + "Order": 3, "Group": "getting-started", "GroupOrder": 1 }, { "Title": "Real World Setup", "Slug": "getting-started/real-world-setup", - "Order": 3, + "Order": 4, "Group": "getting-started", "GroupOrder": 1 }, diff --git a/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/getting-started/ecosystem.json b/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/getting-started/ecosystem.json new file mode 100644 index 00000000..4377a1f8 --- /dev/null +++ b/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/getting-started/ecosystem.json @@ -0,0 +1,152 @@ +{ + "Slug": "getting-started/ecosystem", + "Title": "UltimateAuth Ecosystem", + "Html": "\n\u003Cp\u003EUltimateAuth is designed as a modular authentication and identity platform for .NET.\u003C/p\u003E\n\u003Cp\u003EThe platform has three primary foundations:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003E UltimateAuth\n |\n Core\n |\n \u002B------------\u002B------------\u002B\n | |\n Server Client\n | |\n Server composition Client integration\n through bundles for the application\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003E\u003Cstrong\u003ECore\u003C/strong\u003E defines the common language and foundational abstractions of the platform.\u003C/p\u003E\n\u003Cp\u003E\u003Cstrong\u003EServer\u003C/strong\u003E hosts and executes authentication and identity capabilities.\u003C/p\u003E\n\u003Cp\u003E\u003Cstrong\u003EClient\u003C/strong\u003E provides the application-facing model used by applications to interact with those capabilities.\u003C/p\u003E\n\u003Cp\u003EAn application does not necessarily need both Server and Client. Depending on its role, it may use:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003EServer only\u003C/li\u003E\n\u003Cli\u003EClient only\u003C/li\u003E\n\u003Cli\u003EServer and Client together\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cp\u003EThis separation is intentional. UltimateAuth is designed so that application topology does not dictate a monolithic package structure.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022platform-at-a-glance\u0022\u003EPlatform at a Glance\u003C/h2\u003E\n\u003Cp\u003EA useful way to think about UltimateAuth is:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EUltimateAuth\n|\n\u002B-- Core\n|\n\u002B-- Server\n| |\n| \u002B-- Essential server capabilities\n| | \u002B-- Authentication\n| | \u002B-- Sessions\n| | \u002B-- Tokens\n| | \u002B-- Policies\n| |\n| \u002B-- Plugin Domains\n| | \u002B-- Users\n| | \u002B-- Credentials\n| | \u002B-- Authorization\n| |\n| \u002B-- Implementations\n| \u002B-- Reference\n| \u002B-- InMemory\n| \u002B-- Entity Framework Core\n|\n\u002B-- Client\n |\n \u002B-- Client.Blazor\n \u002B-- Client.AspNetCore compatibility\n \u002B-- Future client integrations\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThe important distinction is that these packages are not intended to make installation complicated.\u003C/p\u003E\n\u003Cp\u003EThe internal architecture is modular, while the installation experience is deliberately composed around \u003Cstrong\u003Eserver bundles\u003C/strong\u003E and \u003Cstrong\u003Eclient-specific packages\u003C/strong\u003E.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022core\u0022\u003ECore\u003C/h1\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022codebeam.ultimateauth.core\u0022\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.Core\u003C/code\u003E\u003C/h2\u003E\n\u003Cp\u003ECore is the foundation of the entire UltimateAuth platform.\u003C/p\u003E\n\u003Cp\u003EIt contains the shared primitives, domain concepts, contracts, abstractions, value objects, configuration foundations, and common infrastructure required by the rest of UltimateAuth.\u003C/p\u003E\n\u003Cp\u003EConcepts such as UltimateAuth\u0027s identity and session model originate from this layer.\u003C/p\u003E\n\u003Cp\u003ECore is intentionally independent from a particular application type or persistence technology.\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003E Core\n |\n \u002B--------\u002B--------\u002B\n | |\n Server Client\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EServer and Client share the same platform vocabulary because both are built on Core.\u003C/p\u003E\n\u003Cp\u003EMost application developers do not need to install Core directly. It is normally brought into the application through the appropriate Server bundle or Client integration package.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022server\u0022\u003EServer\u003C/h1\u003E\n\u003Cp\u003EThe Server side is the authority that executes UltimateAuth authentication and identity behavior.\u003C/p\u003E\n\u003Cp\u003EIt is responsible for the server-side runtime, including authentication flows, security decisions, orchestration, endpoints, middleware integration, and the coordination of server capabilities.\u003C/p\u003E\n\u003Cp\u003EAt source level, \u003Ccode\u003ECodeBeam.UltimateAuth.Server\u003C/code\u003E is the central server project and depends on major server domains such as:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECodeBeam.UltimateAuth.Server\n|\n\u002B-- Core\n\u002B-- Authorization\n\u002B-- Credentials\n\u002B-- Users\n\u002B-- Policies\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EOther essential server capabilities, including authentication, sessions, and tokens, are kept in focused projects rather than being merged into one oversized server assembly.\u003C/p\u003E\n\u003Cp\u003EThis gives UltimateAuth a modular internal architecture without forcing that complexity onto application developers.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022do-i-install-codebeam.ultimateauth.server-directly\u0022\u003EDo I install \u003Ccode\u003ECodeBeam.UltimateAuth.Server\u003C/code\u003E directly?\u003C/h2\u003E\n\u003Cp\u003EFor normal application setup, \u003Cstrong\u003Eno\u003C/strong\u003E.\u003C/p\u003E\n\u003Cp\u003EThe recommended server installation unit is a \u003Cstrong\u003EBundle\u003C/strong\u003E.\u003C/p\u003E\n\u003Cp\u003EA bundle represents a complete server composition for a particular infrastructure strategy.\u003C/p\u003E\n\u003Cp\u003EInstead of manually selecting all server packages and implementations, choose the bundle that matches your application.\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003E Your Server\n |\n Bundle\n |\n \u002B---------------\u002B---------------\u002B\n | | |\n Server Domains Infrastructure\n | | |\n Runtime Reference Persistence\n behavior providers\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThis is an important part of the UltimateAuth design:\u003C/p\u003E\n\u003Cblockquote\u003E\n\u003Cp\u003EThe framework remains modular internally, while common server configurations remain simple to install.\u003C/p\u003E\n\u003C/blockquote\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022server-bundles\u0022\u003EServer Bundles\u003C/h1\u003E\n\u003Cp\u003EBundles are server-side composition packages.\u003C/p\u003E\n\u003Cp\u003EThey collect the UltimateAuth server capabilities and the implementations required for a particular configuration into a single installation unit.\u003C/p\u003E\n\u003Cp\u003EYou normally choose \u003Cstrong\u003Eone server bundle\u003C/strong\u003E.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022reference-bundle\u0022\u003EReference Bundle\u003C/h2\u003E\n\u003Ch3 class=\u0022mud-scrollspy-section\u0022 id=\u0022codebeam.ultimateauth.reference.bundle\u0022\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.Reference.Bundle\u003C/code\u003E\u003C/h3\u003E\n\u003Cp\u003EThe Reference Bundle provides the recommended UltimateAuth server composition without selecting a persistence implementation for your application.\u003C/p\u003E\n\u003Cp\u003EUse it when you want UltimateAuth\u0027s reference behavior but provide your own persistence infrastructure.\u003C/p\u003E\n\u003Cp\u003EConceptually:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EReference.Bundle\n|\n\u002B-- Server\n\u002B-- UltimateAuth reference implementations\n\u002B-- Required server capabilities\n|\n\u002B-- Persistence: supplied by your application\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThis is the lowest-level recommended server composition for applications that want to own their storage implementation.\u003C/p\u003E\n\u003Cp\u003EIt is also an important extensibility point: UltimateAuth provides a recommended architecture without requiring applications to use one particular persistence technology.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022inmemory-bundle\u0022\u003EInMemory Bundle\u003C/h2\u003E\n\u003Ch3 class=\u0022mud-scrollspy-section\u0022 id=\u0022codebeam.ultimateauth.inmemory.bundle\u0022\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.InMemory.Bundle\u003C/code\u003E\u003C/h3\u003E\n\u003Cp\u003EThe InMemory Bundle provides a complete server setup backed by UltimateAuth\u0027s in-memory implementations.\u003C/p\u003E\n\u003Cp\u003EIt is primarily intended for:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003Edevelopment\u003C/li\u003E\n\u003Cli\u003EQuick Start\u003C/li\u003E\n\u003Cli\u003Esamples\u003C/li\u003E\n\u003Cli\u003Eautomated tests\u003C/li\u003E\n\u003Cli\u003Eevaluation\u003C/li\u003E\n\u003Cli\u003Eprototypes\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EInMemory.Bundle\n|\n\u002B-- Server\n\u002B-- Reference implementations\n\u002B-- InMemory persistence implementations\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThis is the easiest way to start an UltimateAuth server.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022entity-framework-core-bundle\u0022\u003EEntity Framework Core Bundle\u003C/h2\u003E\n\u003Ch3 class=\u0022mud-scrollspy-section\u0022 id=\u0022codebeam.ultimateauth.entityframeworkcore.bundle\u0022\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.EntityFrameworkCore.Bundle\u003C/code\u003E\u003C/h3\u003E\n\u003Cp\u003EThe Entity Framework Core Bundle provides the complete server composition using UltimateAuth\u0027s EF Core persistence implementations.\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EEntityFrameworkCore.Bundle\n|\n\u002B-- Server\n\u002B-- Reference implementations\n\u002B-- EF Core persistence implementations\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFor applications that use EF Core for persistent UltimateAuth data, this is normally the server package to install.\u003C/p\u003E\n\u003Cp\u003EThe developer does not need to manually assemble the individual Users, Credentials, Authorization, Sessions, Tokens, and other persistence packages.\u003C/p\u003E\n\u003Cp\u003EThe bundle performs that composition.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022why-bundles-matter\u0022\u003EWhy Bundles Matter\u003C/h1\u003E\n\u003Cp\u003EA highly modular framework can easily make the developer experience worse if every application has to understand and install its internal package graph.\u003C/p\u003E\n\u003Cp\u003EUltimateAuth deliberately separates \u003Cstrong\u003Earchitecture modularity\u003C/strong\u003E from \u003Cstrong\u003Einstallation complexity\u003C/strong\u003E.\u003C/p\u003E\n\u003Cp\u003EInternally:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EServer\n \u002B Users\n \u002B Credentials\n \u002B Authorization\n \u002B Authentication\n \u002B Sessions\n \u002B Tokens\n \u002B Policies\n \u002B persistence implementations\n \u002B reference implementations\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFrom the application:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-bash\u0022\u003Edotnet add package CodeBeam.UltimateAuth.EntityFrameworkCore.Bundle\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThis gives UltimateAuth two useful properties at the same time:\u003C/p\u003E\n\u003Col\u003E\n\u003Cli\u003Eindividual capabilities remain independently replaceable and evolvable;\u003C/li\u003E\n\u003Cli\u003Ethe common path remains simple.\u003C/li\u003E\n\u003C/ol\u003E\n\u003Cp\u003EYou should not need to understand the complete internal dependency graph before building your first application.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022client\u0022\u003EClient\u003C/h1\u003E\n\u003Cp\u003EThe Client side has a different packaging model.\u003C/p\u003E\n\u003Cp\u003EThere are \u003Cstrong\u003Eno Client bundles\u003C/strong\u003E.\u003C/p\u003E\n\u003Cp\u003EInstead, applications install the client package designed for their application model.\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003E Client Foundation\n |\n \u002B-------------\u002B-------------\u002B\n | | |\n Blazor MAUI Future\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFor example, a Blazor application installs:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-bash\u0022\u003Edotnet add package CodeBeam.UltimateAuth.Client.Blazor\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EA future MAUI integration can follow the same model without changing the underlying UltimateAuth Client architecture.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022codebeam.ultimateauth.client\u0022\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.Client\u003C/code\u003E\u003C/h2\u003E\n\u003Cp\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.Client\u003C/code\u003E is the shared client foundation.\u003C/p\u003E\n\u003Cp\u003EIt contains common client contracts, abstractions, flow APIs, state concepts, and runtime-independent client behavior.\u003C/p\u003E\n\u003Cp\u003EIt should be thought of as the foundation on which concrete UltimateAuth client integrations are built.\u003C/p\u003E\n\u003Cp\u003EMost applications should therefore install their platform-specific client package rather than installing \u003Ccode\u003ECodeBeam.UltimateAuth.Client\u003C/code\u003E directly.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022codebeam.ultimateauth.client.blazor\u0022\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.Client.Blazor\u003C/code\u003E\u003C/h2\u003E\n\u003Cp\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.Client.Blazor\u003C/code\u003E is the concrete UltimateAuth client integration for Blazor.\u003C/p\u003E\n\u003Cp\u003EIt builds on the Client foundation and adds the Blazor-specific runtime and UI integration required by Blazor applications.\u003C/p\u003E\n\u003Cp\u003EThis includes capabilities such as:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003E\u003Ccode\u003EUAuthApp\u003C/code\u003E\u003C/li\u003E\n\u003Cli\u003E\u003Ccode\u003EUAuthLoginForm\u003C/code\u003E\u003C/li\u003E\n\u003Cli\u003E\u003Ccode\u003EUAuthStateView\u003C/code\u003E\u003C/li\u003E\n\u003Cli\u003Eauthentication state integration\u003C/li\u003E\n\u003Cli\u003EBlazor authorization integration\u003C/li\u003E\n\u003Cli\u003Erouting integration\u003C/li\u003E\n\u003Cli\u003Eauthentication flow components\u003C/li\u003E\n\u003Cli\u003EJavaScript transport integration\u003C/li\u003E\n\u003Cli\u003Eclient lifecycle coordination\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cp\u003EConceptually:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECore\n |\nClient\n |\nClient.Blazor\n |\nYour Blazor Application\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThis model keeps the shared Client architecture independent from Blazor while still giving Blazor developers one natural package to install.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022client-compatibility-packages\u0022\u003EClient Compatibility Packages\u003C/h1\u003E\n\u003Cp\u003ENot every client-side package represents a complete client implementation.\u003C/p\u003E\n\u003Cp\u003ESome packages exist to bridge UltimateAuth with a host framework.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022codebeam.ultimateauth.client.aspnetcore\u0022\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.Client.AspNetCore\u003C/code\u003E\u003C/h2\u003E\n\u003Cp\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.Client.AspNetCore\u003C/code\u003E is a lightweight ASP.NET Core compatibility layer for UltimateAuth client applications.\u003C/p\u003E\n\u003Cp\u003EIt allows client-oriented applications to integrate with ASP.NET Core authentication and authorization infrastructure without introducing the full UltimateAuth Server runtime.\u003C/p\u003E\n\u003Cp\u003EThis is particularly useful for hosting models such as Blazor Web App with Interactive WebAssembly.\u003C/p\u003E\n\u003Cp\u003EIt can enable compatibility with ASP.NET Core features such as \u003Ccode\u003E[Authorize]\u003C/code\u003E, but it does \u003Cstrong\u003Enot\u003C/strong\u003E implement authentication itself and does not turn the application into an UltimateAuth Server.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022application-composition\u0022\u003EApplication Composition\u003C/h1\u003E\n\u003Cp\u003EBecause Server and Client are independent platform sides, different applications can compose UltimateAuth differently.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022server-only\u0022\u003EServer Only\u003C/h2\u003E\n\u003Cp\u003ETypical examples include:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003Ededicated authentication servers\u003C/li\u003E\n\u003Cli\u003Ebackend services hosting UltimateAuth\u003C/li\u003E\n\u003Cli\u003Eserver-side identity infrastructure\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EApplication\n|\n\u002B-- Server Bundle\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022client-only\u0022\u003EClient Only\u003C/h2\u003E\n\u003Cp\u003ETypical examples include:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003Estandalone Blazor WebAssembly\u003C/li\u003E\n\u003Cli\u003Efuture MAUI applications\u003C/li\u003E\n\u003Cli\u003Eapplications using a remote UAuthHub\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EApplication\n|\n\u002B-- Client.Blazor\n |\n \u002B---- remote UltimateAuth Server / UAuthHub\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022server-client\u0022\u003EServer \u002B Client\u003C/h2\u003E\n\u003Cp\u003ESome applications host UltimateAuth and consume its client API in the same application.\u003C/p\u003E\n\u003Cp\u003EBlazor Server is a common example.\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EBlazor Server Application\n|\n\u002B-- Server Bundle\n|\n\u002B-- Client.Blazor\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThe two sides remain architecturally distinct even when deployed in the same process.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022plugin-domains\u0022\u003EPlugin Domains\u003C/h1\u003E\n\u003Cp\u003EUltimateAuth extends its identity platform through \u003Cstrong\u003EPlugin Domains\u003C/strong\u003E.\u003C/p\u003E\n\u003Cp\u003EThe current primary Plugin Domains are:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003EUsers\u003C/li\u003E\n\u003Cli\u003ECredentials\u003C/li\u003E\n\u003Cli\u003EAuthorization\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cp\u003EA Plugin Domain is more than a single assembly. It is a capability area with contracts, runtime behavior, recommended implementations, and infrastructure implementations.\u003C/p\u003E\n\u003Cp\u003EThis structure allows a domain to remain replaceable without requiring applications to redesign the rest of UltimateAuth.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022anatomy-of-a-plugin-domain\u0022\u003EAnatomy of a Plugin Domain\u003C/h2\u003E\n\u003Cp\u003EA typical Plugin Domain follows this model:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EPlugin Domain\n|\n\u002B-- Contracts\n|\n\u002B-- Domain / Runtime\n|\n\u002B-- Reference\n|\n\u002B-- Persistence\n |\n \u002B-- InMemory\n \u002B-- EntityFrameworkCore\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EEach layer has a distinct purpose.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022contracts\u0022\u003EContracts\u003C/h2\u003E\n\u003Cp\u003EExample:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECodeBeam.UltimateAuth.Users.Contracts\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EContracts define the public boundary of the domain. Server and Client can communicate through same contracts without requiring one to depend on the other.\u003C/p\u003E\n\u003Cp\u003EThey are intentionally kept close to Core and represent the smallest dependency surface for applications or extensions that only need to interact with the domain contract.\u003C/p\u003E\n\u003Cp\u003EDepending on the domain, contracts can contain concepts such as:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003Erequests\u003C/li\u003E\n\u003Cli\u003Eresults\u003C/li\u003E\n\u003Cli\u003Epublic models\u003C/li\u003E\n\u003Cli\u003Eabstractions\u003C/li\u003E\n\u003Cli\u003Edomain-facing contracts\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cp\u003EThis allows another implementation to integrate with UltimateAuth without depending on the entire built-in implementation.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022domain-runtime\u0022\u003EDomain / Runtime\u003C/h2\u003E\n\u003Cp\u003EExample:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECodeBeam.UltimateAuth.Users\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThe main domain project provides the runtime and application behavior of that Plugin Domain.\u003C/p\u003E\n\u003Cp\u003EIt operates against abstractions rather than requiring one persistence implementation.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022reference-implementations\u0022\u003EReference Implementations\u003C/h2\u003E\n\u003Cp\u003EExample:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECodeBeam.UltimateAuth.Users.Reference\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EReference packages contain the implementation UltimateAuth recommends as the standard baseline for the domain.\u003C/p\u003E\n\u003Cp\u003EThe distinction between \u003Cstrong\u003Econtract\u003C/strong\u003E and \u003Cstrong\u003Ereference implementation\u003C/strong\u003E is intentional.\u003C/p\u003E\n\u003Cp\u003EUltimateAuth does not leave extensibility points empty and require every developer to design critical identity behavior from scratch.\u003C/p\u003E\n\u003Cp\u003EInstead, the platform provides:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EContract\n |\n \u002B---- UltimateAuth Reference Implementation\n |\n \u002B---- Your Custom Implementation\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFor the common path, use the UltimateAuth reference implementation.\u003C/p\u003E\n\u003Cp\u003EFor specialized requirements, replace the appropriate implementation while preserving the surrounding platform contract and security boundaries.\u003C/p\u003E\n\u003Cp\u003EThis pattern gives advanced applications extensibility without making simple applications incomplete.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022persistence-implementations\u0022\u003EPersistence Implementations\u003C/h2\u003E\n\u003Cp\u003EPlugin Domains can provide persistence-specific packages independently.\u003C/p\u003E\n\u003Cp\u003EFor example:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EUsers\n|\n\u002B-- Users.Contracts\n\u002B-- Users\n\u002B-- Users.Reference\n\u002B-- Users.InMemory\n\u002B-- Users.EntityFrameworkCore\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThe same pattern applies to other Plugin Domains where appropriate.\u003C/p\u003E\n\u003Cp\u003EA developer using a server bundle normally does not need to install these packages individually. The selected bundle composes the appropriate persistence strategy.\u003C/p\u003E\n\u003Cp\u003ETheir separation exists primarily to preserve architectural modularity and replaceability.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022current-plugin-domains\u0022\u003ECurrent Plugin Domains\u003C/h1\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022users\u0022\u003EUsers\u003C/h2\u003E\n\u003Cp\u003EThe Users domain owns user lifecycle and user-management capabilities.\u003C/p\u003E\n\u003Cp\u003EIts package family includes:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECodeBeam.UltimateAuth.Users.Contracts\nCodeBeam.UltimateAuth.Users\nCodeBeam.UltimateAuth.Users.Reference\nCodeBeam.UltimateAuth.Users.InMemory\nCodeBeam.UltimateAuth.Users.EntityFrameworkCore\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022credentials\u0022\u003ECredentials\u003C/h2\u003E\n\u003Cp\u003EThe Credentials domain owns credential-related capabilities and credential management.\u003C/p\u003E\n\u003Cp\u003EIts package family includes:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECodeBeam.UltimateAuth.Credentials.Contracts\nCodeBeam.UltimateAuth.Credentials\nCodeBeam.UltimateAuth.Credentials.Reference\nCodeBeam.UltimateAuth.Credentials.InMemory\nCodeBeam.UltimateAuth.Credentials.EntityFrameworkCore\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022authorization\u0022\u003EAuthorization\u003C/h2\u003E\n\u003Cp\u003EThe Authorization domain provides UltimateAuth authorization capabilities.\u003C/p\u003E\n\u003Cp\u003EIts package family includes:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECodeBeam.UltimateAuth.Authorization.Contracts\nCodeBeam.UltimateAuth.Authorization\nCodeBeam.UltimateAuth.Authorization.Reference\nCodeBeam.UltimateAuth.Authorization.InMemory\nCodeBeam.UltimateAuth.Authorization.EntityFrameworkCore\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThe same architectural pattern makes these capabilities independently evolvable while keeping their public boundaries explicit.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022essential-server-capabilities\u0022\u003EEssential Server Capabilities\u003C/h1\u003E\n\u003Cp\u003EAuthentication, Sessions, and Tokens are slightly different from Plugin Domains.\u003C/p\u003E\n\u003Cp\u003EThey are fundamental parts of an UltimateAuth Server and are not treated as optional identity plugins in the same sense as Users, Credentials, or Authorization.\u003C/p\u003E\n\u003Cp\u003EHowever, they are still separated into focused projects.\u003C/p\u003E\n\u003Cp\u003EConceptually:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003E UltimateAuth Server\n |\n \u002B--------------------\u002B--------------------\u002B\n | | |\n Authentication Sessions Tokens\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EWhy separate them if the Server needs them?\u003C/p\u003E\n\u003Cp\u003EBecause \u003Cstrong\u003Erequired does not have to mean monolithic\u003C/strong\u003E.\u003C/p\u003E\n\u003Cp\u003EKeeping these capabilities isolated:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003Eprevents the central Server project from becoming an oversized implementation assembly;\u003C/li\u003E\n\u003Cli\u003Ekeeps responsibilities and dependency boundaries explicit;\u003C/li\u003E\n\u003Cli\u003Eallows implementations to evolve independently;\u003C/li\u003E\n\u003Cli\u003Emakes persistence providers independently composable;\u003C/li\u003E\n\u003Cli\u003Ekeeps replacement and testing boundaries smaller.\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cp\u003EThey can be thought of as \u003Cstrong\u003Emodular server subsystems\u003C/strong\u003E rather than full Plugin Domains.\u003C/p\u003E\n\u003Cp\u003EFor example, persistence implementations can still exist independently:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EAuthentication\n\u002B-- Authentication.InMemory\n\u002B-- Authentication.EntityFrameworkCore\n\nSessions\n\u002B-- Sessions.InMemory\n\u002B-- Sessions.EntityFrameworkCore\n\nTokens\n\u002B-- Tokens.InMemory\n\u002B-- Tokens.EntityFrameworkCore\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThe selected Server bundle composes the required implementations for the application.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022policies-and-security\u0022\u003EPolicies and Security\u003C/h1\u003E\n\u003Cp\u003ESome capabilities are deliberately isolated even though they support multiple areas of the platform.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022policies\u0022\u003EPolicies\u003C/h2\u003E\n\u003Cp\u003E\u003Ccode\u003ECodeBeam.UltimateAuth.Policies\u003C/code\u003E contains policy infrastructure used to keep security and application decisions explicit and extensible.\u003C/p\u003E\n\u003Cp\u003EPolicies are part of the server architecture rather than application-specific transport logic.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022security-implementations\u0022\u003ESecurity Implementations\u003C/h2\u003E\n\u003Cp\u003ESecurity algorithms can also live behind focused implementations.\u003C/p\u003E\n\u003Cp\u003EFor example:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECodeBeam.UltimateAuth.Security.Argon2\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EKeeping security implementations separate avoids coupling the entire platform to one concrete algorithm or provider.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022modularity-without-an-incomplete-framework\u0022\u003EModularity Without an Incomplete Framework\u003C/h1\u003E\n\u003Cp\u003EUltimateAuth\u0027s modularity has an important design goal:\u003C/p\u003E\n\u003Cblockquote\u003E\n\u003Cp\u003EExtensibility should not require developers to build the missing half of the framework themselves.\u003C/p\u003E\n\u003C/blockquote\u003E\n\u003Cp\u003EEvery major extensibility boundary should have a practical UltimateAuth-provided path.\u003C/p\u003E\n\u003Cp\u003EThe common model is:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003E UltimateAuth Contract\n |\n \u002B-----------\u002B-----------\u002B\n | |\n Reference Path Custom Path\n | |\n Works out of the box Replace when needed\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThis means the platform can provide strong defaults and reference implementations while still allowing advanced applications to replace individual capabilities.\u003C/p\u003E\n\u003Cp\u003EA customization should be local to the capability being replaced rather than requiring the authentication architecture to be rewritten.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022replaceability-by-design\u0022\u003EReplaceability by Design\u003C/h1\u003E\n\u003Cp\u003EUltimateAuth is intentionally built from small architectural boundaries.\u003C/p\u003E\n\u003Cp\u003EThe goal is not modularity for its own sake.\u003C/p\u003E\n\u003Cp\u003EThe goal is to reduce the cost of change.\u003C/p\u003E\n\u003Cp\u003EAn application may start with:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003EEntityFrameworkCore.Bundle\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003Ewhile still having clearly separated domains and infrastructure underneath.\u003C/p\u003E\n\u003Cp\u003EIf a specialized application later needs a custom implementation for one capability, the architecture already has a boundary for it.\u003C/p\u003E\n\u003Cp\u003EThis provides a different model from choosing between two extremes:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ESimple but monolithic\n OR\nFlexible but difficult to configure\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EUltimateAuth aims for:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003E Simple installation\n \u002B\n Modular internals\n \u002B\n Reference implementations\n \u002B\n Explicit contracts\n =\n Low-cost customization\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003ESecurity-sensitive extension points still remain subject to UltimateAuth\u0027s security invariants and authority boundaries. Replaceability is intended to enable integration and specialization, not to bypass required security decisions.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022choosing-packages\u0022\u003EChoosing Packages\u003C/h1\u003E\n\u003Cp\u003EFor most developers, package selection should be simple.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022blazor-server-with-inmemory-persistence\u0022\u003EBlazor Server with InMemory persistence\u003C/h2\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-bash\u0022\u003Edotnet add package CodeBeam.UltimateAuth.InMemory.Bundle\ndotnet add package CodeBeam.UltimateAuth.Client.Blazor\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThe application both hosts UltimateAuth and consumes the Blazor client integration.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022blazor-server-with-entity-framework-core\u0022\u003EBlazor Server with Entity Framework Core\u003C/h2\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-bash\u0022\u003Edotnet add package CodeBeam.UltimateAuth.EntityFrameworkCore.Bundle\ndotnet add package CodeBeam.UltimateAuth.Client.Blazor\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022custom-persistence\u0022\u003ECustom persistence\u003C/h2\u003E\n\u003Cp\u003EStart from:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-bash\u0022\u003Edotnet add package CodeBeam.UltimateAuth.Reference.Bundle\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003Eand provide the required persistence implementations for your architecture.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022standalone-blazor-webassembly\u0022\u003EStandalone Blazor WebAssembly\u003C/h2\u003E\n\u003Cp\u003EInstall the client integration:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-bash\u0022\u003Edotnet add package CodeBeam.UltimateAuth.Client.Blazor\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThe authentication authority lives in a remote UltimateAuth Server or UAuthHub.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022the-rule-of-thumb\u0022\u003EThe Rule of Thumb\u003C/h1\u003E\n\u003Cp\u003EYou generally do not need to assemble UltimateAuth package-by-package.\u003C/p\u003E\n\u003Cp\u003EFor the \u003Cstrong\u003EServer\u003C/strong\u003E:\u003C/p\u003E\n\u003Cblockquote\u003E\n\u003Cp\u003EChoose the Bundle that matches your infrastructure.\u003C/p\u003E\n\u003C/blockquote\u003E\n\u003Cp\u003EFor the \u003Cstrong\u003EClient\u003C/strong\u003E:\u003C/p\u003E\n\u003Cblockquote\u003E\n\u003Cp\u003EChoose the Client package that matches your application platform.\u003C/p\u003E\n\u003C/blockquote\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ESERVER\n\u0026quot;What infrastructure do I use?\u0026quot;\n |\n \u002B-- Reference.Bundle\n \u002B-- InMemory.Bundle\n \u002B-- EntityFrameworkCore.Bundle\n\n\nCLIENT\n\u0026quot;What kind of application am I building?\u0026quot;\n |\n \u002B-- Client.Blazor\n \u002B-- Client.Maui (future)\n \u002B-- ...\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EThe detailed package graph exists so that UltimateAuth remains extensible.\u003C/p\u003E\n\u003Cp\u003EThe bundles and client integrations exist so that you do not have to manage that graph for ordinary applications.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch1 id=\u0022next\u0022\u003ENext\u003C/h1\u003E\n\u003Cp\u003EYou now have the mental model needed to understand the rest of the UltimateAuth documentation:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-text\u0022\u003ECore\n |\n \u002B-- Server --\u0026gt; choose a Bundle\n |\n \u002B-- Client --\u0026gt; choose your platform integration\n\nServer\n |\n \u002B-- Essential server subsystems\n |\n \u002B-- Plugin Domains\n |\n \u002B-- Contracts\n \u002B-- Runtime\n \u002B-- Reference implementations\n \u002B-- Persistence implementations\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EContinue with the \u003Ca href=\u0022./quickstart.md\u0022\u003EQuick Start\u003C/a\u003E to build your first UltimateAuth application.\u003C/p\u003E\n\u003Cp\u003EFor persistent storage, UAuthHub, standalone WebAssembly, Resource API, and other deployment models, continue with the \u003Ca href=\u0022./real-world-setup.md\u0022\u003EReal-World Setup\u003C/a\u003E.\u003C/p\u003E\n", + "Headings": [ + { + "Id": "platform-at-a-glance", + "Text": "Platform at a Glance", + "Level": 0 + }, + { + "Id": "codebeam.ultimateauth.core", + "Text": "CodeBeam.UltimateAuth.Core", + "Level": 0 + }, + { + "Id": "do-i-install-codebeam.ultimateauth.server-directly", + "Text": "Do I install CodeBeam.UltimateAuth.Server directly?", + "Level": 0 + }, + { + "Id": "reference-bundle", + "Text": "Reference Bundle", + "Level": 0 + }, + { + "Id": "codebeam.ultimateauth.reference.bundle", + "Text": "CodeBeam.UltimateAuth.Reference.Bundle", + "Level": 1 + }, + { + "Id": "inmemory-bundle", + "Text": "InMemory Bundle", + "Level": 0 + }, + { + "Id": "codebeam.ultimateauth.inmemory.bundle", + "Text": "CodeBeam.UltimateAuth.InMemory.Bundle", + "Level": 1 + }, + { + "Id": "entity-framework-core-bundle", + "Text": "Entity Framework Core Bundle", + "Level": 0 + }, + { + "Id": "codebeam.ultimateauth.entityframeworkcore.bundle", + "Text": "CodeBeam.UltimateAuth.EntityFrameworkCore.Bundle", + "Level": 1 + }, + { + "Id": "codebeam.ultimateauth.client", + "Text": "CodeBeam.UltimateAuth.Client", + "Level": 0 + }, + { + "Id": "codebeam.ultimateauth.client.blazor", + "Text": "CodeBeam.UltimateAuth.Client.Blazor", + "Level": 0 + }, + { + "Id": "codebeam.ultimateauth.client.aspnetcore", + "Text": "CodeBeam.UltimateAuth.Client.AspNetCore", + "Level": 0 + }, + { + "Id": "server-only", + "Text": "Server Only", + "Level": 0 + }, + { + "Id": "client-only", + "Text": "Client Only", + "Level": 0 + }, + { + "Id": "server-client", + "Text": "Server \u002B Client", + "Level": 0 + }, + { + "Id": "anatomy-of-a-plugin-domain", + "Text": "Anatomy of a Plugin Domain", + "Level": 0 + }, + { + "Id": "contracts", + "Text": "Contracts", + "Level": 0 + }, + { + "Id": "domain-runtime", + "Text": "Domain / Runtime", + "Level": 0 + }, + { + "Id": "reference-implementations", + "Text": "Reference Implementations", + "Level": 0 + }, + { + "Id": "persistence-implementations", + "Text": "Persistence Implementations", + "Level": 0 + }, + { + "Id": "users", + "Text": "Users", + "Level": 0 + }, + { + "Id": "credentials", + "Text": "Credentials", + "Level": 0 + }, + { + "Id": "authorization", + "Text": "Authorization", + "Level": 0 + }, + { + "Id": "policies", + "Text": "Policies", + "Level": 0 + }, + { + "Id": "security-implementations", + "Text": "Security Implementations", + "Level": 0 + }, + { + "Id": "blazor-server-with-inmemory-persistence", + "Text": "Blazor Server with InMemory persistence", + "Level": 0 + }, + { + "Id": "blazor-server-with-entity-framework-core", + "Text": "Blazor Server with Entity Framework Core", + "Level": 0 + }, + { + "Id": "custom-persistence", + "Text": "Custom persistence", + "Level": 0 + }, + { + "Id": "standalone-blazor-webassembly", + "Text": "Standalone Blazor WebAssembly", + "Level": 0 + } + ] +} \ No newline at end of file diff --git a/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/getting-started/quickstart.json b/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/getting-started/quickstart.json index 3f6da51e..49dd73b0 100644 --- a/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/getting-started/quickstart.json +++ b/docs/website/CodeBeam.UltimateAuth.Docs.Wasm/CodeBeam.UltimateAuth.Docs.Wasm.Client/wwwroot/docs/getting-started/quickstart.json @@ -1,7 +1,7 @@ { "Slug": "getting-started/quickstart", "Title": "QuickStart", - "Html": "\n\u003Cp\u003EIn this guide, you will set up UltimateAuth in a few minutes and perform your \u003Cstrong\u003Efirst login\u003C/strong\u003E.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022create-a-project\u0022\u003E1. Create a Project\u003C/h2\u003E\n\u003Cp\u003EStart by creating a new Blazor app:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-bash\u0022\u003Edotnet new blazorserver -n UltimateAuthDemo\ncd UltimateAuthDemo\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022install-packages\u0022\u003E2. Install Packages\u003C/h2\u003E\n\u003Cp\u003EInstall the required UltimateAuth packages:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Edotnet add package CodeBeam.UltimateAuth.Server\ndotnet add package CodeBeam.UltimateAuth.Client.Blazor\ndotnet add package CodeBeam.UltimateAuth.InMemory.Bundle\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022configure-services\u0022\u003E3. Configure Services\u003C/h2\u003E\n\u003Cp\u003EUpdate your Program.cs:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Ebuilder.Services\n .AddUltimateAuthServer()\n .AddUltimateAuthInMemory();\n\nbuilder.Services\n .AddUltimateAuthClientBlazor();\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022configure-middleware\u0022\u003E4. Configure Middleware\u003C/h2\u003E\n\u003Cp\u003EIn \u003Ccode\u003EProgram.cs\u003C/code\u003E\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Eapp.UseUltimateAuthWithAspNetCore();\napp.MapUltimateAuthEndpoints();\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022enable-blazor-integration\u0022\u003E5. Enable Blazor Integration\u003C/h2\u003E\n\u003Cp\u003EIn \u003Ccode\u003EProgram.cs\u003C/code\u003E\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Eapp.MapRazorComponents\u0026lt;App\u0026gt;()\n .AddInteractiveServerRenderMode() // or webassembly (depends on your application type)\n .AddUltimateAuthRoutes(UAuthAssemblies.BlazorClient());\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022add-uauth-script\u0022\u003E6. Add UAuth Script\u003C/h2\u003E\n\u003Cp\u003EAdd this to \u003Ccode\u003EApp.razor\u003C/code\u003E or \u003Ccode\u003Eindex.html\u003C/code\u003E:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E\u0026lt;script src=\u0026quot;_content/CodeBeam.UltimateAuth.Client.Blazor/uauth.min.js\u0026quot;\u0026gt;\u0026lt;/script\u0026gt;\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022configure-application-lifecycle\u0022\u003E7. Configure Application Lifecycle\u003C/h2\u003E\n\u003Cp\u003EReplace \u003Ccode\u003ERoutes.razor\u003C/code\u003E with this code:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E\u0026lt;UAuthApp UseBuiltInRouter=\u0026quot;true\u0026quot; AppAssembly=\u0026quot;typeof(Program).Assembly\u0026quot; DefaultLayout=\u0026quot;typeof(Layout.MainLayout)\u0026quot; /\u0026gt;\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022recommended-setup-optional\u0022\u003E8. Recommended Setup (Optional)\u003C/h2\u003E\n\u003Cp\u003EAdd these for better experience:\u003C/p\u003E\n\u003Cp\u003EFor login page (Use this only once in your application)\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E@attribute [UAuthLoginPage]\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFor protected pages\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E@attribute [UAuthAuthorize]\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFor any page that you use UltimateAuth features like AuthState etc.\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E@inherits UAuthFlowPageBase\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022seed-data-for-quickstart-optional\u0022\u003E9. Seed Data For QuickStart (Optional)\u003C/h2\u003E\n\u003Cp\u003EThis code creates admin and user users with same password and admin role.\u003C/p\u003E\n\u003Cp\u003EFor in memory\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Ebuilder.Services.AddUltimateAuthSampleSeed();\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFor entity framework core:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Ebuilder.Services.AddScopedUltimateAuthSampleSeed();\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EIn pipeline configuration\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Eif (app.Environment.IsDevelopment())\n{\n await app.SeedUltimateAuthAsync();\n}\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022perform-your-first-login\u0022\u003E10. Perform Your First Login\u003C/h2\u003E\n\u003Cp\u003EExample using IUAuthClient:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E[Inject] IUAuthClient UAuthClient { get; set; } = null!;\n\nprivate async Task Login()\n{\n await UAuthClient.Flows.LoginAsync(new LoginRequest\n {\n Identifier = \u0026quot;admin\u0026quot;,\n Secret = \u0026quot;admin\u0026quot;\n });\n}\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022thats-it\u0022\u003E\uD83C\uDF89 That\u2019s It\u003C/h2\u003E\n\u003Cp\u003EYou now have a working authentication system with:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003ESession-based authentication\u003C/li\u003E\n\u003Cli\u003EAutomatic client detection\u003C/li\u003E\n\u003Cli\u003EBuilt-in login flow\u003C/li\u003E\n\u003Cli\u003ESecure session handling\u003C/li\u003E\n\u003C/ul\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022what-just-happened\u0022\u003EWhat Just Happened?\u003C/h2\u003E\n\u003Cp\u003EWhen you logged in:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003EA session (with root and chain) was created on the server,\u003C/li\u003E\n\u003Cli\u003EYour client received an authentication grant (cookie or token),\u003C/li\u003E\n\u003Cli\u003EUltimateAuth established your auth state automatically.\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cp\u003E\uD83D\uDC49 You didn\u2019t manage cookies, tokens, or redirects manually.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022next-steps\u0022\u003ENext Steps\u003C/h2\u003E\n\u003Cp\u003EDiscover the setup for real world applications with entity framework core.\u003C/p\u003E\n", + "Html": "\n\u003Cp\u003EIn this guide, you will set up UltimateAuth in a few minutes and perform your \u003Cstrong\u003Efirst login\u003C/strong\u003E.\u003C/p\u003E\n\u003Chr /\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022create-a-project\u0022\u003E1. Create a Project\u003C/h2\u003E\n\u003Cp\u003EStart by creating a new Blazor app:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-bash\u0022\u003Edotnet new blazorserver -n UltimateAuthDemo\ncd UltimateAuthDemo\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022install-packages\u0022\u003E2. Install Packages\u003C/h2\u003E\n\u003Cp\u003EInstall the required UltimateAuth packages:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Edotnet add package CodeBeam.UltimateAuth.Client.Blazor\ndotnet add package CodeBeam.UltimateAuth.InMemory.Bundle\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022configure-services\u0022\u003E3. Configure Services\u003C/h2\u003E\n\u003Cp\u003EUpdate your Program.cs:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Ebuilder.Services\n .AddUltimateAuthServer()\n .AddUltimateAuthInMemory();\n\nbuilder.Services\n .AddUltimateAuthClientBlazor();\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022configure-middleware\u0022\u003E4. Configure Middleware\u003C/h2\u003E\n\u003Cp\u003EIn \u003Ccode\u003EProgram.cs\u003C/code\u003E\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Eapp.UseUltimateAuthWithAspNetCore();\napp.MapUltimateAuthEndpoints();\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022enable-blazor-integration\u0022\u003E5. Enable Blazor Integration\u003C/h2\u003E\n\u003Cp\u003EIn \u003Ccode\u003EProgram.cs\u003C/code\u003E\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Eapp.MapRazorComponents\u0026lt;App\u0026gt;()\n .AddInteractiveServerRenderMode() // or webassembly (depends on your application type)\n .AddUltimateAuthRoutes(UAuthAssemblies.BlazorClient());\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022add-uauth-script\u0022\u003E6. Add UAuth Script\u003C/h2\u003E\n\u003Cp\u003EAdd this to \u003Ccode\u003EApp.razor\u003C/code\u003E or \u003Ccode\u003Eindex.html\u003C/code\u003E:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E\u0026lt;script src=\u0026quot;_content/CodeBeam.UltimateAuth.Client.Blazor/uauth.min.js\u0026quot;\u0026gt;\u0026lt;/script\u0026gt;\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022configure-application-lifecycle\u0022\u003E7. Configure Application Lifecycle\u003C/h2\u003E\n\u003Cp\u003EReplace \u003Ccode\u003ERoutes.razor\u003C/code\u003E with this code:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E\u0026lt;UAuthApp UseBuiltInRouter=\u0026quot;true\u0026quot; AppAssembly=\u0026quot;typeof(Program).Assembly\u0026quot; DefaultLayout=\u0026quot;typeof(Layout.MainLayout)\u0026quot; /\u0026gt;\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022recommended-setup-optional\u0022\u003E8. Recommended Setup (Optional)\u003C/h2\u003E\n\u003Cp\u003EAdd these for better experience:\u003C/p\u003E\n\u003Cp\u003EFor login page (Use this only once in your application)\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E@attribute [UAuthLoginPage]\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFor protected pages\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E@attribute [UAuthAuthorize]\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFor any page that you use UltimateAuth features like AuthState etc.\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E@inherits UAuthPageBase\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022seed-data-for-quickstart-optional\u0022\u003E9. Seed Data For QuickStart (Optional)\u003C/h2\u003E\n\u003Cp\u003EThis code creates admin and user users with same password and admin role.\u003C/p\u003E\n\u003Cp\u003EFor in memory\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Ebuilder.Services.AddUltimateAuthSampleSeed();\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EFor entity framework core:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Ebuilder.Services.AddScopedUltimateAuthSampleSeed();\n\u003C/code\u003E\u003C/pre\u003E\n\u003Cp\u003EIn pipeline configuration\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003Eif (app.Environment.IsDevelopment())\n{\n await app.SeedUltimateAuthAsync();\n}\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022perform-your-first-login\u0022\u003E10. Perform Your First Login\u003C/h2\u003E\n\u003Cp\u003EExample using IUAuthClient:\u003C/p\u003E\n\u003Cpre\u003E\u003Ccode class=\u0022language-csharp\u0022\u003E[Inject] IUAuthClient UAuthClient { get; set; } = null!;\n\nprivate async Task Login()\n{\n await UAuthClient.Flows.LoginAsync(new LoginRequest\n {\n Identifier = \u0026quot;admin\u0026quot;,\n Secret = \u0026quot;admin\u0026quot;\n });\n}\n\u003C/code\u003E\u003C/pre\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022thats-it\u0022\u003E\uD83C\uDF89 That\u2019s It\u003C/h2\u003E\n\u003Cp\u003EYou now have a working authentication system with:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003ESession-based authentication\u003C/li\u003E\n\u003Cli\u003EAutomatic client detection\u003C/li\u003E\n\u003Cli\u003EBuilt-in login flow\u003C/li\u003E\n\u003Cli\u003ESecure session handling\u003C/li\u003E\n\u003C/ul\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022what-just-happened\u0022\u003EWhat Just Happened?\u003C/h2\u003E\n\u003Cp\u003EWhen you logged in:\u003C/p\u003E\n\u003Cul\u003E\n\u003Cli\u003EA session (with root and chain) was created on the server,\u003C/li\u003E\n\u003Cli\u003EYour client received an authentication grant (cookie or token),\u003C/li\u003E\n\u003Cli\u003EUltimateAuth established your auth state automatically.\u003C/li\u003E\n\u003C/ul\u003E\n\u003Cp\u003E\uD83D\uDC49 You didn\u2019t manage cookies, tokens, or redirects manually.\u003C/p\u003E\n\u003Ch2 class=\u0022mud-scrollspy-section\u0022 id=\u0022next-steps\u0022\u003ENext Steps\u003C/h2\u003E\n\u003Cp\u003EDiscover the setup for real world applications with entity framework core.\u003C/p\u003E\n", "Headings": [ { "Id": "create-a-project", diff --git a/src/utilities/CodeBeam.UltimateAuth.DocsBuilder/Program.cs b/src/utilities/CodeBeam.UltimateAuth.DocsBuilder/Program.cs index b771bd4d..0b6de37a 100644 --- a/src/utilities/CodeBeam.UltimateAuth.DocsBuilder/Program.cs +++ b/src/utilities/CodeBeam.UltimateAuth.DocsBuilder/Program.cs @@ -86,18 +86,18 @@ GroupOrder = groupOrder }); - //var inputLastWrite = File.GetLastWriteTimeUtc(file); - - //if (File.Exists(outputPath)) - //{ - // var outputLastWrite = File.GetLastWriteTimeUtc(outputPath); - - // if (outputLastWrite >= inputLastWrite) - // { - // Console.WriteLine($"⏩ Skipped: {relativePath}"); - // continue; - // } - //} + var inputLastWrite = File.GetLastWriteTimeUtc(file); + + if (File.Exists(outputPath)) + { + var outputLastWrite = File.GetLastWriteTimeUtc(outputPath); + + if (outputLastWrite >= inputLastWrite) + { + Console.WriteLine($"⏩ Skipped: {relativePath}"); + continue; + } + } Console.WriteLine($"⚙ Processing: {relativePath}");