Triển khai Authentik + SSO
Quản lý định danh và đăng nhập một lần (SSO) tập trung.
Bối cảnh & Lý do triển khai
Không có SSO, mỗi service (Grafana, Gitea, Harbor, Vaultwarden...) có tài khoản riêng biệt. Khi nhân viên nghỉ việc phải xóa tài khoản thủ công từng service — dễ bỏ sót dẫn đến tài khoản "ma" tồn tại mãi. Authentik là điểm kiểm soát danh tính duy nhất: disable 1 tài khoản là revoke toàn bộ.
| Mục | Nội dung |
|---|---|
| Ứng dụng trong DN | Centralized user lifecycle management, onboarding/offboarding tức thì, audit log truy cập tất cả service |
| Tác dụng chính | SSO cho Grafana/Gitea/Harbor/NetBox qua OIDC; RADIUS outpost cho VPN (Mailu dùng tài khoản nội bộ, không qua Authentik) |
| Nếu không triển khai | Quản lý tài khoản riêng lẻ, nguy cơ tài khoản mồ côi, không có audit trail thống nhất |
| Các service phụ thuộc vào đây | Grafana, Gitea, Harbor, NetBox, Headscale |
| Trường | Giá trị |
|---|---|
| VMID | 234 |
| Hostname | authentik |
| IP | 10.11.25.40/24 |
| Gateway | 10.11.25.1 |
| DNS | 10.11.45.53 (Pi-hole VM247) |
| VLAN | VLAN_SEC (tag 25) |
| Node PVE | node1 (10.11.45.210) |
| vCPU | 4 |
| RAM | 4 GB |
| Disk | 50 GB (Ceph pool vm-ceph) |
| OS | Ubuntu Server 24.04 LTS |
| Cluster | HOATRANHUB (PVE 9.2.20) |
Danh sách máy chủ & IP liên quan
Bảng dưới liệt kê các máy chủ mà bài này tạo hoặc kết nối tới. Địa chỉ, VMID, VLAN và node lấy từ bảng quy hoạch chung của lab, dùng thống nhất cho cả bộ bài lab.
| Máy chủ | IP | VLAN · Node | Vai trò trong bài này |
|---|---|---|---|
| authentik (Authentik SSO) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | Máy chủ của bài — Ubuntu 24.04, Docker Compose chạy Authentik 2026.8.4 (server, worker, PostgreSQL); web UI HTTP cổng 9000, HTTPS cổng 9443. |
| node1 (Proxmox VE) | 10.11.45.210 | 45 (MGMT) · cluster HOATRANHUB | Node Proxmox chứa VM234; tạo VM và chạy vzdump thủ công tại đây; node1–node4 là Redirect URI (https://nodeN.hoatranlabs.local:8006) của realm OpenID Connect Proxmox (mục 8.4, bài 08). |
| pihole (Pi-hole DNS) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | DNS bắt buộc của VM234 (nameserver trong netplan) và nơi có bản ghi authentik.hoatranlabs.local trỏ về 10.11.25.40 (bài 12). |
| step-ca (step-CA PKI) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Tùy chọn: cấp cert TLS bằng step ca certificate cho HTTPS cổng 9443; chưa có thì dùng self-signed tạm (bài 13). |
| pbs01 (PBS Primary) · VM101 | 10.11.45.17 | 45 (MGMT) · node4 | Nhận backup VM234: storage pbs-primary, namespace st-20, lịch 03:00, mode Snapshot, retention do Prune Job trên PBS quản lý (bài 04). |
| FortiGate (firewall) | 10.100.100.1 | Quản trị 10.100.100.0/24 · thiết bị mạng | Rule Allow-Authentik-Admin (cổng 9000, 9443) từ VLAN MGMT/SEC và Allow-Authentik-SSO (cổng 9443) từ VLAN SRV/DMZ/STORAGE tới Authentik. |
| mailu (Mailu Mail Server) · VM246 | 10.11.35.46 | 35 (DMZ) · node2 | Tùy chọn: relay SMTP cổng 587 STARTTLS gửi thông báo của Authentik; Mailu dùng tài khoản nội bộ, không dùng SSO hay LDAP của Authentik (bài 16). |
| grafana (Grafana + Uptime Kuma + Gotify) · VM236 | 10.11.45.36 | 45 (MGMT) · node2 | Ứng dụng OIDC mẫu: provider grafana-oidc, redirect URI :3000/login/generic_oauth, cấu hình [auth.generic_oauth] trỏ về cổng 9443 (bài 15). |
| harbor (Harbor Registry) · VM239 | 10.11.45.39 | 45 (MGMT) · node2 | Đăng nhập SSO bằng OIDC; redirect URI /c/oidc/callback, cấu hình tại Administration → Configuration → Auth (bài 21). |
| gitea (Gitea + Actions) · VM240 | 10.11.45.40 | 45 (MGMT) · node2 | Đăng nhập SSO bằng OIDC (OAuth2); redirect URI /user/oauth2/authentik/callback, cấu hình tại Authentication Sources (bài 22). |
| netbox (NetBox IPAM) · VM245 | 10.11.45.45 | 45 (MGMT) · node2 | Đăng nhập SSO bằng OIDC (Social Auth) trên cổng 8080; cấu hình REMOTE_AUTH_BACKEND trong configuration.py (bài 23). |
| wazuh-siem (Wazuh SIEM) · VM280 | 10.11.45.25 | 45 (MGMT) · node1 | Có trong bảng tích hợp SSO: Wazuh 4.9+ hỗ trợ OIDC/SAML qua OpenSearch Security (bài 17). |
Gateway của mỗi VLAN là địa chỉ .1. Tên DNS nội bộ do Pi-hole phân giải (bài 12). Tên in đậm là hostname; FQDN = hostname + .hoatranlabs.local.
Phụ thuộc (Dependencies)
Pi-hole VM247 (10.11.45.53) — BẮT BUỘC: Authentik cần DNS resolve để hoạt động đúng
step-CA VM242 (10.11.25.42) — TÙY CHỌN: cấp TLS cert nội bộ cho HTTPS port 9443
PBS VM101 (10.11.45.17) — cần có trước khi cấu hình backup job
FortiGate (10.100.100.1) — mở port 9000/9443 cho các VLAN truy cập SSO redirect
Thứ tự triển khai khuyến nghị:
- Pi-hole (VM247) — DNS nội bộ
- PBS (VM101) — backup
- step-CA (VM242) — PKI nội bộ (nếu muốn TLS hợp lệ ngay)
- Authentik SSO (VM234) ← file này
- Tích hợp từng service: Grafana → Harbor → Gitea → NetBox
Tổng Quan
Vai trò trong hạ tầng HOATRANLABS · Kiến trúc
Authentik là Identity Provider (IdP) mã nguồn mở, cung cấp:
- SSO (Single Sign-On) qua giao thức OIDC/OAuth2 và SAML 2.0
- MFA (Multi-Factor Authentication) với TOTP, WebAuthn, Duo
- Social Login tích hợp Google, GitHub, Microsoft, v.v.
- LDAP Provider cho các ứng dụng chỉ hỗ trợ LDAP (một số legacy app; Mailu không dùng, xem bài 16)
- Proxy Provider cho các ứng dụng không có tính năng xác thực riêng
Vai trò trong hạ tầng HOATRANLABS
Sau khi Authentik được deploy, tất cả service nội bộ đều dùng Authentik làm nguồn xác thực duy nhất:
| Service | Giao thức | VLAN |
|---|---|---|
| Grafana | OIDC | VLAN_MGMT |
| Harbor | OIDC | VLAN_MGMT |
| Gitea | OIDC | VLAN_MGMT |
| NetBox | OIDC | VLAN_MGMT |
| Proxmox | OIDC | VLAN_MGMT |
Kiến trúc
[Người dùng / Service]
│ HTTPS redirect đến SSO
▼
[VM234 authentik - VLAN_SEC 10.11.25.40]
┌──────────────────────────────────────────┐
│ authentik-server (web UI + API :9000) │
│ authentik-worker (xử lý background) │
│ PostgreSQL (DB, cache, session) │
└──────────────────────────────────────────┘
│ OIDC/SAML callback
▼
[Service nhận token và cho phép đăng nhập]
Thông Số VM
| Thông số | Giá trị |
|---|---|
| VMID | 234 |
| Hostname | authentik |
| vCPU | 4 |
| RAM | 4 GB (4096 MiB) |
| Disk | 50 GB (vm-ceph RBD) |
| OS | Ubuntu Server 24.04 LTS |
| IP | 10.11.25.40/24 |
| Gateway | 10.11.25.1 |
| DNS | 10.11.45.53 |
| VLAN | VLAN_SEC, tag 25 |
| Bridge | vmbr0 |
| Node | node1 (10.11.45.210) |
create-lab-vms.sh (bài 07) thì VM234 có scsi0 = 30 GB trên SSD vm-ceph (thin provisioning) và không có đĩa dữ liệu scsi1 (xdisk = 0). Số 50 GB ở bài này là trần danh nghĩa/khuyến nghị cho môi trường thật; ước tính ở bài 07 (mục 8.6) cho thấy Authentik chỉ dùng khoảng 10 GB thật (hệ điều hành + Docker ≈ 7 GB, image ≈ 2,5 GB, cơ sở dữ liệu nhỏ), nên 30 GB là đủ và cần thêm thì qm resize 234 scsi0 +10G.
Cổng dịch vụ:
| Port | Protocol | Mục đích |
|---|---|---|
| 9000 | TCP/HTTP | Authentik web UI (plain HTTP) |
| 9443 | TCP/HTTPS | Authentik web UI (TLS) |
Phiên bản phần mềm sử dụng (đã xác minh 2026-10-15):
| Thành phần | Phiên bản | Ghi chú |
|---|---|---|
| Ubuntu Server | 24.04.5 LTS (ISO ubuntu-24.04.5-live-server-amd64.iso) | Hỗ trợ chuẩn tới 04/2029; kernel 6.8, systemd 255, netplan 1.0 |
| Docker Engine + Compose plugin | Bản stable mới nhất trong repo download.docker.com/linux/ubuntu noble (29.9.1 ngày 2026-10-14) | Gói docker-ce + docker-compose-plugin (lệnh docker compose), không dùng docker.io của Ubuntu |
| Authentik | 2026.8.4 | Tag mặc định trong compose.yml chính thức tại thời điểm xác minh; ba service server, worker, postgresql (không còn Redis) |
| PostgreSQL (container) | 16-alpine | docker.io/library/postgres:16-alpine theo compose chính thức |
| step CLI | 0.31.0 | Giá trị dùng chung của series; cài từ gói .deb (mục 7.1) |
Tạo VM Trên PVE
Chạy lệnh tạo VM · Cài đặt Ubuntu qua Console · Xác nhận kết nối sau khi boot
3.1 Chạy lệnh tạo VM
SSH vào node1 với quyền root:
Tạo VM234:
Cách 1: Web UI Proxmox (GUI)
- VM ID:
234 - Name:
authentik - Bỏ tick Start after created
- Storage:
local(hoặc nơi chứa ISO) - ISO Image:
ubuntu-24.04.5-live-server-amd64.iso(tải từ https://releases.ubuntu.com/24.04/) - Guest OS Type:
Linux, Version:6.x - 2.6 Kernel
- Machine:
q35 - SCSI Controller:
VirtIO SCSI single - BIOS:
SeaBIOS - Qemu Agent: ☑
- Bus/Device:
SCSI 0, Storage:vm-ceph(thường làvm-ceph) - Disk size:
50 GiB, Cache:Write back, Discard: ☑
- Sockets:
1, Cores:4, Type:x86-64-v2-AES
- Memory (MiB):
4096
- Bridge:
vmbr0, VLAN Tag:25, Model:VirtIO (paravirtualized), Firewall: ☐
Cách 2: CLI (qm create)
qm create 234 --name authentik \
--memory 4096 --cores 4 \
--net0 virtio,bridge=vmbr0,tag=25 \
--scsi0 vm-ceph:50 \
--scsihw virtio-scsi-pci \
--ide2 local:iso/ubuntu-24.04.5-live-server-amd64.iso,media=cdrom \
--boot "order=ide2;scsi0" \
--ostype l26 \
--agent enabled=1
qm start 234
ubuntu-24.04.5-live-server-amd64.iso phải đã có trong local storage của node1. Kiểm tra: PVE Web UI → node1 → local → ISO Images.
3.2 Cài đặt Ubuntu qua Console
- Hostname:
authentik - Username:
sysadmin - Network:
- Interface: tên NIC thật của VM (kiểm tra bằng
ip -br link; VM q35 thường làens18hoặcenp6s18) - IP:
10.11.25.40/24 - Gateway:
10.11.25.1 - DNS:
10.11.45.53 - Disk: toàn bộ 50 GB
- Cài OpenSSH Server: có
3.3 Xác nhận kết nối sau khi boot
ssh [email protected]
ip a
ping -c 3 10.11.25.1
ping -c 3 10.11.45.53
Cài Đặt OS Ban Đầu
Đặt hostname và cập nhật · Cấu hình IP tĩnh (nếu chưa set khi cài) · Cài Docker và công cụ
4.1 Đặt hostname và cập nhật
sudo hostnamectl set-hostname authentik
# Ubuntu 24.04: needrestart có thể hiện hộp thoại hỏi khi apt cập nhật thư viện; đặt chế độ tự động để không bị dừng
export NEEDRESTART_MODE=a
sudo apt update && sudo apt upgrade -y
4.2 Cấu hình IP tĩnh (nếu chưa set khi cài)
Trên Ubuntu 24.04 file netplan do bộ cài/cloud-init sinh ra thường là /etc/netplan/50-cloud-init.yaml (bộ cài đời trước dùng 00-installer-config.yaml): chạy ls /etc/netplan/ rồi sửa đúng file đang có, đừng tạo thêm file thứ hai chứa cùng NIC. Để cloud-init không ghi đè sau khi khởi động lại, tắt phần mạng của cloud-init:
echo 'network: {config: disabled}' | sudo tee /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
sudo nano /etc/netplan/50-cloud-init.yaml # tên file: xem kết quả ls /etc/netplan/
network:
version: 2
ethernets:
ens18:
dhcp4: false
addresses:
- 10.11.25.40/24
routes:
- to: default
via: 10.11.25.1
nameservers:
addresses:
- 10.11.45.53
- 8.8.8.8
Thay ens18 bằng tên NIC thật (ip -br link), rồi:
sudo chmod 600 /etc/netplan/*.yaml # netplan 1.0 (Ubuntu 24.04) cảnh báo nếu file cấu hình đọc được bởi user khác
sudo netplan apply
4.3 Cài Docker và công cụ
Dùng repo chính thức của Docker cho Ubuntu 24.04 (suite noble, dạng deb822 + Signed-By, không dùng apt-key) thay cho docker.io / docker-compose-v2 của Ubuntu:
# Gỡ gói Docker không chính thức nếu có (bỏ qua lỗi nếu chưa cài)
sudo apt remove -y docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc 2>/dev/null || true
sudo apt install -y ca-certificates curl wget openssl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null << EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
docker --version && docker compose version
grep Suites /etc/apt/sources.list.d/docker.sources # phải ra: Suites: noble
# Docker Engine mới nhất đã xác minh 2026-10-15: 29.9.1
Đăng xuất và đăng nhập lại để áp dụng nhóm docker.
4.4 Tạo thư mục làm việc
sudo mkdir -p /opt/authentik/certs
sudo chown -R $USER:$USER /opt/authentik
Cài Đặt Authentik via Docker Compose
Tải file docker-compose chính thức · Tạo file .env với secret key và database password · Pull image và khởi động
5.1 Tải file docker-compose chính thức
cd /opt/authentik
# Compose chính thức của Authentik (đã xác minh 2026-10-15: tag mặc định 2026.8.4); lưu thành docker-compose.yml
# để khớp các lệnh `-f /opt/authentik/docker-compose.yml` ở bài 13
curl -fsSL https://docs.goauthentik.io/compose.yml -o docker-compose.yml
5.2 Tạo file .env với secret key và database password
cd /opt/authentik
# Tạo PostgreSQL password ngẫu nhiên
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
# Tạo secret key cho Authentik (dùng mã hóa session/token)
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
# Tắt error reporting về Authentik cloud (privacy)
echo "AUTHENTIK_ERROR_REPORTING__ENABLED=false" >> .env
# Tùy chọn: set email nếu cần gửi thông báo (SMTP relay qua Mailu, bài 16: cổng 587 STARTTLS có xác thực)
# echo "AUTHENTIK_EMAIL__HOST=mailu.hoatranlabs.local" >> .env
# echo "AUTHENTIK_EMAIL__PORT=587" >> .env
# echo "[email protected]" >> .env
# echo "AUTHENTIK_EMAIL__PASSWORD=Noreply@Mailu2024!" >> .env
# echo "AUTHENTIK_EMAIL__USE_TLS=true" >> .env
# echo "[email protected]" >> .env
Xem nội dung .env để xác nhận (KHÔNG commit file này vào git):
cat /opt/authentik/.env
5.3 Pull image và khởi động
cd /opt/authentik
docker compose pull
docker compose up -d
Lần đầu pull image sẽ mất vài phút. Theo dõi quá trình:
docker compose logs -f
Sau khoảng 2-3 phút, các container sau sẽ chạy:
docker compose ps
Kết quả mong đợi:
NAME IMAGE STATUS
authentik-server-1 ghcr.io/goauthentik/server Up
authentik-worker-1 ghcr.io/goauthentik/server Up
authentik-postgresql-1 docker.io/library/postgres Up
server, worker, postgresql; Redis đã được bỏ (từ Authentik 2025.10), cache/session/task chuyển sang PostgreSQL. Chỉ khi dùng compose của bản cũ hơn mới có thêm container authentik-redis-1. Image lấy theo biến AUTHENTIK_TAG (mặc định 2026.8.4); muốn nâng cấp sau này thì backup (mục 13) rồi đặt AUTHENTIK_TAG=<bản mới> trong .env và chạy lại docker compose pull && docker compose up -d.
5.4 Xác nhận server đã sẵn sàng
# Kiểm tra health endpoint (in mã HTTP vì thân phản hồi rỗng)
curl -s -o /dev/null -w "%{http_code}\n" http://10.11.25.40:9000/-/health/live/
# Kết quả mong đợi: 200
curl -s -o /dev/null -w "%{http_code}\n" http://10.11.25.40:9000/-/health/ready/
# Kết quả mong đợi: 200 (503 nghĩa là chưa sẵn sàng, đợi thêm rồi chạy lại)
Thiết Lập Ban Đầu (Initial Setup)
Truy cập trang khởi tạo · Tạo tài khoản admin · Xác nhận đăng nhập
6.1 Truy cập trang khởi tạo
Mở trình duyệt và truy cập:
http://10.11.25.40:9000/if/flow/initial-setup/
docker compose logs -f server.
6.2 Tạo tài khoản admin
- Điền Email của admin (ví dụ:
[email protected]) - Điền Password mạnh (ít nhất 12 ký tự, có chữ hoa + số + ký tự đặc biệt)
- Click Continue
Sau khi tạo xong, bạn được chuyển tự động đến trang Dashboard của Authentik.
6.3 Xác nhận đăng nhập
URL đăng nhập thông thường:
http://10.11.25.40:9000/
Cấu Hình HTTPS (TLS)
Phương án A — Dùng certificate từ step-CA (VM242) · Phương án B — Tạo self-signed certificate · Upload certificate vào Authentik GUI
7.1 Phương án A — Dùng certificate từ step-CA (VM242)
Nếu step-CA (VM242, 10.11.25.42) đã deploy và hoạt động:
# Trên VM234 — cài step CLI 0.31.0 bằng gói .deb (cùng cách với bài 13 Bước 3; gói đặt /usr/bin/step-cli và tạo lệnh `step` bằng update-alternatives)
cd /tmp
wget https://github.com/smallstep/cli/releases/download/v0.31.0/step-cli_0.31.0-1_amd64.deb
sudo apt install -y ./step-cli_0.31.0-1_amd64.deb
# Bootstrap trust với step-CA
step ca bootstrap --ca-url https://step-ca.hoatranlabs.local:9000 --fingerprint <CA_FINGERPRINT>
# Cấp certificate cho authentik (giống bài 13 Bước 10: SAN gồm cả tên lẫn IP; có --san thì tên subject không tự thành SAN)
step ca certificate "authentik.hoatranlabs.local" \
/opt/authentik/certs/authentik.crt \
/opt/authentik/certs/authentik.key \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--provisioner [email protected] \
--san authentik.hoatranlabs.local \
--san 10.11.25.40
# Copy root CA cert
cp $HOME/.step/certs/root_ca.crt /opt/authentik/certs/root_ca.crt
<CA_FINGERPRINT> bằng fingerprint thực của step-CA. Lấy từ VM242: step certificate fingerprint /etc/step-ca/certs/root_ca.crt
7.2 Phương án B — Tạo self-signed certificate
Nếu step-CA chưa sẵn sàng, tạo self-signed cert tạm:
openssl req -x509 -nodes -days 3650 \
-newkey rsa:4096 \
-keyout /opt/authentik/certs/authentik.key \
-out /opt/authentik/certs/authentik.crt \
-subj "/CN=authentik.hoatranlabs.local/O=HOATRANLABS/C=VN" \
-addext "subjectAltName=IP:10.11.25.40,DNS:authentik.hoatranlabs.local"
7.3 Upload certificate vào Authentik GUI
Authentik không đọc trực tiếp file cert của web server: cặp cert/key phải nằm trong database của Authentik (mục System → Certificates). Compose chính thức mount thư mục ./certs (= /opt/authentik/certs trên host) vào container worker tại /certs, và Authentik tự động import (certificate discovery) mọi cert/key trong đó: file ở thư mục gốc được đặt tên key pair theo tên file, nên authentik.crt + authentik.key trở thành key pair authentik; khi cert được gia hạn (bài 13) key pair được cập nhật tại chỗ. Chọn MỘT trong hai cách:
Cách A (khuyến nghị): import tự động từ /certs — không phải dán lại cert mỗi lần gia hạn. Tác vụ certificate_discovery của worker chạy theo lịch; muốn import ngay thì vào Dashboards → System Tasks và khởi động lại tác vụ certificate_discovery, hoặc chạy lệnh:
cd /opt/authentik
docker compose exec worker ak import_certificate \
--certificate /certs/authentik.crt \
--private-key /certs/authentik.key \
--name authentik
Sau đó vào System → Certificates và kiểm tra key pair authentik đã xuất hiện (có private key).
Cách B: upload thủ công qua GUI — dùng khi không mount thư mục /certs; mỗi lần gia hạn cert phải dán lại nội dung mới.
- Certificate: nội dung file
/opt/authentik/certs/authentik.crt - Private Key: nội dung file
/opt/authentik/certs/authentik.key
authentik-lan-cert7.4 Gán certificate cho HTTPS listener
- System → Brands → chọn brand mặc định → Edit
- Ở trường Web certificate, chọn key pair
authentik(hoặcauthentik-lan-certnếu upload thủ công) - Click Update
- Khởi động lại container:
cd /opt/authentik
docker compose restart server
Truy cập thử: https://10.11.25.40:9443
Tạo Application Provider (Ví Dụ: Grafana OIDC)
Tạo Provider cho Grafana · Tạo Application cho Grafana · Cấu hình Grafana nhận OIDC từ Authentik
Mỗi service cần 2 đối tượng trong Authentik:
- Provider — định nghĩa giao thức (OIDC, SAML, LDAP, Proxy)
- Application — liên kết Provider với metadata của service (tên, icon, URL)
8.1 Tạo Provider cho Grafana
- Name:
grafana-oidc - Authorization flow:
default-provider-authorization-implicit-consent - Redirect URIs:
http://grafana.hoatranlabs.local:3000/login/generic_oauth - Client type:
Confidential
8.2 Tạo Application cho Grafana
- Name:
Grafana - Slug:
grafana - Provider: chọn
grafana-oidcvừa tạo - Launch URL:
http://grafana.hoatranlabs.local:3000
Tạo nhóm grafana-admin (Grafana dùng nhóm này để gán role Admin, xem bài 15):
- Directory → Groups → Create
- Name:
grafana-admin(không bật quyền superuser cho nhóm) → Create - Directory → Users → chọn user
akadmin→ tab Groups → Add to existing group → chọngrafana-admin→ Add
Danh sách nhóm của user (claim groups) nằm trong scope profile của Authentik, nên Provider grafana-oidc chỉ cần giữ các scope mặc định openid, email, profile (Advanced protocol settings → Selected Scopes). User thuộc nhóm grafana-admin nhận role Admin trong Grafana, các user khác nhận role Viewer.
8.3 Cấu hình Grafana nhận OIDC từ Authentik
Thêm vào grafana.ini hoặc biến môi trường Grafana:
[auth.generic_oauth]
enabled = true
name = Authentik
allow_sign_up = true
client_id = <CLIENT_ID_TU_AUTHENTIK>
client_secret = <CLIENT_SECRET_TU_AUTHENTIK>
scopes = openid email profile
auth_url = https://authentik.hoatranlabs.local:9443/application/o/authorize/
token_url = https://authentik.hoatranlabs.local:9443/application/o/token/
api_url = https://authentik.hoatranlabs.local:9443/application/o/userinfo/
role_attribute_path = contains(groups[*], 'grafana-admin') && 'Admin' || 'Viewer'
8.4 Application OIDC cho Proxmox VE (bài 08)
Mục này tạo phía Authentik cho realm OpenID Connect của giao diện web Proxmox VE (bài 08). Phần lõi của bài 08 (realm pam/pve, nhóm, role, API token, TFA) chạy độc lập; chỉ làm mục này sau khi Authentik đã chạy HTTPS cổng 9443 (mục 7) và các node PVE đã tin Root CA của step-CA (bài 13 Bước 9), vì PVE gọi https://authentik.hoatranlabs.local:9443 để lấy cấu hình OIDC.
grp-pve-admin, grp-pve-ops, grp-pve-readonly, grp-pve-backup, grp-pve-automation; rồi thêm user vào nhóm tương ứng (Directory → Users → user → tab Groups). Lưu ý: phía Proxmox, tên nhóm lấy từ claim được gắn thêm hậu tố -<tên realm>; realm đặt tên authentik thì nhóm grp-pve-admin trở thành grp-pve-admin-authentik và ACL ở bài 08 gán role cho tên nhóm đó (theo tài liệu Proxmox, mục OpenID Connect).- Name:
proxmox-oidc - Authorization flow:
default-provider-authorization-implicit-consent - Client type:
Confidential - Redirect URIs (kiểu Strict, loại Authorization; không có dấu
/cuối):https://node1.hoatranlabs.local:8006,https://node2.hoatranlabs.local:8006,https://node3.hoatranlabs.local:8006,https://node4.hoatranlabs.local:8006(thêm dạng IP nhưhttps://10.11.45.210:8006nếu có đăng nhập bằng IP) - Signing Key: chọn một key có sẵn (ví dụ
authentik Self-signed Certificate) - Advanced protocol settings → Selected Scopes: giữ
openid,email,profile. Claimgroups(danh sách nhóm của user) nằm trong scopeprofilenên không cần scope riêng têngroups; nếu bài 08 liệt kêgroupstrong danh sách scope của realm thì đối chiếu lại cho khớp (cách Authentik xử lý một scope không có mapping: cần kiểm lại trên máy thật) - Ghi lại Client ID và Client Secret
Proxmox VE, Slug proxmox (slug quyết định đường dẫn Issuer, không đổi sau khi đã cấu hình PVE), Provider proxmox-oidc, Launch URL https://node1.hoatranlabs.local:8006. Tùy chọn: tab Policy / Group / User Bindings gắn các nhóm grp-pve-* để chỉ những user này thấy ứng dụng.Issuer URL của ứng dụng này (dùng ở phía Proxmox): https://authentik.hoatranlabs.local:9443/application/o/proxmox/
- Phía Proxmox (lệnh đối chiếu; thao tác đầy đủ ở bài 08, chạy một lần trên một node vì
/etc/pvedùng chung cả cluster):
pveum realm add authentik --type openid \
--issuer-url https://authentik.hoatranlabs.local:9443/application/o/proxmox/ \
--client-id "<CLIENT_ID_TU_AUTHENTIK>" --client-key "<CLIENT_SECRET_TU_AUTHENTIK>" \
--username-claim username --autocreate 1 \
--scopes "email profile" --groups-claim groups --groups-autocreate 0 --groups-overwrite 1
GUI tương đương: Datacenter → Permissions → Realms → Add → OpenID Connect Server (Realm authentik, Username Claim username, Scopes email profile, Groups Claim groups, Autocreate Groups tắt, Overwrite Groups bật — nhóm PVE grp-pve-*-authentik được tạo sẵn ở bài 08, nên thành viên nhóm luôn khớp Authentik). Kiểm tra: đăng xuất khỏi PVE, chọn realm authentik ở màn hình đăng nhập, đăng nhập bằng tài khoản Authentik; user xuất hiện dạng <tên>@authentik, sau đó gán role cho nhóm grp-pve-*-authentik ở Datacenter → Permissions (bài 08). Lỗi redirect_uri_mismatch xem mục 14.3.
entitlements (hướng dẫn tích hợp Proxmox chính thức hiện dùng cách này, kèm --groups-claim entitlements). Bài giữ cách dùng claim groups theo quy ước bài 08; cả hai cách đều hợp lệ.
Tích Hợp Các Service Quan Trọng
Cấu hình LDAP Provider (tùy chọn, không dùng cho Mailu)
Bảng tổng hợp tích hợp SSO cho toàn bộ hạ tầng:
| Service | Giao thức | Redirect URI mẫu | Ghi chú |
|---|---|---|---|
| Grafana | OIDC (OAuth2) | http://grafana.hoatranlabs.local:3000/login/generic_oauth | Cấu hình [auth.generic_oauth] trong .ini |
| Harbor | OIDC | https://harbor.hoatranlabs.local/c/oidc/callback | Harbor: Administration → Configuration → Auth → OIDC |
| Gitea | OIDC (OAuth2) | https://gitea.hoatranlabs.local/user/oauth2/authentik/callback | Gitea: Site Administration → Authentication Sources |
| NetBox | OIDC (Social Auth) | http://netbox.hoatranlabs.local:8080/oauth/complete/oidc/ | Cấu hình REMOTE_AUTH_BACKEND trong configuration.py (xem bài 23) |
| Proxmox | OIDC | https://node1.hoatranlabs.local:8006 | PVE: Datacenter → Permissions → Realms → Add → OpenID Connect Server (các bước đầy đủ ở mục 8.4; xem lưu ý dưới bảng) |
| Wazuh | OIDC / SAML | https://wazuh-siem.hoatranlabs.local/ | Wazuh 4.9+ hỗ trợ SAML qua OpenSearch Security |
| Headscale | OIDC (PKCE S256) | https://headscale.hoatranlabs.local/oidc/callback | Provider headscale-oidc, slug headscale, redirect Strict, để trống Encryption Key; cấu hình đầy đủ ở bài 20 |
redirect-url là địa chỉ đang mở trên trình duyệt (giao thức + host + cổng :8006, không có đường dẫn, không dấu / cuối) và Authentik so khớp tuyệt đối (kiểu Strict Authorization, ví dụ của Authentik là https://proxmox.company:8006). Vì vậy mỗi địa chỉ dùng để mở PVE là một Redirect URI riêng: thêm https://node1.hoatranlabs.local:8006 và tương tự cho node2–node4, hoặc dạng IP như https://10.11.45.210:8006 nếu đăng nhập bằng IP.
9.1 Cấu hình LDAP Provider (tùy chọn, không dùng cho Mailu)
Mailu (bài 16) dùng tài khoản nội bộ của Mailu (tạo bằng flask mailu user), không dùng LDAP của Authentik. LDAP Provider chỉ cần khi có ứng dụng legacy chỉ hỗ trợ LDAP:
- Name:
legacy-ldap - Base DN:
DC=hoatranlabs,DC=local - Bind Flow:
default-authentication-flow
docker-compose.yml của Authentik, thêm LDAP outpost:# Tạo LDAP Outpost qua Authentik GUI
# Applications → Outposts → Create
# Type: LDAP
# Providers: chọn legacy-ldap
Ứng dụng legacy bind vào outpost qua ldap://10.11.25.40:389 với Base DN ou=users,DC=hoatranlabs,DC=local.
MFA Setup
Bật TOTP (Google Authenticator / Authy) · Thêm TOTP vào Login Flow · Bật WebAuthn (Hardware Key / Fingerprint)
10.1 Bật TOTP (Google Authenticator / Authy)
- Name:
totp-setup-stage - Digits:
6 - Issuer:
HOATRANLABS
10.2 Thêm TOTP vào Login Flow
- Flows → tìm flow
default-authentication-flow→ click vào - Tab Stage Bindings → Bind existing stage
- Chọn
totp-setup-stage - Order:
30(sau password check ở order 20) - Click Create
10.3 Bật WebAuthn (Hardware Key / Fingerprint)
- Stages → Create → Authenticator WebAuthn Stage
- Name:
webauthn-setup-stage - Bind vào login flow tương tự TOTP, Order:
35
10.4 Yêu cầu MFA cho toàn bộ user admin
- Flows → default-authentication-flow → Stage Bindings
- Sửa binding của TOTP stage: bật Re-evaluate policies
- Tạo Policy: Expression Policy:
return ak_is_group_member(request.user, name="authentik Admins")
Điều này chỉ yêu cầu MFA khi user thuộc nhóm Admins.
Pi-hole DNS
Thêm DNS record để truy cập Authentik qua hostname.
ssh [email protected]
# Pi-hole chạy trong Docker (bài 12): thêm record bằng Admin UI
# Settings → Local DNS Records: authentik.hoatranlabs.local → 10.11.25.40
# (hoặc dùng script add_dns_records.sh ở bài 12 — đã có sẵn record này)
# Pi-hole v6 không còn lệnh restartdns, dùng reloaddns để nạp lại DNS
docker exec pihole pihole reloaddns
Xác nhận:
nslookup authentik.hoatranlabs.local 10.11.45.53
# Kết quả mong đợi: Address: 10.11.25.40
Sau khi DNS hoạt động:
- HTTP:
http://authentik.hoatranlabs.local:9000 - HTTPS:
https://authentik.hoatranlabs.local:9443
Cấu Hình Firewall (FortiGate)
Bảng rule cần tạo · Tạo Address Object trong FortiGate
12.1 Bảng rule cần tạo
| Tên Rule | Source | Destination | Port(s) | Action |
|---|---|---|---|---|
| Allow-Authentik-Admin | VLAN_MGMT | 10.11.25.40 | 9000, 9443/TCP | Accept |
| Allow-Authentik-Admin | VLAN_SEC | 10.11.25.40 | 9000, 9443/TCP | Accept |
| Allow-Authentik-SSO | VLAN_SRV | 10.11.25.40 | 9443/TCP | Accept |
| Allow-Authentik-SSO | VLAN_DMZ | 10.11.25.40 | 9443/TCP | Accept |
| Allow-Authentik-SSO | VLAN_STORAGE | 10.11.25.40 | 9443/TCP | Accept |
s3.json và Admin UI có mật khẩu riêng nên không dùng Authentik, có thể bỏ dòng này nếu không còn dịch vụ nào khác ở VLAN 85 cần SSO. Port 9000 (HTTP) chỉ nên mở cho VLAN quản trị. Port 389 chỉ mở nếu có ứng dụng legacy dùng LDAP Provider (mục 9.1); Mailu không dùng LDAP.
12.2 Tạo Address Object trong FortiGate
Qua FortiGate Web GUI:
authentik-sso, Type: Subnet, Subnet: 10.11.25.40/32
Sau đó tạo Firewall Policy với address object vừa tạo.
Backup PBS
Tạo backup job trong Proxmox Web UI · Chạy backup thủ công lần đầu · Backup file .env quan trọng
Cấu hình backup VM234 vào PBS (pbs01 – VM101, 10.11.45.17).
13.1 Tạo backup job trong Proxmox Web UI
- Storage:
pbs-primary - Schedule:
03:00(sau job Wazuh 02:00 và privacyIDEA 02:30 để các job không chạy chồng nhau) - Selection: VM 234
- Mode: Snapshot
- Retention: để mặc định (retention do Prune Job trên PBS quản lý, bài 04 mục 7)
- Namespace:
st-20(đã khai báo trong storagepbs-primary, xem bài 04)
13.2 Chạy backup thủ công lần đầu
# Trên node1
vzdump 234 --storage pbs-primary --mode snapshot --compress zstd
13.3 Backup file .env quan trọng
File /opt/authentik/.env chứa secret key và database password. Nếu mất file này, không thể khôi phục session sau khi restore VM. Lưu backup an toàn:
# Encrypt và lưu vào nơi an toàn
gpg --symmetric --cipher-algo AES256 /opt/authentik/.env
# File mã hóa: /opt/authentik/.env.gpg
# Sao chép .env.gpg vào PBS hoặc NAS riêng
Troubleshooting
Worker không khởi động hoặc crash · Quên mật khẩu admin · OIDC redirect lỗi (redirect_uri_mismatch)
14.1 Worker không khởi động hoặc crash
cd /opt/authentik
docker compose logs worker --tail=50
# Lỗi thường gặp: database chưa sẵn sàng
docker compose logs postgresql --tail=20
# Nếu worker báo lỗi DB connection — restart theo thứ tự
docker compose restart postgresql
sleep 10
docker compose restart worker
docker compose restart server
14.2 Quên mật khẩu admin
cd /opt/authentik
# Cách 1: tạo recovery key cho akadmin (hiệu lực 10 phút). Lệnh in ra một liên kết đăng nhập tức thì;
# mở liên kết đó (ghép vào địa chỉ Authentik, ví dụ http://10.11.25.40:9000) rồi đặt lại mật khẩu
docker compose exec server ak create_recovery_key 10 akadmin
# Cách 2: đặt lại mật khẩu trực tiếp, lệnh sẽ hỏi mật khẩu mới (thay akadmin bằng tên user thực nếu cần)
docker compose exec server ak changepassword akadmin
14.3 OIDC redirect lỗi (redirect_uri_mismatch)
Triệu chứng: Sau khi đăng nhập, browser hiển thị lỗi redirect_uri_mismatch hoặc invalid_redirect_uri.
Nguyên nhân: Redirect URI đăng ký trong Authentik Provider không khớp với URI thực tế service gửi lên.
# Kiểm tra log để xem URI nào được gửi
docker compose logs server | grep "redirect_uri" | tail -20
Khắc phục:
- Authentik → Applications → Providers → chọn provider bị lỗi
- Tab Advanced protocol settings → Redirect URIs/Origins
- Thêm đúng URI service đang dùng (không trailing slash)
- Click Update
14.4 LDAP Outpost không hoạt động (nếu đã tạo ở mục 9.1)
# Test kết nối LDAP từ VM234
docker exec -it authentik-server-1 \
ldapsearch -H ldap://localhost:389 \
-x -D "cn=ldapservice,ou=users,DC=hoatranlabs,DC=local" \
-w "<PASSWORD>" \
-b "ou=users,DC=hoatranlabs,DC=local" "([email protected])"
Nếu lỗi connection refused: kiểm tra Outpost LDAP đã được tạo và đang chạy trong Applications → Outposts.
14.5 Container khởi động nhưng web UI không response
# Kiểm tra port đang bind
ss -tlnp | grep -E '9000|9443'
# Nếu không thấy — kiểm tra docker compose binding
docker compose ps
docker inspect authentik-server-1 | python3 -m json.tool | grep -A 10 "Ports"
# Restart toàn bộ stack
cd /opt/authentik
docker compose down && docker compose up -d
Checklist Hoàn Thành
- VM234 tạo thành công trên node1 với 4vCPU / 4GB RAM / 50GB Ceph
- Ubuntu Server 24.04 LTS cài xong, IP tĩnh 10.11.25.40/24 hoạt động (đúng tên NIC theo
ip -br link, đúng file trong/etc/netplan/) - Docker Engine + Compose plugin cài từ repo
download.docker.comsuitenoble(docker compose versionchạy được) - File
.envđã tạo với PG_PASS và AUTHENTIK_SECRET_KEY ngẫu nhiên - Tất cả 3 container (server, worker, postgresql) ở trạng thái Up
- Truy cập được initial-setup tại
http://10.11.25.40:9000/if/flow/initial-setup/ - Tài khoản admin đã tạo thành công
- DNS A record
authentik.hoatranlabs.local → 10.11.25.40đã thêm vào Pi-hole VM247 - TLS certificate đã upload và HTTPS port 9443 hoạt động
- Ít nhất 1 OIDC Provider + Application đã tạo (ví dụ: Grafana)
- (Làm bài 08) Application
Proxmox VE(slugproxmox, providerproxmox-oidc) đã tạo, Redirect URIhttps://node1…node4.hoatranlabs.local:8006; đăng nhập PVE bằng realmauthentikthành công - MFA (TOTP) đã bật và test thành công với tài khoản admin
- Rule FortiGate đã mở port 9000/9443 từ VLAN_MGMT và port 9443 từ VLAN_SRV/DMZ/STORAGE
- Backup job PBS đã tạo cho VM234, schedule daily 03:00, retention do Prune Job trên PBS
- File
.envđã được backup mã hóa ra ngoài VM234
Tài Liệu Tham Khảo
- Authentik — cài đặt bằng Docker Compose: https://docs.goauthentik.io/install-config/install/docker-compose/
- Authentik — OAuth2/OpenID provider (scope, issuer, endpoint): https://docs.goauthentik.io/add-secure-apps/providers/oauth2/
- Authentik — tích hợp Proxmox VE: https://integrations.goauthentik.io/hypervisors-orchestrators/proxmox-ve/
- Proxmox VE — User Management, realm OpenID Connect: https://pve.proxmox.com/pve-docs/chapter-pveum.html
- Docker Engine trên Ubuntu (repo apt, suite noble): https://docs.docker.com/engine/install/ubuntu/
- Ubuntu Server 24.04 LTS: https://releases.ubuntu.com/24.04/
Tài liệu cập nhật: 2026-10-15 | Cluster: HOATRANHUB PVE 9.2.20 | Authentik 2026.8.4