Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,55 @@
# infra/authentik/bootstrap/blueprints/01-groups.yaml
#
# Authentik Blueprint — declarative group setup.
#
# Loaded by the worker on boot (mounted at /blueprints/toolctrl/01-groups.yaml
# via docker-compose.yml). Blueprints in /blueprints/* are evaluated by
# Authentik at startup and applied idempotently — re-applying the same
# blueprint is a no-op if entities already exist with the same `identifiers`.
#
# Spec: https://goauthentik.io/docs/customize/blueprints
#
# Groups created:
# - toolctrl-admin (attribute role=super_admin) — full Toolctrl super-admin
# - toolctrl-staff (attribute role=staff) — restricted admin (read +
# limited write per app rules)
# - toolctrl-users (attribute role=user) — placeholder for future
# customer-tenant-SSO (#66);
# no app uses this today
version: 1
metadata:
labels:
blueprints.goauthentik.io/instantiate: "true"
name: "Toolctrl Groups"
entries:
- identifiers:
name: toolctrl-admin
model: authentik_core.group
state: present
attrs:
is_superuser: false # we use the group attr, NOT Authentik's built-in superuser flag
attributes:
role: super_admin
toolctrl_managed: true
- identifiers:
name: toolctrl-staff
model: authentik_core.group
state: present
attrs:
is_superuser: false
attributes:
role: staff
toolctrl_managed: true
- identifiers:
name: toolctrl-users
model: authentik_core.group
state: present
attrs:
is_superuser: false
attributes:
role: user
toolctrl_managed: true
@@ -0,0 +1,111 @@
# infra/authentik/bootstrap/blueprints/02-policies.yaml
#
# Authentik Blueprint — security policies.
#
# Policies created:
# 1. toolctrl-password-policy
# - min 12 chars, mixed case + digit + symbol, no common-password dict
# - applied to the default password stage so every password set / reset
# goes through this gate
# 2. toolctrl-require-mfa-totp-for-admin (expression policy)
# - returns ak_message + denies the auth flow if a user in
# toolctrl-admin tries to authenticate without a verified TOTP factor
# - attached to the admin OIDC application access binding
# 3. toolctrl-bruteforce-lockout (reputation policy)
# - 5 failed authentication attempts in 1 minute from the same IP
# drops the reputation score below threshold and triggers a
# 15-minute IP lockout via the default reputation policy chain
#
# Note: the bind objects (PolicyBinding) are created against the default
# password stage and the admin application, but the admin-application binding
# only takes effect AFTER 03-application-toolctrl-admin.yaml has been
# applied (Authentik resolves cross-blueprint references on each apply pass;
# you may see a single retry on the first boot, which is normal).
version: 1
metadata:
labels:
blueprints.goauthentik.io/instantiate: "true"
name: "Toolctrl Policies"
entries:
# ---------- 1. Password policy ----------------------------------------
- identifiers:
name: toolctrl-password-policy
model: authentik_policies_password.passwordpolicy
state: present
attrs:
execution_logging: true
password_field: password
amount_uppercase: 1
amount_lowercase: 1
amount_digits: 1
amount_symbols: 1
length_min: 12
symbol_charset: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
error_message: "Password must be at least 12 characters and contain upper, lower, digit, and symbol."
check_static_rules: true
check_have_i_been_pwned: true
check_zxcvbn: true
zxcvbn_score_threshold: 3
hibp_allowed_count: 0
# Bind the password policy to the default password-change Flow so every
# new password / reset goes through it. Authentik 2026.x rejects binding
# a PolicyBinding.target to a Stage directly (Stage is not a
# PolicyBindingModel subclass); we target the Flow instead which IS a PBM
# and applies to all stages inside it. See B-007.
- identifiers:
target: !Find [authentik_flows.flow, [slug, default-password-change]]
policy: !Find [authentik_policies_password.passwordpolicy, [name, toolctrl-password-policy]]
order: 0
model: authentik_policies.policybinding
state: present
attrs:
enabled: true
# ---------- 2. Require MFA-TOTP for toolctrl-admin --------------------
- identifiers:
name: toolctrl-require-mfa-totp-for-admin
model: authentik_policies_expression.expressionpolicy
state: present
attrs:
execution_logging: true
expression: |
# Returns True (allow) only if the user is NOT in toolctrl-admin,
# OR the user has a verified TOTP factor attached.
# If they are in toolctrl-admin and have no TOTP, deny + message.
from authentik.stages.authenticator_totp.models import TOTPDevice
is_admin = ak_is_group_member(request.user, name="toolctrl-admin")
if not is_admin:
return True
has_totp = TOTPDevice.objects.filter(user=request.user, confirmed=True).exists()
if not has_totp:
ak_message("MFA-TOTP is required for super-admin accounts. Enroll a TOTP device first.")
return False
return True
# ---------- 3. Brute-force lockout (reputation policy) ----------------
- identifiers:
name: toolctrl-bruteforce-lockout
model: authentik_policies_reputation.reputationpolicy
state: present
attrs:
execution_logging: true
check_ip: true
check_username: true
# Reputation drops by 1 per failed login; -5 in 1min triggers the
# default flow-level deny. Authentik's built-in reputation policy chain
# applies a 15min cool-down before reputation recovers.
threshold: -5
# Bind the brute-force policy to the default authentication flow so it
# runs on every login attempt.
- identifiers:
target: !Find [authentik_flows.flow, [slug, default-authentication-flow]]
policy: !Find [authentik_policies_reputation.reputationpolicy, [name, toolctrl-bruteforce-lockout]]
order: 10
model: authentik_policies.policybinding
state: present
attrs:
enabled: true
@@ -0,0 +1,141 @@
# infra/authentik/bootstrap/blueprints/03-application-toolctrl-admin.yaml
#
# Authentik Blueprint — OIDC provider + application for the Toolctrl
# admin panel. Consumed by Phase 09 task #82 (admin-panel OIDC login).
#
# Creates:
# - OIDC Provider `toolctrl-admin-panel`
# * client_type=confidential
# * client_id from env (TOOLCTRL_ADMIN_OIDC_CLIENT_ID)
# * client_secret from env (TOOLCTRL_ADMIN_OIDC_CLIENT_SECRET)
# * scope_mappings: openid, email, profile, groups
# * subject_mode=hashed_user_id (avoids leaking the Authentik integer PK)
# * token TTLs: code 1m, access 10m, refresh 7d, id-token 10m
# * include_claims_in_id_token=true
# - Application `Toolctrl Admin Panel`
# * launchURL points at https://admin.boiler.saas-ctrl.com/
# * Access binding: only members of toolctrl-admin OR toolctrl-staff
#
# Also creates a DISABLED placeholder provider `toolctrl-tenant-sso` reserved
# for Backlog #66. It is created with enabled=false so it occupies the slug
# without affecting routing. When #66 is picked up, just flip `enabled` and
# add the per-tenant redirect_uri templates.
version: 1
metadata:
labels:
blueprints.goauthentik.io/instantiate: "true"
name: "Toolctrl Admin Panel OIDC"
context:
client_id: "%(env:TOOLCTRL_ADMIN_OIDC_CLIENT_ID)s"
client_secret: "%(env:TOOLCTRL_ADMIN_OIDC_CLIENT_SECRET)s"
redirect_uri: "%(env:TOOLCTRL_ADMIN_OIDC_REDIRECT_URI)s"
entries:
# ---------- Signing key (use the bundled self-signed by default) -----
# Authentik ships a `authentik Self-signed Certificate` after install; we
# reference it by name so the blueprint applies cleanly on a fresh boot.
# ---------- OIDC Provider: toolctrl-admin-panel ----------------------
- identifiers:
name: toolctrl-admin-panel
model: authentik_providers_oauth2.oauth2provider
state: present
attrs:
client_type: confidential
client_id: !Context client_id
client_secret: !Context client_secret
authorization_flow: !Find [authentik_flows.flow, [slug, default-provider-authorization-implicit-consent]]
authentication_flow: !Find [authentik_flows.flow, [slug, default-authentication-flow]]
invalidation_flow: !Find [authentik_flows.flow, [slug, default-provider-invalidation-flow]]
property_mappings:
- !Find [authentik_providers_oauth2.scopemapping, [scope_name, openid]]
- !Find [authentik_providers_oauth2.scopemapping, [scope_name, email]]
- !Find [authentik_providers_oauth2.scopemapping, [scope_name, profile]]
property_mappings_group:
- !Find [authentik_providers_oauth2.scopemapping, [scope_name, openid]]
signing_key: !Find [authentik_crypto.certificatekeypair, [name, authentik Self-signed Certificate]]
sub_mode: hashed_user_id
include_claims_in_id_token: true
issuer_mode: per_provider
# Authentik 2026.x changed redirect_uris from a string to a list of
# {matching_mode, url} dicts (RedirectURI dataclass). See B-007.
redirect_uris:
- matching_mode: strict
url: !Context redirect_uri
# Short-lived auth code + access token; longer refresh window for
# admin-panel sessions (operator can revoke in Authentik UI).
access_code_validity: minutes=1
access_token_validity: minutes=10
refresh_token_validity: days=7
# ---------- Application: Toolctrl Admin Panel -------------------------
- identifiers:
slug: toolctrl-admin-panel
model: authentik_core.application
state: present
attrs:
name: "Toolctrl Admin Panel"
provider: !Find [authentik_providers_oauth2.oauth2provider, [name, toolctrl-admin-panel]]
meta_launch_url: "https://admin.boiler.saas-ctrl.com/"
meta_description: "Toolctrl admin panel — super-admin + staff console"
policy_engine_mode: any
open_in_new_tab: false
# ---------- Access bindings: admin OR staff group --------------------
- identifiers:
target: !Find [authentik_core.application, [slug, toolctrl-admin-panel]]
group: !Find [authentik_core.group, [name, toolctrl-admin]]
order: 0
model: authentik_policies.policybinding
state: present
attrs:
enabled: true
- identifiers:
target: !Find [authentik_core.application, [slug, toolctrl-admin-panel]]
group: !Find [authentik_core.group, [name, toolctrl-staff]]
order: 10
model: authentik_policies.policybinding
state: present
attrs:
enabled: true
# ---------- MFA-TOTP-for-admin binding on the application -----------
- identifiers:
target: !Find [authentik_core.application, [slug, toolctrl-admin-panel]]
policy: !Find [authentik_policies_expression.expressionpolicy, [name, toolctrl-require-mfa-totp-for-admin]]
order: 20
model: authentik_policies.policybinding
state: present
attrs:
enabled: true
# ---------- DISABLED placeholder: toolctrl-tenant-sso (#66) ---------
- identifiers:
name: toolctrl-tenant-sso
model: authentik_providers_oauth2.oauth2provider
state: present
attrs:
client_type: confidential
# Sentinel values; #66 will rewrite these.
client_id: "toolctrl-tenant-sso-placeholder"
client_secret: "placeholder-do-not-use"
authorization_flow: !Find [authentik_flows.flow, [slug, default-provider-authorization-implicit-consent]]
authentication_flow: !Find [authentik_flows.flow, [slug, default-authentication-flow]]
invalidation_flow: !Find [authentik_flows.flow, [slug, default-provider-invalidation-flow]]
signing_key: !Find [authentik_crypto.certificatekeypair, [name, authentik Self-signed Certificate]]
sub_mode: hashed_user_id
include_claims_in_id_token: true
issuer_mode: per_provider
# Authentik has no `enabled` flag at the provider level; we keep this
# provider un-attached to any Application so it has no live route.
# 2026.x requires redirect_uris even on unattached providers — use a
# non-routable placeholder. #66 will rewrite when tenant SSO lands.
redirect_uris:
- matching_mode: strict
url: "https://placeholder.invalid/oidc/callback"
access_code_validity: minutes=1
access_token_validity: minutes=10
refresh_token_validity: days=7
@@ -0,0 +1,105 @@
#!/usr/bin/env bash
# infra/authentik/bootstrap/bootstrap.sh
#
# Idempotent post-deploy bootstrap. Waits for the Authentik server to become
# ready, then ensures the project blueprints (./blueprints/*.yaml) are loaded
# and applied. The blueprint files themselves are also mounted into the
# server/worker containers via docker-compose.yml — the worker auto-applies
# them at startup. This script is a belt-and-braces re-trigger that:
# 1. polls /-/health/ready/ until it returns 200,
# 2. triggers /api/v3/managed/blueprints/<id>/apply/ for every blueprint
# so they re-apply immediately rather than waiting for the next worker
# tick,
# 3. prints the operator-actionable next steps (rotate bootstrap token,
# enable MFA on the admin account, etc.).
#
# Run this from the operator's machine OR inside a Coolify post-deploy hook:
#
# export AUTHENTIK_BASE_URL=https://auth.boiler.saas-ctrl.com
# export AUTHENTIK_BOOTSTRAP_TOKEN=$(cat ~/.cli-tokens/authentik-bootstrap)
# bash infra/authentik/bootstrap/bootstrap.sh
set -Eeuo pipefail
: "${AUTHENTIK_BASE_URL:?AUTHENTIK_BASE_URL must be set (e.g. https://auth.boiler.saas-ctrl.com)}"
: "${AUTHENTIK_BOOTSTRAP_TOKEN:?AUTHENTIK_BOOTSTRAP_TOKEN must be set (see .env.example)}"
WAIT_MAX_SECONDS="${WAIT_MAX_SECONDS:-300}"
WAIT_INTERVAL_SECONDS="${WAIT_INTERVAL_SECONDS:-5}"
log() { printf "\033[1;34m[authentik-bootstrap]\033[0m %s\n" "$*"; }
err() { printf "\033[1;31m[authentik-bootstrap:ERROR]\033[0m %s\n" "$*" >&2; }
die() { err "$*"; exit 1; }
# ----------------------------------------------------------------------------
# Step 1: wait for /-/health/ready/
# ----------------------------------------------------------------------------
log "waiting for ${AUTHENTIK_BASE_URL}/-/health/ready/ (timeout ${WAIT_MAX_SECONDS}s)"
deadline=$(( $(date +%s) + WAIT_MAX_SECONDS ))
while true; do
if curl -fsS -o /dev/null -w "%{http_code}" "${AUTHENTIK_BASE_URL}/-/health/ready/" | grep -q "^200$"; then
log "server ready"
break
fi
if [[ $(date +%s) -ge ${deadline} ]]; then
die "timed out waiting for /-/health/ready/"
fi
sleep "${WAIT_INTERVAL_SECONDS}"
done
# ----------------------------------------------------------------------------
# Step 2: list blueprints and trigger re-apply
# ----------------------------------------------------------------------------
auth_header="Authorization: Bearer ${AUTHENTIK_BOOTSTRAP_TOKEN}"
log "listing managed blueprints"
blueprints_json="$(curl -fsS -H "${auth_header}" "${AUTHENTIK_BASE_URL}/api/v3/managed/blueprints/?page_size=200")" || die "blueprint listing failed (check AUTHENTIK_BOOTSTRAP_TOKEN)"
# Extract pk for any blueprint whose `path` starts with /blueprints/toolctrl/.
ids="$(printf "%s" "${blueprints_json}" \
| python3 -c 'import sys, json; data=json.load(sys.stdin); [print(b["pk"]) for b in data.get("results", []) if b.get("path","").startswith("/blueprints/toolctrl/")]')"
if [[ -z "${ids}" ]]; then
log "no /blueprints/toolctrl/* blueprints found yet — the worker has not picked them up"
log "this is expected on the very first boot; the worker auto-discovers them within ~30s"
log "re-run this script in 1 minute to apply explicitly"
exit 0
fi
# ----------------------------------------------------------------------------
# Step 3: apply each blueprint
# ----------------------------------------------------------------------------
for id in ${ids}; do
log "applying blueprint ${id}"
curl -fsS -X POST -H "${auth_header}" "${AUTHENTIK_BASE_URL}/api/v3/managed/blueprints/${id}/apply/" \
-o /dev/null \
|| err "apply failed for blueprint ${id} (will be retried by the worker)"
done
log "bootstrap complete"
cat <<'EONOTE'
----------------------------------------------------------------------
NEXT STEPS (operator)
----------------------------------------------------------------------
1. Log into https://auth.boiler.saas-ctrl.com using AUTHENTIK_BOOTSTRAP_EMAIL
+ AUTHENTIK_BOOTSTRAP_PASSWORD. The first login forces a password change.
2. In the Authentik UI, enroll TOTP for your account
(User Settings -> Authenticators -> Set up TOTP). Required because
the toolctrl-require-mfa-totp-for-admin policy denies access to the
admin OIDC application without a verified TOTP device.
3. Rotate AUTHENTIK_BOOTSTRAP_TOKEN — it grants full admin-API access
and is no longer needed after this bootstrap. Generate a fresh
personal admin token instead, and store it in Coolify-Vault.
4. Add real human admins by creating users in the Authentik UI and
adding them to the `toolctrl-admin` group. Force TOTP enrollment
on each.
5. Verify OIDC discovery from the admin-panel side once #82 is wired:
curl -fsS https://auth.boiler.saas-ctrl.com/application/o/toolctrl-admin-panel/.well-known/openid-configuration | jq .issuer
----------------------------------------------------------------------
EONOTE