feat(spa): opt-in 'https' nx serve config for dev-server TLS
Entra refuses http: redirect URIs for any host other than localhost,
which blocked the ADR-0030 dockerised dev mode the moment a developer
tried to share the stack with another teammate via a hostname (e.g.
apf-portal.dev.local). Add an opt-in 'https' Nx serve configuration
on both SPAs so the dev-server can terminate TLS using a mkcert cert,
and let the apps Compose profile pick the configuration via an env
var so behaviour stays unchanged by default.
- apps/portal-{shell,admin}/project.json: new https configuration
inheriting development + ssl/sslKey/sslCert at .secrets/dev-tls.*.
- infra/local/dev.compose.yml: shell + admin commands gain
--configuration=${NX_SERVE_CONFIGURATION:-development}, interpolated
from infra/local/.env at parse time.
- infra/local/.env.example: NX_SERVE_CONFIGURATION block + rationale.
- apps/portal-bff/.env.example: comment block above the ENTRA_*_
REDIRECT_URI defaults shows the https hostname override pattern and
reminds that each URI must be registered Entra-side.
- infra/README.md: new HTTPS dev-server setup subsection covering
mkcert install, cert generation, the .secrets/ convention, the
Entra step, and how to flip NX_SERVE_CONFIGURATION on.
Native WSL / localhost is unaffected: defaultConfiguration stays
development, no SSL files required, existing Entra localhost URIs
work as before. BFF stays plain HTTP behind the SPA proxy.
This commit is contained in:
@@ -226,6 +226,50 @@ How it works (see [ADR-0030](../docs/decisions/0030-dockerised-dev-mode.md)):
|
||||
|
||||
The three dev modes (native `nx serve`, devcontainer, this `apps` profile) and when to use each are summarised in [docs/setup/01-dev-debian-vm-setup.md](../docs/setup/01-dev-debian-vm-setup.md).
|
||||
|
||||
### HTTPS dev-server setup — remote-browser access via a hostname
|
||||
|
||||
By default the dev-servers serve plain HTTP — fine when the browser is on the same host as the BFF (`http://localhost:4200/`), which is also the only HTTP origin Entra accepts as a redirect URI. The moment you access the SPA over a **hostname** (e.g. `apf-portal.dev.local`, useful when the browser sits on a workstation and the stack runs on a shared / per-dev VM), Entra refuses the `http:` redirect URI and the dev-servers must terminate TLS.
|
||||
|
||||
The setup is one-time per dev:
|
||||
|
||||
1. **Install [mkcert](https://github.com/FiloSottile/mkcert)** on your workstation (the machine where the browser runs) and bootstrap its local CA:
|
||||
|
||||
```bash
|
||||
# Debian / WSL Ubuntu:
|
||||
sudo apt install -y libnss3-tools
|
||||
# macOS:
|
||||
# brew install mkcert nss
|
||||
# Windows (PowerShell, choco):
|
||||
# choco install mkcert
|
||||
mkcert -install
|
||||
```
|
||||
|
||||
2. **Generate the cert** for the hostname you registered in your `/etc/hosts` and in Entra. From the repo root on your workstation:
|
||||
|
||||
```bash
|
||||
mkdir -p .secrets
|
||||
mkcert -key-file .secrets/dev-tls.key -cert-file .secrets/dev-tls.pem \
|
||||
apf-portal.dev-jg.local # ← replace with YOUR hostname
|
||||
```
|
||||
|
||||
`.secrets/` is git-ignored; the bind-mount in the `apps` profile (the repo at `/workspace`) makes the files visible inside the containers at the path the `https` configuration expects.
|
||||
|
||||
3. **Update `apps/portal-bff/.env`** so the BFF tells Entra the matching HTTPS URIs — see the redirect-URI block in [`apps/portal-bff/.env.example`](../apps/portal-bff/.env.example) for the override pattern. The same URIs must be registered in your Entra app registration's "Redirect URIs" list (the BFF only sends one of them per auth request; Entra validates it is on the list).
|
||||
|
||||
4. **Enable the `https` Nx serve configuration** for the compose dev-servers by adding to `infra/local/.env`:
|
||||
|
||||
```env
|
||||
NX_SERVE_CONFIGURATION=https
|
||||
```
|
||||
|
||||
The compose command resolves `--configuration=${NX_SERVE_CONFIGURATION:-development}` at parse time, so the SPAs pick up the `https` config defined in `apps/portal-shell/project.json` and `apps/portal-admin/project.json`. The BFF stays HTTP behind the proxy — only the public origin is HTTPS.
|
||||
|
||||
5. `./infra/local/dev.sh up apps` → browser opens `https://apf-portal.dev-jg.local:4200/`. No cert warning (mkcert's CA is trusted by the workstation after step 1).
|
||||
|
||||
Native `nx serve` (WSL / localhost) is **unaffected** — it keeps using the `development` configuration by default, no SSL required, and the `localhost` URIs registered in Entra still work.
|
||||
|
||||
When real DNS + corp-CA-signed certs arrive, the hostname can be reused as-is (Entra registrations are literal strings — they don't care who signs the cert). Drop the cert files back into `.secrets/` and remove the mkcert step.
|
||||
|
||||
### Service endpoints (defaults)
|
||||
|
||||
| Service | Host port | Purpose |
|
||||
|
||||
Reference in New Issue
Block a user