khayashi/headscale-entra-runbook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
3 commits 1 branch 0 tags 115 KiB
Find a file
Exact
Kevin Hayashi 7497185bc3 Add §1.1 per-site intake checklist, find-and-replace map, and Claude prompt 
Makes the template self-service: someone can hand the runbook to Claude
with the filled-in values and get a customer-specific version back.
Includes an intake checklist (identity/DNS/network/ops), a
generic-value -> meaning -> customer-value map, and a ready-to-paste
prompt. Bumped to v2.3.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-20 10:04:24 -07:00
.gitignore Initial commit: Headscale + Entra ID deployment runbook 2026-08-20 09:29:34 -07:00
headscale_entra_lab_runbook.md Add §1.1 per-site intake checklist, find-and-replace map, and Claude prompt 2026-08-20 10:04:24 -07:00
README.md Initial commit: Headscale + Entra ID deployment runbook 2026-08-20 09:29:34 -07:00

README.md

headscale-entra-runbook

A production-oriented deployment runbook for a self-hosted Headscale remote-access stack authenticated with Microsoft Entra ID (OIDC + MFA), managed through the Headplane web UI, and fronted by Caddy for HTTPS.

The full procedure lives in headscale_entra_lab_runbook.md — build it top to bottom to stand up the environment from scratch, including validation, rollback, backup, firewall, DNS, authentication, and hardening steps.

What this deploys

  • HS01 — Headscale control plane + public HTTPS endpoint (Caddy, Headplane web UI)
  • HSRTR01 — dedicated Tailscale subnet router advertising only authorized internal routes
  • Microsoft Entra ID as the OIDC identity provider, with MFA (Security Defaults or Conditional Access / P1)
  • Headplane web UI for day-to-day management (nodes, routes, users, keys, DNS, and ACL/grants in database mode)
  • Remote Windows Tailscale clients reaching approved internal resources over WireGuard

Stack (verify current versions at build time)

Ubuntu Server 26.04 LTS · Headscale · Tailscale · Caddy · Headplane · Microsoft Entra ID (OIDC v2.0)

How to use

  1. Read §0–§2 for versions, placeholders, and architecture.
  2. Fill in the placeholder table (§1) with the target environment's values.
  3. Work through the numbered sections in order.
  4. Sign off against the acceptance checklist (§27).

Security notes

  • The runbook uses placeholders (<TENANT_ID>, <CLIENT_ID>, <CLIENT_SECRET>, <TEST_RDS_IP>, etc.). Do not replace them with real secrets in a committed copy.
  • Never commit deployed configs, secrets, API keys, cookie secrets, databases, or backups — see .gitignore.
  • This is a template. For a specific engagement, keep the real per-customer values in a separate private location, not in this repo.
  • Recommended: keep this repo private; it contains internal network topology and design detail.

Layout

headscale_entra_lab_runbook.md   # the runbook (primary deliverable)
README.md                        # this file
.gitignore                       # keeps secrets / business docs / DBs out