Skip to content

Commit c977ebf

Browse files
christiannagelchristiannagel
committed
Migrate to Microsoft Entra External ID
Updated authentication across the Codebreaker platform to use Microsoft Entra External ID, replacing Azure AD B2C. Key changes include: - Updated configuration keys (`AzureAdB2C` → `EntraExternalId`) and endpoints (`*.b2clogin.com` → `*.ciamlogin.com`). - Added a migration guide (`azure-ad-b2c.md`) with steps, comparisons, and testing strategies. - Updated platform-specific configurations for Blazor, WPF, MAUI, Uno, and WinUI. - Enhanced security practices and troubleshooting for Entra External ID. - Deprecated Azure AD B2C references with a migration checklist. - Updated architecture diagrams and code snippets to reflect the new setup. - Adjusted CI/CD workflows and documentation links for the new authentication system. These changes ensure compatibility with modern authentication standards and streamline the developer experience.
1 parent 28a80c5 commit c977ebf

6 files changed

Lines changed: 818 additions & 1164 deletions

File tree

‎docs/authentication/README.md‎

Lines changed: 97 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,38 @@
22

33
This directory contains comprehensive documentation for authentication and authorization in the Codebreaker platform.
44

5+
## Current Implementation Status
6+
7+
**The Codebreaker project is migrating to Microsoft Entra External ID** for authentication. The documentation reflects the target implementation using Entra External ID.
8+
59
## Documentation Files
610

7-
### [Microsoft External ID Configuration Guide](./microsoft-external-id.md)
11+
### [Microsoft Entra External ID Configuration Guide](./microsoft-external-id.md) ✅ **Target Implementation**
812

9-
Comprehensive guide covering:
10-
- Gateway configuration with Microsoft External ID
13+
Comprehensive guide for the target authentication setup:
14+
- Gateway configuration with Microsoft Entra External ID
1115
- Token flow architecture between Gateway and APIs
1216
- Blazor Server and Blazor WebAssembly client configuration
1317
- Desktop client configuration (WPF, .NET MAUI, Uno Platform, WinUI)
1418
- Security best practices
1519
- Troubleshooting common issues
1620

17-
**When to use**: Reference this guide for detailed implementation instructions and comprehensive coverage of all authentication scenarios.
21+
**When to use**: Reference this guide for implementing and maintaining Microsoft Entra External ID authentication.
22+
23+
### [Azure AD B2C Configuration Guide](./azure-ad-b2c.md) ⚠️ **Legacy Reference**
24+
25+
Guide for the previous authentication implementation:
26+
- Legacy Azure AD B2C configuration
27+
- Migration considerations
28+
- Comparison with Entra External ID
29+
- Deprecation timeline
30+
31+
**When to use**: Reference this guide only for migration from Azure AD B2C or understanding legacy implementations.
1832

1933
### [Quick Start Guide](./quick-start.md)
2034

2135
Fast-track guide with:
22-
- 5-minute setup instructions
36+
- 5-minute setup instructions for Entra External ID
2337
- Common configuration patterns
2438
- Code snippets for each platform
2539
- Quick troubleshooting tips
@@ -39,7 +53,7 @@ Visual documentation with:
3953

4054
## Overview
4155

42-
The Codebreaker platform uses **Microsoft External ID** (formerly Azure AD B2C) for identity and access management across all client applications and backend services.
56+
The Codebreaker platform uses **Microsoft Entra External ID** for identity and access management across all client applications and backend services.
4357

4458
### Architecture
4559

@@ -59,7 +73,7 @@ The Codebreaker platform uses **Microsoft External ID** (formerly Azure AD B2C)
5973

6074
1. **Gateway (YARP Reverse Proxy)**
6175
- Entry point for all API requests
62-
- JWT token validation
76+
- JWT token validation using Microsoft Entra External ID
6377
- Authorization policy enforcement
6478
- Token forwarding to backend services
6579

@@ -78,58 +92,58 @@ The Codebreaker platform uses **Microsoft External ID** (formerly Azure AD B2C)
7892

7993
### For New Developers
8094

81-
1. Read the [Quick Start Guide](./quick-start.md) first
82-
2. Set up your development environment
95+
1. Read the [Microsoft Entra External ID Guide](./microsoft-external-id.md) for current implementation
96+
2. Use the [Quick Start Guide](./quick-start.md) for fast setup
8397
3. Configure authentication for your specific platform
8498
4. Test with the provided code snippets
8599

86-
### For Detailed Implementation
100+
### For Migration from Azure AD B2C
87101

88-
1. Review the [comprehensive guide](./microsoft-external-id.md)
89-
2. Understand the token flow architecture
90-
3. Follow platform-specific configuration sections
91-
4. Implement security best practices
102+
1. Review the [Azure AD B2C Migration Guide](./azure-ad-b2c.md)
103+
2. Understand the differences between B2C and External ID
104+
3. Update configuration endpoints and settings
105+
4. Test thoroughly before production deployment
92106

93107
## Platform Support Matrix
94108

95-
| Platform | Authentication Library | Status | Documentation |
96-
|----------|----------------------|--------|---------------|
97-
| Gateway (YARP) | Microsoft.Identity.Web | ✅ Configured | [Section](./microsoft-external-id.md#gateway-configuration) |
98-
| Game APIs | Microsoft.Identity.Web | ⚠️ Optional | [Section](./microsoft-external-id.md#game-apis-service-configuration) |
99-
| Blazor Server | Microsoft.Identity.Web | ✅ Supported | [Section](./microsoft-external-id.md#blazor-server-configuration) |
100-
| Blazor WASM | MSAL.js | ✅ Supported | [Section](./microsoft-external-id.md#blazor-webassembly-wasm-configuration) |
101-
| WPF | MSAL.NET | ✅ Supported | [Section](./microsoft-external-id.md#wpf-configuration) |
102-
| .NET MAUI | MSAL.NET | ✅ Supported | [Section](./microsoft-external-id.md#net-maui-configuration) |
103-
| Uno Platform | MSAL.NET | ✅ Supported | [Section](./microsoft-external-id.md#uno-platform-configuration) |
104-
| WinUI 3 | MSAL.NET | ✅ Supported | [Section](./microsoft-external-id.md#winui-3-configuration) |
109+
| Platform | Authentication Library | Current Status | Documentation |
110+
|----------|----------------------|----------------|---------------|
111+
| Gateway (YARP) | Microsoft.Identity.Web | ✅ Entra External ID | [Entra External ID](./microsoft-external-id.md#gateway-configuration) |
112+
| Game APIs | Microsoft.Identity.Web | ⚠️ Optional | [Entra External ID](./microsoft-external-id.md#game-apis-service-configuration) |
113+
| Blazor Server | Microsoft.Identity.Web | ✅ Supported | [Entra External ID](./microsoft-external-id.md#blazor-server-configuration) |
114+
| Blazor WASM | MSAL.js | ✅ Supported | [Entra External ID](./microsoft-external-id.md#blazor-webassembly-wasm-configuration) |
115+
| WPF | MSAL.NET | ✅ Supported | [Entra External ID](./microsoft-external-id.md#wpf-configuration) |
116+
| .NET MAUI | MSAL.NET | ✅ Supported | [Entra External ID](./microsoft-external-id.md#net-maui-configuration) |
117+
| Uno Platform | MSAL.NET | ✅ Supported | [Entra External ID](./microsoft-external-id.md#uno-platform-configuration) |
118+
| WinUI 3 | MSAL.NET | ✅ Supported | [Entra External ID](./microsoft-external-id.md#winui-3-configuration) |
105119

106120
## Configuration Overview
107121

108-
### Minimum Required Configuration
122+
### Target Implementation (Microsoft Entra External ID)
109123

110124
All platforms require:
111125

112-
1. **Azure AD B2C Tenant**: Microsoft Entra ID with External ID configured
126+
1. **Microsoft Entra External ID Tenant**: Configured with user flows
113127
2. **App Registration**: One per platform/client type
114128
3. **Redirect URIs**: Platform-specific callback URLs
115129
4. **Client ID**: Application (client) ID from app registration
116-
5. **Authority URL**: B2C tenant and policy endpoint
130+
5. **Authority URL**: External ID tenant endpoint (*.ciamlogin.com)
117131

118-
### Environment Variables
132+
### Environment Variables (Target)
119133

120134
Development:
121135
```bash
122-
AzureAdB2C__Instance=https://your-tenant.b2clogin.com
123-
AzureAdB2C__Domain=your-tenant.onmicrosoft.com
124-
AzureAdB2C__ClientId=<client-id>
125-
AzureAdB2C__SignUpSignInPolicyId=B2C_1_SUSI
136+
EntraExternalId__Instance=https://your-tenant.ciamlogin.com
137+
EntraExternalId__Domain=your-tenant.onmicrosoft.com
138+
EntraExternalId__TenantId=<tenant-id>
139+
EntraExternalId__ClientId=<client-id>
126140
```
127141

128142
Production (use Azure Key Vault):
129143
```bash
130144
az keyvault secret set --vault-name gateway-keyvault \
131-
--name "AzureAdB2C--ClientSecret" \
132-
--value "<client-secret>"
145+
--name "EntraExternalId--ClientSecret" \
146+
--value "<secure-password>"
133147
```
134148

135149
## Common Scenarios
@@ -140,46 +154,35 @@ az keyvault secret set --vault-name gateway-keyvault \
140154

141155
**Setup**:
142156
- Blazor Server or Blazor WASM
143-
- Microsoft External ID for authentication
157+
- Microsoft Entra External ID for authentication
144158
- Gateway forwards authenticated requests to APIs
145159

146-
**Documentation**: [Blazor Client Configuration](./microsoft-external-id.md#blazor-client-configuration)
160+
**Documentation**: [Entra External ID Blazor Configuration](./microsoft-external-id.md#blazor-client-configuration)
147161

148162
### Scenario 2: Desktop Application (WPF/MAUI)
149163

150164
**Use Case**: Native desktop/mobile application
151165

152166
**Setup**:
153167
- MSAL.NET for authentication
154-
- Native platform authentication UI
168+
- Microsoft Entra External ID authority
155169
- Direct API calls through Gateway
156170

157-
**Documentation**: [Desktop Client Configuration](./microsoft-external-id.md#desktop-client-configuration)
171+
**Documentation**: [Entra External ID Desktop Configuration](./microsoft-external-id.md#desktop-client-configuration)
158172

159173
### Scenario 3: Anonymous + Authenticated Users
160174

161175
**Use Case**: Game supporting both guest and registered players
162176

163177
**Setup**:
164178
- Anonymous user service for guest accounts
165-
- Optional authentication upgrade
179+
- Optional authentication upgrade to Entra External ID
166180
- Mixed authorization policies
167181

168182
**Documentation**:
169-
- [Identity Service README](../../src/services/identity/README.md)
183+
- [User Service README](../../src/services/user/README.md)
170184
- [Gateway Configuration](./microsoft-external-id.md#gateway-configuration)
171185

172-
### Scenario 4: API-to-API Communication
173-
174-
**Use Case**: Backend service calling another backend service
175-
176-
**Setup**:
177-
- Client credentials flow
178-
- Service principal authentication
179-
- Managed identity
180-
181-
**Documentation**: [Token Flow Architecture](./microsoft-external-id.md#token-flow-architecture)
182-
183186
## Security Considerations
184187

185188
### Critical Security Practices
@@ -191,51 +194,76 @@ az keyvault secret set --vault-name gateway-keyvault \
191194
5. **Rotate secrets regularly**: Set up automated secret rotation
192195
6. **Monitor authentication**: Log and alert on suspicious activity
193196

194-
See [Security Best Practices](./microsoft-external-id.md#security-best-practices) for detailed guidance.
197+
See [Entra External ID Security Guide](./microsoft-external-id.md#security-best-practices) for detailed guidance.
195198

196199
## Troubleshooting
197200

198-
### Quick Diagnostics
201+
### Quick Diagnostics (Target Implementation)
199202

200203
```bash
201-
# Check if token is valid
204+
# Check if Entra External ID token is valid
202205
curl -H "Authorization: Bearer <token>" https://your-gateway-url.com/games
203206

204207
# Decode JWT token
205208
# Visit https://jwt.ms and paste your token
206209

207-
# Test authentication endpoint
208-
curl https://your-tenant.b2clogin.com/your-tenant.onmicrosoft.com/B2C_1_SUSI/v2.0/.well-known/openid-configuration
210+
# Test Entra External ID authentication endpoint
211+
curl https://your-tenant.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration
209212
```
210213

211214
### Common Issues
212215

213-
1. **CORS errors**: See [Troubleshooting](./microsoft-external-id.md#2-cors-errors-in-browser)
214-
2. **Token validation failures**: See [Troubleshooting](./microsoft-external-id.md#1-the-access-token-provided-is-not-valid-error)
215-
3. **Redirect URI mismatch**: See [Troubleshooting](./microsoft-external-id.md#6-redirect-uri-mismatch)
216-
4. **Authentication state not persisting**: See [Troubleshooting](./microsoft-external-id.md#8-blazor-wasm-authentication-state-not-persisting)
216+
1. **CORS errors**: See [Entra External ID Troubleshooting](./microsoft-external-id.md#2-cors-errors-in-browser)
217+
2. **Token validation failures**: Check Entra External ID configuration
218+
3. **Redirect URI mismatch**: Verify Entra External ID app registration
219+
4. **Authority not found**: Check tenant ID and ciamlogin.com endpoint
220+
221+
Full troubleshooting guide: [Entra External ID Troubleshooting](./microsoft-external-id.md#troubleshooting)
222+
223+
## Migration from Azure AD B2C
224+
225+
### Migration Checklist
226+
227+
If migrating from Azure AD B2C to Microsoft Entra External ID:
228+
229+
1. **Setup External ID tenant**:
230+
- Create new Entra External ID tenant
231+
- Configure user flows
232+
- Create app registrations
233+
234+
2. **Update configuration**:
235+
- Change endpoints from *.b2clogin.com to *.ciamlogin.com
236+
- Update configuration sections from AzureAdB2C to EntraExternalId
237+
- Update authority URLs to include tenant ID
238+
239+
3. **Test migration**:
240+
- Test with non-production workloads first
241+
- Validate token compatibility
242+
- Verify all client platforms
217243

218-
Full troubleshooting guide: [Troubleshooting Section](./microsoft-external-id.md#troubleshooting)
244+
4. **Resources**:
245+
- [Microsoft Entra External ID Guide](./microsoft-external-id.md)
246+
- [Migration Reference](./azure-ad-b2c.md)
219247

220248
## Additional Resources
221249

222250
### Official Microsoft Documentation
223251

224-
- [Microsoft Identity Platform](https://learn.microsoft.com/en-us/azure/active-directory/develop/)
225-
- [Microsoft External ID](https://learn.microsoft.com/en-us/azure/active-directory-b2c/)
252+
- [Microsoft Entra External ID](https://learn.microsoft.com/en-us/entra/external-id/) ✅ **Current**
253+
- [Azure AD B2C Documentation](https://learn.microsoft.com/en-us/azure/active-directory-b2c/) ⚠️ **Legacy**
226254
- [MSAL.NET](https://learn.microsoft.com/en-us/azure/active-directory/develop/msal-overview)
227255
- [Microsoft.Identity.Web](https://learn.microsoft.com/en-us/azure/active-directory/develop/microsoft-identity-web)
228256

229257
### Codebreaker Resources
230258

231-
- [Identity Service](../../src/services/identity/)
232-
- [Gateway Service](../../src/services/gateway/)
259+
- [Gateway Service](../../src/services/gateway/) ✅ **Uses Entra External ID**
260+
- [User Service](../../src/services/user/)
233261
- [Game APIs](../../src/services/gameapis/)
234262
- [Main README](../../README.md)
235263

236264
### Sample Code
237265

238-
- [Microsoft Identity Samples](https://github.com/Azure-Samples?q=active-directory)
266+
- [Microsoft Entra External ID Samples](https://github.com/Azure-Samples?q=external-id) ✅ **Current**
239267
- [Codebreaker Backend Repository](https://github.com/CodebreakerApp/Codebreaker.Backend)
240268

241269
## Contributing
@@ -250,9 +278,9 @@ Found an issue or have a suggestion?
250278

251279
For questions or issues:
252280

253-
- **Documentation issues**: Open a GitHub issue
254-
- **Implementation questions**: Check [Troubleshooting](./microsoft-external-id.md#troubleshooting)
255-
- **Microsoft Identity issues**: See [Official Documentation](https://learn.microsoft.com/en-us/azure/active-directory/)
281+
- **Current implementation**: Use [Microsoft Entra External ID Guide](./microsoft-external-id.md)
282+
- **Migration questions**: See [Azure AD B2C Migration Guide](./azure-ad-b2c.md)
283+
- **Microsoft Identity issues**: See [Official Documentation](https://learn.microsoft.com/en-us/entra/external-id/)
256284

257285
## License
258286

0 commit comments

Comments
 (0)