Skip to content

Commit 6e17092

Browse files
Copilotchristiannagel
Copilot
and
christiannagel
committed
Add comprehensive Microsoft External ID authentication documentation
Co-authored-by: christiannagel <1908285+christiannagel@users.noreply.github.com>
1 parent ae3950f commit 6e17092

4 files changed

Lines changed: 2499 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -104,10 +104,35 @@ TODO: this test will move to this repo
104104
* Azure Storage message queue
105105
* Azure Key Vault
106106

107-
## Configuration authentication with Azure AD B2C
107+
## Authentication Configuration
108108

109-
With AADB2C, the API connectors need to be updated after publishing the backend, by:
109+
The Codebreaker platform uses **Microsoft External ID** (formerly Azure AD B2C) for authentication across all components.
110110

111-
- setting the Endpoint URLs to https://<<gateway>>/users/api-connectors/validate-before-user-creation and https://<<gateway>>/users/api-connectors/enrich-token
112-
- setting the basic-authentication password in the gateway-keyvault with the key AADB2C-ApiConnector-Password
113-
- and setting that password in tha API connectors
111+
### Documentation
112+
113+
- **[Complete Authentication Guide](docs/authentication/microsoft-external-id.md)**: Comprehensive documentation covering Gateway, APIs, Blazor, WPF, MAUI, Uno Platform, and WinUI configuration
114+
- **[Quick Start Guide](docs/authentication/quick-start.md)**: Fast-track setup with code snippets and common patterns
115+
- **[Authentication Overview](docs/authentication/README.md)**: Architecture overview and platform support matrix
116+
117+
### Quick Setup
118+
119+
For the Gateway service with Azure AD B2C:
120+
121+
1. Configure `appsettings.json`:
122+
```json
123+
{
124+
"AzureAdB2C": {
125+
"Instance": "https://<tenant>.b2clogin.com",
126+
"Domain": "<tenant>.onmicrosoft.com",
127+
"ClientId": "<client-id>",
128+
"SignUpSignInPolicyId": "B2C_1_SUSI"
129+
}
130+
}
131+
```
132+
133+
2. The API connectors need to be updated after publishing the backend:
134+
- Set Endpoint URLs to `https://<gateway>/users/api-connectors/validate-before-user-creation` and `https://<gateway>/users/api-connectors/enrich-token`
135+
- Store the basic-authentication password in `gateway-keyvault` with the key `AADB2C-ApiConnector-Password`
136+
- Set that password in the API connectors configuration
137+
138+
For detailed configuration instructions for all platforms, see the [authentication documentation](docs/authentication/).

‎docs/authentication/README.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# Authentication Documentation
2+
3+
This directory contains comprehensive documentation for authentication and authorization in the Codebreaker platform.
4+
5+
## Documentation Files
6+
7+
### [Microsoft External ID Configuration Guide](./microsoft-external-id.md)
8+
9+
Comprehensive guide covering:
10+
- Gateway configuration with Microsoft External ID
11+
- Token flow architecture between Gateway and APIs
12+
- Blazor Server and Blazor WebAssembly client configuration
13+
- Desktop client configuration (WPF, .NET MAUI, Uno Platform, WinUI)
14+
- Security best practices
15+
- Troubleshooting common issues
16+
17+
**When to use**: Reference this guide for detailed implementation instructions and comprehensive coverage of all authentication scenarios.
18+
19+
### [Quick Start Guide](./quick-start.md)
20+
21+
Fast-track guide with:
22+
- 5-minute setup instructions
23+
- Common configuration patterns
24+
- Code snippets for each platform
25+
- Quick troubleshooting tips
26+
27+
**When to use**: Use this guide when you need to quickly set up authentication or find a specific code snippet.
28+
29+
## Overview
30+
31+
The Codebreaker platform uses **Microsoft External ID** (formerly Azure AD B2C) for identity and access management across all client applications and backend services.
32+
33+
### Architecture
34+
35+
```
36+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
37+
│ Clients │ │ Gateway │ │ Backend │
38+
│ (Various) │────────▶│ (YARP) │────────▶│ Services │
39+
└──────────────┘ └──────────────┘ └──────────────┘
40+
• Blazor • JWT Validation • Game APIs
41+
• WPF • Token Forwarding • Ranking
42+
• MAUI • Authorization • Live
43+
• Uno Platform • API Routing • User Service
44+
• WinUI
45+
```
46+
47+
### Key Components
48+
49+
1. **Gateway (YARP Reverse Proxy)**
50+
- Entry point for all API requests
51+
- JWT token validation
52+
- Authorization policy enforcement
53+
- Token forwarding to backend services
54+
55+
2. **Backend Services**
56+
- Game APIs, Ranking, Live, User services
57+
- Can optionally validate tokens (defense in depth)
58+
- Extract user claims for business logic
59+
60+
3. **Client Applications**
61+
- Multiple platforms supported
62+
- MSAL for desktop/mobile authentication
63+
- Microsoft.Identity.Web for Blazor
64+
- Automatic token management
65+
66+
## Getting Started
67+
68+
### For New Developers
69+
70+
1. Read the [Quick Start Guide](./quick-start.md) first
71+
2. Set up your development environment
72+
3. Configure authentication for your specific platform
73+
4. Test with the provided code snippets
74+
75+
### For Detailed Implementation
76+
77+
1. Review the [comprehensive guide](./microsoft-external-id.md)
78+
2. Understand the token flow architecture
79+
3. Follow platform-specific configuration sections
80+
4. Implement security best practices
81+
82+
## Platform Support Matrix
83+
84+
| Platform | Authentication Library | Status | Documentation |
85+
|----------|----------------------|--------|---------------|
86+
| Gateway (YARP) | Microsoft.Identity.Web | ✅ Configured | [Section](./microsoft-external-id.md#gateway-configuration) |
87+
| Game APIs | Microsoft.Identity.Web | ⚠️ Optional | [Section](./microsoft-external-id.md#game-apis-service-configuration) |
88+
| Blazor Server | Microsoft.Identity.Web | ✅ Supported | [Section](./microsoft-external-id.md#blazor-server-configuration) |
89+
| Blazor WASM | MSAL.js | ✅ Supported | [Section](./microsoft-external-id.md#blazor-webassembly-wasm-configuration) |
90+
| WPF | MSAL.NET | ✅ Supported | [Section](./microsoft-external-id.md#wpf-configuration) |
91+
| .NET MAUI | MSAL.NET | ✅ Supported | [Section](./microsoft-external-id.md#net-maui-configuration) |
92+
| Uno Platform | MSAL.NET | ✅ Supported | [Section](./microsoft-external-id.md#uno-platform-configuration) |
93+
| WinUI 3 | MSAL.NET | ✅ Supported | [Section](./microsoft-external-id.md#winui-3-configuration) |
94+
95+
## Configuration Overview
96+
97+
### Minimum Required Configuration
98+
99+
All platforms require:
100+
101+
1. **Azure AD B2C Tenant**: Microsoft Entra ID with External ID configured
102+
2. **App Registration**: One per platform/client type
103+
3. **Redirect URIs**: Platform-specific callback URLs
104+
4. **Client ID**: Application (client) ID from app registration
105+
5. **Authority URL**: B2C tenant and policy endpoint
106+
107+
### Environment Variables
108+
109+
Development:
110+
```bash
111+
AzureAdB2C__Instance=https://your-tenant.b2clogin.com
112+
AzureAdB2C__Domain=your-tenant.onmicrosoft.com
113+
AzureAdB2C__ClientId=<client-id>
114+
AzureAdB2C__SignUpSignInPolicyId=B2C_1_SUSI
115+
```
116+
117+
Production (use Azure Key Vault):
118+
```bash
119+
az keyvault secret set --vault-name gateway-keyvault \
120+
--name "AzureAdB2C--ClientSecret" \
121+
--value "<client-secret>"
122+
```
123+
124+
## Common Scenarios
125+
126+
### Scenario 1: Web Application (Blazor)
127+
128+
**Use Case**: Public-facing web application with user authentication
129+
130+
**Setup**:
131+
- Blazor Server or Blazor WASM
132+
- Microsoft External ID for authentication
133+
- Gateway forwards authenticated requests to APIs
134+
135+
**Documentation**: [Blazor Client Configuration](./microsoft-external-id.md#blazor-client-configuration)
136+
137+
### Scenario 2: Desktop Application (WPF/MAUI)
138+
139+
**Use Case**: Native desktop/mobile application
140+
141+
**Setup**:
142+
- MSAL.NET for authentication
143+
- Native platform authentication UI
144+
- Direct API calls through Gateway
145+
146+
**Documentation**: [Desktop Client Configuration](./microsoft-external-id.md#desktop-client-configuration)
147+
148+
### Scenario 3: Anonymous + Authenticated Users
149+
150+
**Use Case**: Game supporting both guest and registered players
151+
152+
**Setup**:
153+
- Anonymous user service for guest accounts
154+
- Optional authentication upgrade
155+
- Mixed authorization policies
156+
157+
**Documentation**:
158+
- [Identity Service README](../../src/services/identity/README.md)
159+
- [Gateway Configuration](./microsoft-external-id.md#gateway-configuration)
160+
161+
### Scenario 4: API-to-API Communication
162+
163+
**Use Case**: Backend service calling another backend service
164+
165+
**Setup**:
166+
- Client credentials flow
167+
- Service principal authentication
168+
- Managed identity
169+
170+
**Documentation**: [Token Flow Architecture](./microsoft-external-id.md#token-flow-architecture)
171+
172+
## Security Considerations
173+
174+
### Critical Security Practices
175+
176+
1. **Never commit secrets**: Use Azure Key Vault or user secrets
177+
2. **Use HTTPS in production**: HTTP only for local development
178+
3. **Validate tokens at multiple layers**: Gateway AND API services
179+
4. **Implement proper CORS**: Don't use `AllowAnyOrigin()` in production
180+
5. **Rotate secrets regularly**: Set up automated secret rotation
181+
6. **Monitor authentication**: Log and alert on suspicious activity
182+
183+
See [Security Best Practices](./microsoft-external-id.md#security-best-practices) for detailed guidance.
184+
185+
## Troubleshooting
186+
187+
### Quick Diagnostics
188+
189+
```bash
190+
# Check if token is valid
191+
curl -H "Authorization: Bearer <token>" https://your-gateway-url.com/games
192+
193+
# Decode JWT token
194+
# Visit https://jwt.ms and paste your token
195+
196+
# Test authentication endpoint
197+
curl https://your-tenant.b2clogin.com/your-tenant.onmicrosoft.com/B2C_1_SUSI/v2.0/.well-known/openid-configuration
198+
```
199+
200+
### Common Issues
201+
202+
1. **CORS errors**: See [Troubleshooting](./microsoft-external-id.md#2-cors-errors-in-browser)
203+
2. **Token validation failures**: See [Troubleshooting](./microsoft-external-id.md#1-the-access-token-provided-is-not-valid-error)
204+
3. **Redirect URI mismatch**: See [Troubleshooting](./microsoft-external-id.md#6-redirect-uri-mismatch)
205+
4. **Authentication state not persisting**: See [Troubleshooting](./microsoft-external-id.md#8-blazor-wasm-authentication-state-not-persisting)
206+
207+
Full troubleshooting guide: [Troubleshooting Section](./microsoft-external-id.md#troubleshooting)
208+
209+
## Additional Resources
210+
211+
### Official Microsoft Documentation
212+
213+
- [Microsoft Identity Platform](https://learn.microsoft.com/en-us/azure/active-directory/develop/)
214+
- [Microsoft External ID](https://learn.microsoft.com/en-us/azure/active-directory-b2c/)
215+
- [MSAL.NET](https://learn.microsoft.com/en-us/azure/active-directory/develop/msal-overview)
216+
- [Microsoft.Identity.Web](https://learn.microsoft.com/en-us/azure/active-directory/develop/microsoft-identity-web)
217+
218+
### Codebreaker Resources
219+
220+
- [Identity Service](../../src/services/identity/)
221+
- [Gateway Service](../../src/services/gateway/)
222+
- [Game APIs](../../src/services/gameapis/)
223+
- [Main README](../../README.md)
224+
225+
### Sample Code
226+
227+
- [Microsoft Identity Samples](https://github.com/Azure-Samples?q=active-directory)
228+
- [Codebreaker Backend Repository](https://github.com/CodebreakerApp/Codebreaker.Backend)
229+
230+
## Contributing
231+
232+
Found an issue or have a suggestion?
233+
234+
1. Check existing [issues](https://github.com/CodebreakerApp/Codebreaker.Backend/issues)
235+
2. Open a new issue with details
236+
3. Submit a pull request with improvements
237+
238+
## Support
239+
240+
For questions or issues:
241+
242+
- **Documentation issues**: Open a GitHub issue
243+
- **Implementation questions**: Check [Troubleshooting](./microsoft-external-id.md#troubleshooting)
244+
- **Microsoft Identity issues**: See [Official Documentation](https://learn.microsoft.com/en-us/azure/active-directory/)
245+
246+
## License
247+
248+
This documentation is part of the Codebreaker project. See [LICENSE](../../LICENSE) for details.

0 commit comments

Comments
 (0)