Skip to content

Commit e1feef1

Browse files
mckaragozmckaragoz
authored
Docs Content (#30)
* Docs Content * Refactor and enhance getting started documentation * Add quick start guide for UltimateAuth setup Added a quick start guide for setting up UltimateAuth with Blazor Server, including project creation, package installation, service configuration, middleware setup, and first login example. * Enhance Real-World Setup documentation for UltimateAuth Updated the Real-World Setup guide to clarify the use of a persistent configuration and added detailed setup instructions for UltimateAuth with Entity Framework Core and Blazor. * Improve Service Collection Extensions * Add authentication model documentation for UltimateAuth Added comprehensive documentation on the authentication model for UltimateAuth, detailing the concepts of Root, Chain, and Session, and their interactions. * Move fundaments to content * Add flow-based authentication documentation Introduced a comprehensive guide on flow-based authentication, detailing its principles, processes, and benefits compared to traditional token-based systems. * Document authentication modes in UltimateAuth Added documentation for authentication modes in UltimateAuth, detailing available modes, comparisons, and recommendations. * Add fundamentals section to documentation * Add documentation for Client Profiles in UltimateAuth Added detailed documentation on Client Profiles, including definitions, runtime detection, configuration options, and built-in profiles. * Add runtime architecture documentation for UltimateAuth This document outlines the runtime architecture of UltimateAuth, detailing the structured execution pipeline for authentication, including components like Endpoint Filter, AuthFlowContext, Flow Service, Orchestrator, and Authority. * Enhance getting started guide with UAuthHub config Added UAuthHub Pipeline Configuration section to the setup guide. * Add request lifecycle documentation for UltimateAuth This document explains the request lifecycle in UltimateAuth, detailing the processing of passive and active flow requests, middleware pipeline, and user resolution. * Document Flow Execution Boundary for authentication Add section on Flow Execution Boundary to clarify authentication flow behavior. * Fix Tenant Restriction even in normal Requests * Add documentation for Auth Flows in UltimateAuth Introduced a comprehensive guide on authentication flows in UltimateAuth, detailing the flow-driven system, types of flows, and supporting concepts. * Add detailed documentation for login flow in UltimateAuth This document outlines the login flow in UltimateAuth, detailing the structured pipeline from identifier resolution to session creation and optional token issuance. It emphasizes the importance of session hierarchy and security considerations. * Add documentation for UltimateAuth refresh flow Document the refresh flow in UltimateAuth, detailing its strategies and execution steps. * Add documentation for logout flow in UltimateAuth Document the logout flow and its distinctions in UltimateAuth, including session, device, and identity scopes. * Add session lifecycle documentation for UltimateAuth Document the structured session lifecycle in UltimateAuth, detailing core entities, relationships, and lifecycle phases. * Add documentation for token behavior in UltimateAuth Document the behavior and characteristics of tokens in UltimateAuth, including types, modes, access and refresh tokens, security model, and key takeaways. * Add device management documentation Document the device management features in UltimateAuth, covering the importance of devices, their lifecycle, security model, and configuration options. * Add configuration and extensibility documentation Added detailed documentation on configuration and extensibility in UltimateAuth, covering configuration layers, sources, and safety measures. * Create configuration overview documentation Added comprehensive overview of UltimateAuth configuration, detailing its runtime-adaptive nature and layered configuration model. * Some Improvements * Document server options for UltimateAuth configuration Added documentation for configuring server options in UltimateAuth, including usage examples and key takeaways. * Add client options documentation for UltimateAuth Added documentation for client options in UltimateAuth, detailing configuration, usage, and key features. * Add documentation for configuration sources and rules Document configuration sources, precedence rules, and best practices for UltimateAuth. * Add advanced configuration documentation for UltimateAuth Added detailed documentation on advanced configuration options for UltimateAuth, including customization points, service replacement, and safety boundaries. * Add documentation for Plugin Domains in UltimateAuth Introduced documentation for Plugin Domains in UltimateAuth, detailing architecture, extensibility, and recommended approaches. * Add Users Domain documentation Document the Users Domain in UltimateAuth, detailing core concepts, lifecycle, identifiers, and user profiles. * Add documentation for Credentials Domain Document the credentials domain, including core concepts, types, validation, integration with users, lifecycle, and security behavior. * Enhance documentation on plugin domains Added sections on domain isolation and communication via hooks. * Clean up formatting in plugin-domains index Remove unnecessary line break in documentation. * Add documentation for Authorization & Policies domain Added detailed documentation for the Authorization & Policies domain, covering core concepts, permission structure, built-in action catalog, role definitions, permission resolution, claims integration, authorization flow, and policies. * Create policies.md * Add client usage guide for UltimateAuth Added a comprehensive client usage guide for UltimateAuth, detailing its features, architecture, core concepts, examples, and state events. * Add authentication guide for UltimateAuth client Added comprehensive authentication guide for UltimateAuth client, covering login, refresh, logout, and PKCE flow. * Document Client Entry Point for UltimateAuth Added section on Client Entry Point with usage examples. * Update example for LoginAsync method * Improve clarity on authentication mode usage Clarified usage recommendations for authentication modes. * Add session management guide for UltimateAuth client Added comprehensive session management guide for UltimateAuth client, detailing session structure, methods for retrieving active sessions, logging out, revoking sessions, and security implications. * Add User Identifiers Guide documentation This document provides a comprehensive guide on user identifiers in UltimateAuth, detailing their types, management, and security considerations. * Add User Management Guide for UltimateAuth client This document provides a comprehensive guide on user management using the UltimateAuth client, covering user operations, profile management, lifecycle, and admin functionalities. * Add Authorization Guide for UltimateAuth client This guide details the management of roles, permissions, and access control using the UltimateAuth client, including core concepts, querying roles, creating and renaming roles, setting permissions, and user role assignments. * Add Credential Management Guide This document provides a comprehensive guide on managing user credentials with the UltimateAuth client, covering operations like changing, resetting, adding, and revoking credentials, along with security notes and summaries. * Add session security model documentation Document the hierarchical session security model of UltimateAuth, detailing the roles of Root, Chain, and Session in authentication, as well as security versioning, validation, device awareness, expiration, and revocation boundaries. * Document refresh token rotation security features Added comprehensive documentation on refresh token rotation, detailing its security features, rotation model, and invalid scenarios. * Add documentation for access token behavior in UltimateAuth Document the behavior and principles of access tokens in UltimateAuth, including token types, mode-dependent behavior, lifetime strategy, refresh interaction, claims model, and security implications. * Add detailed policy pipeline documentation This document provides a comprehensive overview of the multi-stage policy pipeline used in UltimateAuth for authorization decisions, detailing each step from context enrichment to final decision-making. * Create readme.md
1 parent d37fe48 commit e1feef1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+6088
-49
lines changed

‎docs/.gitkeep‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/content/auth-flows/device-management.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# 📱 Device Management
2+
3+
In UltimateAuth, devices are not an afterthought.
4+
5+
👉 They are a **first-class concept**
6+
7+
## 🧠 Why Device Matters
8+
9+
Most authentication systems ignore devices.
10+
11+
- A user logs in
12+
- A token is issued
13+
- Everything is treated the same
14+
15+
👉 This breaks down when you need:
16+
17+
- Multi-device control
18+
- Session visibility
19+
- Security enforcement
20+
21+
👉 UltimateAuth solves this with **device-aware authentication**
22+
23+
## 🧩 Core Concept: Chain = Device
24+
25+
In UltimateAuth:
26+
27+
👉 A **SessionChain represents a device**
28+
29+
```
30+
Device → Chain → Sessions
31+
```
32+
33+
Each chain:
34+
35+
- Is bound to a device
36+
- Groups sessions
37+
- Tracks activity
38+
39+
👉 A device is not inferred — it is explicitly modeled
40+
41+
## 🔗 What Defines a Device?
42+
43+
A chain includes:
44+
45+
- DeviceId
46+
- Platform (web, mobile, etc.)
47+
- Operating System
48+
- Browser
49+
- IP (optional binding)
50+
51+
👉 This forms a **device fingerprint**
52+
53+
## 🔄 Device Lifecycle
54+
55+
### 1️⃣ First Login
56+
57+
- New device detected
58+
- New chain is created
59+
60+
### 2️⃣ Subsequent Logins
61+
62+
- Same device → reuse chain
63+
- New device → new chain
64+
65+
👉 Device continuity is preserved
66+
67+
### 3️⃣ Activity (Touch)
68+
69+
- Chain `LastSeenAt` updated
70+
- `TouchCount` increases
71+
72+
👉 Tracks real usage
73+
74+
### 4️⃣ Token Rotation
75+
76+
- Session changes
77+
- Chain remains
78+
- `RotationCount` increases
79+
80+
👉 Device identity stays stable
81+
82+
### 5️⃣ Logout
83+
84+
- Session removed
85+
- Chain remains
86+
87+
👉 Device still trusted
88+
89+
### 6️⃣ Revoke
90+
91+
- Chain invalidated
92+
- All sessions removed
93+
94+
👉 Device trust is reset
95+
96+
<br>
97+
98+
## 🔐 Security Model
99+
100+
### 🔗 Device Binding
101+
102+
Sessions and tokens are tied to:
103+
104+
- Chain
105+
- Device context
106+
107+
👉 Prevents cross-device reuse
108+
109+
### 🔁 Rotation Tracking
110+
111+
Chains track:
112+
113+
- RotationCount
114+
- TouchCount
115+
116+
👉 Enables anomaly detection
117+
118+
### 🚨 Revoke Cascade
119+
120+
If a device is compromised:
121+
122+
- Entire chain can be revoked
123+
- All sessions invalidated
124+
125+
👉 Immediate containment
126+
127+
<br>
128+
129+
## ⚙️ Configuration
130+
131+
Device behavior is configurable via session options:
132+
133+
- Max chains per user
134+
- Max sessions per chain
135+
- Platform-based limits
136+
- Device mismatch behavior
137+
138+
👉 Fine-grained control for enterprise scenarios
139+
140+
<br>
141+
142+
## 🧠 Mental Model
143+
144+
If you remember one thing:
145+
146+
👉 Device = Chain
147+
👉 Not just metadata
148+
149+
## 📌 Key Takeaways
150+
151+
- Devices are explicitly modeled
152+
- Each device has its own chain
153+
- Sessions belong to chains
154+
- Security is enforced per device
155+
- Logout and revoke operate on device scope
156+
157+
## ➡️ Next Step
158+
159+
Continue to **Configuration & Extensibility**

‎docs/content/auth-flows/index.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# 🔐 Auth Flows
2+
3+
Authentication in UltimateAuth is not a single operation.
4+
5+
👉 It is a **flow-driven system**.
6+
7+
<br>
8+
9+
## 🧠 What is an Auth Flow?
10+
An auth flow represents a complete authentication operation, such as:
11+
12+
- Logging in
13+
- Refreshing a session
14+
- Logging out
15+
16+
Each flow:
17+
18+
- Has a defined lifecycle
19+
- Runs through the orchestration pipeline
20+
- Produces a controlled authentication outcome
21+
22+
👉 Instead of calling isolated APIs, you execute **flows**.
23+
24+
## 🔄 Why Flow-Based?
25+
Traditional systems treat authentication as:
26+
27+
- A login endpoint
28+
- A token generator
29+
- A cookie setter
30+
31+
👉 These approaches often lead to fragmented logic.
32+
33+
UltimateAuth solves this by:
34+
- Structuring authentication as flows
35+
- Enforcing a consistent execution model
36+
- Centralizing security decisions
37+
38+
<br>
39+
40+
## 🧩 What Happens During a Flow?
41+
Every flow follows the same pattern:
42+
```
43+
Flow → Context → Orchestrator → Authority → Result
44+
```
45+
46+
- The **flow** defines the intent
47+
- The **context** carries state
48+
- The **orchestrator** coordinates execution
49+
- The **authority** enforces rules
50+
51+
👉 This ensures consistent and secure behavior across all operations.
52+
53+
<br>
54+
55+
## 🔐 Types of Flows
56+
UltimateAuth provides built-in flows for common scenarios:
57+
58+
### 🔑 Login Flow
59+
Establishes authentication by:
60+
61+
- Validating credentials
62+
- Creating session hierarchy (root, chain, session)
63+
- Issuing tokens if required
64+
65+
👉 [Learn more](./login-flow.md)
66+
67+
### 🔄 Refresh Flow
68+
Extends an existing session:
69+
70+
- Rotates refresh tokens
71+
- Maintains session continuity
72+
- Applies sliding expiration
73+
74+
👉 [Learn more](./refresh-flow.md)
75+
76+
### 🚪 Logout Flow
77+
Terminates authentication:
78+
79+
- Revokes session(s)
80+
- Invalidates tokens
81+
- Supports device-level or global logout
82+
83+
👉 [Learn more](./logout-flow.md)
84+
85+
<br>
86+
87+
## 🧠 Supporting Concepts
88+
These flows operate on top of deeper system models:
89+
90+
### 🧬 Session Lifecycle
91+
92+
- Root → Chain → Session hierarchy
93+
- Device-aware session structure
94+
- Lifecycle management and revocation
95+
96+
👉 [Learn more](./session-lifecycle.md)
97+
98+
### 🎟 Token Behavior
99+
100+
- Access token vs refresh token
101+
- Opaque vs JWT
102+
- Mode-dependent behavior
103+
104+
👉 [Learn more](./token-behavior.md)
105+
106+
### 📱 Device Management
107+
108+
- Device binding
109+
- Multi-device sessions
110+
- Security implications
111+
112+
👉 [Learn more](./device-management.md)
113+
114+
<br>
115+
116+
## 🧠 Mental Model
117+
118+
If you remember one thing:
119+
120+
👉 **Authentication is not a single step**
121+
👉 **It is a controlled flow of state transitions**
122+
123+
## 📌 Key Takeaways
124+
125+
- Authentication is executed as flows
126+
- Each flow follows a consistent pipeline
127+
- Sessions and tokens are created as part of flows
128+
- Security is enforced centrally
129+
130+
---
131+
132+
## ➡️ Next Step
133+
134+
Start with the most important flow:
135+
136+
👉 Continue to **Login Flow**

0 commit comments

Comments
 (0)