System & Network RBAC · Token · OIDC
Bài 08 · Giai đoạn 1 — Vận hành & Bảo mật Proxmox

Phân quyền Proxmox RBAC · API Token · OIDC

User, group, role, pool, API token và đăng nhập SSO OIDC bằng Authentik cho giao diện PVE.

Giai đoạn: Vận hành & Bảo mật Proxmox

Bối cảnh & Lý do triển khai

Vị trí trong chuỗi bài: Bài 08 thuộc Giai đoạn 1 — Vận hành & Bảo mật Proxmox, nối tiếp Bài 07. Template + Cloud-Init và đứng trước Bài 09. ACME + step-CA. Cần có sẵn / liên quan: 04. Triển khai PBS + PDM · 13. step-CA PKI · 14. Authentik SSO · 15. Prometheus + Grafana · 25. Samba AD DC · 26. Linux Samba.
Mức độ cần thiết: 🔴 Bắt buộc — mọi thao tác quản trị phải truy vết được tới một con người, và công cụ tự động hoá không bao giờ được dùng root

Sau bài 02–04, con người quản trị cả cụm chỉ có một tài khoản root@pam dùng chung (ngoài pdm@pve của bài 04 cho PDM): ai đăng nhập cũng là "root", không biết ai đã xoá VM, và mọi script (Ansible, Prometheus exporter, PDM) nếu muốn gọi API đều phải cầm mật khẩu root. Chỉ cần một laptop bị mất hoặc một file cấu hình bị lộ là toàn bộ hạ tầng thuộc về kẻ khác. Bài này dựng mô hình phân quyền theo nguyên tắc quyền tối thiểu: người dùng thật vào bằng tài khoản riêng (có xác thực hai lớp), nhân sự được chia nhóm theo công việc, VM được gom vào pool để phân quyền theo nhóm tài nguyên thay vì từng VM, công cụ tự động dùng API token có hạn dùng và chỉ chạm đúng phạm vi cần thiết, còn root@pam và sysadmin@pam được giữ làm lối thoát hiểm (break-glass) cho lúc SSO hỏng.

Phần lõi (mục 1–8) chỉ cần cụm PVE của bài 01–04 và chạy được ngay. Phần tích hợp (mục 9–10: đăng nhập OIDC bằng Authentik, realm AD/LDAP với dc1) chỉ làm sau khi hoàn thành bài 14 và bài 25; hạ tầng không vì thế mà bị chặn.

MụcNội dung
Ứng dụng trong DNMỗi quản trị viên một tài khoản riêng có 2FA; nhóm vận hành chỉ thao tác trên pool được giao; kiểm toán "ai được làm gì, ai đã làm gì"; nhân sự nghỉ việc thì vô hiệu hoá một chỗ (SSO) là hết quyền vào PVE
Tác dụng chínhChuẩn hoá nhóm grp-pve-*, vai trò tuỳ chỉnh, pool pool-*, ACL theo nhóm; API token quyền tối thiểu cho Ansible/Prometheus/PDM; 2FA bắt buộc cho tài khoản người; break-glass; script áp dụng + kiểm toán RBAC chạy được từ 1 node tới hàng trăm node
Nếu không triển khaiDùng chung root, không truy vết được; token/script cầm quyền Administrator; nhân sự nghỉ việc vẫn còn tài khoản "ma"; một lỗi cấu hình hoặc một máy bị chiếm có thể xoá toàn bộ cụm
Các service phụ thuộc vào đâyops01 và Ansible/OpenTofu dùng token svc-automation@pve!ansible (bài 07) và dùng chính token đó để ghi firewall (bài 05), cấp chứng chỉ (bài 09), cấu hình thông báo (bài 10); prometheus-pve-exporter dùng token svc-monitoring@pve!prometheus (bài 15); PDM dùng pdm@pve (bài 04, được hạ quyền ở mục 6); OIDC với Authentik (bài 14); realm AD với dc1 (bài 25); runbook sự cố dùng quy trình break-glass (bài 11)

Ngày cập nhật: 2026-10-15
Người thực hiện: hoatv
Môi trường: HOATRANLABS – 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ủIPVLAN · NodeVai trò trong bài này
node1 (Proxmox VE)10.11.45.21045 (MGMT) · cluster HOATRANHUBMáy chủ của bài — chạy pveum/pvesh và script pve-rbac-*.sh (cấu hình /etc/pve dùng chung cả cluster); timer kiểm toán 05:10; tạo realm OIDC.
node2 (Proxmox VE)10.11.45.21145 (MGMT) · cluster HOATRANHUBNode cluster: cần người dùng Linux sysadmin (realm pam là cục bộ từng node) và root CA step-CA; thêm Redirect URI :8006 trong Authentik.
node3 (Proxmox VE)10.11.45.21245 (MGMT) · cluster HOATRANHUBNode cluster: cần sysadmin cục bộ và root CA step-CA; Redirect URI :8006 của Authentik; dùng chung token và ACL qua /etc/pve.
node4 (Proxmox VE)10.11.45.21345 (MGMT) · cluster HOATRANHUBNode cluster chứa VM101, VM102 (pool-infra): cần sysadmin cục bộ và root CA step-CA; Redirect URI :8006 của Authentik.
node5 (Proxmox VE standalone)10.100.100.20Site phụ 10.100.100.0/24 · standalonePVE standalone site phụ: có CSDL RBAC riêng, chạy lại script mục 5; hạ quyền pdm@pve riêng (bài 04); Redirect URI :8006 nếu dùng OIDC.
node6 (Proxmox VE standalone)10.100.100.21Site phụ 10.100.100.0/24 · standalonePVE standalone site phụ: như node5 — RBAC, token pdm@pve và Redirect URI áp dụng riêng cho node này.
ops01 (Ansible/OpenTofu + bastion) · VM29010.11.45.2045 (MGMT) · node2Máy quản trị/tự động hoá (bài 07): giữ secret token svc-automation@pve!ansible trong ansible-vault; chạy playbook rbac.yml qua API 8006 và SSH.
pdm01 (Proxmox Datacenter Manager) · VM10210.11.45.1845 (MGMT) · node4Proxmox Datacenter Manager (bài 04): dùng token pdm@pve!pdm-token; bài này hạ quyền từ PVEAdmin xuống AuditReadOnly và đặt hạn dùng token.
prometheus (Prometheus + Alertmanager) · VM23510.11.45.3545 (MGMT) · node2Chạy pve-exporter (bài 15, Bước 11) với token svc-monitoring@pve!prometheus có quyền AuditReadOnly tại /; cần mở 8006 tới các node (bài 05).
authentik (Authentik SSO) · VM23410.11.25.4025 (SEC) · node1Sau bài 14: IdP OIDC (provider proxmox-oidc, slug proxmox); nhóm grp-pve-* thành nhóm PVE hậu tố -authentik; issuer :9443/application/o/proxmox/.
step-ca (step-CA PKI) · VM24210.11.25.4225 (SEC) · node1Root CA của lab (bài 13): mỗi node PVE phải tin root CA để gọi Authentik (9443) và dc1 (LDAPS 636) với chứng chỉ hợp lệ.
dc1 (Samba AD DC + FreeRADIUS) · VM25010.11.65.5065 (SRV) · node1Tích hợp tuỳ chọn (sau bài 25): Samba AD DC, realm hoatran-ad qua LDAPS 636; tài khoản bind svc-pve-ldap và nhóm AD grp-pve-* đồng bộ vào PVE.
pbs01 (PBS Primary) · VM10110.11.45.1745 (MGMT) · node4PBS Primary (bài 04): storage pbs-primary được cấp BackupOperator cho nhóm grp-pve-backup; VM101 thuộc pool-infra.
pihole (Pi-hole DNS) · VM24710.11.45.5345 (MGMT) · node3DNS nội bộ (bài 12) phân giải authentik/dc1/step-ca cho node PVE; hoặc dùng /etc/hosts trên node để đăng nhập OIDC không phụ thuộc VM Pi-hole.

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. FortiGate cần cho phép VLAN 45 (MGMT) tới Authentik cổng 9443 và dc1 cổng 636; đây là cấu hình ở bài 14 và bài 25.

Tổng quan

Thông số · Quy ước đặt tên (dùng xuyên suốt cả bộ bài) · Phiên bản phần mềm sử dụng

Mô hình phân quyền của Proxmox VE gồm hai nửa tách bạch: xác thực (bạn là ai, qua realm nào) và phân quyền (bạn được làm gì, ở path nào, bằng role nào). Bài này làm cả hai nửa theo đúng thứ tự: dựng nửa phân quyền trước (nhóm, vai trò, pool, ACL, token) vì nó không phụ thuộc dịch vụ ngoài, sau đó mới cắm nguồn xác thực ngoài (OIDC, AD) vào phía trước.

Ai?                    Xác thực (realm)                 Được làm gì? (ACL = path + chủ thể + role)
 ┌─────────────────┐     ┌──────────────────────┐        ┌──────────────────────────────────────────┐
 │ root@pam        │────▶│ pam     (OS, từng node)│       │ path:  /  ·  /pool/pool-prod  ·  /vms/9000│
 │ sysadmin@pam    │     │ pve     (cả cluster)  │        │ chủ thể: user | @nhóm | token (user!tên) │
 │ svc-*@pve!token │     │ openid  (Authentik)   │──────▶ │ role:  Administrator, VMOperator, ...     │
 │ alice@authentik │     │ ad/ldap (dc1)         │        │ propagate: kế thừa xuống path con         │
 └─────────────────┘     └──────────────────────┘        └──────────────────────────────────────────┘
        người dùng GUI / SSH / script  ──▶  pveproxy :8006 (API)  ──▶  kiểm tra ACL cho từng lời gọi

Thông số

Thông sốGiá trị
Bài08 — Phân quyền (RBAC)
Phiên bản PVE9.2.20 (Debian 13)
Quy mô áp dụng1 node → hàng trăm node
Realm lõipam · pve
Realm tích hợpOIDC (bài 14) · AD (bài 25)
Nhóm chuẩn5 nhóm grp-pve-*
Pool chuẩnpool-prod/infra/test
Công cụ chínhpveum · pvesh · Ansible
Thời gian thực hiện~90 phút + ~45 phút (OIDC)
Điều kiện tiên quyếtBài 01–04 (lõi)

Quy ước đặt tên (dùng xuyên suốt cả bộ bài)

Đối tượngTên chuẩnGhi chú
Tài khoản quản trị hằng ngàysysadmin@pamNgười dùng Linux sysadmin tồn tại trên mọi node; thuộc nhóm grp-pve-admin
Tài khoản break-glassroot@pamChỉ dùng khi SSO/sysadmin hỏng; mật khẩu niêm phong, có TOTP + recovery keys
Nhómgrp-pve-admin · grp-pve-ops · grp-pve-readonly · grp-pve-backup · grp-pve-automationMọi ACL gắn vào nhóm, không gắn vào từng người
Vai trò tuỳ chỉnhVMOperator · AuditReadOnly · TemplateDeployer · BackupOperator · FirewallOperator · NotificationOperatorKhông được bắt đầu bằng PVE (tiền tố dành riêng cho vai trò dựng sẵn)
Tài khoản dịch vụsvc-automation@pve · svc-monitoring@pveRealm pve, không đặt mật khẩu: chỉ đăng nhập được bằng token
API tokensvc-automation@pve!ansible · svc-monitoring@pve!prometheusPrivilege separation bật, có hạn dùng
Poolpool-prod · pool-infra · pool-testTên pool phải bắt đầu bằng chữ cái (PVE 9.0+)
Realm OIDCauthentikNhóm từ OIDC có hậu tố -authentik (ví dụ grp-pve-ops-authentik)
Realm AD (tuỳ chọn)hoatran-adNhóm đồng bộ có hậu tố -hoatran-ad

Phiên bản phần mềm sử dụng

Đã xác minh ngày 2026-10-15 (docs chính thức, trang phát hành, PyPI).

Thành phầnPhiên bảnGhi chú
Proxmox VE9.2.x (lab 9.2.20, Debian 13 "trixie")Tài liệu pveum đối chiếu: man page 9.2.13. PVE 9.2 phát hành 2026-05-21
Công cụ pveum / pveshđi kèm PVECấu hình ở /etc/pve/user.cfg, /etc/pve/domains.cfg, /etc/pve/priv/*
Proxmox Datacenter Manager1.1 (bài 04)Dùng token pdm@pve!pdm-token ở mục 6
Authentik2026.8.4 (bài 14; compose chính thức: server, worker, PostgreSQL, không Redis)Redirect URI có loại Strict + Authorization (từ 2026.5); tích hợp Proxmox ở bài 14 mục 8.4
Ubuntu Server (ops01, VM Authentik)24.04 LTS, bản point mới nhất 24.04.5Theo bài 07 và bài 14
Samba AD DC (dc1)theo bài 25LDAPS cổng 636, chứng chỉ do step-CA cấp
prometheus-pve-exporter3.10.1 (PyPI, 2026-10-03; Python ≥ 3.11)Chạy bằng Docker image prompve/prometheus-pve-exporter ở bài 15, cổng 9221
Ansible collection community.proxmox2.0.0 (ansible-core ≥ 2.17)validate_certs mặc định true; có proxmox_access_acl, proxmox_pool, proxmox_pool_member, proxmox_user_info
OpenTofu + provider bpg/proxmoxprovider v0.111.x (07/2026)Tài nguyên proxmox_virtual_environment_* đang được đổi sang tiền tố proxmox_* (dự kiến v1.0)
jq, python3gói Debian 13Dùng cho script kiểm toán ở mục 8

Quy mô triển khai

Quy môĐặc điểm RBACCách làm khuyến nghị
1 node standaloneCấu hình ở máy đó, không đồng bộroot@pam (break-glass) + sysadmin@pam + TOTP; 2 nhóm là đủ (grp-pve-admin, grp-pve-readonly); token cho exporter giám sát; pool tuỳ chọn
2–3 node (qdevice)user.cfg, domains.cfg đồng bộ qua pmxcfs; user pam không đồng bộTạo sysadmin giống hệt trên từng node; ghi user/ACL/token cần cụm có quorum (mất quorum thì /etc/pve chỉ đọc)
Cluster 4–~30 node (HOATRANHUB là ví dụ)Toàn bộ mô hình của bài: nhóm, vai trò, pool, ACL, token, OIDCÁp dụng script ở mục 4–5 trên 1 node; kiểm toán định kỳ (mục 8)
>~30 node (nhiều cluster)Mỗi cluster có CSDL RBAC riêng; tài liệu PVE không đặt giới hạn cứng số node (có báo cáo >50 node từ 2021) nhưng khuyến nghị thực hành là chia cụm theo miền lỗiRBAC như mã: Ansible/OpenTofu từ ops01 áp cùng một bộ nhóm/vai trò cho mọi cluster; IdP chung (OIDC/AD); PDM (bài 04) để nhìn tập trung; mỗi cluster token riêng

Công cụ & chi phí

Toàn bộ bài dùng công cụ miễn phí: pveum/pvesh có sẵn trong PVE, Authentik (bài 14) và Samba AD (bài 25) đã có trong lab, Ansible/OpenTofu/prometheus-pve-exporter là mã nguồn mở. Quản lý user/role/ACL/token/OIDC/LDAP không đòi subscription — mọi tính năng của bài hoạt động với repo pve-no-subscription. Chỉ khi cần SLA hỗ trợ chính thức từ Proxmox mới cân nhắc subscription; không liên quan tới RBAC.

Phụ thuộc xuôi và ngược

Bài 08 nằm trước các dịch vụ hạ tầng (bài 12 trở đi), nên mỗi phần có điều kiện riêng. Thứ tự khuyến nghị: làm hết phần lõi, rồi quay lại làm phần tích hợp khi bài tương ứng đã xong.

Thành phầnBàiBắt buộc choGhi chú
Cụm PVE (hoặc 1 node)01–03Toàn bộpvecm status phải Quorate nếu là cluster
PBS + PDM04Mục 4 (ACL storage pbs-primary), mục 6 (hạ quyền pdm@pve)Có thể bỏ qua nếu chưa dùng PBS
ops01, Ansible07Mục 6.6, mục 11Chưa có ops01 thì chạy từ máy quản trị bất kỳ có ssh + curl
step-CA (root CA)13Mục 9, 10 (PVE phải tin chứng chỉ của Authentik/dc1)Chưa có thì chưa làm được OIDC/LDAPS chuẩn
Authentik14Mục 9Tích hợp OIDC: làm sau bài 14
Prometheus15Mục 6.5Token đã tạo sẵn; cấu hình exporter làm ở bài 15
Samba AD DC dc125Mục 10Tuỳ chọn: realm AD làm sau bài 25

Ngược lại, bài 08 cung cấp cho các bài khác: tên nhóm/vai trò/pool/token chuẩn (mục "Quy ước đặt tên"), token cho ops01 và Prometheus, quy trình break-glass cho runbook (bài 11), và lệnh kiểm toán cho bài 17 (Wazuh) và bài 33 (Loki) thu log xác thực.

01

Mô hình quyền của PVE: realm, user, group, role, path, pool

Các loại realm · Định dạng ID · Tệp cấu hình và hình dạng của chúng

1.1 Các loại realm

RealmLưu thông tin ở đâuPhạm viDùng trong lab
pam (Linux PAM)/etc/passwd, /etc/shadow của từng nodeUser phải tồn tại ở từng node mà họ đăng nhập; đổi mật khẩu qua GUI chỉ tác động node đang mởBreak-glass: root@pam, sysadmin@pam
pve (Proxmox VE authentication server)Mật khẩu băm SHA-256 ở /etc/pve/priv/shadow.cfgĐồng bộ cả clusterTài khoản dịch vụ svc-*@pve
openidIdP bên ngoài (Authentik)Cả cluster (cấu hình ở domains.cfg)Người dùng hằng ngày (mục 9)
ad / ldapMáy chủ thư mục (dc1)Cả cluster; có thể đồng bộ user/nhóm về user.cfgTuỳ chọn (mục 10)

Quy tắc áp dụng: người đăng nhập GUI qua OIDC/AD; máy (script, exporter) dùng token của user pve; thoát hiểm dùng pam. Cấu hình realm nằm ở /etc/pve/domains.cfg (đồng bộ cả cluster), danh sách user/nhóm/pool/vai trò/ACL nằm ở /etc/pve/user.cfg.

1.2 Định dạng ID

Đối tượngDạngVí dụ
Usertên@realmsysadmin@pam, alice@authentik
Tokentên@realm!tên-tokensvc-monitoring@pve!prometheus
Groupchuỗi [A-Za-z0-9._-], nhóm đồng bộ từ OIDC/LDAP có hậu tố -<realm>grp-pve-ops, grp-pve-ops-authentik
Poolbắt đầu bằng chữ cáipool-prod
Rolekhông dùng tiền tố PVE (dành riêng)VMOperator

1.3 Tệp cấu hình và hình dạng của chúng

Chỉ để đọc cho hiểu; không sửa tay mà dùng pveum. Ví dụ dưới là hình dạng điển hình (mẫu, rút gọn):

# /etc/pve/user.cfg (mẫu, rút gọn)
user:sysadmin@pam:1:0:::::::
token:svc-monitoring@pve!prometheus:1824000000:1::
group:grp-pve-admin:sysadmin@pam::
pool:pool-prod:Dịch vụ ứng dụng::
role:VMOperator:VM.Audit,VM.Console,VM.PowerMgmt,VM.Snapshot:
acl:1:/:@grp-pve-admin:Administrator:
acl:1:/pool/pool-prod:@grp-pve-ops:VMOperator:
acl:1:/:svc-monitoring@pve!prometheus:AuditReadOnly:
# /etc/pve/domains.cfg (mẫu, rút gọn)
pam: pam
	comment Linux PAM standard authentication

pve: pve
	comment Proxmox VE authentication server

openid: authentik
	issuer-url https://authentik.hoatranlabs.local:9443/application/o/proxmox/
	client-id <CLIENT_ID>
	username-claim username
	autocreate 1

Thông tin nhạy cảm nằm ở /etc/pve/priv/ (chỉ root đọc được): shadow.cfg (băm mật khẩu realm pve), tfa.cfg (bí mật TOTP/WebAuthn/recovery keys), token.cfg (băm secret của token), realm/<tên>.pw (mật khẩu bind LDAP). Đừng đưa các tệp này vào git hoặc ảnh chụp; bản sao lưu của chúng phải được mã hoá (backup /etc/pve đã làm ở bài 05).

Mẹo đọc nhanh. pveum acl list, pveum user list --full 1, pveum role list cho cùng thông tin dưới dạng bảng; thêm --output-format json-pretty khi cần xử lý bằng script.

1.4 Vai trò dựng sẵn

Vai tròÝ nghĩa (theo tài liệu PVE)Dùng trong lab
AdministratorToàn quyền, kể cả sửa quyền và cấu hình hệ thốngChỉ grp-pve-admin
NoAccessKhông quyền; cũng dùng để chặn quyền kế thừa ở một pathDự phòng
PVEAdminHầu hết tác vụ, trừ Sys.PowerMgmt, Sys.Modify, Realm.Allocate, Permissions.ModifyKhông dùng cho người; xem ghi chú PDM ở mục 6
PVEAuditorChỉ đọcThay bằng AuditReadOnly (mục 4)
PVEVMAdmin / PVEVMUserQuản trị đầy đủ VM / xem, backup, CD-ROM, console, nguồnThay bằng VMOperator
PVEDatastoreAdmin / PVEDatastoreUserQuản lý / cấp phát không gian lưu trữ và xem storagePVEDatastoreUser cho storage vm-ceph
PVETemplateUserXem và clone templateTemplate 9000/9001
PVEPoolAdmin / PVEPoolUserQuản lý / xem poolDự phòng
PVESDNAdmin / PVESDNUserQuản lý SDN / dùng bridge, vnetPVESDNUser cho vmbr0
PVESysAdminAudit, console hệ thống, đọc syslogDự phòng
PVEUserAdminQuản lý userDự phòng

Danh sách privilege chính xác của từng vai trò có thể đổi giữa các bản PVE; xem đúng bản đang chạy bằng pveum role list --output-format json-pretty hoặc ở Datacenter → Permissions → Roles.

1.5 Path, kế thừa (propagate) và pool

PathPhạm vi
/Toàn bộ cluster
/nodes/{node}Một node
/vms · /vms/{vmid}Mọi VM · một VM
/storage/{storeid}Một storage
/pool/{pool}Mọi VM và storage thuộc pool
/sdn/zones/localnetworkCác bridge cục bộ (privilege SDN.Use)
/access/groups · /access/realms/{realm}Quản trị nhóm · quản trị realm

Các quy tắc cần nhớ:

  • Mặc định propagate = 1: quyền ở path cha kế thừa xuống path con; quyền đặt ở path sâu hơn thay thế quyền kế thừa.
  • Quyền của user thay thế quyền của nhóm mà user thuộc về; quyền nhóm áp dụng cho mọi thành viên.
  • NoAccess huỷ mọi vai trò khác tại path đó.
  • Quyền của VM được xét cả theo /vms/{vmid} lẫn pool chứa VM đó. VM không thuộc pool nào thì chỉ chịu ACL ở /vms/... và / — đó là tính chất "mặc định chặn" mà mô hình pool tận dụng (mục 5).
  • Token có privilege separation (mặc định khi tạo) có quyền hiệu lực là giao của quyền user và quyền của chính token: token không bao giờ vượt quá user sở hữu.
  • Token không dùng được cho các endpoint console VM/node.

1.6 Thay đổi privilege cần biết khi viết vai trò tuỳ chỉnh

Từ bảnThay đổiẢnh hưởng
9.0VM.Monitor bị bỏ; xem monitor KVM cần Sys.Audit (lệnh khác cần Sys.Modify)Vai trò tuỳ chỉnh cũ có VM.Monitor phải sửa; pve8to9 phát hiện
9.0Thêm VM.Replicate; thêm nhóm VM.GuestAgent.*Replication không còn đòi Datastore.Allocate
9.0Tên pool mới phải bắt đầu bằng chữ cáiDùng pool-prod, không dùng 1-prod
9.2Khởi động VM sau khi tạo / restore / rollback snapshot cần VM.PowerMgmtTemplateDeployer phải có VM.PowerMgmt
9.2Thêm VM/CT làm HA resource ngay lúc tạo/restore cần Sys.ConsoleNgười tạo VM kèm HA phải có quyền này (cần kiểm lại trên máy thật)
9.2Xem mật khẩu cloud-init cần VM.Config.CloudinitChỉ vai trò triển khai mới nên có
9.2Token có thể tạo lại secret tại chỗ (--regenerate 1) mà giữ nguyên ACLDùng cho quay vòng token ở mục 6
02

Chuẩn bị: kiểm tra hiện trạng và sao lưu cấu hình

Chỉ chạy RBAC khi cluster có quorum. Ghi user.cfg, tạo user/token/ACL cần thư mục /etc/pve ghi được; nếu mất quorum, /etc/pve chuyển sang chỉ đọc và mọi lệnh pveum ghi sẽ lỗi. Kiểm tra trước khi làm.

Chạy trên node1 (SSH root@node1; các mục sau dùng sudo với sysadmin khi đã tạo xong):

pveversion                       # pve-manager/9.2.x/...
pvecm status | grep -E 'Quorate|Nodes|Expected votes'   # cluster: Quorate: Yes
timedatectl | grep -E 'System clock synchronized|NTP service'   # phải là yes/active (OIDC, token expire đều dựa vào giờ)

pveum realm list                 # mặc định chỉ có pam và pve
pveum user list --full 1         # mặc định chỉ có root@pam
pveum group list
pveum role list
pveum acl list
Terminal node1: pveversion báo pve-manager 9.2.x, pvecm status có Quorate: Yes, pveum realm list chỉ có pam và pve, pveum user list --full 1 chỉ có root@pam trước khi áp dụng RBAC.
Terminal node1: pveversion báo pve-manager 9.2.x, pvecm status có Quorate: Yes, pveum realm list chỉ có pam và pve, pveum user list --full 1 chỉ có root@pam trước khi áp dụng RBAC.

Kết quả mong đợi trên cụm mới (mẫu, rút gọn):

realm : pam, pve
user  : root@pam   (enable 1, TFA: totp nếu đã làm ở bài 02); pdm@pve nếu đã làm bài 04 mục 9.3.1
group : (trống)
acl   : /  root@pam  Administrator   (ngầm định, không hiện trong user.cfg)

Cài công cụ phụ và sao lưu cấu hình hiện tại (sudo, jq không có sẵn trên PVE mới cài):

apt-get update
apt-get install -y sudo jq          # python3 đã có sẵn; kiểm tra: python3 --version

BK=/root/rbac-backup-$(date +%F)
install -d -m 700 "$BK"
cp -a /etc/pve/user.cfg /etc/pve/domains.cfg "$BK"/
cp -a /etc/pve/priv/tfa.cfg /etc/pve/priv/token.cfg "$BK"/ 2>/dev/null || true
ls -l "$BK"
Thư mục sao lưu chứa bí mật 2FA/token. tfa.cfg và token.cfg chỉ nên nằm ở thư mục 700 của root; xoá hoặc mã hoá (gpg --symmetric) sau khi mọi thứ ổn, không copy ra máy cá nhân.
03

Tài khoản quản trị hằng ngày và break-glass

Tạo người dùng Linux sysadmin trên MỌI node · Tạo nhóm, người dùng PVE và gán quyền Administrator · Bật xác thực hai lớp và recovery keys cho sysadmin@pam và root@pam

3.1 Tạo người dùng Linux sysadmin trên MỌI node

Realm pam dùng tài khoản Linux của từng node, vì vậy sysadmin phải tồn tại ở cả node1–node4 (và node5, node6 nếu quản trị chúng). Từ node1, dùng SSH giữa các node của cluster (đã có sẵn khoá root giữa các node sau khi join):

for n in node1 node2 node3 node4; do
  echo "=== $n ==="
  ssh -o BatchMode=yes root@"$n" '
    set -e
    apt-get install -y sudo >/dev/null
    id sysadmin >/dev/null 2>&1 || useradd -m -s /bin/bash -G sudo sysadmin
    id sysadmin
  '
done

Đặt mật khẩu (nhập tay, không đưa vào lệnh hay history; cùng một mật khẩu trên mọi node để đăng nhập GUI vào node nào cũng được — ở quy mô lớn dùng Ansible với băm trong vault, mục 11):

for n in node1 node2 node3 node4; do ssh -t root@"$n" passwd sysadmin; done

Chép khoá công khai SSH của quản trị viên cho sysadmin (từ máy quản trị): ssh-copy-id sysadmin@node1 rồi lặp lại cho từng node. Chính sách SSH (chỉ khoá, AllowGroups, tắt root login) do bài 05 quy định; nếu bài 05 dùng AllowGroups, thêm sysadmin vào nhóm đó.

Giữ phiên root đang mở cho tới khi sysadmin đăng nhập GUI và dùng sudo thành công (mục 3.3). Đừng tự khoá mình ra ngoài.

3.2 Tạo nhóm, người dùng PVE và gán quyền Administrator

pveum user add không tạo người dùng Linux, chỉ đăng ký tên đó vào PVE; vì vậy bước 3.1 phải làm trước.

pveum group add grp-pve-admin --comment 'Quản trị viên PVE (Administrator)'
pveum user add sysadmin@pam --comment 'Quản trị hằng ngày' --groups grp-pve-admin
pveum acl modify / --groups grp-pve-admin --roles Administrator
pveum user list --full 1
pveum acl list

Tương đương trên GUI (PVE 9): Datacenter → Permissions → Groups → Create (Name grp-pve-admin), Datacenter → Permissions → Users → Add (User name sysadmin, Realm Linux PAM standard authentication, Group grp-pve-admin), Datacenter → Permissions → Add → Group Permission (Path /, Group grp-pve-admin, Role Administrator, Propagate ☑).

3.3 Bật xác thực hai lớp và recovery keys cho sysadmin@pam và root@pam

Đăng nhập GUI bằng sysadmin (Realm Linux PAM), mở tên tài khoản ở góc trên bên phải → TFA (hoặc Datacenter → Permissions → Two Factor) → Add → TOTP: quét mã QR bằng ứng dụng authenticator, nhập mã 6 số, Add. Ngay sau đó Add → Recovery Keys và in/ghi lại cả bộ mã (mỗi user chỉ có một bộ recovery keys tại một thời điểm, mỗi mã dùng một lần). Làm lại cho root@pam nếu ở bài 02 chưa có recovery keys.

Datacenter → Permissions → Two Factor: user sysadmin@pam có một dòng TOTP và một dòng Recovery, kèm hộp thoại Add a TOTP login factor với mã QR (che secret).
Datacenter → Permissions → Two Factor: user sysadmin@pam có một dòng TOTP và một dòng Recovery, kèm hộp thoại Add a TOTP login factor với mã QR (che secret).
Kiểm tra trước khi đi tiếp. Đăng xuất, đăng nhập lại bằng sysadmin + mã TOTP; mở Datacenter → Permissions → Two Factor thấy một dòng TOTP và một dòng Recovery cho mỗi user; chạy sudo pveum acl list bằng phiên SSH của sysadmin thấy kết quả. Chỉ khi cả hai đều đạt mới coi sysadmin@pam là lối vào hằng ngày.

3.4 Chính sách break-glass

Tài khoảnRealmDùng khiQuy tắc
sysadmin@pampamSSO hoặc IdP ngừng; trước khi OIDC (bài 14) xongTOTP + recovery keys; không chia sẻ; chỉ 2–3 người biết mật khẩu
root@pampamMọi thứ khác hỏng (kể cả sysadmin, quorum, ACL cấu hình sai)Mật khẩu dài ≥ 24 ký tự ngẫu nhiên, in và niêm phong cất két; TOTP + recovery keys cất riêng chỗ khác; không dùng hằng ngày; không tạo API token cho root@pam

Lý do phải giữ lối thoát hiểm local: Authentik chạy ngay trên cluster này (VM234 trên node1). Nếu cluster mất nguồn hoặc node1 chưa lên, đăng nhập OIDC không thể hoạt động; pam thì vẫn dùng được trên từng node vì chỉ cần /etc/passwd của node đó. Riêng khi mất quorum, /etc/pve chuyển sang chỉ đọc: đăng nhập GUI bằng tài khoản đã bật 2FA có thể bị từ chối (PVE ghi trạng thái 2FA vào /etc/pve/priv/tfa.cfg — cần kiểm lại trên máy thật), nên lối vào khi mất quorum là console/SSH bằng root (quy trình ở bài 11), không dựa vào GUI. Mọi nội dung trong bảng này phải được diễn tập mỗi quý (mục 8.5).

Mật khẩu root cũng có thể lưu bản sao trong Vaultwarden (bài 19) cho tiện, nhưng Vaultwarden là VM chạy trên cùng cluster, nên bản niêm phong ngoại tuyến mới là bản "chắc chắn dùng được" lúc sự cố.
04

Nhóm, vai trò tuỳ chỉnh và ACL

Năm nhóm chuẩn · Sáu vai trò tuỳ chỉnh · Bảng ACL chuẩn

4.1 Năm nhóm chuẩn

Mọi quyền gắn vào nhóm, không gắn vào từng người: thêm/bớt nhân sự chỉ là thêm/bớt thành viên nhóm, không đụng tới ACL.

NhómAiQuyền tóm tắt
grp-pve-admin2–3 quản trị viên hạ tầngAdministrator tại /
grp-pve-opsNhân viên vận hànhXem toàn cluster; vận hành VM trong pool-prod; vận hành và dựng VM thử trong pool-test
grp-pve-readonlyKiểm toán viên, helpdeskChỉ đọc toàn cluster
grp-pve-backupNhóm sao lưu / DRChạy backup mọi pool tới pbs-primary; không restore đè, không sửa cấu hình
grp-pve-automationChỉ tài khoản dịch vụ (không bao giờ là người)Giống ops nhưng được dựng VM ở cả hai pool, kèm quyền hạ tầng qua API (firewall, chứng chỉ, thông báo); token của nó hẹp hơn nữa (mục 6)

4.2 Sáu vai trò tuỳ chỉnh

Vai trò dựng sẵn của PVE có thể đổi giữa các bản (9.0 đã bỏ VM.Monitor, thêm VM.Replicate, VM.GuestAgent.*), nên lab định nghĩa vai trò tường minh để so sánh được qua git diff và không bị nới quyền âm thầm khi nâng cấp.

Vai tròPrivilegeCố ý KHÔNG có
VMOperatorVM.Audit VM.Console VM.PowerMgmt VM.SnapshotVM.Allocate, VM.Config.*, VM.Clone, VM.Backup, mọi Sys.* — không tạo/xoá/đổi cấu hình VM
AuditReadOnlySys.Audit VM.Audit Datastore.Audit Pool.Audit SDN.Audit Mapping.AuditMọi privilege ghi; không Sys.Syslog (log hệ thống có thể chứa dữ liệu nhạy cảm)
TemplateDeployerVM.Allocate VM.Clone VM.Audit VM.PowerMgmt VM.Console VM.Config.CPU VM.Config.Memory VM.Config.Disk VM.Config.Network VM.Config.Options VM.Config.Cloudinit VM.Config.HWTypeSys.*, Permissions.Modify, Datastore.Allocate; VM.PowerMgmt bắt buộc từ PVE 9.2 để khởi động VM vừa clone
BackupOperatorVM.Audit VM.Backup Datastore.Audit Datastore.AllocateSpace Pool.AuditVM.Allocate — nên nhóm backup chạy được backup nhưng không restore đè VM đang chạy
FirewallOperatorSys.Audit Sys.Modify Sys.Syslog VM.Config.NetworkVM.Allocate, VM.PowerMgmt, User.Modify, Permissions.Modify. Dùng cho cấu hình qua API: firewall cấp cluster (Sys.Modify tại /), cấp node (Sys.Modify tại /nodes/<node>, cũng đủ cho cấp chứng chỉ ACME ở bài 09), cấp VM (VM.Config.Network), đọc log firewall (Sys.Syslog) — bài 05. Sys.Modify là quyền nhạy cảm (đổi cả cấu hình mạng node), nên ACL được đặt hẹp ở 4.3
NotificationOperatorMapping.Audit Mapping.Modify Mapping.UseMọi Sys.* và VM.*. Dùng để cấu hình target/matcher thông báo tại /mapping/notifications qua API (bài 10)

Ý nghĩa các privilege then chốt: VM.PowerMgmt (start/stop/reset), VM.Console (noVNC/SPICE vào VM; console node là Sys.Console), VM.Snapshot (tạo/xoá snapshot; VM.Snapshot.Rollback là quyền riêng, chỉ admin giữ), VM.Clone (clone từ template), VM.Allocate (tạo/xoá VM), VM.Config.* (từng nhóm thiết lập của VM), Datastore.AllocateSpace (cấp phát dung lượng trên storage — cần cho clone, backup, restore).

Thêm bớt privilege theo nhu cầu thật. VM.Config.HWType chỉ cần khi người triển khai đổi kiểu máy/controller; nếu template đã chuẩn hoá (bài 07) có thể bỏ. Sau mỗi lần nâng cấp PVE chạy lại pve-rbac-audit.sh (mục 8) và đọc release notes — ví dụ 9.2 đòi thêm VM.PowerMgmt cho luồng clone-rồi-start.

Tạo một vai trò trên GUI (PVE 9): Datacenter → Permissions → Roles → Create → Name VMOperator → tick các Privileges trong danh sách → Create. Vì phải làm cho cả sáu vai trò và lặp lại ở nhiều cluster, mục 5.3 dùng script thay vì GUI.

Datacenter → Permissions → Roles → Create: hộp thoại tạo vai trò VMOperator với bốn privilege VM.Audit, VM.Console, VM.PowerMgmt, VM.Snapshot được tick.
Datacenter → Permissions → Roles → Create: hộp thoại tạo vai trò VMOperator với bốn privilege VM.Audit, VM.Console, VM.PowerMgmt, VM.Snapshot được tick.

4.3 Bảng ACL chuẩn

Đây là toàn bộ ACL của mô hình (script ở mục 5.3 tạo đúng các dòng này). @nhóm là nhóm; ở realm OIDC/AD, mỗi nhóm của người được lặp thêm bản có hậu tố realm (grp-pve-ops-authentik, grp-pve-ops-hoatran-ad).

PathChủ thểVai tròMục đích
/@grp-pve-adminAdministratorQuản trị toàn bộ
/@grp-pve-ops @grp-pve-readonly @grp-pve-backup @grp-pve-automationAuditReadOnlyMọi nhóm thấy toàn cluster nhưng không sửa
/pool/pool-prod@grp-pve-opsVMOperatorVận hành dịch vụ ứng dụng
/pool/pool-prod@grp-pve-automationVMOperator TemplateDeployerTự động hoá dựng/vận hành
/pool/pool-test@grp-pve-ops @grp-pve-automationVMOperator TemplateDeployerDựng VM thử
/pool/pool-prod /pool/pool-test /pool/pool-infra@grp-pve-backupBackupOperatorChạy backup (VM.Backup)
/storage/pbs-primary@grp-pve-backupBackupOperatorGhi backup lên PBS (Datastore.AllocateSpace)
/ (không propagate)@grp-pve-automationFirewallOperatorSys.Modify đúng ở cấp cluster (firewall datacenter, tuỳ chọn cluster), không kế thừa xuống node/VM
/nodes@grp-pve-automationFirewallOperatorFirewall cấp node, cấp chứng chỉ node (bài 09), đọc log (Sys.Syslog)
/pool/pool-prod /pool/pool-test@grp-pve-automationFirewallOperatorFirewall cấp VM (VM.Config.Network); không gồm pool-infra
/mapping/notifications@grp-pve-automationNotificationOperatorCấu hình thông báo qua API (bài 10)
/storage/vm-ceph@grp-pve-ops @grp-pve-automationPVEDatastoreUserCấp đĩa cho VM mới/clone
/sdn/zones/localnetwork@grp-pve-ops @grp-pve-automationPVESDNUserGắn VM vào bridge vmbr0 (SDN.Use)
/vms/9000 /vms/9001@grp-pve-ops @grp-pve-automationPVETemplateUserĐược clone từ template

Điều bảng này cố ý để trống: pool-infra (PBS, PDM, Authentik, step-CA, dc1, Wazuh, ops01...) chỉ grp-pve-admin thao tác; ops/readonly/backup chỉ nhìn thấy.

Ma trận tóm tắt "ai làm được gì".
Việcadminopsreadonlybackupautomation
Xem mọi tài nguyên✅✅✅✅✅
Start/stop/console VM pool-prod✅✅❌❌✅ (start/stop)
Tạo/clone VM trong pool-test✅✅❌❌✅
Tạo/xoá VM trong pool-prod✅❌❌❌user có (nhóm); token ansible thì không (mục 6)
Thao tác VM trong pool-infra✅❌❌❌❌
Chạy backup ngay✅❌❌✅❌
Restore đè VM, sửa storage✅❌❌❌❌
Ghi firewall / chứng chỉ / thông báo qua API (Sys.Modify)✅❌❌❌⚠️ token hạ tầng (mục 6.2)
Quản lý user/ACL/realm✅❌❌❌❌
05

Pool và script áp dụng RBAC

Vì sao phải dùng pool · Phân loại VM theo pool (ví dụ cho 30 VM lõi của lab) · Script pve-rbac-apply.sh: dựng toàn bộ mô hình, chạy lại được

5.1 Vì sao phải dùng pool

Gắn quyền cho từng VM là cách chắc chắn dẫn tới ACL mồ côi và quên cấp quyền cho VM mới. Pool gom VM (và storage) vào một nhóm tài nguyên; quyền đặt ở /pool/<tên> kế thừa cho mọi thành viên. Khi dựng VM mới chỉ cần chọn đúng pool — phân quyền đi theo. VM không thuộc pool nào là VM "vô chủ": chỉ admin và những ai có ACL ở / nhìn thấy/chỉnh được.

5.2 Phân loại VM theo pool (ví dụ cho 30 VM lõi của lab)

PoolAi thao tácVMIDNội dung
pool-infraChỉ grp-pve-admin101, 102, 232, 233, 234, 235, 236, 242, 243, 246, 247, 250, 269, 280, 290PBS, PDM, Headscale, privacyIDEA, Authentik, Prometheus, Grafana, step-CA, Vaultwarden, Mailu, Pi-hole, dc1, Vault, Wazuh, ops01
pool-prodgrp-pve-ops (+ token của automation)239, 240, 241, 244, 245, 251, 260–265, 266, 267, 268, 270, 271, 272Harbor, Gitea, MediaMTX, OpenVAS, NetBox, Samba file server, 6 VM K3s, SonarQube, Nexus, SeaweedFS S3, TheHive, CrowdSec, Mattermost
pool-testgrp-pve-ops, grp-pve-automation281, 282, 283 và mọi VM thử mớiLab WiFi RADIUS (bài 39, 40) và VM thử

Đây là một cách chia hợp lý cho lab chứ không phải quy định cứng: tiêu chí là "hỏng/bị thao tác nhầm thì ảnh hưởng nền tảng hay chỉ một ứng dụng". Template 9000/9001 nằm ở pool-infra và được cấp quyền clone riêng qua /vms/9000, /vms/9001.

5.3 Script pve-rbac-apply.sh: dựng toàn bộ mô hình, chạy lại được

Script idempotent (chạy bao nhiêu lần cũng ra cùng kết quả, không xoá ACL ngoài danh sách), có DRY_RUN=1 để xem trước, chỉ gán pool cho VM đang tồn tại (bài làm tuần tự nên nhiều VM chưa dựng), và bỏ qua storage/template chưa có. Chạy trên một node (cấu hình /etc/pve đồng bộ cả cluster):

#!/usr/bin/env bash
# /usr/local/sbin/pve-rbac-apply.sh — áp dụng mô hình RBAC chuẩn HOATRANLABS (bài 08). Idempotent.
#   DRY_RUN=1 pve-rbac-apply.sh                       # chỉ in lệnh, không thực thi
#   EXTRA_REALMS="authentik hoatran-ad" pve-rbac-apply.sh   # thêm nhóm của realm OIDC/AD (mục 9, 10)
set -euo pipefail

[ "$(id -u)" -eq 0 ] || { echo "Cần chạy bằng root (sudo)." >&2; exit 1; }
command -v jq >/dev/null || { echo "Thiếu jq: apt-get install -y jq" >&2; exit 1; }
if [ -f /etc/pve/corosync.conf ]; then          # cluster: bắt buộc có quorum mới ghi được /etc/pve
  pvecm status | grep -Eq 'Quorate:[[:space:]]+Yes' || { echo "Cluster mất quorum — dừng." >&2; exit 1; }
fi

EXTRA_REALMS="${EXTRA_REALMS:-}"
run() { if [ "${DRY_RUN:-0}" = 1 ]; then echo "+ $*"; else "$@"; fi; }
has() { awk -F: -v t="$1" -v i="$2" '$1==t && $2==i {f=1} END{exit !f}' /etc/pve/user.cfg 2>/dev/null; }
RES_VMS=" $(pvesh get /cluster/resources --type vm --output-format json | jq -r '[.[].vmid] | join(" ")') "
vm_exists() { case "$RES_VMS" in *" $1 "*) return 0 ;; *) return 1 ;; esac; }
storage_exists() { pvesm status 2>/dev/null | awk 'NR>1{print $1}' | grep -qx "$1"; }

# ── 1. Vai trò tuỳ chỉnh ─────────────────────────────────────────────────────
declare -A ROLES=(
  [VMOperator]="VM.Audit VM.Console VM.PowerMgmt VM.Snapshot"
  [AuditReadOnly]="Sys.Audit VM.Audit Datastore.Audit Pool.Audit SDN.Audit Mapping.Audit"
  [TemplateDeployer]="VM.Allocate VM.Clone VM.Audit VM.PowerMgmt VM.Console VM.Config.CPU VM.Config.Memory VM.Config.Disk VM.Config.Network VM.Config.Options VM.Config.Cloudinit VM.Config.HWType"
  [BackupOperator]="VM.Audit VM.Backup Datastore.Audit Datastore.AllocateSpace Pool.Audit"
  [FirewallOperator]="Sys.Audit Sys.Modify Sys.Syslog VM.Config.Network"
  [NotificationOperator]="Mapping.Audit Mapping.Modify Mapping.Use"
)
for r in "${!ROLES[@]}"; do
  if has role "$r"; then run pveum role modify "$r" --privs "${ROLES[$r]}"
  else run pveum role add "$r" --privs "${ROLES[$r]}"; fi
done

# ── 2. Nhóm (nhóm của người được nhân bản sang các realm OIDC/AD) ───────────
declare -A GROUP_COMMENT=(
  [grp-pve-admin]="Quản trị viên (Administrator)"
  [grp-pve-ops]="Vận hành VM"
  [grp-pve-readonly]="Chỉ đọc / kiểm toán"
  [grp-pve-backup]="Sao lưu / DR"
  [grp-pve-automation]="Tài khoản dịch vụ (Ansible, OpenTofu)"
)
HUMAN="grp-pve-admin grp-pve-ops grp-pve-readonly grp-pve-backup"
ensure_group() { if ! has group "$1"; then run pveum group add "$1" --comment "$2"; fi; }
for g in "${!GROUP_COMMENT[@]}"; do ensure_group "$g" "${GROUP_COMMENT[$g]}"; done
for g in $HUMAN; do for r in $EXTRA_REALMS; do ensure_group "$g-$r" "${GROUP_COMMENT[$g]} (realm $r)"; done; done

# ── 3. Pool (chỉ thêm VM đang tồn tại) ───────────────────────────────────────
declare -A POOL_COMMENT=(
  [pool-infra]="Hạ tầng nền tảng và bảo mật — chỉ grp-pve-admin thao tác"
  [pool-prod]="Dịch vụ ứng dụng"
  [pool-test]="Thử nghiệm / lab"
)
declare -A POOL_VMS=(
  [pool-infra]="101 102 232 233 234 235 236 242 243 246 247 250 269 280 290"
  [pool-prod]="239 240 241 244 245 251 260 261 262 263 264 265 266 267 268 270 271 272"
  [pool-test]="281 282 283"
)
for p in "${!POOL_COMMENT[@]}"; do
  if ! has pool "$p"; then run pveum pool add "$p" --comment "${POOL_COMMENT[$p]}"; fi
  ids=""
  for v in ${POOL_VMS[$p]}; do if vm_exists "$v"; then ids="${ids:+$ids,}$v"; fi; done
  if [ -n "$ids" ]; then run pveum pool modify "$p" --vms "$ids" --allow-move 1; fi
done

# ── 4. ACL ───────────────────────────────────────────────────────────────────
expand() {       # "g1 g2" -> "g1,g1-r1,g1-r2,g2,..." (chỉ dùng cho nhóm của người)
  local out="" g r
  for g in $1; do out="${out:+$out,}$g"; for r in $EXTRA_REALMS; do out="$out,$g-$r"; done; done
  echo "$out"
}
acl_h() { run pveum acl modify "$1" --roles "$2" --groups "$(expand "$3")"; }   # nhóm của người
acl_a() { run pveum acl modify "$1" --roles "$2" --groups "${3// /,}" "${@:4}"; }   # nhóm tự động hoá (không mở rộng); $4... = tuỳ chọn thêm, vd --propagate 0
token_exists() { pveum user token list "${1%%!*}" --output-format json 2>/dev/null | jq -e --arg t "${1#*!}" '.[] | select(.tokenid == $t)' >/dev/null; }
acl_t() { if token_exists "$3"; then run pveum acl modify "$1" --roles "$2" --tokens "$3" "${@:4}"; fi; }   # token chưa tạo thì bỏ qua
acl_u() { if has user "$3"; then run pveum acl modify "$1" --roles "$2" --users "$3"; fi; }       # tài khoản dịch vụ (ACL trực tiếp)

acl_h /                    Administrator   "grp-pve-admin"
acl_h /                    AuditReadOnly   "grp-pve-ops grp-pve-readonly grp-pve-backup"
acl_a /                    AuditReadOnly   "grp-pve-automation"
acl_h /pool/pool-prod      VMOperator      "grp-pve-ops"
acl_a /pool/pool-prod      VMOperator,TemplateDeployer "grp-pve-automation"
acl_h /pool/pool-test      VMOperator,TemplateDeployer "grp-pve-ops"
acl_a /pool/pool-test      VMOperator,TemplateDeployer "grp-pve-automation"
for p in pool-prod pool-test pool-infra; do acl_h "/pool/$p" BackupOperator "grp-pve-backup"; done
if storage_exists pbs-primary; then acl_h /storage/pbs-primary BackupOperator "grp-pve-backup"; fi
if storage_exists vm-ceph; then
  acl_h /storage/vm-ceph PVEDatastoreUser "grp-pve-ops"
  acl_a /storage/vm-ceph PVEDatastoreUser "grp-pve-automation"
fi
acl_h /sdn/zones/localnetwork PVESDNUser "grp-pve-ops"
acl_a /sdn/zones/localnetwork PVESDNUser "grp-pve-automation"
# Cấu hình hạ tầng qua API (bài 05 firewall, bài 09 chứng chỉ, bài 10 thông báo) — Sys.Modify chỉ đặt ở những path cần
acl_a /                    FirewallOperator "grp-pve-automation" --propagate 0
acl_a /nodes               FirewallOperator "grp-pve-automation"
acl_a /pool/pool-prod      FirewallOperator "grp-pve-automation"
acl_a /pool/pool-test      FirewallOperator "grp-pve-automation"
acl_a /mapping/notifications NotificationOperator "grp-pve-automation" || echo "!! bỏ qua /mapping/notifications (PVE bản này không nhận path đó — cần kiểm lại)" >&2
for t in 9000 9001; do
  if vm_exists "$t"; then acl_h "/vms/$t" PVETemplateUser "grp-pve-ops"; acl_a "/vms/$t" PVETemplateUser "grp-pve-automation"; fi
done

# ── 5. ACL của API token (chỉ chạy khi token đã được tạo ở mục 6) — hẹp hơn quyền của user sở hữu ─
TA='svc-automation@pve!ansible'
acl_t /                         AuditReadOnly                    "$TA"
acl_t /pool/pool-test           VMOperator,TemplateDeployer      "$TA"
acl_t /pool/pool-prod           VMOperator                       "$TA"
if storage_exists vm-ceph; then acl_t /storage/vm-ceph PVEDatastoreUser "$TA"; fi
acl_t /sdn/zones/localnetwork   PVESDNUser                       "$TA"
for t in 9000 9001; do if vm_exists "$t"; then acl_t "/vms/$t" PVETemplateUser "$TA"; fi; done
acl_u /                         AuditReadOnly                    'svc-monitoring@pve'                # user (bài 15, Bước 11.1)
acl_t /                         AuditReadOnly                    'svc-monitoring@pve!prometheus'     # và token
# Quyền hạ tầng của token: mặc định dùng chung token ansible (bài 05, 09, 10 gọi API bằng token này). Muốn tách khỏi quyền vòng đời VM:
#   tạo token thứ hai (vd svc-automation@pve!ansible-infra, mục 6.2) rồi chạy INFRA_TOKEN='svc-automation@pve!ansible-infra' pve-rbac-apply.sh
TI="${INFRA_TOKEN:-$TA}"
acl_t /                         FirewallOperator                 "$TI" --propagate 0
acl_t /nodes                    FirewallOperator                 "$TI"
acl_t /pool/pool-prod           FirewallOperator                 "$TI"
acl_t /pool/pool-test           FirewallOperator                 "$TI"
acl_t /mapping/notifications    NotificationOperator             "$TI" || echo "!! bỏ qua /mapping/notifications cho token (cần kiểm lại)" >&2

echo "--- Hoàn tất. ACL hiện tại:"; pveum acl list

Lưu thành /usr/local/sbin/pve-rbac-apply.sh (chmod 750) trên node1, chạy thử trước:

DRY_RUN=1 /usr/local/sbin/pve-rbac-apply.sh | head -60     # đọc kỹ các lệnh sẽ chạy
/usr/local/sbin/pve-rbac-apply.sh
Terminal node1: DRY_RUN=1 pve-rbac-apply.sh in danh sách lệnh pveum role/group/pool/acl sẽ chạy, rồi chạy thật và kết thúc bằng pveum acl list.
Terminal node1: DRY_RUN=1 pve-rbac-apply.sh in danh sách lệnh pveum role/group/pool/acl sẽ chạy, rồi chạy thật và kết thúc bằng pveum acl list.
Script chỉ thêm/sửa, không xoá. Nếu trước đó ai đó đã tạo ACL khác (ví dụ gán PVEAdmin cho một user), chúng vẫn còn nguyên; mục 8 có bước phát hiện và gỡ chúng bằng pveum acl delete. pveum role modify ghi đè danh sách privilege của vai trò (không --append) nên script luôn kéo vai trò về đúng định nghĩa.

5.4 Đặt VM vào đúng pool khi tạo mới

Cách tạoCách chọn pool
GUI Create VMTab General → Resource Pool
qm create / qm clone--pool pool-test (ví dụ qm clone 9000 391 --name test-rbac --full 1 --pool pool-test)
Đã có sẵn VMpveum pool modify pool-prod --vms 300 --allow-move 1
Script create-lab-vms.sh (bài 07)Thêm --pool theo bảng 5.2

Tìm VM "vô chủ" (chưa thuộc pool nào):

pvesh get /cluster/resources --type vm --output-format json \
  | jq -r '.[] | select((.pool // "") == "") | "\(.vmid)\t\(.name)\t\(.node)"'
Datacenter → Permissions → Pools → pool-prod → Members: danh sách VM thuộc pool-prod (Harbor, Gitea, K3s...).
Datacenter → Permissions → Pools → pool-prod → Members: danh sách VM thuộc pool-prod (Harbor, Gitea, K3s...).

5.5 Kiểm tra kết quả

pveum group list
pveum role list --output-format json-pretty | jq -r '.[] | select(.roleid|test("^(VMOperator|AuditReadOnly|TemplateDeployer|BackupOperator|FirewallOperator|NotificationOperator)$")) | "\(.roleid): \(.privs)"'
pveum pool list
pveum acl list

Kết quả pveum acl list (mẫu, rút gọn):

path                      ugid                    roleid            propagate
/                         grp-pve-admin           Administrator     1
/                         grp-pve-ops             AuditReadOnly     1
/pool/pool-prod           grp-pve-ops             VMOperator        1
/pool/pool-prod           grp-pve-automation      TemplateDeployer  1
/pool/pool-prod           grp-pve-automation      VMOperator        1
/pool/pool-infra          grp-pve-backup          BackupOperator    1
/storage/vm-ceph          grp-pve-ops             PVEDatastoreUser  1
/sdn/zones/localnetwork   grp-pve-ops             PVESDNUser        1
...
Datacenter → Permissions (bảng ACL): các dòng path /, /pool/pool-prod, /storage/vm-ceph gán cho nhóm grp-pve-* với vai trò AuditReadOnly, VMOperator, TemplateDeployer.
Datacenter → Permissions (bảng ACL): các dòng path /, /pool/pool-prod, /storage/vm-ceph gán cho nhóm grp-pve-* với vai trò AuditReadOnly, VMOperator, TemplateDeployer.

5.6 Thử "đóng vai" một nhân viên vận hành (kiểm tra quyền âm)

Phân quyền chỉ đáng tin khi đã thử cả những việc không được làm. Tạo user thử trong nhóm ops, kiểm tra quyền hiệu lực bằng lệnh rồi bằng GUI:

pveum user add test-ops@pve --comment 'Tài khoản thử, xoá sau khi kiểm tra' --groups grp-pve-ops
pveum passwd test-ops@pve                          # nhập mật khẩu tạm khi được hỏi
pveum user permissions test-ops@pve --path /pool/pool-prod     # kỳ vọng: VM.Audit VM.Console VM.PowerMgmt VM.Snapshot + các *.Audit
pveum user permissions test-ops@pve --path /pool/pool-infra    # kỳ vọng: chỉ các quyền *.Audit (kế thừa từ /)

Đăng nhập GUI bằng test-ops (Realm Proxmox VE authentication server): trong một VM của pool-prod bấm được Console, Start/Shutdown, Snapshots → Take Snapshot; nhưng Hardware → Edit, Remove, Migrate phải báo "Permission check failed"; VM của pool-infra chỉ xem được. Xong thì xoá: pveum user delete test-ops@pve.

Đăng nhập GUI bằng test-ops@pve: VM trong pool-prod có nút Console/Start, còn Hardware → Edit hoặc Remove báo 'Permission check failed'; VM pool-infra chỉ xem được.
Đăng nhập GUI bằng test-ops@pve: VM trong pool-prod có nút Console/Start, còn Hardware → Edit hoặc Remove báo 'Permission check failed'; VM pool-infra chỉ xem được.
Nếu ops xoá/sửa được VM pool-infra, tìm ACL thừa ở / hoặc /vms (pveum acl list | grep -E '^/ |^/vms') — quyền cấp ở path cha kế thừa xuống pool.
06

Tài khoản dịch vụ và API token (quyền tối thiểu)

Nguyên tắc · Tài khoản và token chuẩn · Tạo user và token

6.1 Nguyên tắc

Nguyên tắcCách thực hiện
Mỗi công cụ, mỗi máy một token riêngansible (ops01), prometheus (VM235), pdm-token (pdm01): lộ một cái chỉ thu hồi một cái
Không bao giờ dùng token của root@pamToken thừa hưởng toàn quyền; thao tác root-only không đáng để mở cửa này
Privilege separation bật (--privsep 1)Quyền hiệu lực = giao của user và token → đặt ACL thẳng cho token để thu hẹp hơn user
Có hạn dùng (--expire)180 ngày cho tự động hoá, 365 ngày cho giám sát; script kiểm toán cảnh báo khi còn ≤ 30 ngày
User dịch vụ ở realm pve, không đặt mật khẩuKhông đăng nhập GUI/SSH được, chỉ gọi API bằng token
Secret không ghi vào git, ảnh chụp, SlackCất trong ansible-vault (bài 07) hoặc HashiCorp Vault (bài 34), file env chmod 600
Giới hạn nguồn gọi APIFirewall (bài 05): cổng 8006 chỉ mở cho IPSet mgmt-admins (có ops01) và nhóm sg-pve-integr (PDM, Prometheus); PVE không có tuỳ chọn ràng buộc token theo IP

6.2 Tài khoản và token chuẩn

UserTokenCông cụQuyền của tokenHết hạn
svc-automation@pve (nhóm grp-pve-automation)ansibleAnsible từ ops01 (bài 07)AuditReadOnly tại /; VMOperator+TemplateDeployer tại pool-test; VMOperator tại pool-prod; PVEDatastoreUser tại vm-ceph; PVESDNUser; PVETemplateUser tại 9000/9001; hạ tầng: FirewallOperator tại / (không propagate), /nodes, pool-prod, pool-test và NotificationOperator tại /mapping/notifications180 ngày
svc-monitoring@pve (ACL gán trực tiếp, không qua nhóm)prometheusprometheus-pve-exporter (bài 15)AuditReadOnly tại /365 ngày
pdm@pve (đã tạo ở bài 04)pdm-tokenProxmox Datacenter Manager (bài 04)Hạ từ PVEAdmin xuống AuditReadOnly (mục 6.7); token privsep=0 nên lấy quyền từ user365 ngày

Token ansible cố ý hẹp hơn grp-pve-automation: nhóm cho phép dựng VM ở cả pool-prod, nhưng token chỉ được vận hành VM ở pool-prod và chỉ dựng VM ở pool-test. Khi cần tạo VM ở pool-prod, người dùng (hoặc một token khác, có ghi nhận) làm có chủ đích.

Các bài 05 (firewall), 09 (chứng chỉ) và 10 (thông báo) đều gọi API bằng token svc-automation@pve!ansible, nên token này mang thêm quyền hạ tầng: FirewallOperator (Sys.Modify tại / không kế thừa, Sys.Modify + Sys.Syslog tại /nodes, VM.Config.Network tại hai pool ứng dụng, không gồm pool-infra) và NotificationOperator tại /mapping/notifications. Hãy hiểu đây là quyền lớn: Sys.Modify cho phép đổi cả cấu hình mạng của node, nên token có thể làm node mất kết nối nếu bị lạm dụng. Lab chấp nhận vì ops01 vốn đã SSH sysadmin + sudo vào node (quyền lớn hơn). Muốn tách quyền: tạo token thứ hai svc-automation@pve!ansible-infra (cùng cách tạo ở mục 6.3), cấp quyền hạ tầng bằng INFRA_TOKEN='svc-automation@pve!ansible-infra' pve-rbac-apply.sh, chỉ giữ !ansible cho vòng đời VM, rồi đổi biến token trong các playbook firewall/chứng chỉ/thông báo. Vì privilege separation, user svc-automation@pve (qua nhóm grp-pve-automation) cũng phải có đúng những quyền này — script đã gán.

6.3 Tạo user và token

Chạy trên node1 (root hoặc sudo). User dịch vụ không có mật khẩu:

pveum user add svc-automation@pve --comment 'Ansible/OpenTofu từ ops01 (bài 07)' --groups grp-pve-automation
pveum user add svc-monitoring@pve --comment 'prometheus-pve-exporter (bài 15)'

# Token giám sát: hết hạn sau 365 ngày, privilege separation bật
pveum user token add svc-monitoring@pve prometheus --privsep 1 \
  --expire "$(date -d '+365 days' +%s)" --comment 'pve-exporter trên VM235 (bài 15)'

# Token tự động hoá: 180 ngày
pveum user token add svc-automation@pve ansible --privsep 1 \
  --expire "$(date -d '+180 days' +%s)" --comment 'Ansible trên ops01 (bài 07)'

Kết quả (mẫu — secret chỉ hiện một lần, copy ngay):

┌──────────────┬──────────────────────────────────────┐
│ key          │ value                                │
╞══════════════╪══════════════════════════════════════╡
│ full-tokenid │ svc-monitoring@pve!prometheus        │
├──────────────┼──────────────────────────────────────┤
│ info         │ {"expire":1824000000,"privsep":"1"}  │
├──────────────┼──────────────────────────────────────┤
│ value        │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
└──────────────┴──────────────────────────────────────┘

Cách làm trên GUI (PVE 9): Datacenter → Permissions → API Tokens → Add → User svc-monitoring@pve, Token ID prometheus, Privilege Separation ☑, Expire (chọn ngày), Comment → Add → hộp thoại hiện Token ID và Secret; bấm Copy Secret Value trước khi đóng.

Datacenter → Permissions → API Tokens → Add: User svc-monitoring@pve, Token ID prometheus, Privilege Separation đã tick, Expire đặt ngày; hộp thoại Token Secret hiện một lần (che giá trị).
Datacenter → Permissions → API Tokens → Add: User svc-monitoring@pve, Token ID prometheus, Privilege Separation đã tick, Expire đặt ngày; hộp thoại Token Secret hiện một lần (che giá trị).

Cất secret đúng chỗ ngay lập tức. Với Ansible: trên ops01 mã hoá secret vào ansible-vault, dán secret rồi bấm Ctrl-D — secret không vào history và không nằm dạng rõ trên đĩa:

ansible-vault encrypt_string --vault-password-file ~/.ansible/vault_pass --stdin-name pve_api_token_secret \
  | tee -a ~/ansible/group_vars/pve_nodes/vault.yml     # mkdir -p ~/ansible/group_vars/pve_nodes trước nếu chưa có

Với Prometheus: đặt vào /opt/prometheus/pve-exporter/pve.env (chmod 600) theo bài 15, Bước 11.

Hai việc không được làm với token. (1) Tạo token cho root@pam — nếu đã lỡ có, pveum user token remove root@pam <tên>. (2) Dán secret vào ticket, chat, README hay commit. Nếu nghi ngờ lộ: quay vòng ngay (mục 6.8), không đợi xác minh.

6.4 Cấp ACL cho token

ACL của token do script ở mục 5.3 gán (khối "ACL của API token" chỉ chạy khi token đã tồn tại). Chạy lại script rồi kiểm tra:

/usr/local/sbin/pve-rbac-apply.sh >/dev/null
pveum user token permissions svc-monitoring@pve prometheus
pveum user token permissions svc-automation@pve ansible --path /pool/pool-prod

Kết quả svc-automation@pve!ansible (mẫu, rút gọn):

/pool/pool-prod: VM.Audit, VM.Console, VM.PowerMgmt, VM.Snapshot, Pool.Audit, ...

Phép thử "quyền hiệu lực là giao": nếu quên ACL cho token, token nhận 403 dù user có quyền — đó là hành vi đúng của privilege separation, không phải lỗi. Xem trực tiếp mà không cần secret bằng hai lệnh pveum user permissions <user> và pveum user token permissions <user> <token>.

6.5 Token giám sát cho prometheus-pve-exporter (bài 15)

Bài 15, Bước 11 chạy prometheus-pve-exporter 3.10.1 trong container pve-exporter trên VM235, đọc cấu hình từ pve.env, gọi API https://nodeN.hoatranlabs.local:8006 bằng token này. Phần của bài 08 chỉ gồm ba việc:

  • User svc-monitoring@pve và token svc-monitoring@pve!prometheus đều có AuditReadOnly tại / (ACL của user gán trực tiếp, ACL của token riêng; script mục 5.3 làm cả hai) — bắt buộc cả hai vì privilege separation. Bài 15 viết lệnh PVEAuditor trực tiếp cho user/token; dùng AuditReadOnly (cùng tập privilege chỉ đọc) là tương đương, script kiểm toán bỏ qua ACL trực tiếp của tài khoản svc-*.
  • Secret đưa vào pve.env: PVE_USER=svc-monitoring@pve, PVE_TOKEN_NAME=prometheus, PVE_TOKEN_VALUE=<TOKEN_SECRET>.
  • Exporter xác thực chứng chỉ của node theo FQDN: dùng PVE_VERIFY_SSL=true khi node đã có chứng chỉ step-CA hợp lệ (bài 09); trước đó tạm PVE_VERIFY_SSL=false (chứng chỉ tự ký mặc định của PVE), và nhớ rằng cổng 8006 được mở cho Prometheus (VM235) qua nhóm sg-pve-integr ở firewall (bài 05; rule được soạn sẵn ở trạng thái tắt, bật khi làm bài 15).

Kiểm tra trước khi sang bài 15 (chạy từ VM235 hoặc ops01):

read -rs -p 'Token secret: ' S; echo
curl -sS -k -H "Authorization: PVEAPIToken=svc-monitoring@pve!prometheus=$S" \
  https://node1.hoatranlabs.local:8006/api2/json/version ; echo
# Kỳ vọng (mẫu): {"data":{"release":"9.2","repoid":"...","version":"9.2.x"}}

# Phép thử quyền âm: token chỉ đọc KHÔNG được bật VM
curl -sS -k -o /dev/null -w '%{http_code}\n' -X POST \
  -H "Authorization: PVEAPIToken=svc-monitoring@pve!prometheus=$S" \
  https://node1.hoatranlabs.local:8006/api2/json/nodes/node1/qemu/247/status/start
# Kỳ vọng: 403   (Permission check failed (/vms/247, VM.PowerMgmt))
unset S
Terminal ops01 hoặc VM235: curl với token svc-monitoring@pve!prometheus trả dữ liệu /version, còn POST status/start trả mã 403 Permission check failed.
Terminal ops01 hoặc VM235: curl với token svc-monitoring@pve!prometheus trả dữ liệu /version, còn POST status/start trả mã 403 Permission check failed.

6.6 Token Ansible trên ops01 (bài 07)

ops01 gọi API bằng header Authorization: PVEAPIToken=svc-automation@pve!ansible=<secret> (token API không cần CSRF token cho POST/PUT/DELETE). Quản lý hệ điều hành của node (cập nhật, hardening) vẫn đi qua SSH bằng sysadmin, không đi qua token. Playbook thử xem token có quyền như thiết kế:

# ~/ansible/pve-token-check.yml
- hosts: localhost
  gather_facts: false
  vars:
    pve_api_host: node1.hoatranlabs.local
    pve_token: "svc-automation@pve!ansible={{ pve_api_token_secret }}"   # biến lấy từ ansible-vault
  tasks:
    - name: Liệt kê VM trong cluster (kỳ vọng thành công)
      ansible.builtin.uri:
        url: "https://{{ pve_api_host }}:8006/api2/json/cluster/resources?type=vm"
        headers: { Authorization: "PVEAPIToken={{ pve_token }}" }
        validate_certs: false          # lab; đặt true sau khi node có chứng chỉ step-CA (bài 09)
        return_content: true
      register: vms
    - name: Số VM nhìn thấy
      ansible.builtin.debug: { msg: "{{ vms.json.data | length }} VM" }

    - name: Bật VM thuộc pool-infra (kỳ vọng 403)
      ansible.builtin.uri:
        url: "https://{{ pve_api_host }}:8006/api2/json/nodes/node1/qemu/247/status/start"
        method: POST
        headers: { Authorization: "PVEAPIToken={{ pve_token }}" }
        validate_certs: false
        status_code: [403]

Chạy: ansible-playbook -e @group_vars/pve_nodes/vault.yml --vault-password-file ~/.ansible/vault_pass pve-token-check.yml. Với module community.proxmox (collection 2.0.0) dùng cùng bộ api_user: svc-automation@pve, api_token_id: ansible, api_token_secret; từ 2.0.0 validate_certs mặc định true, nên node dùng chứng chỉ tự ký phải đặt validate_certs: false hoặc tin cậy root CA (bài 09).

OpenTofu / Terraform (bpg/proxmox). Cùng một token dùng được qua PROXMOX_VE_API_TOKEN, nhưng theo tài liệu provider có vài thao tác API token không làm được kể cả với Administrator (đổi feature flag container đặc quyền, đặt arch của VM, ...) — cần mật khẩu root@pam. Đừng vì thế nới quyền token; hãy để admin làm tay những thao tác hiếm đó. Upload snippet cloud-init cần SSH với sysadmin và sudo giới hạn tối thiểu cho lệnh cần thiết (chi tiết ở bài 07).

6.7 Hạ quyền pdm@pve đã tạo ở bài 04

Bài 04 mục 9.3.1 tạo pdm@pve với PVEAdmin tại / và token pdm-token có --privsep 0 để lab chạy nhanh, ghi chú "production nên hạ quyền". Vì privsep=0 nên token lấy đúng quyền của user; chỉ cần đổi quyền của user:

pveum acl delete / --users pdm@pve --roles PVEAdmin
pveum acl modify / --users pdm@pve --roles AuditReadOnly
pveum user token modify pdm@pve pdm-token --expire "$(date -d '+365 days' +%s)"
pveum user token permissions pdm@pve pdm-token

Sau đó mở PDM (https://pdm01.hoatranlabs.local:8443) → Dashboard: remote phải vẫn online. Giám sát cần tối thiểu Sys.Audit tại / (thiếu thì PDM báo 403 "Permission check failed (/, Sys.Audit)"). Nếu muốn dùng PDM để bật/tắt VM hay migrate thì thêm quyền đúng phạm vi (ví dụ pveum acl modify /pool/pool-prod --users pdm@pve --roles VMOperator); quyền tối thiểu cho từng thao tác của PDM cần kiểm lại trên máy thật theo tài liệu PDM. Thay đổi này áp dụng riêng cho từng remote (cluster HOATRANHUB, node5, node6), mỗi nơi một lần.

6.8 Quay vòng, hết hạn và thu hồi

Tình huốngLệnh
Quay vòng định kỳ (PVE 9.2+) — giữ nguyên ACL, secret cũ chết ngaypveum user token modify svc-monitoring@pve prometheus --regenerate 1 --expire "$(date -d '+365 days' +%s)", rồi cập nhật nơi dùng
PVE < 9.2pveum user token remove … → token add … → chạy lại pve-rbac-apply.sh để cấp lại ACL
Thu hồi một token (nghi lộ)pveum user token remove svc-automation@pve ansible
Chặn mọi token của một user dịch vụpveum user modify svc-automation@pve --enable 0
Xem token còn hạn bao lâuScript kiểm toán (mục 8) hoặc pveum user token list svc-automation@pve

Sau khi quay vòng, kiểm tra ngay nơi dùng (pve-exporter UP trên Prometheus, playbook pve-token-check.yml chạy lại) rồi mới coi là xong; đừng để secret cũ nằm ở file .env bị bỏ quên.

07

Xác thực hai lớp (2FA) và chính sách mật khẩu

Chính sách · Thêm yếu tố trên GUI (PVE 9) · Khoá TFA, mất điện thoại

7.1 Chính sách

Loại tài khoảnXác thựcYêu cầu
Người, realm pam / pve / ad / ldapMật khẩu + TOTP (hoặc WebAuthn)Bắt buộc; có Recovery Keys; kiểm tra bằng script mục 8
Người, realm openid (Authentik)MFA tại Authentik (bài 14, mục 10)PVE không nhìn thấy MFA của IdP; phải ép bên Authentik cho ứng dụng Proxmox
root@pam (break-glass)Mật khẩu niêm phong + TOTP + Recovery KeysKhông dùng hằng ngày
Tài khoản dịch vụ svc-*@pveChỉ tokenKhông mật khẩu, không đăng nhập GUI

7.2 Thêm yếu tố trên GUI (PVE 9)

Datacenter → Permissions → Two Factor → Add (hoặc menu tên user → TFA):

  • TOTP: quét QR, nhập mã, ghi chú tên thiết bị trong Description. Dùng được với mọi cách truy cập, không phụ thuộc địa chỉ trang.
  • Recovery Keys: một bộ mã dùng một lần cho mỗi user; in/cất ngoại tuyến.
  • WebAuthn (khoá cứng/passkey): cần HTTPS tin cậy (bài 09) và cấu hình phía máy chủ ở /etc/pve/datacenter.cfg, ví dụ webauthn: rp=hoatranlabs.local,origin=https://node1.hoatranlabs.local:8006,id=hoatranlabs.local. origin là một địa chỉ duy nhất; thay đổi cấu hình này có thể làm các đăng ký WebAuthn cũ không dùng được. Với cluster truy cập vào node bất kỳ thì origin không khớp → dùng TOTP, hoặc luôn vào qua một địa chỉ cố định (cần kiểm lại trên máy thật).

7.3 Khoá TFA, mất điện thoại

  • Nhập sai TOTP 8 lần: yếu tố TOTP bị vô hiệu cho tới khi dùng Recovery Key hoặc admin mở khoá. Sai WebAuthn/Recovery Key 100 lần: khoá mọi yếu tố trong 1 giờ.
  • Admin mở khoá: pveum user tfa unlock sysadmin@pam.
  • Mất điện thoại và Recovery Keys: dùng tài khoản admin khác, hoặc root@pam trên console/SSH:
pveum user tfa list sysadmin@pam                       # xem ID từng yếu tố
pveum user tfa delete sysadmin@pam --id <ID>           # xoá một yếu tố; bỏ --id để xoá TẤT CẢ

Sau đó đăng nhập (chỉ còn mật khẩu) và thêm lại TOTP + Recovery Keys. Cách này thay thế việc sửa tay /etc/pve/priv/tfa.cfg đã nêu ở bài 02 (chỉ còn là phương án cuối cùng nếu pveum không chạy được).

7.4 Vì sao không dùng "2FA bắt buộc theo realm"

Mục TFA khi sửa realm (OATH/TOTP hay Yubico OTP) buộc mọi user trong realm có yếu tố đó mới đăng nhập được. Ưu điểm là ép buộc, nhược điểm: user chưa kịp cấu hình sẽ bị khoá, và cơ chế dựa trên khoá lưu trong cấu hình user chứ không phải bảng Two Factor hiện đại. Lab không bật cho realm pam/pve (tránh tự khoá root@pam); thay vào đó dùng quy trình + kiểm toán: không ai được thêm vào nhóm grp-pve-* trước khi có TOTP, và script mục 8 báo cáo user nào thiếu 2FA mỗi ngày. Hành vi chính xác của TFA theo realm cần kiểm lại trên máy thật trước khi bật.

7.5 Mật khẩu

LoạiQuy tắc
pve (người)Tối thiểu 8 ký tự theo PVE 9 — lab đặt nội quy ≥ 16 ký tự hoặc passphrase; người dùng hằng ngày nên đi qua OIDC/AD thay vì mật khẩu cục bộ
pamDo hệ điều hành quản lý, riêng từng node; chính sách phức tạp (libpam-pwquality) chỉ thêm khi đã test kỹ trên một node vì PAM dùng chung cho SSH và console
root@pam≥ 24 ký tự ngẫu nhiên, niêm phong; đổi sau mỗi lần có người rời nhóm biết mật khẩu
Dịch vụKhông mật khẩu

Tuỳ chọn: bật biểu ngữ đồng ý khi đăng nhập ở Datacenter → Options → Consent Text (PVE 8.4+) cho nhu cầu tuân thủ.

08

Kiểm toán: log, báo cáo ACL/token/2FA và lịch rà soát

Nguồn dữ liệu kiểm toán · Lệnh xem nhanh · Script kiểm toán pve-rbac-audit.py và bộ bao pve-rbac-audit.sh

8.1 Nguồn dữ liệu kiểm toán

NguồnGhi gìXem ở đâu
Task logMọi thao tác thay đổi (tạo/xoá/start VM, backup...), kèm user hoặc user@realm!token thực hiệnGUI Node → Tasks; pvesh get /cluster/tasks; /var/log/pve/tasks/
Cluster logSự kiện clusterGUI panel dưới Cluster Log; pvesh get /cluster/log
Access log của pveproxyMỗi lời gọi GUI/API: IP, user, URL, mã trả về/var/log/pveproxy/access.log
Journal của pvedaemon/pveproxyĐăng nhập thành công/thất bại (kèm rhost)journalctl -u pvedaemon -u pveproxy
Ảnh chụp user.cfg hằng ngày + diffAi thay đổi nhóm/ACL/token và khi nàoScript mục 8.3

8.2 Lệnh xem nhanh

# Đăng nhập thất bại / thành công trong 1 giờ qua
journalctl -u pvedaemon --since '1 hour ago' | grep -E 'authentication failure|successful auth'

# 20 request API gần nhất (cột 3 là user)
tail -n 20 /var/log/pveproxy/access.log

# Thao tác do TOKEN thực hiện (user có dấu "!") trong danh sách task gần đây
pvesh get /cluster/tasks --output-format json \
  | jq -r '.[] | select(.user|test("!")) | [(.starttime|todate), .user, .type, (.status // "running")] | @tsv' | head -20

# Ai đang có quyền gì
pveum acl list
pveum user permissions sysadmin@pam --path /

8.3 Script kiểm toán pve-rbac-audit.py và bộ bao pve-rbac-audit.sh

Script Python kiểm tra bốn điều: (1) tài khoản người ở realm pam/pve/ad/ldap còn bật mà chưa có 2FA, (2) ACL gán trực tiếp cho user (ngoài root@pam, sysadmin@pam, tài khoản svc-* và pdm@pve), (3) token của root@pam, token privsep=0 (ngoài pdm-token đã chấp nhận), token không hạn hoặc sắp/đã hết hạn (≤ 30 ngày), (4) liệt kê ai giữ quyền Permissions.Modify/Sys.Modify để người rà soát xác nhận. Cần python3 (có sẵn trên PVE; thiếu thì apt-get install -y python3-minimal).

#!/usr/bin/env python3
"""/usr/local/sbin/pve-rbac-audit.py — kiểm toán RBAC Proxmox VE (bài 08). Chạy bằng root trên 1 node. Thoát 1 nếu có cảnh báo."""
import json
import subprocess
import sys
import time

BREAK_GLASS = {"root@pam", "sysadmin@pam"}          # được phép có ACL trực tiếp
MFA_REALM_TYPES = {"pam", "pve", "ad", "ldap"}      # realm openid: MFA do IdP (Authentik) đảm nhiệm
PRIVSEP0_OK = {"pdm@pve!pdm-token"}                 # token privsep=0 được chấp nhận có chủ đích (bài 04, mục 6.7)
HIGH_PRIV = {"Permissions.Modify", "Sys.Modify"}
WARN_DAYS = 30


def pvesh(path, *extra):
    r = subprocess.run(["pvesh", "get", path, "--output-format", "json", *extra], capture_output=True, text=True)
    return json.loads(r.stdout) if r.returncode == 0 and r.stdout.strip() else None


def is_svc(uid):
    return uid.split("@")[0].startswith("svc-") or uid == "pdm@pve"


now = time.time()
warns, infos = [], []
realm_type = {d["realm"]: d.get("type") for d in (pvesh("/access/domains") or [])}
users = pvesh("/access/users", "--full", "1") or []
acls = pvesh("/access/acl") or []
roles = {r["roleid"]: set(filter(None, (r.get("privs") or "").split(","))) for r in (pvesh("/access/roles") or [])}
tfa_raw = pvesh("/access/tfa")
tfa = {t["userid"]: t.get("entries", []) for t in tfa_raw} if tfa_raw is not None else None

# 1) 2FA cho tài khoản của người (realm pam/pve/ad/ldap)
if tfa is None:
    warns.append("Không đọc được /access/tfa — kiểm tra thủ công: pveum user tfa list")
else:
    for u in users:
        uid = u["userid"]
        realm = uid.rsplit("@", 1)[-1]
        if not u.get("enable", 1) or is_svc(uid):
            continue
        if realm_type.get(realm) in MFA_REALM_TYPES and not tfa.get(uid):
            warns.append(f"{uid}: chưa có yếu tố 2FA (realm {realm})")

# 2) ACL gán trực tiếp cho user (ngoại trừ break-glass và tài khoản dịch vụ)
for a in acls:
    if a.get("type") == "user" and a["ugid"] not in BREAK_GLASS and not is_svc(a["ugid"]):
        warns.append(f"ACL trực tiếp cho user {a['ugid']}: {a['roleid']} @ {a['path']} (nên gán qua nhóm)")

# 3) Ai đang giữ quyền sửa quyền / sửa hệ thống (để người rà soát xác nhận)
for a in acls:
    if roles.get(a["roleid"], set()) & HIGH_PRIV:
        infos.append(f"Quyền cao: {a['roleid']} @ {a['path']} -> {a['type']}:{a['ugid']}")

# 4) API token: chủ sở hữu, privilege separation, hạn dùng
for u in users:
    for t in (u.get("tokens") or []):
        tid = f"{u['userid']}!{t['tokenid']}"
        exp = int(t.get("expire") or 0)
        if u["userid"] == "root@pam":
            warns.append(f"{tid}: token của root@pam — nên xoá")
        if not int(t.get("privsep", 1)) and tid not in PRIVSEP0_OK:
            warns.append(f"{tid}: privsep=0 (token thừa hưởng toàn bộ quyền của user)")
        if exp == 0:
            warns.append(f"{tid}: không có hạn dùng")
        elif exp < now:
            warns.append(f"{tid}: ĐÃ HẾT HẠN")
        elif exp - now < WARN_DAYS * 86400:
            warns.append(f"{tid}: còn {int((exp - now) / 86400)} ngày là hết hạn")

# 5) User còn bật nhưng không thuộc nhóm nào, hoặc đã quá hạn
for u in users:
    uid = u["userid"]
    if not u.get("enable", 1):
        continue
    if uid not in BREAK_GLASS and not is_svc(uid) and not u.get("groups"):
        infos.append(f"{uid}: không thuộc nhóm nào")
    exp = int(u.get("expire") or 0)
    if exp and exp < now:
        infos.append(f"{uid}: tài khoản đã quá hạn (expire) nhưng vẫn enable")

for m in warns:
    print("WARN  " + m)
for m in infos:
    print("INFO  " + m)
print(f"=== pve-rbac-audit: {len(warns)} cảnh báo, {len(infos)} thông tin, {len(users)} user, {len(acls)} ACL ===")
sys.exit(1 if warns else 0)

Bộ bao chụp user.cfg hằng ngày (không chứa bí mật), che client-key trong domains.cfg, so với bản hôm trước và ghi syslog khi có thay đổi:

#!/usr/bin/env bash
# /usr/local/sbin/pve-rbac-audit.sh — chụp cấu hình RBAC, so với lần trước, chạy kiểm toán, ghi syslog (tag pve-rbac-audit)
set -uo pipefail
DIR=/var/lib/pve-rbac-audit
install -d -m 700 "$DIR"
TODAY=$(date +%F)
install -m 600 /etc/pve/user.cfg "$DIR/user.cfg.$TODAY"
sed -E 's/^([[:space:]]*client-key[[:space:]]+).*/\1<redacted>/' /etc/pve/domains.cfg > "$DIR/domains.cfg.$TODAY"
chmod 600 "$DIR/domains.cfg.$TODAY"

PREV=$(ls -1 "$DIR"/user.cfg.[0-9]* 2>/dev/null | grep -v "user.cfg.$TODAY" | tail -n 1 || true)
if [ -n "$PREV" ] && ! diff -u "$PREV" "$DIR/user.cfg.$TODAY" > "$DIR/user.cfg.diff.$TODAY"; then
  logger -t pve-rbac-audit -p auth.warning "user.cfg thay đổi so với $(basename "$PREV"): xem $DIR/user.cfg.diff.$TODAY"
else
  rm -f "$DIR/user.cfg.diff.$TODAY"
fi

python3 /usr/local/sbin/pve-rbac-audit.py > "$DIR/report.$TODAY.txt"; RC=$?
logger -t pve-rbac-audit -p auth.notice -f "$DIR/report.$TODAY.txt"
find "$DIR" -type f -mtime +400 -delete
exit "$RC"
chmod 750 /usr/local/sbin/pve-rbac-audit.sh /usr/local/sbin/pve-rbac-audit.py
/usr/local/sbin/pve-rbac-audit.sh; echo "exit=$?"; cat /var/lib/pve-rbac-audit/report.$(date +%F).txt

Kết quả trên cụm vừa dựng xong (mẫu): === pve-rbac-audit: 0 cảnh báo, 7 thông tin, 3 user, 44 ACL ===, kèm các dòng INFO Quyền cao: Administrator @ / -> group:grp-pve-admin và INFO Quyền cao: FirewallOperator @ /nodes -> group:grp-pve-automation (người rà soát xác nhận đúng chủ thể). Nếu có WARN, xử lý theo mục "Troubleshooting" cuối bài.

Terminal node1: pve-rbac-audit.sh chạy xong, report của ngày liệt kê WARN/INFO và dòng tổng kết số cảnh báo, số user, số ACL.
Terminal node1: pve-rbac-audit.sh chạy xong, report của ngày liệt kê WARN/INFO và dòng tổng kết số cảnh báo, số user, số ACL.

8.4 Chạy hằng ngày bằng systemd timer (05:10, chỉ trên node1)

Cấu hình RBAC dùng chung cả cluster nên chạy ở một node là đủ; giờ 05:10 nằm ngoài các cửa sổ backup đã dùng trong lab (01:00–03:30). Ở quy mô lớn chạy từ ops01 bằng Ansible (mục 11).

# /etc/systemd/system/pve-rbac-audit.service
[Unit]
Description=Kiểm toán RBAC Proxmox VE (bài 08)
After=pve-cluster.service

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/pve-rbac-audit.sh
Nice=10
# /etc/systemd/system/pve-rbac-audit.timer
[Unit]
Description=Chạy kiểm toán RBAC Proxmox VE mỗi ngày 05:10

[Timer]
OnCalendar=*-*-* 05:10:00
Persistent=true

[Install]
WantedBy=timers.target
systemctl daemon-reload
systemctl enable --now pve-rbac-audit.timer
systemctl list-timers pve-rbac-audit.timer

Khi có cảnh báo, service ở trạng thái failed (thấy bằng systemctl --failed) và nội dung đã nằm trong syslog theo tag pve-rbac-audit để Wazuh (bài 17) hoặc Loki (bài 33) thu thập sau này; hệ thống thông báo PVE ở bài 10 không tự bắt failed của đơn vị tuỳ chỉnh nên phần gửi mail/Gotify nối với log ở bài đó.

8.5 Lịch rà soát và diễn tập

Tần suấtViệcNgười làm
Hằng ngày (tự động)Timer 05:10 ghi báo cáo và diff user.cfgHệ thống
Hằng tuầnĐọc report.*.txt; xử lý mọi WARNQuản trị viên trực
Hằng thángToken còn ≤ 30 ngày: quay vòng; đối chiếu danh sách thành viên grp-pve-adminQuản trị viên
Hằng quýDiễn tập break-glass: đăng nhập root@pam và sysadmin@pam khi Authentik tắt; dùng thử một Recovery Key; rà soát toàn bộ ACL; thử phục hồi bản user.cfg từ sao lưuHai quản trị viên
Mỗi khi có người vào/raThêm/bớt khỏi nhóm IdP; pveum user modify <user> --enable 0; thu hồi token do người đó tạo; quay vòng mật khẩu root@pam nếu người đó biếtQuản trị viên
Sau mỗi lần nâng cấp PVEChạy pve-rbac-apply.sh (DRY_RUN trước) + đọc mục "Roadmap" về thay đổi privilegeQuản trị viên
09

Tích hợp OIDC Authentik (làm sau khi hoàn thành bài 14)

Điều kiện trước khi cấu hình · Cho các node PVE tin root CA của step-CA · Phía Authentik (đồng bộ với bài 14, mục 8.4)

Từ mục này trở đi cần Authentik (VM234, 2026.8.4) đã chạy HTTPS ở bài 14. Phần lõi (mục 1–8) vẫn dùng bình thường nếu bạn chưa làm tới đây. Kết quả cuối: nhân sự mở https://node1.hoatranlabs.local:8006, chọn realm Authentik, đăng nhập (kèm MFA) tại Authentik, quay lại PVE với đúng nhóm/quyền; vô hiệu một tài khoản ở Authentik là hết đường vào PVE.

9.1 Điều kiện trước khi cấu hình

Điều kiệnKiểm traNếu thiếu
Authentik HTTPS cổng 9443 với chứng chỉ step-CA (bài 14, mục 7)curl -sS https://authentik.hoatranlabs.local:9443/-/health/live/ -o /dev/null -w '%{http_code}\n' → 200 (chạy sau khi node tin root CA)Làm bài 14 / bài 13
Mỗi node phân giải được authentik.hoatranlabs.localgetent hosts authentik.hoatranlabs.local → 10.11.25.40Thêm vào /etc/hosts của node (như bài 04) hoặc cho node dùng Pi-hole 10.11.45.53 làm DNS (bài 12); khuyến nghị /etc/hosts để đăng nhập không phụ thuộc VM Pi-hole
Node → Authentik 9443nc -vz authentik.hoatranlabs.local 9443 từ nodeChính sách FortiGate Allow-Authentik-Admin cho VLAN MGMT (bài 14, mục 12)
Node tin root CA của step-CAxem 9.2Làm 9.2
Giờ đồng bộ (node, Authentik)timedatectl / chronyc trackingToken OIDC có thời hạn; lệch giờ → đăng nhập lỗi

9.2 Cho các node PVE tin root CA của step-CA

PVE gọi Authentik bằng chính kho chứng chỉ hệ điều hành của node, nên root CA của step-CA (bài 13) phải được cài lên từng node. Dùng script distribute-root-ca.sh ở bài 13, Bước 9, hoặc làm thủ công: lấy file root_ca.crt từ step-CA, đối chiếu fingerprint với giá trị đã ghi ở bài 13, rồi cài:

# Trên node1: sao chép root CA từ step-CA (VM242) và kiểm fingerprint trước khi tin cậy
scp [email protected]:/etc/step-ca/certs/root_ca.crt /root/hoatranlabs-root.crt     # 10.11.25.42 = step-ca (VM242)
openssl x509 -in /root/hoatranlabs-root.crt -noout -fingerprint -sha256 | cut -d= -f2 | tr -d ':' | tr 'A-F' 'a-f'
#  ↑ phải trùng với: step certificate fingerprint /etc/step-ca/certs/root_ca.crt (chạy trên step-ca, bài 13 Bước 5)

for n in node1 node2 node3 node4; do
  scp /root/hoatranlabs-root.crt root@"$n":/usr/local/share/ca-certificates/hoatranlabs-root.crt
  ssh root@"$n" 'update-ca-certificates && systemctl restart pveproxy'
done

systemctl restart pveproxy chỉ ngắt kết nối GUI vài giây (không đụng tới VM, phiên đăng nhập hiện có vẫn hợp lệ); bước restart để chắc chắn tiến trình nạp lại kho chứng chỉ (cần kiểm lại trên máy thật xem có bắt buộc không). Kiểm tra: lệnh sau phải in đúng issuer mà không cần -k.

curl -sS https://authentik.hoatranlabs.local:9443/application/o/proxmox/.well-known/openid-configuration | jq -r .issuer
# Sau khi làm 9.3 xong, kỳ vọng: https://authentik.hoatranlabs.local:9443/application/o/proxmox/   (có dấu / ở cuối)
issuer-url ở PVE phải trùng từng ký tự với issuer Authentik trả về, kể cả dấu / cuối. Lệch một ký tự là đăng nhập lỗi.

9.3 Phía Authentik (đồng bộ với bài 14, mục 8.4)

Nguồn chuẩn của phía Authentik là bài 14, mục 8.4 (Authentik 2026.8.4); làm đúng các bước ở đó rồi bổ sung phần bảo mật bên dưới. Giá trị dùng xuyên suốt:

Thành phầnGiá trị
Nhóm Authentikgrp-pve-admin, grp-pve-ops, grp-pve-readonly, grp-pve-backup (không bật superuser). Nhóm grp-pve-automation chỉ dành cho tài khoản dịch vụ ở PVE nên không dùng ở Authentik; nếu đã tạo theo bài 14 thì để trống
Providerproxmox-oidc — OAuth2/OpenID Provider, Client type Confidential, Authorization flow default-provider-authorization-implicit-consent
Redirect URIsKiểu Strict, loại Authorization, mỗi địa chỉ dùng để mở PVE là một URI, không có đường dẫn hay / cuối: https://node1.hoatranlabs.local:8006 … https://node4.hoatranlabs.local:8006 (thêm node5, node6 nếu hai node standalone cũng dùng realm này; thêm dạng IP như https://10.11.45.210:8006 nếu đăng nhập bằng IP)
Signing KeyKhoá RSA (ví dụ authentik Self-signed Certificate). Tài liệu tích hợp chỉ nói "chọn khoá bất kỳ", nhưng báo cáo cộng đồng ghi khoá ECDSA khiến PVE trả 401 — tránh ECDSA
ScopesGiữ openid, email, profile. Claim groups đã nằm trong scope profile, không cần scope riêng tên groups
ApplicationName 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
Issuer URLhttps://authentik.hoatranlabs.local:9443/application/o/proxmox/
Authentik Admin → Applications → Providers → proxmox-oidc: Client type Confidential, Redirect URIs kiểu Strict cho node1–node4 cổng 8006, Signing Key RSA và Issuer .../application/o/proxmox/.
Authentik Admin → Applications → Providers → proxmox-oidc: Client type Confidential, Redirect URIs kiểu Strict cho node1–node4 cổng 8006, Signing Key RSA và Issuer .../application/o/proxmox/.

Bốn việc bổ sung về bảo mật (thuộc bài 08):

  1. Tên nhóm phải khớp từng ký tự. PVE lấy tên nhóm từ claim rồi gắn hậu tố -<tên realm>: nhóm Authentik grp-pve-admin thành nhóm PVE grp-pve-admin-authentik. Thêm người quản trị (ví dụ akadmin) vào grp-pve-admin, nhân viên vận hành vào grp-pve-ops...
  2. Giới hạn ai được dùng ứng dụng: tab Policy / Group / User Bindings của ứng dụng Proxmox VE chỉ gắn các nhóm grp-pve-*. Không ràng buộc thì mọi user Authentik đều đăng nhập được và autocreate tạo tài khoản PVE cho họ (không có quyền, nhưng thành rác và là bề mặt tấn công).
  3. MFA bắt buộc cho ứng dụng này: PVE không nhìn thấy MFA của IdP, nên ép ở Authentik — Authenticator Validation Stage trong flow đăng nhập, hoặc policy theo nhóm như bài 14, mục 10.
  4. Khoá việc tự đổi username: trong cấu hình hệ thống của Authentik, tắt quyền "người dùng tự đổi username" (tên mục tuỳ phiên bản). PVE định danh người dùng theo username-claim; nếu người dùng tự đổi được tên và lấy được tên của tài khoản cũ đã xoá mà còn ACL ở PVE, họ thừa hưởng quyền đó.

9.4 Phía PVE: tạo realm

GUI (PVE 9): Datacenter → Permissions → Realms → Add → OpenID Connect Server.

TrườngGiá trị
Issuer URLhttps://authentik.hoatranlabs.local:9443/application/o/proxmox/
Realmauthentik
Client ID / Client Keytừ provider proxmox-oidc (Client ID / Client Secret)
Default☐ (chỉ bật sau mục 9.6)
Autocreate Users☑
Username Claimusername
Scopesemail profile (mặc định của PVE; PVE tự thêm openid)
Groups Claimgroups
Autocreate Groups☐ — xem giải thích bên dưới
Overwrite Groups☑ — đặt lại toàn bộ nhóm của user theo claim ở mỗi lần đăng nhập
Datacenter → Permissions → Realms → Add → OpenID Connect Server: Issuer URL, Realm authentik, Username Claim username, Scopes email profile, Groups Claim groups, Overwrite Groups đã tick.
Datacenter → Permissions → Realms → Add → OpenID Connect Server: Issuer URL, Realm authentik, Username Claim username, Scopes email profile, Groups Claim groups, Overwrite Groups đã tick.

CLI tương đương (nhập secret bằng read -s để không vào history; tham số vẫn thoáng hiện trong ps nên chỉ chạy trên node quản trị):

read -rs -p 'Client Secret (từ Authentik): ' OIDC_SECRET; echo
pveum realm add authentik --type openid \
  --issuer-url https://authentik.hoatranlabs.local:9443/application/o/proxmox/ \
  --client-id '<CLIENT_ID>' --client-key "$OIDC_SECRET" \
  --username-claim username --autocreate 1 \
  --scopes 'email profile' \
  --groups-claim groups --groups-autocreate 0 --groups-overwrite 1 \
  --comment 'SSO Authentik (bài 14)'
unset OIDC_SECRET
pveum realm list

Lệnh này giống lệnh ở bài 14, mục 8.4; chạy ở bài nào trước cũng được. Nếu realm đã được tạo bằng tuỳ chọn khác, chỉnh lại bằng pveum realm modify authentik --groups-autocreate 0 --groups-overwrite 1.

Ba tuỳ chọn quyết định độ an toàn:

  • --groups-overwrite 1: nếu để mặc định 0, PVE chỉ thêm nhóm theo claim và không bao giờ gỡ — rút quyền ở Authentik sẽ không có tác dụng ở PVE. Bật 1 thì mỗi lần đăng nhập, nhóm của user được đặt lại đúng theo claim (kể cả nhóm cục bộ gán tay cho user OIDC).
  • --groups-autocreate 0: claim groups gồm mọi nhóm Authentik của người đó (cả nhóm Grafana, Gitea... không liên quan). Bật autocreate thì PVE sinh nhóm rác cho tất cả (tên có khoảng trắng bị bỏ qua và ghi log). Bốn nhóm cần dùng đã được script mục 5.3 tạo sẵn (EXTRA_REALMS), nhóm nào không có sẵn thì PVE bỏ qua — nhờ đó đặt nhầm một người vào grp-pve-automation ở Authentik cũng vô hại.
  • --client-key được lưu trong /etc/pve/domains.cfg mà mọi node đọc được qua pmxcfs (lưu dạng rõ hay không cần kiểm lại trên máy thật) — coi là secret: không chụp màn hình, quay vòng Client Secret ở Authentik nếu nghi ngờ. --username-claim username (thay cho mặc định subject là chuỗi ngẫu nhiên) cho tên dạng alice@authentik dễ đọc, đổi lại đòi hỏi việc 4 ở mục 9.3.

PVE 9.2 thêm tuỳ chọn --audiences cho IdP gửi thêm audience; Authentik không cần.

9.5 Nhóm và ACL cho người đăng nhập qua OIDC

Nhóm theo claim được PVE đặt tên <tên nhóm Authentik>-<realm>: grp-pve-ops thành grp-pve-ops-authentik. ACL phải gán cho tên có hậu tố. Chạy lại script mục 5.3 với EXTRA_REALMS để tạo sẵn các nhóm này và nhân bản đúng bảng ACL ở mục 4.3 (nhóm grp-pve-automation cố ý không được nhân bản: chỉ tài khoản dịch vụ dùng):

DRY_RUN=1 EXTRA_REALMS="authentik" /usr/local/sbin/pve-rbac-apply.sh | grep -- '-authentik' | head
EXTRA_REALMS="authentik" /usr/local/sbin/pve-rbac-apply.sh
pveum group list | grep authentik

9.6 Đăng nhập thử và chuyển đổi

1
Mở cửa sổ ẩn danh → https://node2.hoatranlabs.local:8006 → ô Realm chọn Authentik → bấm Login → trình duyệt chuyển sang Authentik → đăng nhập + MFA → quay lại PVE.
Màn hình đăng nhập PVE: ô Realm chọn Authentik; sau khi bấm Login trình duyệt chuyển sang trang đăng nhập và MFA của Authentik rồi quay lại giao diện PVE.
Màn hình đăng nhập PVE: ô Realm chọn Authentik; sau khi bấm Login trình duyệt chuyển sang trang đăng nhập và MFA của Authentik rồi quay lại giao diện PVE.
2
Trên node: pveum user list --full 1 | grep authentik và pveum user permissions alice@authentik --path /pool/pool-prod.
Terminal node1: pveum user list --full 1 thấy alice@authentik cùng nhóm grp-pve-ops-authentik và pveum user permissions alice@authentik --path /pool/pool-prod liệt kê quyền VMOperator.
Terminal node1: pveum user list --full 1 thấy alice@authentik cùng nhóm grp-pve-ops-authentik và pveum user permissions alice@authentik --path /pool/pool-prod liệt kê quyền VMOperator.
3
Thử một tài khoản không thuộc nhóm grp-pve-* nào của Authentik: đăng nhập được (nếu chưa ràng buộc ứng dụng) nhưng không thấy VM — đúng thiết kế "đăng nhập ≠ có quyền".
4
Thử gỡ alice khỏi nhóm grp-pve-ops ở Authentik, đăng xuất, đăng nhập lại: nhóm grp-pve-ops-authentik của alice ở PVE phải biến mất (nhờ --groups-overwrite 1).
5
Diễn tập break-glass (mục 8.5) khi Authentik tắt: đăng nhập sysadmin@pam phải vẫn chạy.
6
Chỉ khi 1–5 đạt, tuỳ chọn đặt realm này làm mặc định cho trang đăng nhập: pveum realm modify authentik --default 1 (người cần pam vẫn chọn trong ô Realm).

9.7 Cho nghỉ việc, và độ trễ phiên

Vô hiệu tài khoản ở Authentik chặn các lần đăng nhập mới; phiên đang mở ở PVE vẫn dùng được cho tới khi ticket hết hạn (khoảng 2 giờ). Khi cần cắt ngay:

pveum user modify alice@authentik --enable 0       # cắt quyền ngay ở PVE
pveum user token list alice@authentik              # thu hồi token của người đó (nếu có): pveum user token remove alice@authentik <tên>
Authentik trở thành tài sản cấp cao nhất. Ai là admin Authentik có thể tự thêm mình vào nhóm grp-pve-admin và thành Administrator của PVE. Hạn chế số admin Authentik, bắt buộc MFA cho họ, bật cảnh báo thay đổi thành viên nhóm (audit log Authentik), và giữ break-glass cục bộ. Authentik lại chạy trên chính cluster này (VM234 ở node1): không bao giờ để mọi con đường vào PVE chỉ còn OIDC.

9.8 Phương án thay thế: Application entitlements thay cho claim groups

Hướng dẫn tích hợp Proxmox chính thức của Authentik dùng Application entitlements: mỗi entitlement của ứng dụng Proxmox VE (đặt tên grp-pve-admin...) bind vào nhóm/người, Provider thêm scope mapping authentik default OAuth Mapping: OpenID 'entitlements', và phía PVE đổi thành:

pveum realm modify authentik --scopes 'email profile entitlements' --groups-claim entitlements

Ưu điểm: token chỉ chứa đúng những nhóm dành cho ứng dụng này thay vì mọi nhóm của user, nên có thể bật --groups-autocreate 1 mà không sinh nhóm rác. Bài giữ claim groups làm mặc định để khớp bài 14; cả hai cách đều hợp lệ, miễn các tuỳ chọn --groups-overwrite 1 và tên có hậu tố -authentik ở ACL giữ nguyên.

9.9 Quy mô nhiều node, nhiều cluster

Vấn đềCách xử lý
Mỗi địa chỉ truy cập PVE là một Redirect URI≤ ~6 node: liệt kê Strict. Nhiều node: dùng một tên truy cập cố định cho mỗi cluster (ví dụ tên cân bằng tải/VIP) hoặc kiểu khớp regex có neo ^…$ và thoát dấu chấm (\.) — regex lỏng gây lỗ hổng chuyển hướng, cần đọc kỹ tài liệu Authentik và kiểm lại trên máy thật
Nhiều cluster dùng chung IdPMỗi cluster một Application/Provider riêng (ví dụ proxmox-oidc-<cluster>) và Client Secret riêng: lộ một cluster không ảnh hưởng cluster khác; nhóm Authentik dùng cùng tên grp-pve-*
Cấu hình realm ở từng clusterĐưa lệnh pveum realm add vào Ansible (mục 11), secret lấy từ vault
10

Tích hợp realm AD/LDAP với dc1 (làm sau khi hoàn thành bài 25, tuỳ chọn)

Điều kiện · Trên dc1: tài khoản bind chỉ đọc và nhóm cho PVE · Trên PVE: tạo realm AD và đồng bộ

Dùng khi muốn tài khoản AD của doanh nghiệp (Samba AD DC dc1, bài 25) đăng nhập thẳng vào PVE, hoặc khi chưa dùng Authentik. Với doanh nghiệp đã có Authentik thì OIDC (mục 9) là đường chính; realm AD là đường dự phòng thứ hai. Lưu ý dc1 cũng là VM chạy trên cluster nên không thay thế được break-glass.

10.1 Điều kiện

  • dc1 phục vụ LDAPS cổng 636 với chứng chỉ step-CA (bài 25, mục 8). Samba từ chối simple bind trên LDAP 389 không mã hoá nên PVE bắt buộc dùng ldaps hoặc ldap+starttls.
  • Node tin root CA (mục 9.2) và phân giải được dc1.hoatranlabs.local → 10.11.65.50 (thêm vào /etc/hosts của node hoặc dùng DNS lab).
  • Chính sách FortiGate cho phép VLAN 45 (MGMT) → dc1 TCP 636; bài 25 chỉ mở 636 cho VLAN Authentik, nên cần thêm quy tắc cho các node PVE.

10.2 Trên dc1: tài khoản bind chỉ đọc và nhóm cho PVE

# Chạy trên dc1 (bài 25). Đổi mật khẩu mẫu; tài khoản không cần quyền gì ngoài đọc thư mục
samba-tool user create svc-pve-ldap 'PveBind@2024!' --use-username-as-cn --userou="OU=HOATRAN" \
  --description="Bind LDAP chỉ đọc cho Proxmox VE (bài 08)"
samba-tool user setexpiry svc-pve-ldap --noexpiry

for g in grp-pve-admin grp-pve-ops grp-pve-readonly grp-pve-backup; do
  samba-tool group add "$g" --groupou="OU=HOATRAN" --description="Nhóm Proxmox VE"
done
samba-tool group addmembers grp-pve-admin hoatv
samba-tool group addmembers grp-pve-ops user01

Đặt tên nhóm AD trùng tên nhóm PVE để realm AD dùng chung bộ ACL của mục 4. Kiểm tra bind và nhóm từ một node PVE (apt-get install -y ldap-utils; lệnh hỏi mật khẩu):

LDAPTLS_CACERT=/usr/local/share/ca-certificates/hoatranlabs-root.crt \
ldapsearch -H ldaps://dc1.hoatranlabs.local:636 -x -W \
  -D 'CN=svc-pve-ldap,OU=HOATRAN,DC=hoatranlabs,DC=local' \
  -b 'OU=HOATRAN,DC=hoatranlabs,DC=local' '(cn=grp-pve-*)' cn member

10.3 Trên PVE: tạo realm AD và đồng bộ

GUI: Datacenter → Permissions → Realms → Add → Active Directory Server. CLI:

read -rs -p 'Mật khẩu svc-pve-ldap: ' LDAP_PW; echo
pveum realm add hoatran-ad --type ad --domain hoatranlabs.local \
  --server1 dc1.hoatranlabs.local --port 636 --mode ldaps --verify 1 \
  --base_dn 'OU=HOATRAN,DC=hoatranlabs,DC=local' \
  --bind_dn 'CN=svc-pve-ldap,OU=HOATRAN,DC=hoatranlabs,DC=local' --password "$LDAP_PW" \
  --case-sensitive 0 \
  --group_filter '(&(objectClass=group)(cn=grp-pve-*))' \
  --sync_attributes 'email=mail,firstname=givenName,lastname=sn' \
  --sync-defaults-options 'scope=both,enable-new=1,remove-vanished=acl;entry;properties' \
  --comment 'AD hoatranlabs.local (bài 25)'
unset LDAP_PW

--password được PVE cất ở /etc/pve/priv/realm/hoatran-ad.pw (chỉ root đọc), không nằm trong domains.cfg. --base_dn giới hạn user được đồng bộ vào OU HOATRAN; --case-sensitive 0 vì AD không phân biệt hoa thường. Cú pháp chuỗi --sync-defaults-options (dấu ; trong remove-vanished) cần kiểm lại trên máy thật; thất bại thì đặt các lựa chọn này trên GUI (Edit realm → Sync Options).

Đồng bộ thử trước (không ghi gì), rồi mới ghi:

pveum realm sync hoatran-ad --scope both --dry-run 1
pveum realm sync hoatran-ad --scope both
pveum user list | grep hoatran-ad
pveum group list | grep hoatran-ad

Nhóm đồng bộ có tên <tên>-<realm>: grp-pve-ops-hoatran-ad. Man page pveum realm sync cảnh báo: đảm bảo các nhóm đó chưa tồn tại với nội dung cần giữ vì sync sẽ ghi đè. Script mục 5.3 tạo sẵn nhóm rỗng nên an toàn. Sau lần sync đầu, nhân bản ACL cho realm AD:

EXTRA_REALMS="authentik hoatran-ad" /usr/local/sbin/pve-rbac-apply.sh      # bỏ "authentik" nếu chưa làm mục 9

Có thể đặt lịch đồng bộ tự động trong Datacenter → Permissions → Realms → Sync Jobs (hoặc pvesh tới /cluster/jobs/realm-sync; cú pháp tham số cần kiểm lại trên máy thật), chạy lúc 05:20 để tách khỏi các tác vụ khác.

10.4 Đăng nhập thử

Đăng xuất → Realm hoatran-ad → hoatv + mật khẩu AD. Người dùng AD vẫn phải bật TOTP của PVE (AD không có MFA): tài khoản …@hoatran-ad nằm trong phạm vi kiểm tra 2FA của script mục 8.

10.5 Lưu ý vận hành

  • Vô hiệu tài khoản ở AD chặn đăng nhập mới ngay (bind thất bại); phiên đang mở còn tới 2 giờ; remove-vanished dọn user/ACL biến mất ở lần sync kế.
  • Nhập sai mật khẩu AD nhiều lần có thể khoá tài khoản theo chính sách miền (samba-tool domain passwordsettings, bài 25) — kẻ tấn công dò mật khẩu ở 8006 có thể khoá nhân viên. Chặn nguồn truy cập 8006 và fail2ban đã làm ở bài 05.
  • Với LDAP khác (OpenLDAP, FreeIPA): --type ldap cần thêm --user_attr uid, --base_dn, và thường --user_classes/--group_classes. Không khuyến nghị dùng LDAP outpost của Authentik cho PVE: OIDC trực tiếp đơn giản và an toàn hơn.
11

Quản lý ở quy mô lớn: 1 node tới hàng trăm node

Nguyên tắc · Playbook Ansible áp dụng cho nhiều cluster/node (chạy từ ops01) · OpenTofu (bpg/proxmox) cho vai trò, nhóm, pool, ACL

Quy mô chỉ làm tăng số lần lặp lại chứ không làm đổi mô hình: 5 nhóm, 6 vai trò, 3 pool, bảng ACL ở mục 4 giống hệt dù có 1 hay 300 node. Cái thay đổi là cách áp dụng và kiểm chứng: phải biến thành mã, tự động và đo được.

11.1 Nguyên tắc

  • RBAC như mã: script ở mục 5 và 8 cùng danh sách người dùng/nhóm nằm trong một repository (Gitea, bài 22); thay đổi đi qua merge request, một người duyệt; pipeline chạy DRY_RUN=1 trước.
  • Nhóm, không phải người; pool, không phải VM; IdP, không phải mật khẩu cục bộ. Số ACL tăng theo số pool và vai trò, không tăng theo số node hay số người.
  • Mỗi cluster là một ranh giới RBAC độc lập: /etc/pve không chia sẻ giữa các cluster; mỗi cluster có token và secret riêng. PDM (bài 04) cho cái nhìn tập trung nhưng không thay RBAC của từng cluster.
  • Số quản trị viên (grp-pve-admin) không đổi theo quy mô; số node chỉ ảnh hưởng thời gian chạy tự động hoá.

11.2 Playbook Ansible áp dụng cho nhiều cluster/node (chạy từ ops01)

Tạo sysadmin trên mọi node (realm pam là cục bộ từng node), phát script, và áp dụng RBAC một lần mỗi cluster:

# ~/ansible/rbac.yml   —   ansible-playbook rbac.yml -l pve_hoatranhub -e target_cluster=pve_hoatranhub
---
- name: Tài khoản quản trị và script RBAC trên mọi node PVE
  hosts: pve_nodes
  become: true
  serial: 20                                   # hàng trăm node: cuốn chiếu 20 node/lượt
  tasks:
    - name: Gói cần thiết
      ansible.builtin.apt:
        name: [sudo, jq, python3]
        state: present
        update_cache: true
    - name: Người dùng sysadmin (realm pam là cục bộ từng node)
      ansible.builtin.user:
        name: sysadmin
        groups: sudo
        append: true
        shell: /bin/bash
        password: "{{ sysadmin_password_hash }}"     # băm sha512 trong ansible-vault; KHÔNG để mật khẩu rõ
    - name: Khoá SSH của sysadmin
      ansible.posix.authorized_key:
        user: sysadmin
        key: "{{ lookup('file', 'files/sysadmin.pub') }}"
        exclusive: true                              # xoá mọi khoá khác của sysadmin
    - name: Script RBAC
      ansible.builtin.copy:
        src: "files/{{ item }}"
        dest: "/usr/local/sbin/{{ item }}"
        owner: root
        mode: "0750"
      loop: [pve-rbac-apply.sh, pve-rbac-audit.sh, pve-rbac-audit.py]

- name: Áp dụng RBAC một lần cho mỗi cluster
  hosts: "{{ target_cluster }}"
  become: true
  tasks:
    - name: Chạy pve-rbac-apply.sh trên một node
      ansible.builtin.command: /usr/local/sbin/pve-rbac-apply.sh
      environment:
        EXTRA_REALMS: "{{ rbac_extra_realms | default('') }}"     # vd: "authentik hoatran-ad"
      run_once: true
      register: rbac
      changed_when: false
    - name: Kiểm toán và dừng nếu có WARN
      ansible.builtin.command: /usr/local/sbin/pve-rbac-audit.py
      run_once: true
      changed_when: false
      failed_when: false
      register: audit
    - ansible.builtin.debug: { var: audit.stdout_lines }

Collection community.proxmox 2.0.0 có proxmox_access_acl, proxmox_pool, proxmox_pool_member, proxmox_user_info nếu muốn thay pveum bằng module; user/role/token vẫn dùng pveum hoặc API trực tiếp vì collection không có đủ module cho chúng (cần kiểm lại theo phiên bản). inventory nhóm theo cluster (pve_hoatranhub, pve_standalone) và biến rbac_extra_realms đặt trong group_vars.

11.3 OpenTofu (bpg/proxmox) cho vai trò, nhóm, pool, ACL

Cho tổ chức đã quản lý toàn bộ bằng OpenTofu. Tên resource dưới đây theo provider v0.111 (tài liệu bpg ghi sẽ đổi sang tiền tố proxmox_* ở v1.0 — ghim phiên bản provider và đối chiếu docs trước khi nâng):

variable "pve_admin_token" { sensitive = true }            # token của tài khoản có quyền sửa ACL, ngắn hạn

provider "proxmox" {
  endpoint  = "https://node1.hoatranlabs.local:8006/"
  api_token = var.pve_admin_token                         # dạng user@realm!tên=secret
  insecure  = false                                       # true chỉ khi node còn chứng chỉ tự ký (trước bài 09)
}

locals {
  roles = {
    VMOperator    = ["VM.Audit", "VM.Console", "VM.PowerMgmt", "VM.Snapshot"]
    AuditReadOnly = ["Sys.Audit", "VM.Audit", "Datastore.Audit", "Pool.Audit", "SDN.Audit", "Mapping.Audit"]
  }
  pools = ["pool-prod", "pool-infra", "pool-test"]
}

resource "proxmox_virtual_environment_role" "r" {
  for_each   = local.roles
  role_id    = each.key
  privileges = each.value
}

resource "proxmox_virtual_environment_pool" "p" {
  for_each = toset(local.pools)
  pool_id  = each.key
}

resource "proxmox_virtual_environment_group" "ops" {
  group_id = "grp-pve-ops"
  comment  = "Vận hành VM"
}

resource "proxmox_virtual_environment_acl" "ops_prod" {
  group_id  = proxmox_virtual_environment_group.ops.group_id
  role_id   = proxmox_virtual_environment_role.r["VMOperator"].role_id
  path      = "/pool/pool-prod"
  propagate = true
}

Việc gán VM vào pool nên đặt ở resource VM (pool_id) hoặc pveum pool modify; resource pool của provider không có tham số thành viên. Token có quyền sửa ACL tương đương Administrator: không đặt trên ops01 dùng chung với token ansible; chạy RBAC-as-code từ một pipeline được bảo vệ với token ngắn hạn.

11.4 Bảng "khi quy mô tăng"

Khía cạnh1 nodeCluster ~4–30Nhiều cluster, hàng trăm node
Danh tính con ngườisysadmin@pam + TOTPOIDC/AD, nhóm grp-pve-*Cùng IdP; mỗi cluster Application/Client Secret riêng
Tạo sysadmin ở realm pamMột lầnVòng lặp/Ansible 4–30 nodeAnsible serial theo lô; băm mật khẩu trong vault
Áp dụng ACLChạy script tại chỗMột node/clusterPipeline: một lần mỗi cluster, DRY_RUN rồi apply
Tokenprometheus+ ansibleMỗi cluster một bộ token; quay vòng theo lịch bằng Ansible
Kiểm toánTimer + đọc tayTimer + log về SIEMGom báo cáo từng cluster về một kho; cảnh báo khi diff user.cfg ngoài cửa sổ thay đổi
Giám sát/quản lý tập trungPVE GUIPVE GUI + PrometheusPDM + Prometheus; PDM giữ token AuditReadOnly riêng cho từng remote

Điểm chưa xác minh (cần kiểm lại trên máy thật)

Các mục dưới đây được viết theo tài liệu/ghi chú phát hành nhưng chưa chạy trên cụm thật của lab, hãy thử trên một node/cluster thử trước:

  • Hình dạng JSON trả về của pveum user token add --output-format json, GET /access/tfa và GET /access/users?full=1 (trường tokens, entries) mà script kiểm toán dựa vào.
  • Danh sách privilege tối thiểu của TemplateDeployer cho luồng clone + cloud-init + start trên PVE 9.2 (đặc biệt VM.PowerMgmt, Sys.Console khi thêm HA resource lúc tạo VM), và đường dẫn /sdn/zones/localnetwork cho SDN.Use.
  • Việc PVE tự thêm scope openid; tên trường GUI của realm OpenID (Overwrite Groups); client-key có nằm dạng rõ trong domains.cfg hay không; có cần restart pveproxy sau khi cài root CA hay không.
  • Cách Authentik/PVE xử lý claim groups chứa tên nhóm có khoảng trắng; menu Authentik tắt "đổi username"; cảnh báo "ECDSA gây 401" đến từ cộng đồng chứ không phải tài liệu chính thức.
  • Cú pháp --sync-defaults-options (có ;), tham số của pvesh /cluster/jobs/realm-sync, và có cần --user_attr cho realm ad hay không.
  • Quyền tối thiểu của PDM cho từng thao tác quản trị (ngoài giám sát chỉ cần Sys.Audit).
  • Việc /mapping/notifications là path ACL hợp lệ ở bản PVE đang chạy (script có cảnh báo và bỏ qua nếu không), và ACL --propagate 0 tại / có đủ cho các API firewall/tuỳ chọn cấp cluster cần Sys.Modify trên /.
  • Hành vi chính xác của "TFA bắt buộc theo realm" và webauthn trong cluster nhiều node.
  • Tên resource proxmox_virtual_environment_* còn dùng được ở phiên bản provider bạn ghim.

Troubleshooting

Triệu chứngNguyên nhânCách xử lý
pveum ghi báo lỗi cfs-lock ... timeout hoặc không ghi được /etc/pveCluster mất quorum, /etc/pve chỉ đọcpvecm status; khôi phục quorum (bài 03/11). Đừng pvecm expected khi chưa hiểu hậu quả; bài 11 có quy trình
sysadmin đăng nhập được node1 nhưng "Login failed" ở node2User Linux chưa có trên node2 hoặc mật khẩu khác (realm pam là cục bộ từng node)Mục 3.1 hoặc Ansible (mục 11): tạo user và đặt cùng mật khẩu trên mọi node
API/GUI trả 403 Permission check failed (/vms/NNN, VM.PowerMgmt)Thiếu ACL trên path/pool, hoặc VM chưa vào poolpveum user permissions <user> --path /vms/NNN; kiểm pvesh get /cluster/resources --type vm xem cột pool
Token 403 trong khi user vẫn có quyềnPrivilege separation: token thiếu ACL riêng (quyền = giao user ∩ token)pveum user token permissions <user> <token>; chạy lại pve-rbac-apply.sh hoặc pveum acl modify … --tokens
Token 401Hết hạn, sai secret, token bị xoá hoặc user bị disablepveum user token list <user>; kiểm expire; nếu hết hạn: --regenerate 1 (9.2+) hoặc tạo lại
Ghi firewall / cấp chứng chỉ / cấu hình thông báo qua API trả 403 Permission check failed (/, Sys.Modify) hoặc (/nodes/node1, Sys.Modify)Token (hoặc user) thiếu FirewallOperator/NotificationOperator ở đúng path; ACL tại / đặt --propagate 0 nên không kế thừa xuống node; firewall cấp VM cần VM.Config.Network trên /vms/<id>pveum user token permissions svc-automation@pve ansible --path /nodes/node1; chạy lại pve-rbac-apply.sh
Clone xong nhưng VM không tự bật (PVE 9.2)Vai trò thiếu VM.PowerMgmt; hoặc thêm HA lúc tạo thiếu Sys.ConsoleThêm privilege vào vai trò, chạy lại script; đối chiếu release notes 9.2
Nhân viên ops không thấy VMVM chưa vào pool; ACL ở /pool/… thiếu hoặc propagate=0; thiếu VM.AuditMục 5.4 (tìm VM vô chủ), pveum acl list, thêm VM vào pool
pve-rbac-apply.sh dừng "Cluster mất quorum"Đúng chủ ý: không ghi cấu hình khi /etc/pve chỉ đọcKhôi phục quorum rồi chạy lại
pveum pool modify báo VM đang ở pool khácVM đã thuộc pool khácThêm --allow-move 1 (script đã có)
OIDC: redirect_uri_mismatch / invalid_redirect_uriĐịa chỉ đang mở PVE không có trong danh sách Strict của AuthentikThêm đúng https://<host>:8006 (không / cuối); log: docker compose logs server ở VM234 (bài 14, mục 14.3)
OIDC: certificate verify failed / lỗi kết nối tới issuerNode chưa tin root CA, hoặc không phân giải authentik.hoatranlabs.local, hoặc chặn 9443Mục 9.1–9.2: curl từ node không -k phải chạy được
OIDC: lỗi issuer không khớpissuer-url lệch (thiếu / cuối, sai slug)Copy đúng chuỗi issuer từ …/.well-known/openid-configuration
OIDC: đăng nhập xong báo 401 / chữ ký không hợp lệProvider ký bằng khoá ECDSA (cộng đồng báo)Đổi Signing Key sang RSA ở Provider
OIDC: đăng nhập được nhưng không có quyền gìUser chưa thuộc nhóm Authentik grp-pve-* (tên phải khớp từng ký tự); --groups-claim sai (phải là groups); ACL chưa có cho nhóm có hậu tố -authentikpveum user list --full 1 xem nhóm của user; chạy EXTRA_REALMS="authentik" pve-rbac-apply.sh; kiểm --groups-claim groups và --scopes 'email profile'
OIDC: tên user là chuỗi ngẫu nhiênusername-claim còn mặc định subjectĐổi --username-claim username; xoá user cũ, ACL theo nhóm nên tự áp dụng lại
Mất điện thoại TOTP—Mục 7.3: pveum user tfa delete …; đã khoá: pveum user tfa unlock …
Sync AD báo lỗi SSL / không bind đượcChưa tin root CA; sai bind_dn/mật khẩu; chặn 636ldapsearch ở mục 10.2 chạy từ node; kiểm --verify, --port 636, --mode ldaps
User AD đăng nhập được nhưng không có nhómChưa sync nhóm, group_filter sai, hoặc ACL chưa nhân bản cho -hoatran-adpveum realm sync hoatran-ad --scope both; chạy lại script với EXTRA_REALMS
Script kiểm toán báo chưa có 2FAUser thật sự chưa thêm TOTPThêm TOTP/Recovery Keys (mục 3.3); user svc-* tự được bỏ qua
OpenTofu: Permission check failed (user != root@pam)Thao tác chỉ root làm được (đặc quyền container, arch...)Làm tay bằng tài khoản có quyền; đừng cấp token root (mục 6.6)

Checklist nghiệm thu

  • Cụm có quorum; pveversion là 9.2.x; sudo, jq đã cài trên node chạy script
  • Đã sao lưu user.cfg, domains.cfg vào thư mục 700 trước khi thay đổi
  • Người dùng Linux sysadmin tồn tại ở mọi node; đăng nhập SSH bằng khoá và sudo chạy được
  • sysadmin@pam đăng nhập GUI, thuộc grp-pve-admin, có TOTP và Recovery Keys; root@pam cũng có TOTP và Recovery Keys
  • Mật khẩu root@pam dài ≥ 24 ký tự, đã niêm phong ngoại tuyến; Recovery Keys cất riêng
  • Sáu vai trò VMOperator, AuditReadOnly, TemplateDeployer, BackupOperator, FirewallOperator, NotificationOperator tồn tại và đúng privilege (pveum role list)
  • Năm nhóm grp-pve-admin/ops/readonly/backup/automation tồn tại; ACL khớp bảng mục 4.3 (pveum acl list)
  • Ba pool pool-prod, pool-infra, pool-test có đúng VM; không còn VM "vô chủ" (mục 5.4)
  • Thử đóng vai test-ops: thao tác được pool-prod, không sửa/xoá được VM pool-infra; đã xoá user thử
  • svc-automation@pve và svc-monitoring@pve không có mật khẩu; token ansible, prometheus có privsep=1 và có hạn dùng
  • Không tồn tại token của root@pam; pdm-token đã hạ xuống AuditReadOnly và PDM vẫn online
  • Phép thử quyền âm: token prometheus gọi status/start nhận 403
  • Secret token cất trong ansible-vault / file env 600, không có trong git hoặc ảnh chụp
  • Firewall (bài 05): cổng 8006 chỉ mở cho mgmt-admins (ops01) và sg-pve-integr (PDM, Prometheus); token ansible ghi được firewall cấp cluster (thử GET /cluster/firewall/options)
  • pve-rbac-audit.timer chạy 05:10; báo cáo gần nhất không còn WARN
  • Đã diễn tập break-glass: đăng nhập sysadmin@pam và root@pam khi không có SSO; thử một Recovery Key
  • (Sau bài 14) Node tin root CA; curl tới issuer không cần -k; realm authentik có --groups-claim groups, --groups-overwrite 1, --groups-autocreate 0 và --username-claim username
  • (Sau bài 14) Đăng nhập OIDC thử thành công; gỡ user khỏi nhóm Authentik thì nhóm PVE biến mất sau lần đăng nhập kế; Authentik yêu cầu MFA cho ứng dụng Proxmox
  • (Sau bài 14) Đã tắt khả năng người dùng tự đổi username trong Authentik
  • (Sau bài 25, tuỳ chọn) Realm hoatran-ad đồng bộ được user/nhóm; ldapsearch qua LDAPS chạy từ node; ACL đã nhân bản cho -hoatran-ad
  • (Quy mô lớn) Playbook rbac.yml và script nằm trong git; chạy DRY_RUN=1 trước mỗi lần áp dụng

Tài liệu tham khảo

Zalo