Cline rules

1## Brief overview
2 
3This Cline rule file provides project context for an **ASP.NET Core 8.0 training lab application** designed to teach Microsoft Entra ID authentication and authorization concepts. The project is organized into two modules with four hands-on labs where students learn by configuration only—no coding required during labs. All code is prebuilt with a focus on token exploration, authorization patterns, and multi-tier authentication flows.
4 
5## Project structure
6 
7The repository is organized into three modules:
8 
9**Module 1: Authentication & Authorization Basics** (`src/Module1/`)
10- `WebAuthzDemo`: Main web application (Razor Pages) with authentication, token viewers, and protected API
11- `TokenInspector`: Class library for JWT decode/format helpers (shared across all modules)
12 
13**Module 2: Protected Web APIs & Cross-Tenant** (`src/Module2/`)
14- `Labs.Shared`: Common models, constants, and configuration classes
15- `Labs.MiddleTierApi`: Protected Web API with OBO flow to Microsoft Graph
16- `Labs.ClientWeb`: Razor Pages client calling the protected API
17- `Labs.CrossTenantDaemon`: Console daemon app for cross-tenant scenarios
18 
19**Module 3: Public Client Authentication** (`src/Module3/`)
20- `Labs.Cli`: Modern CLI tool demonstrating public client flows (PKCE and Device Code)
21 
22**Documentation structure**:
23- `docs/README.md`: Main course overview
24- `docs/Module1/README.md`: Module 1 overview
25- `docs/Module1/Lab1_Authentication.md`: Authentication lab (10-15 min)
26- `docs/Module1/Lab2_SimpleAuthorization.md`: Authorization lab (10-15 min)
27- `docs/Module2/README.md`: Module 2 overview
28- `docs/Module2/Lab3_ProtectedWebAPI.md`: Protected API + OBO lab (12-15 min)
29- `docs/Module2/Lab4_CrossTenantDaemon.md`: Cross-tenant daemon lab (12-15 min)
30- `docs/Module3/README.md`: Module 3 overview
31- `docs/Module3/Lab5_PublicClientCLI.md`: Public client CLI authentication lab (45-60 min)
32 
33**Scripts**: `scripts/setup.ps1` for generating configuration templates
34 
35## Tech stack requirements
36 
37- **.NET 8** and **ASP.NET Core**
38- **Microsoft.Identity.Web** and **Microsoft.Identity.Web.UI** packages
39- **Authorization Code + PKCE** flow for interactive login
40- **Microsoft Graph SDK** (optional) for delegated API calls
41- **Razor Pages** for UI (lightweight, instructor-friendly)
42- **Minimal APIs** or standard controllers for protected endpoints
43 
44## Lab objectives
45 
46**Module 1: Foundations**
47 
48**Lab 1 (Authentication):**
49- Sign in with Microsoft Entra ID
50- Explore ID token vs Access token differences
51- View claims in tabular format
52- Understand token lifetimes and renewal concepts
53- Simulate common errors (redirect URI mismatch, missing consent)
54 
55**Lab 2 (Authorization - Simplified):**
56- Understand the difference between authentication and authorization
57- Test authentication-only authorization (`[Authorize]` attribute)
58- Test local application-managed RBAC (self-assignment of Admin role)
59- Call Microsoft Graph API with delegated permissions (`User.Read` scope)
60- Understand that Entra ID provides identity while your app manages permissions
61 
62**Module 2: Advanced Scenarios**
63 
64**Lab 3 (Protected Web API + OBO Flow):**
65- Expose and protect custom API with custom scopes (`api.read`)
66- Understand token audience validation for APIs
67- Implement scope-based authorization in ASP.NET Core
68- Use On-Behalf-Of (OBO) flow to call Microsoft Graph from the API
69- Explore three-tier authentication (Client → API → Graph)
70- Compare delegated permissions vs custom API scopes
71 
72**Lab 4 (Cross-Tenant Daemon):**
73- Implement app-only (daemon) authentication with client credentials flow
74- Understand application permissions vs delegated permissions
75- Configure multi-tenant applications
76- Acquire tokens for multiple Entra ID tenants
77- Call Microsoft Graph without user context
78- Explore cross-tenant consent and security considerations
79 
80**Module 3: Public Client Authentication**
81 
82**Lab 5 (Public Client CLI):**
83- Understand why client secrets cannot be used in CLI/desktop/mobile apps
84- Configure public client app registration in Entra ID
85- Use Authorization Code + PKCE flow for interactive authentication
86- Use Device Code flow for limited-input scenarios
87- Explore token caching and security trade-offs for local storage
88- Call Microsoft Graph API from a CLI tool
89- Implement security best practices for public clients
90 
91## Key constraints
92 
93- **No coding by students**: All code must be prebuilt and functional
94- **Configuration only**: Students only update `appsettings.json` or environment variables with Client ID, Tenant ID, etc.
95- **Clear documentation**: Copy/paste ready instructions for app registration and API permissions
96- **Error simulation**: Include UI toggles to demonstrate common mistakes for teaching moments
97- **Security**: Never display refresh tokens; only explain them conceptually
98 
99## Authentication patterns
100 
101- Use **Microsoft.Identity.Web** patterns consistently throughout the application
102- Implement **Authorization Code + PKCE** (not implicit flow)
103- Configure via `appsettings.json`:
104  - `AzureAd:Instance`, `AzureAd:Domain`, `AzureAd:TenantId`, `AzureAd:ClientId`, `AzureAd:CallbackPath`
105- Maintain **HTTPS redirect URI consistency** across app configuration, README, and lab docs
106- Use `launchSettings.json` with consistent HTTPS port
107 
108## Authorization patterns
109 
110**Module 1 patterns:**
111- Define **named policies** for authorization requirements:
112  - `RequireLocalAdmin`: Checks local role store for "Admin" role
113- Apply `[Authorize]` attribute with or without policy names:
114  - `[Authorize]` - Authentication-only (baseline)
115  - `[Authorize(Policy = "RequireLocalAdmin")]` - Application-managed RBAC
116- Use **in-memory role store** (`LocalRoleService`) for demonstration:
117  - Maps user `oid` claim to application roles
118  - Thread-safe using `ConcurrentDictionary`
119  - Would use database in production
120- Provide **role management endpoints**:
121  - `POST /api/roles/assign-admin` - Self-assign Admin role
122  - `POST /api/roles/remove-admin` - Remove Admin role
123 
124**Module 2 patterns:**
125- **Custom API scopes**: Define and expose API-specific scopes (e.g., `api.read`)
126- **Scope-based authorization**: Validate scopes in access tokens with named policies
127  - `RequireApiReadScope`: Checks for `api.read` scope claim
128- **On-Behalf-Of (OBO) flow**: API exchanges user's access token for Graph token
129- **App-only authentication**: Client credentials flow for daemon apps
130- **Application permissions**: Tenant-wide permissions requiring admin consent
131- **Multi-tenant support**: Cross-tenant token acquisition and consent
132- Provide clear guidance when authorization fails with actionable error messages
133 
134## UI/UX priorities
135 
136- **Instructor-friendly**: Clean, simple UI focused on learning concepts
137- **Token exploration**: Dedicated pages for ID Token, Access Token, and Claims
138- **Pretty-print tokens**: Display header/payload/signature with key claims highlighted
139- **Help sidebars**: Include conceptual notes (Authentication vs Authorization, ID token vs Access token, Scopes vs Roles)
140- **External tools**: Provide "Copy token" button and "Open in jwt.ms" link
141- **Error visibility**: Surface clear error messages for teaching moments
142 
143## Development workflow
144 
145- **Build without manual edits**: App must run immediately after configuration
146- **Services encapsulation**: Use `TokenService` for token acquisition/decode, `GraphService` for Graph API calls
147- **JWT helpers**: Centralize token parsing in `TokenInspector/JwtTools.cs`
148- **Error handling**: Gracefully handle and display authorization failures with actionable guidance
149 
150## Documentation standards
151 
152- **Step-by-step instructions**: Numbered steps with exact portal actions
153- **Copy/paste ready**: Provide exact JSON for app roles, exact URIs for redirect configuration
154- **Troubleshooting section**: Cover common errors (AADSTS50011 redirect mismatch, missing consent, audience mismatch)
155- **Screenshot placeholders**: Include markdown image links with descriptive captions
156- **Teaching flow**: Guide instructors through logical progression (Sign In → ID Token → Access Token → Protected API)
157 
158## Security considerations
159 
160- **Refresh tokens**: Never display in UI; only explain concept and lifetime
161- **PII logging**: Set `EnablePiiLogging=false` in production
162- **Token redaction**: Safe redaction of signature section when displaying tokens
163- **HTTPS only**: Enforce HTTPS for all redirect URIs and local development
164 
165## Code organization principles
166 
167- Keep `Program.cs` clean with clear authentication and authorization setup
168- Encapsulate token operations in `TokenService`
169- Encapsulate Graph API calls in `GraphService`
170- Encapsulate local role management in `LocalRoleService`
171- Separate authorization policies in `Authorization/Policies.cs`
172- Use consistent naming: policy name `RequireLocalAdmin`
173- Group related pages: `Pages/Tokens/` for token viewers
174- Register `LocalRoleService` as singleton (static in-memory store)
175 
176## Quality standards
177 
178- All applications build and run without manual code edits after configuration
179- Clear, actionable error messages for authorization failures
180- **Module 1**: Three distinct authorization examples with clear learning goals:
181  1. Authentication-only (baseline)
182  2. Local application-managed roles (interactive self-assignment)
183  3. Delegated permissions to Microsoft Graph
184- **Module 2**: Advanced scenarios demonstrating real-world patterns:
185  1. Custom API protection with scopes
186  2. On-Behalf-Of (OBO) flow for API chaining
187  3. App-only authentication for background services
188  4. Cross-tenant authentication and consent
189- UI provides educational value for token exploration and authorization concepts
190- Interactive demonstrations show separation of identity (Entra ID) and permissions (app/API)
191- Documentation enables self-service setup by instructors
192- Module 1 requires minimal Azure configuration (User.Read is default)
193- Module 2 demonstrates enterprise-grade authentication patterns
194- All solutions use consistent architecture and coding patterns
195 
196## Updates to this document
197 
198- This project-overview.md file should be kept up to date as the poject evolves
199- Any large change to the project must be reflected in this document
200- Prefer to keep the current document structure and update the statements that need to be changed
201