You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: rewrite README with quick start, accurate links, and student instructions
- add 2-minute quick start section with start script usage
- fix exercise links to match actual file paths under workshop/guides/
- replace Spring Cloud Azure 7.2.0 with Spring Security OAuth2 Resource Server in tech stack
- add detailed repo structure with file descriptions
- add key design decisions section explaining dev profile behavior
- add workshop exercises table with durations and descriptions
📖 - Generated by Copilot
Copy file name to clipboardExpand all lines: README.md
+95-32Lines changed: 95 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: "MSAL Java Workshop: Entra ID Authentication with Angular SPA + Spring Boot API"
3
3
description: Workshop and sample applications demonstrating Microsoft Entra ID authentication with Angular 19 SPA and Spring Boot 3.4 API
4
-
ms.date: 2026-04-20
4
+
ms.date: 2026-04-21
5
5
---
6
6
7
7
## Architecture
@@ -29,45 +29,106 @@ The Angular SPA authenticates users via MSAL with Auth Code + PKCE flow. The Spr
29
29
30
30
The workshop centers on a Justice Evidence Portal: a secure application for managing case evidence files. Users authenticate through Entra ID, and the API enforces role-based access (CaseReader, CaseAdmin) before serving evidence documents from Azure Storage. External partners access the system as B2B guest users within the organization's tenant.
31
31
32
-
## Quickstart
32
+
## Getting Started
33
33
34
-
1.**Clone the repository**
34
+
### Prerequisites
35
+
36
+
| Tool | Version | Purpose |
37
+
|---|---|---|
38
+
| Node.js | 20 LTS or later | Angular SPA build and development |
39
+
| Java JDK | 17 or later | Spring Boot API compilation and runtime |
40
+
| Maven | 3.9 or later (auto-installed by start script) | Java dependency management and build |
41
+
| Azure CLI | 2.60 or later | Azure resource provisioning and deployment |
42
+
| VS Code | Latest | Recommended editor with extensions |
43
+
44
+
### Quick Start (Run Locally in 2 Minutes)
45
+
46
+
The sample apps work immediately without any Azure or Entra ID configuration. The `dev` profile serves 5 mock cases and permits all API requests so you can explore the code before setting up authentication.
47
+
48
+
1.**Clone the repository** (or click "Use this template" on GitHub):
2.**Configure app registrations**in Microsoft Entra ID. Follow [Exercise 1](workshop/exercises/exercise-01-app-registration.md) for step-by-step instructions.
55
+
2.**Start both apps**with a single command:
42
56
43
-
3.**Run locally** with the Angular dev server and Spring Boot API. Follow [Exercise 2](workshop/exercises/exercise-02-run-locally.md) for local setup.
57
+
**PowerShell (Windows):**
44
58
45
-
4.**Deploy to Azure** using Bicep templates and the Azure CLI. Follow [Exercise 4](workshop/exercises/exercise-04-deploy-to-azure.md) for deployment steps.
59
+
```powershell
60
+
.\scripts\start.ps1
61
+
```
46
62
47
-
## Prerequisites
63
+
**Bash (macOS/Linux):**
48
64
49
-
| Tool | Version | Purpose |
65
+
```bash
66
+
./scripts/start.sh
67
+
```
68
+
69
+
The start script automatically:
70
+
- Downloads and installs Maven if it is not found on your PATH
71
+
- Installs SPA npm dependencies if `node_modules` is missing
72
+
- Kills any previous instances on ports 4200 and 8080
73
+
- Starts the Spring Boot API (`http://localhost:8080`)
74
+
- Starts the Angular SPA (`http://localhost:4200`)
75
+
76
+
3.**Verify the API** returns mock data:
77
+
78
+
```bash
79
+
curl http://localhost:8080/api/cases
80
+
```
81
+
82
+
You should see 5 JSON case objects.
83
+
84
+
4.**Open the SPA** at [http://localhost:4200](http://localhost:4200) to see the Justice Evidence Portal landing page.
85
+
86
+
> **Note:** The "Sign In" button will fail until you complete Exercise 1 (Entra ID app registration). The API endpoints are fully functional without authentication in dev mode.
87
+
88
+
### Workshop Exercises
89
+
90
+
Follow these exercises in order for the full 3-hour workshop experience:
91
+
92
+
| Exercise | Duration | Description |
50
93
|---|---|---|
51
-
| Node.js | 20 LTS or later | Angular SPA build and development |
52
-
| Java JDK | 17 or later | Spring Boot API compilation and runtime |
53
-
| Maven | 3.9 or later | Java dependency management and build |
54
-
| Azure CLI | 2.60 or later | Azure resource provisioning and deployment |
55
-
| VS Code | Latest | Recommended editor with extensions |
94
+
|[Exercise 1: Configure App Registrations](workshop/guides/exercise-1-app-registrations.md)| 30 min | Create Entra ID app registrations for the SPA and API, configure scopes, roles, and update the SPA environment |
95
+
|[Exercise 2: Run SPA + API Locally](workshop/guides/exercise-2-run-locally.md)| 30 min | Sign in through the SPA, browse cases, download evidence, and inspect JWT tokens |
96
+
|[Exercise 3: Add Role-Protected Endpoint](workshop/guides/exercise-3-add-endpoint.md)| 20 min | Experience the RBAC cycle: 403 Forbidden, assign CaseAdmin role, re-authenticate, 201 Created |
97
+
|[Exercise 4: Deploy to Azure](workshop/guides/exercise-4-deploy-azure.md)| 20 min | Deploy both apps and infrastructure to Azure using Bicep, verify Managed Identity storage access |
98
+
99
+
For the full instructor delivery guide with 9-module schedule and presentation notes, see [workshop/README.md](workshop/README.md).
The full workshop includes presentations, exercises, and instructor notes covering Entra ID app registrations, local development, role-based access, and Azure deployment.
148
+
## Key Design Decisions
89
149
90
-
See [workshop/README.md](workshop/README.md) for the complete workshop guide and schedule.
150
+
-**Dev profile is open**: No authentication required to explore the API locally. JWT validation and `@PreAuthorize` enforcement activate in non-dev profiles.
151
+
-**Dual-mode storage**: `LocalStorageService` serves embedded PDFs in dev; `AzureBlobStorageService` uses Managed Identity in prod.
152
+
-**No storage keys or SAS tokens**: All Azure Blob access uses Managed Identity with Storage Blob Data Reader role.
153
+
-**Simplified workshop infrastructure**: B1 Basic App Service Plan (~$14/month) without Private Endpoints. Production hardening is documented separately.
91
154
92
155
## Production Hardening
93
156
94
-
The workshop deployment uses simplified infrastructure (B1 Basic plan, public endpoints) to keep costs low and focus on authentication concepts. For production deployments requiring network isolation with Private Endpoints, VNet integration, and Private DNS Zones, see the [Production Hardening Guide](docs/production-hardening.md).
157
+
The workshop deployment uses simplified infrastructure to keep costs low and focus on authentication concepts. For production deployments requiring network isolation with Private Endpoints, VNet integration, and Private DNS Zones, see the [Production Hardening Guide](docs/production-hardening.md).
0 commit comments