Xây dựng OTP Server trên Ubuntu 24.04 LTS với privacyIDEA

PHẦN 0. SO SÁNH PHƯƠNG ÁN VÀ CHỐT LỰA CHỌN

0.1. Các phương án OTP server chạy được trên Ubuntu

Tôi đã đọc source code, script cài đặt và tài liệu upstream của từng phương án. Dưới đây là đánh giá dựa trên những gì thực sự có trong code, không phải theo trang marketing.

0.2. ⭐ Chốt lựa chọn: privacyIDEA cài bằng APT trên Ubuntu 24.04

Lý do — bốn điểm quyết định:

1. Đây là phương án duy nhất có gói cài đặt gốc cho Ubuntu 24.04. NetKnights duy trì APT repo với suite noble riêng. Bạn apt install privacyidea-apache2 và script postinst tự làm hết: tạo user hệ thống, sinh SECRET_KEY và PI_PEPPER ngẫu nhiên, tạo database MariaDB với mật khẩu ngẫu nhiên, sinh encryption key, sinh cặp khoá ký audit log, tạo bảng, cấu hình Apache + WSGI, sinh chứng chỉ TLS. Việc duy nhất còn lại của bạn là tạo tài khoản admin.

2. multiOTP trên Linux có vấn đề nghiêm trọng về mặt vận hành. Không phải chê phần mềm — engine OTP của multiOTP tốt và đã OATH-certified. Vấn đề là cách nó được đóng gói cho Linux. Script cài duy nhất (raspberry/boot-part/install.sh) được viết cho appliance Raspberry Pi, và nếu chạy nguyên bản trên một server có sẵn nó sẽ:

• Đổi IP máy thành static 192.168.1.44 (ghi /etc/netplan/, netplan apply) → mất SSH ngay lập tức
• Đặt lại mật khẩu root, ubuntu, pi thành raspberry
• Bật PermitRootLogin yes
• Sửa GRUB thêm net.ifnames=0 → interface đổi tên sau reboot
• iptables -P INPUT DROP và ghi vào rules.v4
• chmod 777 -R /etc/multiotp — thư mục chứa seed OTP thành world-writable
• Tạo RADIUS client 0.0.0.0/0 với secret myfirstpass
• Tự reboot và tự xoá chính nó

Có thể sửa các biến đầu script để né, nhưng khi công cụ cài đặt của một sản phẩm bảo mật cần bạn đọc và vá 65 KB bash trước khi dám chạy, đó là tín hiệu rõ ràng rằng Linux không phải nền tảng chính của nó.

3. Ba thứ privacyIDEA có mà multiOTP open source không có, và bạn sẽ cần cả ba.

4. Đường nâng cấp trong tương lai. privacyIDEA hỗ trợ FIDO2/WebAuthn và Passkey ngay trong cùng hệ thống. TOTP chống được password reuse và brute-force, nhưng không chống được real-time phishing. Khi bạn muốn nâng tài khoản admin lên khoá bảo mật phishing-resistant, privacyIDEA cho phép làm việc đó mà không phải thay hạ tầng. Đây là lý do dài hạn quan trọng nhất.

0.3. Khi nào không nên chọn privacyIDEA

Tôi nên nói rõ cả mặt kia:

Nếu tình huống của bạn nằm trong bảng trên, hãy dừng ở đây và chọn phương án tương ứng. Phần còn lại của tài liệu giả định bạn cần một OTP server tập trung phục vụ cả ba môi trường: Windows, Linux và web.

0.4. Ràng buộc và rủi ro của phương án đã chọn — biết trước để không bất ngờ

0.5. Kết quả cuối cùng sẽ có gì

Sau khi hoàn thành tài liệu này:

PHẦN 1. KIẾN TRÚC LAB, CHUẨN BỊ, ÔN LẠI TOTP

1.1. Ôn nhanh: TOTP hoạt động thế nào (đọc 3 phút)

Nếu bạn đã nắm rồi thì nhảy sang 1.2.

HOTP (RFC 4226) — mật khẩu một lần dựa trên bộ đếm sự kiện:

CopyHOTP(K, C) = Truncate( HMAC-SHA1(K, C) ) mod 10^d

• K = seed / secret, chuỗi bí mật chia sẻ giữa server và điện thoại. 160 bit (20 byte), hiển thị dạng Base32.
• C = bộ đếm, tăng mỗi lần người dùng bấm nút sinh mã.
• Truncate = lấy 4 bit thấp của byte cuối làm offset, đọc 4 byte từ vị trí đó, mask 0x7FFFFFFF, rồi mod 10^6.

TOTP (RFC 6238) = HOTP với bộ đếm lấy từ thời gian:

CopyT = floor( (UnixTime - T0) / X )      với T0 = 0, X = 30 giây
TOTP(K) = HOTP(K, T)

Ba hệ quả thực tế bạn phải nhớ:

Chuẩn URI để nạp seed vào app (chính là nội dung mã QR):

Copyotpauth://totp/LABEL?secret=BASE32SECRET&issuer=ISSUER&algorithm=SHA1&digits=6&period=30

TOTP không chống được gì: real-time phishing (Evilginx lừa bạn nhập OTP rồi dùng ngay trong 30 giây), malware trên máy đã đăng nhập, và kẻ tấn công đã lấy được file seed trên server. Muốn chống phishing thật sự thì phải dùng FIDO2/WebAuthn — privacyIDEA hỗ trợ sẵn, xem Phần 10.6.

1.2. Sơ đồ lab

1.3. Bảng máy chủ và tài nguyên

1.4. Bảng port

Mở firewall trên OTP01:

Copysudo ufw allow 22/tcp    comment 'SSH quan tri'
sudo ufw allow 443/tcp   comment 'privacyIDEA WebUI + API'
sudo ufw allow 1812/udp  comment 'RADIUS auth'
sudo ufw allow 1813/udp  comment 'RADIUS accounting'
sudo ufw --force enable
sudo ufw status numbered

Siết chặt hơn — chỉ cho phép RADIUS từ những IP đã biết:

Copysudo ufw delete allow 1812/udp
sudo ufw allow from 192.168.10.31 to any port 1812 proto udp comment 'LNX01'
sudo ufw allow from 192.168.10.41 to any port 1812 proto udp comment 'WEB01'

1.5. Chuẩn bị OTP01

1.5.1. Cài Ubuntu 24.04 và cập nhật

Copysudo apt update && sudo apt full-upgrade -y
sudo apt install -y curl wget gnupg ca-certificates software-properties-common \
                    chrony net-tools dnsutils jq
sudo reboot

Đặt hostname và tên miền đầy đủ:

Copysudo hostnamectl set-hostname otp01.lab.local

Kiểm tra /etc/hosts có dòng ánh xạ đúng (nếu không, Apache và một số script sẽ chậm do DNS lookup ngược):

Copysudo nano /etc/hosts

Copy127.0.0.1       localhost
192.168.10.10   otp01.lab.local otp01

1.5.2. Đặt IP tĩnh (netplan)

Copysudo nano /etc/netplan/50-cloud-init.yaml

Copynetwork:
  version: 2
  ethernets:
    ens18:                       # đổi thành tên interface thật của bạn: ip -br a
      dhcp4: false
      addresses:
        - 192.168.10.10/24
      routes:
        - to: default
          via: 192.168.10.1
      nameservers:
        addresses: [192.168.10.5, 1.1.1.1]
        search: [lab.local]

Copysudo chmod 600 /etc/netplan/50-cloud-init.yaml   # netplan cảnh báo nếu file world-readable
sudo netplan try                                  # tự rollback sau 120s nếu bạn mất kết nối
sudo netplan apply
ip -br a

1.5.3. ⭐ Đồng bộ thời gian — làm TRƯỚC, không làm SAU

Đây là bước quan trọng nhất trong toàn bộ tài liệu. Bỏ qua nó thì mọi thứ sau đây sẽ hoạt động sai một cách khó hiểu.

Ubuntu 24.04 mặc định dùng systemd-timesyncd (SNTP client đơn giản). Với OTP server, hãy thay bằng chrony — nó chính xác hơn, xử lý được jitter của VM và có công cụ chẩn đoán tốt hơn.

Copysudo apt install -y chrony
sudo systemctl disable --now systemd-timesyncd 2>/dev/null || true
sudo nano /etc/chrony/chrony.conf

Thêm/sửa:

Copy# Nguồn thời gian nội bộ (DC01) trước, pool công cộng làm dự phòng
server 192.168.10.5 iburst prefer
pool vn.pool.ntp.org iburst maxsources 3

# Cho phép bước nhảy lớn trong 3 lần hiệu chỉnh đầu (khi máy vừa boot / vừa restore snapshot)
makestep 1.0 3

# Ghi lại độ trôi của đồng hồ phần cứng
driftfile /var/lib/chrony/chrony.drift
rtcsync

# Ghi log để điều tra sự cố sau này
logdir /var/log/chrony
log measurements statistics tracking

Copysudo timedatectl set-timezone Asia/Bangkok
sudo systemctl restart chrony
sudo systemctl enable chrony

Kiểm tra — cả ba lệnh phải cho kết quả tốt:

Copy$ timedatectl status
# System clock synchronized: yes        ← BẮT BUỘC là yes
#               NTP service: active

$ chronyc sources -v
# Cột đầu phải có dấu '^*' (nguồn đang được đồng bộ) hoặc '^+' (nguồn dự phòng tốt)

$ chronyc tracking
# System time     : 0.000012345 seconds fast of NTP time    ← phải < 0.1 giây
# Leap status     : Normal

Copysudo chronyc makestep && chronyc tracking

Đưa việc giám sát độ lệch giờ vào monitoring ngay từ đầu:

Copysudo tee /usr/local/bin/check-time-drift.sh > /dev/null <<'EOF'
#!/bin/bash
# Cảnh báo nếu đồng hồ lệch quá ngưỡng — TOTP sẽ hỏng trước khi bạn kịp nhận ra
THRESHOLD=5      # giây
OFFSET=$(chronyc tracking | awk '/System time/ {print $4}')
ABS=$(echo "$OFFSET" | awk '{print ($1<0)?-$1:$1}')
if awk -v a="$ABS" -v t="$THRESHOLD" 'BEGIN{exit !(a>t)}'; then
    logger -p auth.crit -t otp-timecheck "CANH BAO: dong ho lech ${ABS}s - TOTP CO THE HONG"
    echo "CRITICAL: lech ${ABS}s"; exit 2
fi
echo "OK: lech ${ABS}s"; exit 0
EOF
sudo chmod +x /usr/local/bin/check-time-drift.sh
sudo /usr/local/bin/check-time-drift.sh

# Chạy mỗi 10 phút
echo '*/10 * * * * root /usr/local/bin/check-time-drift.sh >/dev/null' | sudo tee /etc/cron.d/otp-timecheck

1.5.4. Chuẩn bị chứng chỉ TLS

Gói privacyIDEA sẽ tự sinh chứng chỉ self-signed khi cài. Điều đó đủ để bắt đầu, nhưng Credential Provider trên Windows sẽ từ chối kết nối trừ khi bạn tắt kiểm tra chứng chỉ (không nên) hoặc dùng chứng chỉ được tin cậy.

Ba lựa chọn:

Sinh CSR để xin chứng chỉ từ CA nội bộ:

Copysudo mkdir -p /etc/ssl/privacyidea && cd /etc/ssl/privacyidea

sudo openssl req -new -newkey rsa:4096 -nodes \
  -keyout otp01.key -out otp01.csr \
  -subj "/C=VN/ST=Hanoi/L=Hanoi/O=LAB/CN=otp01.lab.local" \
  -addext "subjectAltName=DNS:otp01.lab.local,DNS:otp.lab.local,IP:192.168.10.10"

sudo chmod 600 otp01.key
cat otp01.csr

Mang otp01.csr sang CA nội bộ ký, rồi lấy về file chứng chỉ. Việc lắp vào Apache làm ở mục 2.6.

1.5.5. Danh sách kiểm tra trước khi sang Phần 2

Copy# Chạy toàn bộ và xác nhận từng dòng
hostnamectl                                      # hostname = otp01.lab.local
ip -br a                                         # IP tĩnh đúng
timedatectl status | grep -E 'synchronized|Time zone'   # synchronized: yes
chronyc tracking | grep 'System time'            # lệch < 0.1s
ping -c2 192.168.10.5                            # tới được DC (nếu có AD)
sudo ufw status                                  # firewall đã bật, đúng port
lsb_release -a                                   # Ubuntu 24.04
python3 --version                                # Python 3.12.x
free -h && df -h /                               # đủ RAM và disk

• Hostname là FQDN, /etc/hosts có ánh xạ đúng
• IP tĩnh, DNS trỏ đúng
• chrony chạy, System clock synchronized: yes, lệch < 0,1 giây
• Đã tắt time sync của hypervisor
• Cron giám sát độ lệch giờ đã cài
• Firewall mở đúng 4 port, đóng phần còn lại
• Máy này chuyên dụng cho OTP — không chạy web app hay dịch vụ nào khác
• Đã có snapshot VM sạch để rollback nếu cần

PHẦN 2. DỰNG PRIVACYIDEA SERVER TRÊN UBUNTU 24.04

2.1. Thêm APT repo của NetKnights

privacyIDEA không có trong repo Ubuntu chính thức. Nguồn duy nhất được hỗ trợ là repo của NetKnights (công ty đứng sau dự án).

Copy# 1. Tải khoá ký của repo
cd /tmp
wget https://lancelot.netknights.it/NetKnights-Release.asc

# 2. ⭐ KIỂM TRA FINGERPRINT — đây là bước bảo mật, đừng bỏ qua
gpg --import --import-options show-only --with-fingerprint NetKnights-Release.asc

Kết quả phải khớp chính xác:

Copypub   4096R/AE250082 2017-05-16
      Key fingerprint = 0940 4ABB EDB3 586D EDE4  AD22 00F7 0D62 AE25 0082
uid                   NetKnights GmbH <[email protected]>

Copy# 3. Cài khoá
sudo mv NetKnights-Release.asc /etc/apt/trusted.gpg.d/
sudo chmod 644 /etc/apt/trusted.gpg.d/NetKnights-Release.asc

# 4. Thêm repo — Ubuntu 24.04 = suite "noble"
echo "deb http://lancelot.netknights.it/community/noble/stable noble main" \
  | sudo tee /etc/apt/sources.list.d/privacyidea-community.list

# 5. Cập nhật danh sách gói
sudo apt update

Kiểm tra repo hoạt động và xem phiên bản sẽ được cài:

Copyapt-cache policy privacyidea

Xem những gói nào có sẵn:

Copyapt-cache search privacyidea
apt-cache policy privacyidea-apache2 privacyidea-nginx privacyidea-radius privacyidea-mysql

2.2. Cài đặt

Copysudo apt install -y privacyidea-apache2

Postinst tự động làm những việc sau — biết để không làm lại thừa và để hiểu hệ thống:

Việc duy nhất bạn phải làm tiếp:

Copysudo pi-manage admin add admin -e [email protected]
# Nhập mật khẩu khi được hỏi — dùng mật khẩu RẤT MẠNH, đây là tài khoản
# kiểm soát toàn bộ hệ thống MFA của tổ chức

Kiểm tra ngay:

Copysudo pi-manage admin list
pi-manage --version    # hoặc: apt-cache policy privacyidea | grep Installed
sudo systemctl status apache2 mariadb

Mở trình duyệt tới https://otp01.lab.local/ → chấp nhận cảnh báo self-signed (tạm thời) → đăng nhập bằng admin.

2.3. Hiểu các file quan trọng — nắm rõ trước khi làm gì tiếp

Copy/etc/privacyidea/
├── pi.cfg                   🔴 Cấu hình chính (chứa SECRET_KEY, PI_PEPPER, DB URI)
├── enckey                   🔴🔴 KHOÁ MÃ HOÁ SEED — mất là mất TOÀN BỘ token
├── private.pem              🔴 Khoá ký audit log
├── public.pem               🟠 Khoá verify audit log
├── privacyideaapp.wsgi         Entry point WSGI
└── gpg/                        Khoá PGP

/opt/privacyidea/            Virtualenv chứa code (dh-virtualenv)
├── bin/pi-manage
└── lib/privacyidea/

/var/log/privacyidea/
└── privacyidea.log             Log ứng dụng

/etc/apache2/sites-available/
├── privacyidea.conf            vhost :443
└── privacyidea-venv.conf

/var/lib/privacyidea/backup/    Nơi pi-manage backup ghi file

Xem file cấu hình:

Copysudo cat /etc/privacyidea/pi.cfg

Nội dung điển hình sau khi cài:

Copyimport logging
SUPERUSER_REALM = ['super', '(?#local admins)']
PI_ENCFILE = '/etc/privacyidea/enckey'
PI_AUDIT_KEY_PRIVATE = '/etc/privacyidea/private.pem'
PI_AUDIT_KEY_PUBLIC  = '/etc/privacyidea/public.pem'
PI_AUDIT_SQL_TRUNCATE = True
PI_ENGINE_REGISTRY_CLASS = "shared"
PI_AUDIT_POOL_SIZE = 20
PI_LOGFILE = '/var/log/privacyidea/privacyidea.log'
PI_LOGLEVEL = logging.INFO
SQLALCHEMY_DATABASE_URI = 'mysql+pymysql://pi:xxxxxxxxxxxx@localhost/pi?charset=utf8'
SECRET_KEY = 'xxxxxxxxxxxxxxxxxxxxxxxx'
PI_PEPPER = 'xxxxxxxxxxxxxxxxxxxxxxxx'

Copysudo python3 -c "exec(open('/etc/privacyidea/pi.cfg').read()); print('Cu phap OK')"

2.4. Hardening cấu hình

Copysudo cp /etc/privacyidea/pi.cfg /etc/privacyidea/pi.cfg.bak-$(date +%F)
sudo nano /etc/privacyidea/pi.cfg

Thêm vào cuối file:

Copy# ══ URL công khai — BẮT BUỘC ═══════════════════════════════════
# Thiếu dòng này thì POST /recover (khôi phục mật khẩu) sẽ TỪ CHỐI hoạt động
# và tag {url} trong email thông báo sẽ rỗng.
PI_BASE_URL = 'https://otp01.lab.local'

# ══ Bảo mật tầng ứng dụng ══════════════════════════════════════
PI_FORCE_HTTPS = True          # ép mọi request qua HTTPS
PI_ENABLE_CSP  = True          # bật Content-Security-Policy nghiêm ngặt

# ══ Log ════════════════════════════════════════════════════════
# Đặt DEBUG trong giai đoạn dựng, HẠ VỀ INFO khi lên production
PI_LOGLEVEL = logging.INFO

# ══ Nếu dùng nhiều app node dùng chung DB (Galera) ═════════════
# PI_DB_SAFE_STORE = True

Kiểm tra và áp dụng:

Copysudo python3 -c "exec(open('/etc/privacyidea/pi.cfg').read()); print('Cu phap OK')"
sudo systemctl restart apache2
sudo systemctl status apache2

Kiểm tra quyền file — postinst đã đặt đúng, nhưng xác nhận lại:

Copysudo ls -l /etc/privacyidea/

Kết quả phải là:

Copy-rw-------  1 privacyidea root    ... enckey        ← 600, chỉ owner đọc
-rw-------  1 privacyidea root    ... private.pem   ← 600
-rw-r--r--  1 privacyidea root    ... public.pem    ← 644
-rw-r-----  1 privacyidea root    ... pi.cfg        ← 640

Nếu lệch, sửa lại:

Copysudo chown privacyidea:root /etc/privacyidea/{pi.cfg,enckey,private.pem,public.pem}
sudo chmod 600 /etc/privacyidea/enckey /etc/privacyidea/private.pem
sudo chmod 640 /etc/privacyidea/pi.cfg
sudo chmod 644 /etc/privacyidea/public.pem

2.5. Nắm cú pháp pi-manage — phần rất dễ sai

Cấu trúc mới:

Copypi-manage <nhóm> <lệnh con> [tham số]

Các nhóm: admin, audit, setup, config, backup, api, token, run.

Bảng chuyển đổi cú pháp cũ → mới:

Các lệnh bạn sẽ dùng thường xuyên:

Copy# ── Quản trị viên ──────────────────────────────────────────────
sudo pi-manage admin add <user> -e <email>       # mật khẩu sẽ được hỏi
sudo pi-manage admin list
sudo pi-manage admin change <user> --password <PW>
sudo pi-manage admin delete <user>

# ── Resolver và realm (Phần 3) ─────────────────────────────────
sudo pi-manage config resolver list
sudo pi-manage config resolver create <ten> <loai> <file_config.py>
sudo pi-manage config resolver create_internal <ten>
sudo pi-manage config realm list                  # dấu '*' = realm mặc định
sudo pi-manage config realm create <realm> <resolver1> [<resolver2>...]
sudo pi-manage config realm set_default <realm>

# ── Policy (Phần 4) ────────────────────────────────────────────
sudo pi-manage config policy list
sudo pi-manage config policy create <ten> <scope> "<action>"
sudo pi-manage config policy enable|disable|delete <ten>

# ── Export / import cấu hình ───────────────────────────────────
sudo pi-manage config export -f yaml -o /root/pi-config.yaml --censor
sudo pi-manage config import -i /root/pi-config.yaml

# ── Backup (Phần 9) ────────────────────────────────────────────
sudo pi-manage backup create -e                   # -e = KÈM enckey, RẤT QUAN TRỌNG
sudo pi-manage backup restore <file.tgz>

# ── Audit ──────────────────────────────────────────────────────
sudo pi-manage audit rotate --age 180
sudo pi-manage audit dump

# ── Dọn challenge cũ — BẮT BUỘC chạy định kỳ từ 3.10 ───────────
sudo pi-manage config challenge cleanup --age 60

Copysudo cat /etc/cron.d/privacyidea

2.6. Lắp chứng chỉ TLS thật

Chứng chỉ self-signed do postinst sinh ra chỉ dùng để bắt đầu. Thay bằng chứng chỉ từ CA nội bộ (đã xin ở mục 1.5.4):

Copy# Sao lưu cert cũ
sudo cp /etc/ssl/certs/privacyideaserver.pem /etc/ssl/certs/privacyideaserver.pem.bak
sudo cp /etc/ssl/private/privacyideaserver.key /etc/ssl/private/privacyideaserver.key.bak

# Đặt cert mới (fullchain: cert của server + intermediate CA)
sudo cp /etc/ssl/privacyidea/otp01-fullchain.pem /etc/ssl/certs/privacyideaserver.pem
sudo cp /etc/ssl/privacyidea/otp01.key           /etc/ssl/private/privacyideaserver.key

sudo chown root:root  /etc/ssl/certs/privacyideaserver.pem /etc/ssl/private/privacyideaserver.key
sudo chmod 644 /etc/ssl/certs/privacyideaserver.pem
sudo chmod 600 /etc/ssl/private/privacyideaserver.key

sudo apache2ctl configtest && sudo systemctl reload apache2

Bật HSTS sau khi chắc chắn cert thật đã hoạt động:

Copysudo nano /etc/apache2/sites-available/privacyidea.conf

Bỏ comment dòng:

CopyHeader always set Strict-Transport-Security "max-age=1209600"

CopyLogFormat "%h %l %u %t \"%m %U %H\" %b ..." privacyIDEA

Kiểm tra TLS từ máy khác:

Copyopenssl s_client -connect otp01.lab.local:443 -servername otp01.lab.local </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

2.7. Kiểm tra hệ thống hoạt động

Copy# 1. Dịch vụ chạy
sudo systemctl is-active apache2 mariadb

# 2. Cổng lắng nghe
sudo ss -tlnp | grep -E ':443|:3306'

# 3. Database có bảng
sudo mysql pi -e "SHOW TABLES;" | head -20

# 4. Log không có lỗi
sudo tail -30 /var/log/privacyidea/privacyidea.log
sudo tail -30 /var/log/apache2/error.log

# 5. API trả lời — lấy JWT
curl -s -k -X POST https://otp01.lab.local/auth \
     -d "username=admin" -d "password=<mat-khau-admin>" | jq -r '.result.value.token' | head -c 60

Nếu bước 5 trả về một chuỗi JWT dài, hệ thống đã hoạt động.

Lưu JWT vào biến để dùng cho các phần sau:

Copyexport PI_URL="https://otp01.lab.local"
export PI_TOKEN=$(curl -s -k -X POST $PI_URL/auth \
  -d "username=admin" -d "password=<mat-khau-admin>" | jq -r '.result.value.token')

echo "${PI_TOKEN:0:40}..."

2.8. Tóm tắt Phần 2

Các bước chính:

1. Thêm repo NetKnights suite noble, kiểm tra GPG fingerprint 0940 4ABB EDB3 586D EDE4 AD22 00F7 0D62 AE25 0082.
2. Xác nhận phiên bản ≥ 3.13.1 (bug backup trên Python 3.12).
3. apt install privacyidea-apache2 trên máy chuyên dụng (nó xoá symlink của mọi site Apache khác).
4. pi-manage admin add admin -e ... — việc duy nhất cần làm thủ công.
5. Thêm PI_BASE_URL, PI_FORCE_HTTPS, PI_ENABLE_CSP vào pi.cfg.
6. Thay chứng chỉ self-signed bằng cert từ CA nội bộ, SAN có cả DNS lẫn IP.
7. Bỏ comment cron challenge cleanup.
8. Ghi nhớ: pi-manage <nhóm> <lệnh con> — cú pháp mới từ 3.10.

Lỗi thường gặp ở giai đoạn này:

PHẦN 3. USER: RESOLVER + REALM

3.1. Mô hình user của privacyIDEA — hiểu trước khi cấu hình

privacyIDEA không lưu người dùng của bạn. Nó chỉ lưu token và gắn token vào một danh tính đến từ nơi khác. Kiến trúc gồm hai lớp:

3.2. Chuẩn bị phía Active Directory

3.2.1. Tạo tài khoản dịch vụ để bind LDAP

Trên DC01 (PowerShell as Administrator):

CopyPS> $pw = ConvertTo-SecureString (-join ((33..126) | Get-Random -Count 32 | %{[char]$_})) -AsPlainText -Force
PS> New-ADUser -Name "svc-privacyidea" `
      -SamAccountName "svc-privacyidea" `
      -UserPrincipalName "[email protected]" `
      -Path "OU=Service Accounts,DC=lab,DC=local" `
      -AccountPassword $pw `
      -PasswordNeverExpires $true `
      -CannotChangePassword $true `
      -Enabled $true `
      -Description "Bind account cho privacyIDEA LDAP resolver - CHI CAN QUYEN DOC"

# Hiển thị mật khẩu để copy sang OTP01 (rồi xoá khỏi lịch sử lệnh)
PS> [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($pw))

3.2.2. Tạo group giới hạn phạm vi

CopyPS> New-ADGroup -Name "OTP-Users" -GroupScope Global -GroupCategory Security `
      -Path "OU=Groups,DC=lab,DC=local" `
      -Description "Nhan vien bat buoc dung MFA"

PS> Add-ADGroupMember -Group "OTP-Users" -Members hoangnv,ducnm

3.2.3. Lấy CA certificate để dùng LDAPS

LDAP trần (port 389) gửi mật khẩu bind dạng plaintext qua mạng. Bắt buộc dùng LDAPS (636).

Trên DC01, export CA certificate:

CopyPS> certutil -ca.cert C:\temp\lab-ca.cer
PS> certutil -encode C:\temp\lab-ca.cer C:\temp\lab-ca.pem

Copy lab-ca.pem sang OTP01:

Copysudo mkdir -p /etc/privacyidea/certs
sudo cp /tmp/lab-ca.pem /etc/privacyidea/ldap-ca.crt
sudo chown privacyidea:root /etc/privacyidea/ldap-ca.crt
sudo chmod 644 /etc/privacyidea/ldap-ca.crt

Kiểm tra LDAPS hoạt động từ OTP01:

Copysudo apt install -y ldap-utils

# Test kết nối TLS
openssl s_client -connect dc01.lab.local:636 -showcerts </dev/null 2>/dev/null | head -20

# Test bind thật
LDAPTLS_CACERT=/etc/privacyidea/ldap-ca.crt ldapsearch -x -H ldaps://dc01.lab.local \
  -D "[email protected]" -W \
  -b "DC=lab,DC=local" \
  "(&(objectClass=user)(sAMAccountName=hoangnv))" sAMAccountName mail displayName

3.3. Tạo LDAP resolver cho Active Directory

3.3.1. Cách 1 — WebUI (khuyến nghị cho lần đầu)

Config → Users → New LDAP resolver

Điền các trường sau — đây là bảng tham chiếu đầy đủ, tên trường chính xác theo source code:

Attribute mapping (dán vào ô Attribute mapping):

Copy{"username": "sAMAccountName", "phone": "telephoneNumber", "mobile": "mobile", "email": "mail", "surname": "sn", "givenname": "givenName", "accountExpires": "accountExpires"}

Bấm Test LDAP resolver → phải báo số user tìm được. Rồi bấm Save.

3.3.2. Cách 2 — CLI (dùng cho tự động hoá, IaC)

Copysudo tee /root/resolver-ad.py > /dev/null <<'EOF'
{
 "LDAPURI": "ldaps://dc01.lab.local, ldaps://dc02.lab.local",
 "LDAPBASE": "DC=lab,DC=local",
 "AUTHTYPE": "Simple",
 "BINDDN": "[email protected]",
 "BINDPW": "MAT_KHAU_SERVICE_ACCOUNT",
 "TIMEOUT": "5",
 "SIZELIMIT": "500",
 "CACHE_TIMEOUT": "120",
 "LOGINNAMEATTRIBUTE": "sAMAccountName, userPrincipalName",
 "LDAPSEARCHFILTER": "(&(objectClass=user)(objectCategory=person))",
 "USERINFO": "{\"username\": \"sAMAccountName\", \"phone\": \"telephoneNumber\", \"mobile\": \"mobile\", \"email\": \"mail\", \"surname\": \"sn\", \"givenname\": \"givenName\", \"accountExpires\": \"accountExpires\"}",
 "UIDTYPE": "objectGUID",
 "NOREFERRALS": "1",
 "NOSCHEMAS": "1",
 "TLS_VERIFY": "1",
 "TLS_CA_FILE": "/etc/privacyidea/ldap-ca.crt",
 "SCOPE": "SUBTREE",
 "EDITABLE": "0"
}
EOF

sudo chmod 600 /root/resolver-ad.py     # chứa mật khẩu bind
sudo pi-manage config resolver create ad_lab ldapresolver /root/resolver-ad.py
sudo pi-manage config resolver list

# Xoá file chứa mật khẩu sau khi xong
sudo shred -u /root/resolver-ad.py

3.3.3. Chỉ lấy user trong group OTP-Users

Sửa Search Filter để lọc theo group:

Copy(&(objectClass=user)(objectCategory=person)(memberOf=CN=OTP-Users,OU=Groups,DC=lab,DC=local))

Hoặc — nếu cần nested group (user thuộc group con của OTP-Users) — dùng extensible match của AD:

Copy(&(objectClass=user)(objectCategory=person)(memberOf:1.2.840.113556.1.4.1941:=CN=OTP-Users,OU=Groups,DC=lab,DC=local))

3.4. Tạo resolver cho user nội bộ (không có AD)

Dùng khi: không có AD, hoặc cần thêm tài khoản nhà thầu / tài khoản dịch vụ không nằm trong AD.

3.4.1. Cách nhanh nhất — SQL resolver nội bộ

Một lệnh duy nhất tạo bảng user ngay trong database của privacyIDEA:

Copysudo pi-manage config resolver create_internal local_users

Lệnh này tạo bảng users_local_users với các cột id, username, email, password, phone, mobile, surname, givenname, description, đặt Editable=1 và ánh xạ thuộc tính sẵn.

Kiểm tra:

Copysudo pi-manage config resolver list
sudo mysql pi -e "DESCRIBE users_local_users;"

Thêm user qua WebUI: Users → (chọn realm) → Add User

Thêm user qua REST API:

Copyexport PI_TOKEN=$(curl -s -k -X POST $PI_URL/auth \
  -d "username=admin" -d "password=<mat-khau>" | jq -r '.result.value.token')

curl -s -k -X POST $PI_URL/user/ \
  -H "PI-Authorization: $PI_TOKEN" \
  -d "user=nhathau01" \
  -d "resolver=local_users" \
  -d "[email protected]" \
  -d "givenname=Tran" \
  -d "surname=Van B" \
  -d "password=MatKhauTamThoi#2026" | jq

3.4.2. Cách 2 — passwd resolver (đọc file dạng /etc/passwd)

Dùng khi bạn muốn quản lý user bằng file phẳng.

Copysudo tee /root/resolver-passwd.py > /dev/null <<'EOF'
{"fileName": "/etc/privacyidea/pi-users"}
EOF

sudo pi-manage config resolver create file_users passwdresolver /root/resolver-passwd.py
sudo rm /root/resolver-passwd.py

Copysudo /opt/privacyidea/bin/privacyidea-create-pwidresolver-user \
     -u nhathau01 -i 1002 | sudo tee -a /etc/privacyidea/pi-users
sudo chown privacyidea:root /etc/privacyidea/pi-users
sudo chmod 600 /etc/privacyidea/pi-users

3.4.3. So sánh nhanh ba loại resolver nội bộ

3.5. Tạo realm — gộp AD và user nội bộ

Copy# Realm chính: AD trước, user nội bộ sau
sudo pi-manage config realm create lab ad_lab local_users

# Đặt làm realm mặc định -> user gõ "hoangnv" thay vì "hoangnv@lab"
sudo pi-manage config realm set_default lab

sudo pi-manage config realm list

Kết quả (dấu * đánh dấu realm mặc định):

Copy*lab
     ad_lab (priority: 1)
     local_users (priority: 2)

Thứ tự resolver có ý nghĩa. privacyIDEA tìm user theo thứ tự ưu tiên; user đầu tiên khớp sẽ thắng. Đặt AD trước để tài khoản công ty luôn được ưu tiên hơn tài khoản nội bộ trùng tên.

Nếu chỉ có user nội bộ (không có AD):

Copysudo pi-manage config resolver create_internal local_users
sudo pi-manage config realm create lab local_users
sudo pi-manage config realm set_default lab

Tạo realm riêng cho nhà thầu (tuỳ chọn — tách policy và audit):

Copysudo pi-manage config resolver create_internal contractors
sudo pi-manage config realm create ext contractors

Khi đó nhà thầu đăng nhập bằng nhathau01@ext, và bạn có thể áp policy chặt hơn riêng cho realm ext.

3.6. Kiểm tra resolver và realm

Qua WebUI: Users → chọn realm → phải thấy danh sách user.

Qua CLI:

Copysudo pi-manage config resolver list
sudo pi-manage config realm list

Qua API — kiểm tra một user cụ thể:

Copycurl -s -k -G $PI_URL/user/ \
  -H "PI-Authorization: $PI_TOKEN" \
  --data-urlencode "realm=lab" \
  --data-urlencode "username=hoangnv" | jq '.result.value'

Kết quả mong đợi:

Copy[
  {
    "description": "",
    "editable": false,
    "email": "[email protected]",
    "givenname": "Hoang",
    "mobile": "0901234567",
    "resolver": "ad_lab",
    "surname": "Nguyen Van",
    "userid": "a1b2c3d4-...",
    "username": "hoangnv"
  }
]

3.7. Tóm tắt Phần 3

Các bước chính:

1. AD: tạo svc-privacyidea (chỉ quyền đọc), tạo group OTP-Users, export CA cert cho LDAPS.
2. Test bằng ldapsearch trước khi động vào privacyIDEA.
3. Tạo LDAP resolver với UIDTYPE=objectGUID, NOREFERRALS=1, NOSCHEMAS=1, LDAPS + TLS verify.
4. Không AD: pi-manage config resolver create_internal local_users — một lệnh là xong.
5. Gộp cả hai vào một realm: pi-manage config realm create lab ad_lab local_users.
6. set_default để user không phải gõ @realm.
7. Verify bằng API trước khi sang Phần 4.

Lỗi thường gặp:

PHẦN 4. POLICY VÀ ENROLL TOKEN TOTP

4.1. Policy engine — hiểu cơ chế trước khi viết policy

Đây là thứ mạnh nhất của privacyIDEA và cũng dễ gây bối rối nhất.

11 scope (phạm vi) — mỗi cái điều khiển một giai đoạn khác nhau:

Thuộc tính của một policy:

4.2. ⭐ Policy quan trọng nhất: otppin

Đây là policy quyết định yếu tố thứ nhất là gì. Nó thay đổi hoàn toàn trải nghiệm người dùng.

Copy# Với AD: dùng mật khẩu AD làm yếu tố 1
sudo pi-manage config policy create auth_userstore authentication "otppin=userstore"

Cấu hình khác nhau cho từng realm — ví dụ AD dùng userstore, nhà thầu dùng tokenpin:

Copysudo pi-manage config policy create auth_ad  authentication "otppin=userstore"
# rồi vào WebUI Config -> Policies -> auth_ad -> đặt realm = lab

sudo pi-manage config policy create auth_ext authentication "otppin=tokenpin"
# realm = ext, priority = 1

4.3. Bộ policy nền tảng — chạy ngay

Copy# ══ 1. Xác thực ════════════════════════════════════════════════
sudo pi-manage config policy create auth_userstore authentication "otppin=userstore"

# ══ 2. Enrollment — nhãn hiển thị trên app OTP ═════════════════
# {user} và {realm} là tag động. Dùng cả hai để tránh nhãn rỗng.
sudo pi-manage config policy create enroll_base enrollment \
     "tokenlabel={user}@{realm},tokenissuer=LAB,max_active_token_per_user=2,verify_enrollment=hotp totp"

# ══ 3. Tự phục vụ — user tự đăng ký và quản lý token của mình ══
sudo pi-manage config policy create selfservice user \
     "enrollTOTP,delete,disable,enable,resync,setpin,reset"

# ══ 4. WebUI ═══════════════════════════════════════════════════
sudo pi-manage config policy create webui_base webui \
     "logout_time=900,jwt_validity=3600"

sudo pi-manage config policy list

Giải nghĩa từng action quan trọng:

4.4. Chống brute-force — bắt buộc phải có

Mã 6 chữ số với timeWindow mặc định 180 giây cho ra 12 mã hợp lệ cùng lúc. Không giới hạn số lần thử thì brute-force là khả thi.

Cấu hình qua WebUI: Config → Tokens → Token defaults

Cách privacyIDEA thực sự tính window — công thức này khác với trực giác:

Copyso_buoc = timeWindow / timeStep
server duyet counter trong khoang: [counter - so_buoc, counter + so_buoc)
=> so ma hop le ≈ 2 × so_buoc

Thêm lớp bảo vệ ở tầng ứng dụng:

Copy# Chặn xác thực từ ngoài dải mạng nội bộ
sudo pi-manage config policy create authz_network authorization "authorized=grant_access"
# rồi vào WebUI đặt client = 192.168.10.0/24

Fail2ban cho tầng HTTP — chặn IP quét mù:

Copysudo apt install -y fail2ban

sudo tee /etc/fail2ban/filter.d/privacyidea.conf > /dev/null <<'EOF'
[Definition]
failregex = ^.*Failed to authenticate user .* from <HOST>.*$
            ^.*privacyIDEA.*authentication failed.*<HOST>.*$
ignoreregex =
EOF

sudo tee /etc/fail2ban/jail.d/privacyidea.conf > /dev/null <<'EOF'
[privacyidea]
enabled  = true
port     = https
filter   = privacyidea
logpath  = /var/log/privacyidea/privacyidea.log
maxretry = 10
findtime = 300
bantime  = 1800
EOF

sudo systemctl restart fail2ban
sudo fail2ban-client status privacyidea

4.5. Enroll token TOTP

4.5.1. Cách 1 — Admin enroll qua WebUI (dùng khi bàn giao trực tiếp)

1. Tokens → Enroll Token
2. Token type: TOTP
3. Username: gõ tên user (có autocomplete từ resolver), chọn Realm
4. PIN: đặt nếu dùng otppin=tokenpin; để trống nếu dùng otppin=userstore
5. Tham số TOTP: Length = 6, Timestep = 30, Hash = sha1 — giữ mặc định
6. Bấm Enroll Token → hiện QR code
7. Người dùng quét bằng app
8. Nếu đã bật verify_enrollment: nhập mã hiện trên app để xác nhận → token mới chuyển sang trạng thái hoạt động
9. Bấm serial token → Test Token để chắc chắn

4.5.2. Cách 2 — REST API (dùng cho tự động hoá)

Copyexport PI_URL="https://otp01.lab.local"
export PI_TOKEN=$(curl -s -k -X POST $PI_URL/auth \
  -d "username=admin" -d "password=<mat-khau>" | jq -r '.result.value.token')

curl -s -k -X POST $PI_URL/token/init \
  -H "PI-Authorization: $PI_TOKEN" \
  -d "type=totp" \
  -d "user=hoangnv" \
  -d "realm=lab" \
  -d "genkey=1" \
  -d "otplen=6" \
  -d "hashlib=sha1" \
  -d "timeStep=30" \
  -d "description=iPhone cua Hoang - cap 2026-08-01" | jq

Tham số quan trọng của /token/init:

Response chứa QR code:

Copy{
  "detail": {
    "googleurl": {
      "description": "URL for google Authenticator",
      "img": "<img width=250 src=\"data:image/png;base64,iVBORw0KGgo...\"/>",
      "value": "otpauth://totp/hoangnv@lab?secret=KRUGKIDROVUWG2ZA...&issuer=LAB&digits=6&period=30"
    },
    "otpkey": {"description": "OTP seed", "value": "seed://3132...3930"},
    "serial": "TOTP0001A2B3",
    "rollout_state": "verify"
  },
  "result": {"status": true, "value": true},
  "version": "privacyIDEA 3.13.3"
}

Trích QR ra file PNG:

Copycurl -s -k -X POST $PI_URL/token/init \
  -H "PI-Authorization: $PI_TOKEN" \
  -d "type=totp" -d "user=hoangnv" -d "realm=lab" -d "genkey=1" \
  | jq -r '.detail.googleurl.img' \
  | sed 's/.*base64,\([^"]*\)".*/\1/' \
  | base64 -d > /tmp/qr_hoangnv.png

Xác nhận enrollment (khi đã bật verify_enrollment):

Copycurl -s -k -X POST $PI_URL/token/init \
  -H "PI-Authorization: $PI_TOKEN" \
  -d "serial=TOTP0001A2B3" \
  -d "verify=123456" | jq '.result'

4.5.3. Cách 3 — Người dùng tự đăng ký (self-service)

Đây là cách tốt nhất khi triển khai quy mô lớn: seed không bao giờ đi qua tay admin.

Điều kiện: đã có policy selfservice với action enrollTOTP (mục 4.3).

1. Người dùng vào https://otp01.lab.local/
2. Đăng nhập bằng mật khẩu AD (chọn đúng realm)
3. Tokens → Enroll Token → TOTP
4. Quét QR, nhập mã xác nhận
5. Xong

4.6. ⚠️ Quy tắc bàn giao token — phần hay bị làm sai

Được phép:

• ✅ Người dùng tự enroll qua self-service portal (seed không rời server)
• ✅ Hiển thị QR trên màn hình khi người dùng có mặt trực tiếp
• ✅ Video call có xác minh danh tính, QR hiện trên màn hình chia sẻ, xoá ngay sau khi quét xong

Tuyệt đối không:

• ❌ Gửi QR qua email, Zalo, Teams, Slack
• ❌ Lưu file QR vào thư mục chung
• ❌ In QR ra giấy rồi để trên bàn
• ❌ Chụp màn hình QR "để phòng khi cần"

Nếu buộc phải xuất file QR, xoá an toàn ngay sau khi dùng:

Copyshred -u /tmp/qr_hoangnv.png

App OTP miễn phí khuyến nghị cho người dùng:

4.7. Test toàn bộ chuỗi xác thực

Copy# ── Test 1: xác thực với PIN/mật khẩu + OTP ───────────────────
# Với otppin=userstore: pass = <mat-khau-AD><OTP>
curl -s -k -X POST $PI_URL/validate/check \
  -d "user=hoangnv" -d "realm=lab" -d "pass=MatKhauAD123456" | jq

Thành công:

Copy{
  "detail": {
    "message": "matching 1 tokens",
    "serial": "TOTP0001A2B3",
    "type": "totp"
  },
  "result": {"status": true, "value": true},
  "version": "privacyIDEA 3.13.3"
}

Đọc kết quả cho đúng — đây là chỗ rất dễ nhầm:

Copy# ── Test 2: mã sai phải bị từ chối ────────────────────────────
curl -s -k -X POST $PI_URL/validate/check \
  -d "user=hoangnv" -d "realm=lab" -d "pass=MatKhauAD000000" \
  | jq '{value: .result.value, message: .detail.message}'
# -> {"value": false, "message": "wrong otp value..."}

# ── Test 3: chống replay — dùng lại đúng mã vừa dùng ──────────
# -> value: false. privacyIDEA từ chối mã đã dùng. Đây là TÍNH NĂNG.

# ── Test 4: endpoint dành cho RADIUS ──────────────────────────
curl -s -k -o /dev/null -w "HTTP %{http_code}\n" -X POST \
  $PI_URL/validate/radiuscheck \
  -d "user=hoangnv" -d "realm=lab" -d "pass=MatKhauAD123456"
# HTTP 204 = thành công (body rỗng)
# HTTP 400 = thất bại

Xem audit log:

Copy# WebUI: Audit
# Hoặc API:
curl -s -k -G $PI_URL/audit/ \
  -H "PI-Authorization: $PI_TOKEN" \
  --data-urlencode "page_size=10" \
  | jq '.result.value.auditdata[] | {date, action, success, user, serial, info}'

4.8. Tóm tắt Phần 4

Các bước chính:

1. Hiểu policy engine: 11 scope, cộng dồn, priority số nhỏ thắng, scope trống = cho phép tất cả.
2. Đặt otppin — quyết định lớn nhất: userstore (dùng mật khẩu AD) hoặc tokenpin (PIN riêng).
3. Tạo bộ policy nền: enroll_base (có verify_enrollment và max_active_token_per_user=2), selfservice, webui_base.
4. Siết Max failcount = 6 và timeWindow = 60 giây; thêm fail2ban.
5. Enroll token: ưu tiên self-service, seed không qua tay admin.
6. Bàn giao token đúng quy tắc: không bao giờ gửi QR qua email/chat.
7. Test bằng /validate/check và nhớ kiểm result.value, không phải result.status.

Lỗi thường gặp:

PHẦN 5. FREERADIUS — CẦU NỐI TỚI MỌI CLIENT

5.1. Vì sao cần RADIUS khi đã có REST API

privacyIDEA có REST API rất tốt, nhưng thiết bị hạ tầng không nói REST. Firewall, VPN gateway, switch, wireless controller, NAS — tất cả đều nói RADIUS. Linux pam_radius cũng vậy.

Windows Credential Provider và web app gọi thẳng REST API — nhanh hơn và an toàn hơn. RADIUS chỉ dùng cho những gì không có lựa chọn khác.

5.2. Cài FreeRADIUS và các phụ thuộc

Copysudo apt update
sudo apt install -y freeradius freeradius-utils

Kiểm tra:

Copyls -l /usr/lib/freeradius/rlm_perl.so
freeradius -v          # Ubuntu 24.04: FreeRADIUS 3.2.5

Cài các Perl module — danh sách này lấy từ cpanfile của plugin, chính xác hơn tài liệu:

Copy# liburi-encode-perl nằm trong repo universe
sudo add-apt-repository -y universe
sudo apt update

sudo apt install -y \
  libwww-perl \
  liblwp-protocol-https-perl \
  libconfig-inifiles-perl \
  libdata-dump-perl \
  libtry-tiny-perl \
  libjson-perl \
  liburi-encode-perl

Kiểm tra tất cả đã cài được:

Copyperl -e 'use LWP; use LWP::Protocol::https; use Config::IniFiles; use Data::Dump; use Try::Tiny; use JSON; use URI::Encode; print "Tat ca Perl module OK\n";'

5.3. Cài plugin privacyIDEA cho FreeRADIUS

Kiểm tra xem có gói .deb cho noble không:

Copyapt-cache policy privacyidea-radius

Nếu có gói, cài bằng apt:

Copysudo apt install -y privacyidea-radius

Cài thủ công (khi không có gói cho noble, hoặc muốn kiểm soát hoàn toàn):

Copysudo install -d -m 755 /usr/share/privacyidea/freeradius

sudo curl -fsSL -o /usr/share/privacyidea/freeradius/privacyidea_radius.pm \
  https://raw.githubusercontent.com/privacyidea/FreeRADIUS/master/privacyidea_radius.pm

sudo chown root:root /usr/share/privacyidea/freeradius/privacyidea_radius.pm
sudo chmod 644 /usr/share/privacyidea/freeradius/privacyidea_radius.pm

# Kiểm tra cú pháp Perl
sudo perl -c /usr/share/privacyidea/freeradius/privacyidea_radius.pm

5.4. Cấu hình rlm_perl.ini

Copysudo tee /etc/privacyidea/rlm_perl.ini > /dev/null <<'EOF'
[Default]
# Endpoint xác thực của privacyIDEA
URL = https://otp01.lab.local/validate/check

# Kiểm tra chứng chỉ TLS.
# ⚠️ Code so khớp bằng regex /true/i -> PHẢI ghi đúng chữ "true".
#    Ghi "1", "yes", "TRUE" đều KHÔNG có tác dụng và SSL sẽ KHÔNG được verify.
SSL_CHECK = true
SSL_CA_PATH = /etc/ssl/certs

# Timeout HTTP (giây)
TIMEOUT = 15

# Log chi tiết — bật khi debug, TẮT khi production
DEBUG = false

# Ghi đè realm mà FreeRADIUS tách từ username. Để trống = giữ nguyên.
#REALM =

# Chỉ định resolver cụ thể. Để trống = tìm trong toàn realm.
#RESCONF =

# Gửi pass="" khi request không có User-Password (dùng cho token PUSH)
#ADD_EMPTY_PASS = false

# RADIUS attribute dùng làm tham số "client" gửi tới privacyIDEA
#CLIENTATTRIBUTE =

# ══ Ánh xạ thông tin từ response privacyIDEA sang RADIUS attribute ══
[Mapping]
serial = privacyIDEA-Serial

[Mapping user]
group = Class
EOF

sudo chown root:freerad /etc/privacyidea/rlm_perl.ini
sudo chmod 0640 /etc/privacyidea/rlm_perl.ini

Bảng đầy đủ các key trong [Default]:

Thứ tự xác định tham số client gửi tới privacyIDEA: NAS-IP-Address → Packet-Src-IP-Address → attribute do CLIENTATTRIBUTE chỉ định (ghi đè cuối cùng).

Cài dictionary của NetKnights (cần cho attribute privacyIDEA-Serial):

Copysudo curl -fsSL -o /usr/share/freeradius/dictionary.netknights \
  https://raw.githubusercontent.com/privacyidea/FreeRADIUS/master/dictionary.netknights

# ⭐ PHẢI dùng ĐƯỜNG DẪN TUYỆT ĐỐI
echo '$INCLUDE /usr/share/freeradius/dictionary.netknights' \
  | sudo tee -a /etc/freeradius/3.0/dictionary

sudo freeradius -XC     # kiểm tra cấu hình, phải in "Configuration appears to be OK"

5.5. Cấu hình FreeRADIUS

5.5.1. Tạo instance module riêng (chỉ khi cài thủ công)

Copysudo tee /etc/freeradius/3.0/mods-available/privacyidea > /dev/null <<'EOF'
# Instance rlm_perl riêng cho privacyIDEA
perl perl-privacyidea {
    filename = /usr/share/privacyidea/freeradius/privacyidea_radius.pm

    # Chỉ định tường minh đường dẫn file ini
    config {
        configfile = "/etc/privacyidea/rlm_perl.ini"
    }
}
EOF

sudo ln -sf ../mods-available/privacyidea /etc/freeradius/3.0/mods-enabled/privacyidea
ls -l /etc/freeradius/3.0/mods-enabled/privacyidea

5.5.2. Sửa virtual server default (chỉ khi cài thủ công)

Copysudo cp /etc/freeradius/3.0/sites-available/default \
        /etc/freeradius/3.0/sites-available/default.bak-$(date +%F)

sudo nano /etc/freeradius/3.0/sites-available/default

Trong section authorize { } — thêm vào cuối, sau files:

Copy    # ── privacyIDEA ────────────────────────────────────────────
    update request {
        # Fallback cho tham số client khi không có NAS-IP-Address
        Packet-Src-IP-Address = "%{Packet-Src-IP-Address}"
    }
    perl-privacyidea
    if (ok || updated) {
        update control {
            Auth-Type := Perl
        }
    }

Trong section authenticate { } — thêm trước pap:

Copy    Auth-Type Perl {
        perl-privacyidea
    }

Section post-auth { } — giữ nguyên Post-Auth-Type Challenge mặc định:

5.5.3. inner-tunnel — chỉ khi dùng EAP

Nếu bạn dùng RADIUS thuần (VPN, SSH, firewall), bỏ qua mục này.

Nếu dùng 802.1X / PEAP / EAP-TTLS, lặp lại cấu hình trên trong /etc/freeradius/3.0/sites-available/inner-tunnel.

5.5.4. Khai báo RADIUS client

Copysudo nano /etc/freeradius/3.0/clients.conf

Copy# ══ Sinh secret ngẫu nhiên: openssl rand -base64 32 ═══════════

client lnx01 {
    ipaddr    = 192.168.10.31
    secret    = 'THAY_BANG_CHUOI_NGAU_NHIEN_32_KY_TU_1'
    shortname = lnx01
    nas_type  = other
    # ⚠️ pam_radius 2.0.1 (bản trong Ubuntu noble) KHÔNG gửi Message-Authenticator.
    #    Đặt "yes" ở đây = mọi request SSH bị vứt im lặng. Dùng "auto".
    require_message_authenticator = auto
}

client web01 {
    ipaddr    = 192.168.10.41
    secret    = 'THAY_BANG_CHUOI_NGAU_NHIEN_32_KY_TU_2'
    shortname = web01
    require_message_authenticator = auto
}

client vpn-gateway {
    ipaddr    = 192.168.10.1
    secret    = 'THAY_BANG_CHUOI_NGAU_NHIEN_32_KY_TU_3'
    shortname = vpn-gw
    nas_type  = other
    # Thiết bị mạng đã vá BlastRADIUS thì đặt "yes" được
    require_message_authenticator = auto
}

Sinh secret ngẫu nhiên:

Copyfor i in 1 2 3; do echo "Secret $i: $(openssl rand -base64 32)"; done

Siết quyền file — nó chứa toàn bộ shared secret:

Copysudo chown root:freerad /etc/freeradius/3.0/clients.conf
sudo chmod 0640 /etc/freeradius/3.0/clients.conf

5.6. Test FreeRADIUS

5.6.1. Chạy ở chế độ debug (bắt buộc làm trước)

Copysudo systemctl stop freeradius
sudo freeradius -X

Đọc kỹ output khi khởi động. Bạn phải thấy:

CopyModule: Linked to module rlm_perl
Module: Instantiating module "perl-privacyidea" from file /etc/freeradius/3.0/mods-enabled/privacyidea

Nếu có lỗi Perl, nó sẽ hiện ngay ở đây.

Từ terminal thứ hai, gửi request thử:

Copy# Cú pháp: radtest <user> <password> <server[:port]> <nas_port> <secret>
radtest hoangnv 'MatKhauAD123456' 127.0.0.1:1812 0 'testing123'

Kết quả mong đợi:

CopySent Access-Request Id 42 from 0.0.0.0:54321 to 127.0.0.1:1812 length 78
        User-Name = "hoangnv"
        User-Password = "MatKhauAD123456"
Received Access-Accept Id 42 from 127.0.0.1:1812 to 127.0.0.1:54321 length 20

Trong output của freeradius -X, tìm dòng chẩn đoán quan trọng nhất:

CopyConfig File /etc/privacyidea/rlm_perl.ini found!

Các dòng log hữu ích khác từ module: user sent to privacyidea:, realm sent to privacyidea:, client sent to privacyidea:, elapsed time for privacyidea call:.

5.6.2. Khởi động dịch vụ

Copysudo systemctl start freeradius
sudo systemctl enable freeradius
sudo systemctl status freeradius
sudo ss -ulnp | grep -E ':1812|:1813'

5.6.3. Test từ máy khác

Copy# Trên LNX01
sudo apt install -y freeradius-utils
radtest hoangnv 'MatKhauAD123456' 192.168.10.10:1812 0 'SECRET_CUA_LNX01'

Bắt gói để nhìn tận mắt:

Copysudo tcpdump -i any -n -vv 'udp port 1812'

Debug sâu hơn:

Copyecho "User-Name=hoangnv,User-Password=MatKhauAD123456" \
  | radclient -x 192.168.10.10:1812 auth 'SECRET_CUA_LNX01'

5.6.4. Script health-check cho monitoring

Copysudo tee /usr/local/bin/check-radius.sh > /dev/null <<'EOF'
#!/bin/bash
# Kiểm tra RADIUS server có PHẢN HỒI hay không.
# Lưu ý: Access-Reject vẫn chứng minh server sống VÀ shared secret đúng.
# Chỉ TIMEOUT mới là sự cố thật.
SERVER="${1:-127.0.0.1}"
SECRET="${2:-testing123}"

OUT=$(echo "User-Name=healthcheck,User-Password=000000" \
      | radclient -t 5 -r 1 "$SERVER:1812" auth "$SECRET" 2>&1)

if echo "$OUT" | grep -qE "Access-(Accept|Reject|Challenge)"; then
    echo "OK - RADIUS $SERVER dang phan hoi"; exit 0
else
    echo "CRITICAL - RADIUS $SERVER KHONG phan hoi: $OUT"; exit 2
fi
EOF

sudo chmod +x /usr/local/bin/check-radius.sh
/usr/local/bin/check-radius.sh

5.7. Lựa chọn thay thế: rlm_rest

privacyIDEA cũng hỗ trợ rlm_rest gọi thẳng endpoint /validate/radiuscheck. Nhưng hãy đọc bảng này trước khi chọn:

Tài liệu chính thức của privacyIDEA nói rõ: endpoint radiuscheck "hiện chưa implement đầy đủ tính năng của rlm_perl, ví dụ challenge-response và attribute mapping".

Kết luận: dùng rlm_perl trừ khi bạn chắc chắn chỉ dùng token nhập-một-lần (TOTP/HOTP/Yubikey) và không cần trả attribute về cho NAS.

Nếu vẫn muốn dùng rlm_rest:

Copysudo apt install -y freeradius-rest
sudo ln -sf ../mods-available/rest /etc/freeradius/3.0/mods-enabled/rest
sudo nano /etc/freeradius/3.0/mods-enabled/rest

Copyrest {
    tls {
        ca_path       = /etc/ssl/certs
        check_cert    = yes
        check_cert_cn = yes
    }

    connect_uri = "https://otp01.lab.local/"

    authenticate {
        uri      = "${..connect_uri}/validate/radiuscheck"
        method   = 'post'
        body     = 'post'
        data     = "user=%{urlquote:%{User-Name}}&pass=%{urlquote:%{User-Password}}"
        force_to = 'plain'
        tls      = ${..tls}
    }
}

5.8. Tóm tắt Phần 5

Các bước chính:

1. apt install freeradius freeradius-utils — không có gói freeradius-perl, rlm_perl.so nằm trong gói chính.
2. Cài 7 Perl module, nhớ liburi-encode-perl (tài liệu chính thức quên liệt kê).
3. Đặt module tại /usr/share/privacyidea/freeradius/privacyidea_radius.pm, phiên bản ≥ 3.4.3.
4. Đặt ini tại /etc/privacyidea/rlm_perl.ini, SSL_CHECK = true (chữ thường, đúng chữ "true").
5. Tạo instance perl perl-privacyidea riêng, không sửa file perl mặc định, không thêm perl_flags.
6. Sửa authorize{} và authenticate{} của site default; giữ nguyên Post-Auth-Type Challenge.
7. Khai client với secret riêng ≥ 24 ký tự và require_message_authenticator = auto (đặt yes sẽ chặn đứng SSH vì libpam-radius-auth 2.0.1 của noble không gửi attribute đó).
8. Test bằng freeradius -X, tìm dòng Config File ... found!.

Lỗi thường gặp:

PHẦN 6. CLIENT WINDOWS — RDP VÀ CONSOLE LOGON

6.1. Cách hoạt động

privacyIDEA Credential Provider thay thế màn hình đăng nhập của Windows, chèn thêm bước nhập OTP. Nó gọi thẳng REST API qua HTTPS — không qua RADIUS.

Phiên bản: 3.8.0 (26/02/2026) Hỗ trợ: Windows 10, 11, Server 2016/2019/2022 Tải: https://github.com/privacyidea/privacyidea-credential-provider/releases

6.2. ⚠️ Chuẩn bị — đọc trước khi cài

CopyPS> $pw = ConvertTo-SecureString (-join ((33..126) | Get-Random -Count 28 | %{[char]$_})) -AsPlainText -Force
PS> New-LocalUser -Name "brk-glass" -Password $pw -PasswordNeverExpires `
      -Description "Break-glass - KHONG dung hang ngay"
PS> Add-LocalGroupMember -Group "Administrators" -Member "brk-glass"

CopyPS> Import-Certificate -FilePath \\dc01\Software$\lab-ca.cer -CertStoreLocation Cert:\LocalMachine\Root

Kiểm tra kết nối từ client trước khi cài:

CopyPS> Test-NetConnection otp01.lab.local -Port 443
PS> Invoke-WebRequest -Uri "https://otp01.lab.local/" -UseBasicParsing | Select-Object StatusCode
# Không được có cảnh báo certificate nào

6.3. Cài đặt

Tải MSI 64-bit từ trang releases, chạy với quyền Administrator.

Trong wizard bạn cấu hình được các tuỳ chọn chính (hostname, path, filter, scenario). Các tuỳ chọn ít dùng hơn không có trong installer và phải đặt qua registry sau.

Cài thủ công (không dùng MSI) — hữu ích khi cần hiểu cơ chế hoặc tự động hoá:

CLSID chính thức:

1. Copy PrivacyIDEACredentialProvider.dll (và PrivacyIDEACredentialProviderFilter.dll) vào %windir%\System32
2. Tạo key HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers\{7BAF541E-...}, giá trị mặc định = PrivacyIDEACredentialProvider
3. Tại HKEY_CLASSES_ROOT\CLSID\{7BAF541E-...}\InprocServer32: giá trị mặc định = PrivacyIDEACredentialProvider.dll, thêm REG_SZ ThreadingModel = Apartment
4. Lặp lại với CLSID Filter tại ...\Authentication\Credential Provider Filters\

Repo có sẵn RegisterProvider.reg, RegisterFilter.reg và các file Unregister tương ứng.

6.4. Cấu hình qua Registry

CopyHKEY_LOCAL_MACHINE\SOFTWARE\Netknights GmbH\PrivacyIDEA-CP

Kiểu dữ liệu mặc định là REG_SZ cho tất cả (trừ vài ngoại lệ ghi rõ bên dưới). Giá trị boolean là chuỗi "1", không phải DWORD.

6.4.1. Kết nối

Failover — CP hỗ trợ server dự phòng native:

Khi đã chuyển sang fallback, CP dùng nó suốt phiên xác thực đó.

6.4.2. Loại trừ khỏi 2FA

6.4.3. ⭐ Filter và scenario (cpus_*) — phần nguy hiểm nhất

Định dạng giá trị: một chữ số 0-3 + một ký tự e hoặc d.

Ví dụ:

Hai ràng buộc nữa:

1. Các setting cpus_* chỉ có hiệu lực khi enable_filter = 1 (từ v3.2).
2. enable_filter là BẮT BUỘC cho RDP. Nếu không bật, Windows sẽ tự dùng System Credential Provider và bỏ qua privacyIDEA hoàn toàn — bạn sẽ đăng nhập được mà không bị hỏi OTP, tưởng là đã cấu hình sai ở đâu đó.

6.4.4. Trải nghiệm đăng nhập

Từ v3.7.0, thứ tự mặc định là: username → MFA → password.

CopyC:\ProgramData\Netknights GmbH\PrivacyIDEA Credential Provider\locales

6.4.5. Realm mapping

Ánh xạ chi tiết nằm ở sub-key ...\PrivacyIDEA-CP\realm-mapping, mỗi entry là REG_SZ với name = Windows domain, data = privacyIDEA realm.

Ví dụ: name LAB → data lab.

6.4.6. Offline OTP

Cho phép đăng nhập khi mất kết nối tới OTP server. Hỗ trợ token HOTP và FIDO.

Bật offline cho một token: WebUI → chọn token → xuống cuối trang → Application ⇒ Offline.

6.4.7. Script cấu hình mẫu — giai đoạn đầu (RDP-only)

CopyPS> $K = "HKLM:\SOFTWARE\Netknights GmbH\PrivacyIDEA-CP"
PS> New-Item -Path $K -Force | Out-Null

# ── Kết nối ────────────────────────────────────────────────────
PS> Set-ItemProperty -Path $K -Name "hostname"          -Type String -Value "otp01.lab.local"
PS> Set-ItemProperty -Path $K -Name "path"              -Type String -Value "/"
PS> Set-ItemProperty -Path $K -Name "fallback_hostname" -Type String -Value "otp02.lab.local"
PS> Set-ItemProperty -Path $K -Name "connect_timeout"   -Type String -Value "10000"
PS> Set-ItemProperty -Path $K -Name "receive_timeout"   -Type String -Value "10000"

# ── Filter + phạm vi: CHỈ RDP, vẫn giữ CP khác làm đường lui ────
PS> Set-ItemProperty -Path $K -Name "enable_filter" -Type String -Value "1"
PS> Set-ItemProperty -Path $K -Name "cpus_logon"    -Type String -Value "1d"
PS> Set-ItemProperty -Path $K -Name "cpus_unlock"   -Type String -Value "3d"
PS> Set-ItemProperty -Path $K -Name "cpus_credui"   -Type String -Value "3d"

# ── Break-glass ────────────────────────────────────────────────
PS> Set-ItemProperty -Path $K -Name "excluded_account" -Type String -Value "WINSRV02\brk-glass"

# ── Luồng đăng nhập: gửi mật khẩu AD để dùng otppin=userstore ───
PS> Set-ItemProperty -Path $K -Name "two_step_send_password" -Type String -Value "1"
PS> Set-ItemProperty -Path $K -Name "default_realm"          -Type String -Value "lab"

# ── Bật log để debug giai đoạn đầu ─────────────────────────────
PS> Set-ItemProperty -Path $K -Name "debug_log" -Type String -Value "1"

# ── Xem lại toàn bộ ────────────────────────────────────────────
PS> Get-ItemProperty -Path $K | Format-List

Ánh xạ realm (nếu tên domain khác tên realm):

CopyPS> New-Item -Path "$K\realm-mapping" -Force | Out-Null
PS> Set-ItemProperty -Path "$K\realm-mapping" -Name "LAB" -Type String -Value "lab"

6.5. Triển khai hàng loạt qua GPO

Cách 1 — truyền property qua command line:

Copymsiexec /i privacyIDEACredentialProvider.msi /qn ^
  HOSTNAME=otp01.lab.local ^
  PATH=/ ^
  FALLBACK_HOSTNAME=otp02.lab.local ^
  ENABLE_FILTER=1 ^
  CPUS_LOGON=1d ^
  CPUS_UNLOCK=3d ^
  CPUS_CREDUI=3d ^
  TWO_STEP_SEND_PASSWORD=1 ^
  DEFAULT_REALM=lab ^
  EXCLUDED_ACCOUNT=LAB\brk-glass ^
  DEBUG_LOG=1

Quy tắc đặt tên property: tên registry value viết HOA toàn bộ. Ví dụ two_step_send_password → TWO_STEP_SEND_PASSWORD.

Registry value KHÔNG có MSI property tương ứng — phải đặt sau khi cài, bằng GPO Registry Preference hoặc script:

• log_sensitive
• user_agent_hide_computer_name
• realm-mapping (là sub-key, không phải value)

Cách 2 — MSI Transform bằng Orca:

1. Mở MSI trong Orca → Transform → New Transform
2. Sửa bảng Property, thêm các property ở trên
3. Transform → Generate Transform → lưu privacyidea-cp.mst
4. GPMC → GPO mới → Computer Configuration → Policies → Software Settings → Software installation → New Package → chọn MSI → Advanced → tab Modifications → Add .mst

Cách 3 — GPO Registry Preference (linh hoạt nhất, đổi cấu hình không cần cài lại):

Computer Configuration → Preferences → Windows Settings → Registry → tạo các item trỏ vào HKLM\SOFTWARE\Netknights GmbH\PrivacyIDEA-CP.

6.6. Test

6.6.1. Test RDP

1. Từ WINCLI01: mstsc /v:192.168.10.22
2. Màn hình đăng nhập phải hiện tile của privacyIDEA
3. Nhập LAB\hoangnv + mật khẩu AD
4. Bước 2: nhập mã OTP 6 số
5. Đăng nhập thành công

Kiểm tra phía server:

Copy# Trên OTP01 — xem audit
curl -s -k -G $PI_URL/audit/ -H "PI-Authorization: $PI_TOKEN" \
  --data-urlencode "page_size=5" \
  | jq '.result.value.auditdata[] | {date, action, success, user, client, serial}'
# Lưu ý: cột IP nguồn trong audit tên là "client", KHÔNG phải "client_ip"

Kiểm tra phía client:

CopyPS> Get-Content C:\PICredentialProviderLog.txt -Tail 50
PS> Get-WinEvent -FilterHashtable @{LogName='Security'; ID=4624} -MaxEvents 3 | Format-List TimeCreated, Message

6.6.2. Test tài khoản break-glass

Đăng nhập bằng WINSRV02\brk-glass → phải không bị hỏi OTP.

6.6.3. Test console logon

Chỉ làm sau khi 6.6.1 và 6.6.2 đều pass, và bạn đã có quyền truy cập console qua hypervisor.

Copy# Chuyển từ "1d" (chỉ RDP) sang "0d" (cả console, vẫn giữ đường lui)
PS> Set-ItemProperty -Path "HKLM:\SOFTWARE\Netknights GmbH\PrivacyIDEA-CP" `
      -Name "cpus_logon" -Type String -Value "0d"
PS> Restart-Computer

6.6.4. Khôi phục khi bị khoá

Nếu không đăng nhập được:

Copy1. Thử tài khoản break-glass (đã exclude)
2. Nếu vẫn không được → Safe Mode:
   - Giữ Shift khi bấm Restart, hoặc từ hypervisor console bấm F8
   - Safe Mode vô hiệu hoá Credential Provider của bên thứ ba
   - Đăng nhập bằng local admin
3. Trong Safe Mode, tắt CP:
   reg add "HKLM\SOFTWARE\Netknights GmbH\PrivacyIDEA-CP" /v cpus_logon /t REG_SZ /d "3d" /f
   hoặc gỡ hẳn: Control Panel → Programs → Uninstall
4. Reboot

Vô hiệu hoá CP từ ngoài (mount ổ đĩa offline):

CopyThêm value "Disabled" (REG_DWORD) = 1 vào:
HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers\{7BAF541E-F8E0-4EDF-B69A-BD2771139E8E}

6.7. Tóm tắt Phần 6

Các bước chính:

1. Trước khi cài: tạo và test tài khoản break-glass, đảm bảo có console qua hypervisor, push CA nội bộ vào Trusted Root.
2. Cài MSI 3.8.0 trên máy đích RDP.
3. Registry tại HKLM\SOFTWARE\Netknights GmbH\PrivacyIDEA-CP (có dấu cách và chữ GmbH).
4. enable_filter = 1 — bắt buộc cho RDP.
5. Bắt đầu bằng cpus_logon = "1d" (chỉ RDP, giữ đường lui). Nhớ: 0 = cả hai, 3 = tắt, 3e là tổ hợp chết.
6. excluded_account đúng định dạng DOMAIN\username, và test nó.
7. two_step_send_password = 1 nếu dùng otppin=userstore.
8. Chỉ chuyển sang 0d (console) sau khi RDP đã chạy ổn.

Lỗi thường gặp:

PHẦN 7. CLIENT LINUX — SSH

Mục tiêu: bắt buộc nhập OTP khi SSH vào LNX01 (Ubuntu 24.04).

privacyIDEA cho Linux có hai phương án, và phương án thứ hai là điểm mạnh mà multiOTP không có:

Tài liệu này làm cả hai: A trước (phổ biến hơn), B sau (cho máy cần offline).

7.1. 🔴 ĐỌC TRƯỚC: quy tắc an toàn khi sửa PAM

Sửa sai PAM là cách nhanh nhất để khoá chính mình khỏi server.

Backup trước khi sửa bất cứ thứ gì:

Copy# Terminal A
BAK=/root/pam-backup-$(date +%F-%H%M)
sudo mkdir -p $BAK
sudo cp -a /etc/pam.d/sshd          $BAK/
sudo cp -a /etc/pam.d/common-auth   $BAK/
sudo cp -a /etc/ssh/sshd_config     $BAK/
sudo cp -a /etc/ssh/sshd_config.d/  $BAK/ 2>/dev/null
sudo ls -la $BAK
echo "Backup tai: $BAK"

7.2. Chuẩn bị LNX01

Copy# Đồng bộ thời gian
sudo apt install -y chrony
sudo timedatectl set-timezone Asia/Bangkok
echo "server 192.168.10.5 iburst prefer" | sudo tee -a /etc/chrony/chrony.conf
sudo systemctl restart chrony
timedatectl status | grep synchronized     # phải là: yes

# Công cụ test RADIUS
sudo apt install -y freeradius-utils

# ⭐ Test RADIUS TRƯỚC khi động vào PAM
radtest hoangnv 'MatKhauAD123456' 192.168.10.10:1812 0 'SECRET_CUA_LNX01'

7.3. Phương án A — PAM + RADIUS

7.3.1. Cài đặt

Copysudo apt install -y libpam-radius-auth

# Xác nhận đường dẫn thật
dpkg -L libpam-radius-auth | grep -E '\.so$|conf'
ls -l /usr/lib/x86_64-linux-gnu/security/pam_radius_auth.so

7.3.2. Cấu hình pam_radius_auth.conf

Copysudo nano /etc/pam_radius_auth.conf

Xoá hết dòng mẫu (127.0.0.1 secret 1) rồi đặt:

Copy# server[:port]        shared_secret                  timeout  [src_ip]
192.168.10.10:1812     SECRET_CUA_LNX01               10
192.168.10.11:1812     SECRET_CUA_LNX01_TREN_OTP02    10

Dòng thứ hai chính là failover — pam_radius tự chuyển sang OTP02 sau khi OTP01 timeout.

Siết quyền — file chứa shared secret:

Copysudo chown root:root /etc/pam_radius_auth.conf
sudo chmod 600 /etc/pam_radius_auth.conf
ls -l /etc/pam_radius_auth.conf     # -rw------- root root

7.3.3. Cấu hình OpenSSH

Copysudo nano /etc/ssh/sshd_config

Copy# ══ Bắt buộc cho OTP qua PAM ═══════════════════════════════════
UsePAM yes
KbdInteractiveAuthentication yes
# Ghi chú: OpenSSH < 8.7 dùng tên cũ "ChallengeResponseAuthentication".
# Ubuntu 24.04 có OpenSSH 9.6 -> dùng tên mới.

# ══ Chọn MỘT trong hai mô hình ═════════════════════════════════

# Mô hình 1: mật khẩu Unix + OTP
PasswordAuthentication no
AuthenticationMethods keyboard-interactive

# Mô hình 2: SSH key + OTP  ⭐ khuyến nghị cho production
# PubkeyAuthentication yes
# PasswordAuthentication no
# AuthenticationMethods publickey,keyboard-interactive

# ══ An toàn ════════════════════════════════════════════════════
PermitRootLogin prohibit-password
MaxAuthTries 3
LoginGraceTime 60

Copyls -la /etc/ssh/sshd_config.d/
sudo sshd -T | grep -iE 'usepam|kbdinteractive|authenticationmethods|passwordauth'

Kiểm tra cú pháp trước khi restart:

Copysudo sshd -t     # không in gì = OK

Chưa restart vội — sửa PAM trước.

7.3.4. 🔴 Cấu hình /etc/pam.d/sshd — phần dễ sai nhất

Mô hình 1 — mật khẩu Unix + OTP:

Copysudo nano /etc/pam.d/sshd

Copy#%PAM-1.0

# ══ YẾU TỐ 1: mật khẩu Unix/AD — PHẢI ĐẶT TRƯỚC ════════════════
@include common-auth

# ══ YẾU TỐ 2: OTP qua RADIUS ═══════════════════════════════════
# force_prompt : ⭐ BẮT BUỘC. Buộc hỏi lại thay vì tái dùng PAM_AUTHTOK
# retry=1      : chỉ cho nhập lại 1 lần
# prompt=OTP   : nhãn hiển thị "OTP: " thay vì "Password: "
# conf=<path>  : chỉ định file config nếu không dùng đường dẫn mặc định
auth       required     pam_radius_auth.so  force_prompt retry=1 prompt=OTP

# ── Phần còn lại giữ nguyên như bản gốc của Ubuntu ──
account    required     pam_nologin.so
@include common-account
session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so close
session    required     pam_loginuid.so
session    optional     pam_keyinit.so force revoke
@include common-session
session    optional     pam_motd.so  motd=/run/motd.dynamic
session    optional     pam_motd.so noupdate
session    optional     pam_mail.so standard noenv
session    required     pam_limits.so
session    required     pam_env.so
session    required     pam_env.so user_readenv=1 envfile=/etc/default/locale
session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so open
@include common-password

Mô hình 2 — SSH key + OTP (file gọn hơn nhiều):

Copy#%PAM-1.0

# Chỉ có OTP ở tầng auth; SSH key đã do sshd xử lý trước đó.
# Không có pam_unix phía sau nên không dính bẫy PAM_AUTHTOK,
# nhưng vẫn để force_prompt cho nhất quán.
auth       required     pam_radius_auth.so  force_prompt retry=1 prompt=OTP

# KHÔNG include common-auth (không hỏi mật khẩu Unix)

account    required     pam_nologin.so
@include common-account
session    required     pam_loginuid.so
@include common-session
session    optional     pam_motd.so  motd=/run/motd.dynamic
session    required     pam_limits.so
session    required     pam_env.so
@include common-password

Giải nghĩa control flag của PAM — phải hiểu để không tự hại mình:

7.3.5. Áp dụng và test

Copy# Terminal A (session cũ — GIỮ NGUYÊN)
sudo sshd -t                          # kiểm tra cú pháp lần cuối
sudo systemctl restart ssh            # Ubuntu 24.04: service tên là "ssh"
sudo systemctl status ssh

# Theo dõi log real-time ở Terminal A
sudo journalctl -u ssh -f

Copy# Terminal B (session MỚI) — test
ssh -v [email protected]

Kết quả mong đợi với Mô hình 1:

CopyPassword:                    ← mật khẩu Unix/AD trước (common-auth)
OTP: 4829173940              ← rồi tới PIN/mật khẩu + OTP
Welcome to Ubuntu 24.04 LTS ...
hoangnv@LNX01:~$

Với Mô hình 2:

Copydebug1: Offering public key: /home/user/.ssh/id_ed25519
debug1: Authentications that can continue: keyboard-interactive
OTP: 4829173940
hoangnv@LNX01:~$

Bắt gói để nhìn tận mắt:

Copysudo tcpdump -i any -n -vv 'udp port 1812'

Phải thấy một cặp Access-Request → Access-Accept. Chỉ thấy Access-Request mà không có phản hồi → firewall/routing. Không thấy gì → module PAM chưa được gọi.

7.3.6. Rollback khẩn cấp

Copy# Terminal A
sudo cp $BAK/sshd        /etc/pam.d/sshd
sudo cp $BAK/sshd_config /etc/ssh/sshd_config
sudo sshd -t && sudo systemctl restart ssh

Nếu đã mất cả Terminal A: vào console qua hypervisor → đăng nhập local → rollback như trên.

Nếu console cũng bị chặn (do lỡ sửa common-auth), boot vào rescue mode:

CopyGRUB → nhấn 'e' ở dòng kernel → thêm 'init=/bin/bash' vào cuối dòng linux → Ctrl+X
# mount -o remount,rw /
# cp /root/pam-backup-.../sshd /etc/pam.d/sshd
# cp /root/pam-backup-.../common-auth /etc/pam.d/common-auth
# sync; reboot -f

7.4. Phương án B — PAM module native (có Offline OTP)

Đây là điểm mạnh riêng của privacyIDEA. Module gọi thẳng REST API và có thể cache trước N mã HOTP xuống máy, cho phép đăng nhập ngay cả khi mất hoàn toàn kết nối tới OTP server.

Phù hợp cho: laptop, máy ở chi nhánh, server ở site có đường truyền không ổn định.

7.4.1. Cài đặt

Copy# Cách 1: nếu repo NetKnights có gói cho noble
apt-cache policy privacyidea-pam
sudo apt install -y privacyidea-pam

# Cách 2: cài thủ công từ GitHub
sudo apt install -y libpam-python python3-requests git
git clone https://github.com/privacyidea/pam_python.git /tmp/pi-pam
sudo cp /tmp/pi-pam/privacyidea_pam.py /lib/security/
sudo chmod 644 /lib/security/privacyidea_pam.py

7.4.2. Cấu hình

Copysudo nano /etc/pam.d/sshd

Copy#%PAM-1.0

# ══ YẾU TỐ 1 ═══════════════════════════════════════════════════
@include common-auth

# ══ YẾU TỐ 2: OTP qua REST API, có offline ═════════════════════
auth requisite pam_python.so /lib/security/privacyidea_pam.py \
     url=https://otp01.lab.local \
     realm=lab \
     prompt=[Ma OTP] \
     sqlfile=/etc/privacyidea/pam.sqlite

account    required     pam_nologin.so
@include common-account
session    required     pam_loginuid.so
@include common-session
@include common-password

Copysudo install -d -o root -g root -m 700 /etc/privacyidea
sudo touch /etc/privacyidea/pam.sqlite
sudo chmod 600 /etc/privacyidea/pam.sqlite

7.4.3. Bật offline cho token

1. WebUI → Tokens → chọn token của user
2. Xuống cuối trang → Application ⇒ Offline
3. Đặt số lượng mã cần cache (VD: 100)
4. Người dùng đăng nhập online một lần → mã được tải xuống pam.sqlite
5. Từ đó về sau, mất mạng vẫn đăng nhập được

7.5. Miễn trừ OTP cho automation

Script backup, Ansible, monitoring agent không thể nhập OTP tương tác. Cách xử lý đúng:

Copysudo nano /etc/ssh/sshd_config

Copy# Tài khoản automation: CHỈ SSH key, không qua PAM OTP
Match User ansible-svc,backup-svc,monitoring
    AuthenticationMethods publickey
    PubkeyAuthentication yes
    KbdInteractiveAuthentication no
    PasswordAuthentication no

# Người dùng thật từ subnet quản trị: bắt OTP đầy đủ
Match Address 192.168.10.0/24
    AuthenticationMethods publickey,keyboard-interactive

Copyfrom="192.168.10.99",command="/usr/local/bin/backup.sh",no-pty,no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-ed25519 AAAA...

7.6. Test đầy đủ

Copy# 1. RADIUS thông
radtest hoangnv 'MatKhauAD123456' 192.168.10.10:1812 0 'SECRET'
#    -> Access-Accept

# 2. Failover: dừng FreeRADIUS trên OTP01, test lại -> phải rơi sang OTP02
#    (trên OTP01: sudo systemctl stop freeradius)
time ssh [email protected]
#    -> vào được, chậm hơn ~10 giây (thời gian timeout server 1)

# 3. SSH mã đúng -> vào được
ssh [email protected]

# 4. SSH mã SAI -> bị từ chối
ssh [email protected]        # nhập 000000 -> Permission denied

# 5. Replay: đăng nhập xong, thử lại NGAY với cùng mã -> phải bị từ chối

# 6. Automation vào bằng key, không bị hỏi OTP
ssh -i ~/.ssh/ansible_ed25519 [email protected]

# 7. Console/local login vẫn hoạt động
#    (vào console qua hypervisor và đăng nhập)

# 8. sudo vẫn bình thường (ta không đụng /etc/pam.d/sudo)
sudo -l

# 9. Offline (nếu dùng Phương án B): ngắt mạng tới OTP01 rồi thử SSH
sudo iptables -A OUTPUT -d 192.168.10.10 -j DROP
ssh [email protected]        # phải vào được bằng mã offline
sudo iptables -D OUTPUT -d 192.168.10.10 -j DROP

7.7. Tóm tắt Phần 7

Các bước chính:

1. Giữ Terminal A mở, backup /etc/pam.d/sshd + sshd_config + common-auth.
2. chrony chạy, radtest ra Access-Accept trước khi động vào PAM.
3. Cài libpam-radius-auth, khai server chính + backup trong /etc/pam_radius_auth.conf, chmod 600.
4. sshd_config: UsePAM yes, KbdInteractiveAuthentication yes, AuthenticationMethods publickey,keyboard-interactive. Kiểm tra /etc/ssh/sshd_config.d/.
5. 🔴 /etc/pam.d/sshd: @include common-auth TRƯỚC, rồi auth required pam_radius_auth.so force_prompt retry=1 prompt=OTP.
6. sshd -t → systemctl restart ssh → test ở Terminal B.
7. Máy cần offline: dùng Phương án B với sqlfile=.
8. Automation: Match User + AuthenticationMethods publickey + siết authorized_keys.

Lỗi thường gặp:

PHẦN 8. TÍCH HỢP VÀO ỨNG DỤNG WEB

8.1. Chọn kiến trúc

Tài liệu này làm Kiến trúc A đầy đủ, và có mục 8.5 cho Kiến trúc C khi bạn cần app độc lập.

8.2. Hiểu API trước khi viết code

Endpoint xác thực:

Copycurl -k -X POST https://otp01.lab.local/validate/check \
     -d "user=hoangnv" -d "realm=lab" -d "pass=MatKhauAD123456"

Thành công:

Copy{
  "detail": {"message": "matching 1 tokens", "serial": "TOTP0001A2B3", "type": "totp"},
  "result": {"status": true, "value": true},
  "version": "privacyIDEA 3.13.3"
}

Thất bại:

Copy{
  "detail": {"message": "wrong otp value"},
  "result": {"status": true, "value": false},
  "version": "privacyIDEA 3.13.3"
}

Challenge-response — khi dùng token PUSH, SMS OTP hoặc Email OTP, lần gọi đầu trả về:

Copy{
  "detail": {
    "message": "Please enter otp from your email",
    "transaction_id": "12345678901234567890",
    "serial": "PIEM0001",
    "multi_challenge": [{"serial": "PIEM0001", "transaction_id": "1234...", "client_mode": "interactive"}]
  },
  "result": {"status": true, "value": false}
}

App phải hiển thị ô nhập mã, rồi gọi lại kèm transaction_id.

Các endpoint chính:

8.3. Bảo vệ endpoint /validate/check

Mặc định endpoint này mở cho mọi máy trong mạng. Bất kỳ ai cũng có thể dò user và brute-force. Ba lớp bảo vệ:

Lớp 1 — chặn theo IP nguồn bằng policy:

Cách đúng — dùng deny_access và gán client là dải cần chặn:

Copysudo pi-manage config policy create authz_deny_external authorization "authorized=deny_access"
# WebUI -> Config -> Policies -> authz_deny_external -> client = !192.168.10.0/24
#   Dấu '!' đứng trước nghĩa là "mọi IP NGOÀI dải này"

Kiểm chứng ngay sau khi tạo — từ một máy ngoài dải:

Copycurl -sk -X POST https://otp01.lab.local/validate/check \
  -d "user=hoangnv" -d "realm=lab" -d "pass=<matkhau><OTP>" | jq '.result'
# Phải bị từ chối

Lớp 2 — API key:

Copy# -u là BẮT BUỘC (tên định danh cho API key này)
sudo pi-manage api createtoken -r validate -u webapp01

Lệnh in ra một API key (hạn 365 ngày, không được lưu trên server — chép ngay). Sau đó tạo policy scope authorization yêu cầu API key. Web app gửi kèm key trong header.

Lớp 3 — rate limiting ở tầng Apache trên OTP01:

Copysudo apt install -y libapache2-mod-qos

# Directive giới hạn -> file conf GLOBAL
sudo tee /etc/apache2/conf-available/qos-validate.conf > /dev/null <<'EOF'
<IfModule mod_qos.c>
    # Tối đa 20 request mang biến validate_limit, mỗi IP, mỗi 60 giây
    QS_ClientEventLimitCount 20 60 validate_limit
</IfModule>
EOF
sudo a2enconf qos-validate

Chỉ SetEnvIf mới được đặt trong vhost:

Copysudo nano /etc/apache2/sites-available/privacyidea.conf

Copy    # Đánh dấu request cần đếm — dòng này ĐƯỢC phép nằm trong <VirtualHost>
    SetEnvIf Request_URI "^/validate/" validate_limit=1

Copysudo apache2ctl configtest && sudo systemctl reload apache2

8.4. Kiến trúc A — Flask gọi privacyIDEA

8.4.1. Chuẩn bị WEB01

Copysudo apt update
sudo apt install -y python3 python3-venv python3-pip nginx
sudo useradd -r -s /usr/sbin/nologin webapp
sudo mkdir -p /opt/otpapp && sudo chown webapp:webapp /opt/otpapp

cd /opt/otpapp
sudo -u webapp python3 -m venv venv
sudo -u webapp ./venv/bin/pip install flask requests gunicorn argon2-cffi

Cài CA nội bộ để verify TLS đúng cách:

Copysudo cp lab-ca.pem /usr/local/share/ca-certificates/lab-ca.crt
sudo update-ca-certificates
# Hoặc trỏ trực tiếp trong code: verify="/usr/local/share/ca-certificates/lab-ca.crt"

8.4.2. Client library

File pi_client.py đính kèm tài liệu này là một client hoàn chỉnh, đã được test thực tế với các kịch bản: mã đúng, mã sai, challenge-response, radiuscheck 204/400, enroll token, và server chết.

Phần cốt lõi — đọc kết quả cho đúng:

Copyresult = j.get("result", {})
detail = j.get("detail") or {}

# ⭐ result.value LÀ kết quả xác thực.
#    result.status chỉ nói "request được xử lý xong" — sai OTP vẫn trả status=true.
#    Nhầm hai trường này là lỗ hổng xác thực.
return AuthResult(
    ok=bool(result.get("value") is True),
    message=detail.get("message", ""),
    serial=detail.get("serial"),
    transaction_id=detail.get("transaction_id"),
    raw=j,
)

Ba chi tiết trong client đáng chú ý:

8.4.3. Ứng dụng Flask

Copy# /opt/otpapp/app.py
import os
import time
from functools import wraps

from flask import Flask, redirect, render_template_string, request, session, url_for
from pi_client import PrivacyIDEAClient, PrivacyIDEAError

app = Flask(__name__)
app.secret_key = os.environ["FLASK_SECRET"]
app.config.update(
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SAMESITE="Lax",
    SESSION_COOKIE_SECURE=True,          # yêu cầu HTTPS
    PERMANENT_SESSION_LIFETIME=1800,
)

pi = PrivacyIDEAClient(
    base_url=os.environ.get("PI_URL", "https://otp01.lab.local"),
    realm=os.environ.get("PI_REALM", "lab"),
    verify=os.environ.get("PI_CA", "/usr/local/share/ca-certificates/lab-ca.crt"),
    timeout=10,
)

LOGIN_HTML = """
<!doctype html><meta charset="utf-8"><title>Dang nhap</title>
<style>body{font-family:system-ui;max-width:380px;margin:80px auto}
input{width:100%;padding:10px;margin:6px 0;box-sizing:border-box}
button{width:100%;padding:10px;cursor:pointer}.err{color:#c00}
small{color:#666}</style>
<h2>LAB Internal Portal</h2>
{% if error %}<p class="err">{{error}}</p>{% endif %}
<form method="post">
  <input name="username" placeholder="Tai khoan" autofocus required>
  <input name="password" type="password"
         placeholder="Mat khau + ma OTP (vd: MatKhau123456)"
         autocomplete="current-password" required>
  <button>Dang nhap</button>
</form>
<p><small>Nhap mat khau roi noi lien 6 so OTP, khong co dau cach.</small></p>
"""

CHALLENGE_HTML = """
<!doctype html><meta charset="utf-8"><title>Xac thuc</title>
<style>body{font-family:system-ui;max-width:380px;margin:80px auto}
input{width:100%;padding:10px;margin:6px 0;box-sizing:border-box;
letter-spacing:.4em;text-align:center;font-size:20px}
button{width:100%;padding:10px}.err{color:#c00}</style>
<h2>Xac thuc buoc 2</h2>
<p>{{message}}</p>
{% if error %}<p class="err">{{error}}</p>{% endif %}
<form method="post">
  <input name="otp" inputmode="numeric" autocomplete="one-time-code" autofocus required>
  <button>Xac nhan</button>
</form>
"""


@app.route("/login", methods=["GET", "POST"])
def login():
    if request.method == "GET":
        return render_template_string(LOGIN_HTML, error=None)

    username = request.form.get("username", "").strip()
    password = request.form.get("password", "")

    try:
        res = pi.check(username, password)
    except PrivacyIDEAError:
        # ⭐ FAIL CLOSED: OTP server chết -> TỪ CHỐI, không cho vào.
        #    Fail open ở đây là vô hiệu hoá toàn bộ MFA chỉ bằng một
        #    cuộc tấn công DoS vào OTP server.
        app.logger.error("OTP server khong phan hoi cho user=%s", username)
        return render_template_string(
            LOGIN_HTML,
            error="He thong xac thuc tam thoi khong san sang. Vui long thu lai sau."), 503

    if res.is_challenge:
        session.clear()
        session["pending_user"] = username
        session["pending_tx"] = res.transaction_id
        session["pending_exp"] = int(time.time()) + 180
        return redirect(url_for("challenge"))

    if not res.ok:
        # Thông báo CHUNG CHUNG — không tiết lộ tài khoản nào tồn tại
        app.logger.warning("Dang nhap that bai user=%s ip=%s reason=%s",
                           username, request.remote_addr, res.message)
        return render_template_string(
            LOGIN_HTML, error="Tai khoan, mat khau hoac ma OTP khong dung"), 401

    # ⭐ Thành công: clear session cũ để chống session fixation
    session.clear()
    session["username"] = username
    session["token_serial"] = res.serial
    session.permanent = True
    app.logger.info("Dang nhap thanh cong user=%s serial=%s", username, res.serial)
    return redirect(url_for("dashboard"))


@app.route("/challenge", methods=["GET", "POST"])
def challenge():
    if not session.get("pending_tx") or session.get("pending_exp", 0) < time.time():
        session.clear()
        return redirect(url_for("login"))

    if request.method == "GET":
        return render_template_string(
            CHALLENGE_HTML, message="Nhap ma da duoc gui toi ban.", error=None)

    try:
        res = pi.check(session["pending_user"], request.form.get("otp", "").strip(),
                       transaction_id=session["pending_tx"])
    except PrivacyIDEAError:
        return render_template_string(
            CHALLENGE_HTML, message="", error="He thong tam thoi khong san sang"), 503

    if not res.ok:
        return render_template_string(
            CHALLENGE_HTML, message="", error="Ma khong dung"), 401

    user = session["pending_user"]
    session.clear()
    session["username"] = user
    session.permanent = True
    return redirect(url_for("dashboard"))


def login_required(f):
    @wraps(f)
    def wrapper(*a, **kw):
        if "username" not in session:
            return redirect(url_for("login"))
        return f(*a, **kw)
    return wrapper


@app.route("/")
@login_required
def dashboard():
    return (f"<h2>Xin chao {session['username']}</h2>"
            f"<p>Token: {session.get('token_serial', '-')}</p>"
            f"<a href='/logout'>Dang xuat</a>")


@app.route("/logout")
def logout():
    session.clear()
    return redirect(url_for("login"))

8.4.4. Deploy production

Copysudo mkdir -p /etc/otpapp
sudo bash -c 'cat > /etc/otpapp/secrets.env' <<EOF
FLASK_SECRET=$(openssl rand -hex 32)
PI_URL=https://otp01.lab.local
PI_REALM=lab
PI_CA=/usr/local/share/ca-certificates/lab-ca.crt
EOF
sudo chmod 600 /etc/otpapp/secrets.env
sudo chown root:root /etc/otpapp/secrets.env

Copysudo tee /etc/systemd/system/otpapp.service > /dev/null <<'EOF'
[Unit]
Description=OTP Demo Web App
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=webapp
Group=webapp
WorkingDirectory=/opt/otpapp
EnvironmentFile=/etc/otpapp/secrets.env
ExecStart=/opt/otpapp/venv/bin/gunicorn -w 4 -b 127.0.0.1:5000 --access-logfile - app:app
Restart=always
RestartSec=5

# Hardening
NoNewPrivileges=true
PrivateTmp=true
PrivateDevices=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
ReadWritePaths=/opt/otpapp

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now otpapp
sudo systemctl status otpapp

Nginx reverse proxy:

Copy# /etc/nginx/sites-available/otpapp
limit_req_zone $binary_remote_addr zone=login:10m rate=10r/m;

server {
    listen 443 ssl;
    http2 on;
    server_name portal.lab.local;

    ssl_certificate     /etc/ssl/certs/portal.lab.local.crt;
    ssl_certificate_key /etc/ssl/private/portal.lab.local.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;

    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Frame-Options DENY always;
    add_header X-Content-Type-Options nosniff always;
    add_header Referrer-Policy strict-origin-when-cross-origin always;

    location /login {
        limit_req zone=login burst=5 nodelay;    # ⭐ lớp chống brute-force thứ hai
        proxy_pass http://127.0.0.1:5000;
        include /etc/nginx/proxy_params;
    }

    location / {
        proxy_pass http://127.0.0.1:5000;
        include /etc/nginx/proxy_params;
    }
}

server {
    listen 80;
    server_name portal.lab.local;
    return 301 https://$host$request_uri;
}

Copysudo ln -s /etc/nginx/sites-available/otpapp /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

Copyfrom werkzeug.middleware.proxy_fix import ProxyFix
app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1)

8.5. Kiến trúc C — App tự quản lý TOTP bằng pyotp

Dùng khi app phải hoạt động độc lập hoàn toàn với OTP server.

Copypip install pyotp "qrcode[pil]" cryptography argon2-cffi

Bốn nguyên tắc phải làm đúng — đây là phần phân biệt code chạy được và code dùng được:

1. Mã hoá seed trong database. Seed plaintext trong DB = một lỗ hổng SQL injection là mất toàn bộ MFA.

Copyfrom cryptography.fernet import Fernet
fernet = Fernet(os.environ["OTP_FERNET_KEY"].encode())   # key lấy từ Vault/systemd, KHÔNG hardcode

def encrypt_secret(s: str) -> str: return fernet.encrypt(s.encode()).decode()
def decrypt_secret(e: str) -> str: return fernet.decrypt(e.encode()).decode()

2. Chống replay — điểm bị bỏ sót nhiều nhất.

pyotp.verify(code, valid_window=1) chấp nhận 3 mã trong 90 giây. Chỉ gọi hàm này thì kẻ tấn công nhìn trộm được mã vẫn dùng lại được trong cửa sổ đó. Cách chặn: lưu bước thời gian (counter) của mã vừa dùng, từ chối mọi mã có counter ≤ giá trị đã lưu.

Copyimport hmac, time, pyotp

TOTP_PERIOD, VALID_WINDOW = 30, 1

def verify_totp_no_replay(user_row, code: str) -> tuple[bool, str]:
    totp = pyotp.TOTP(decrypt_secret(user_row["totp_secret_enc"]),
                      digits=6, interval=TOTP_PERIOD)
    current = int(time.time()) // TOTP_PERIOD

    matched = None
    for off in range(-VALID_WINDOW, VALID_WINDOW + 1):
        c = current + off
        # compare_digest = so sánh constant-time, chống timing attack
        if hmac.compare_digest(totp.at(c * TOTP_PERIOD), code):
            matched = c
            break

    if matched is None:
        return False, "Ma OTP khong dung"
    if matched <= (user_row["last_totp_counter"] or 0):
        return False, "Ma nay da duoc su dung roi (replay)"

    db.execute("UPDATE users SET last_totp_counter=?, failed_attempts=0 WHERE id=?",
               (matched, user_row["id"]))
    db.commit()
    return True, "OK"

3. Rate limiting. Mã 6 số + window ±1 = 3/1.000.000 mỗi lần thử. Không giới hạn = brute-force khả thi. Khoá tài khoản sau 5 lần sai.

4. Không cấp session trước khi qua yếu tố 2. Sau khi verify mật khẩu, chỉ lưu pending_uid có thời hạn ngắn. Session thật chỉ được tạo sau khi OTP đúng, kèm session.clear() để chống session fixation.

Enroll:

Copysecret = pyotp.random_base32()      # 32 ký tự Base32 = 160 bit, đúng khuyến nghị RFC
# LƯU secret (đã mã hoá) TRƯỚC, rồi mới render QR
db.execute("UPDATE users SET totp_secret_enc=? WHERE id=?", (encrypt_secret(secret), uid))

uri = pyotp.TOTP(secret, digits=6, interval=30)\
           .provisioning_uri(name=username, issuer_name="LAB Internal Portal")
img = qrcode.make(uri)              # render TẠI CHỖ — tuyệt đối không dùng dịch vụ QR online

8.6. Thư viện tương đương cho ngôn ngữ khác

8.7. Test

Copy# ── 1. Test API trực tiếp ──────────────────────────────────────
curl -s -k -X POST https://otp01.lab.local/validate/check \
  -d "user=hoangnv" -d "realm=lab" -d "pass=MatKhauAD123456" \
  | jq '{ket_qua: .result.value, ly_do: .detail.message, token: .detail.serial}'

# ── 2. Mã sai phải bị từ chối ──────────────────────────────────
curl -s -k -X POST https://otp01.lab.local/validate/check \
  -d "user=hoangnv" -d "realm=lab" -d "pass=MatKhauAD000000" \
  | jq '.result.value'      # -> false

# ── 3. Replay: dùng lại mã vừa dùng -> false ───────────────────

# ── 4. Endpoint RADIUS ─────────────────────────────────────────
curl -s -k -o /dev/null -w "HTTP %{http_code}\n" -X POST \
  https://otp01.lab.local/validate/radiuscheck \
  -d "user=hoangnv" -d "realm=lab" -d "pass=MatKhauAD123456"
# 204 = OK, 400 = fail

# ── 5. Test client library ─────────────────────────────────────
cd /opt/otpapp && ./venv/bin/python -c "
from pi_client import PrivacyIDEAClient
pi = PrivacyIDEAClient('https://otp01.lab.local', realm='lab',
                       verify='/usr/local/share/ca-certificates/lab-ca.crt')
r = pi.check('hoangnv', 'MatKhauAD123456')
print('ok=', r.ok, '| serial=', r.serial, '| msg=', r.message)
"

# ── 6. Test fail-closed: dừng Apache trên OTP01 rồi thử login ──
#    -> app phải trả HTTP 503, KHÔNG được cho vào

Kịch bản test đã chạy thực tế khi soạn tài liệu (dùng mock server, xác nhận logic parse response):

Copyma dung   -> True TOTP0001 totp
ma sai    -> False | wrong otp value | challenge: False
challenge -> False | tx: 999 | is_challenge: True
radiuscheck GOOD -> True
radiuscheck BAD  -> False
enroll -> TOTP0001 otpauth://totp/x?secret=ABC verify
server chet -> raise dung: PrivacyIDEAError

8.8. Tóm tắt Phần 8

Các bước chính:

1. Chọn Kiến trúc A (gọi REST API) — người dùng chỉ cầm một token cho tất cả.
2. 🔴 Đọc result.value, không đọc result.status. Nhầm là lỗ hổng xác thực.
3. Bảo vệ /validate/check: giới hạn IP bằng policy + API key + rate limit ở Apache.
4. Client: không retry POST xác thực (gây replay), verify=True với CA nội bộ, fail closed khi server chết.
5. Không cấp session trước khi qua yếu tố 2; session.clear() sau khi thành công.
6. Deploy: venv (PEP 668), gunicorn + systemd hardening, nginx TLS + limit_req.
7. Nếu dùng Kiến trúc C: mã hoá seed, chống replay bằng counter, rate limit, sinh secret một lần.

Lỗi thường gặp:

PHẦN 9. BACKUP, DR VÀ HA

9.1. 🔴 Hiểu đúng rủi ro trước khi làm

9.2. Cái gì cần backup

9.3. Backup thủ công — hiểu cơ chế

Copy# ── Backup chuẩn, CÓ enckey ────────────────────────────────────
sudo pi-manage backup create -e

# Mặc định ghi ra: /var/lib/privacyidea/backup/privacyidea-backup-YYYYmmdd-HHMM.tgz
sudo ls -lh /var/lib/privacyidea/backup/

# ── Backup kèm cả cấu hình FreeRADIUS ──────────────────────────
sudo pi-manage backup create -e \
     -d /var/backups/privacyidea \
     -c /etc/privacyidea/ \
     -r /etc/freeradius/3.0

Nội dung file .tgz: dump database (mysqldump --single-transaction --skip-lock-tables) + toàn bộ /etc/privacyidea.

Ba hành vi cần biết:

1. File backup được chmod 0600 tự động.
2. Script tạo tạm /etc/privacyidea/mysql.cnf chứa credential DB (để không lộ mật khẩu trên command line), rồi xoá.
3. Nếu mysqldump fail, script xoá dump dở và exit 2 — không đóng gói backup lỗi. Hành vi này tốt, nhưng nghĩa là bạn phải kiểm tra exit code.

9.4. Script backup tự động

Copysudo tee /usr/local/bin/backup-privacyidea.sh > /dev/null <<'SCRIPT'
#!/bin/bash
#
# /usr/local/bin/backup-privacyidea.sh
# Backup privacyIDEA -> mã hoá GPG -> nhân bản ra 2 nơi -> dọn bản cũ
# Chạy hằng ngày 01:00 qua cron
#
set -euo pipefail

BAK_DIR="/var/backups/privacyidea"
REMOTE="[email protected]:/srv/backup/privacyidea/"
STANDBY="[email protected]:/var/backups/privacyidea/"
GPG_RECIPIENT="[email protected]"     # public key GPG của bộ phận IT
RETAIN_DAYS=30
STAMP=$(date +%Y%m%d-%H%M%S)
LOG="/var/log/privacyidea-backup.log"

log() { echo "$(date '+%F %T')  $*" | tee -a "$LOG"; }
fail() { log "!!! THAT BAI: $*"; logger -p daemon.err -t pi-backup "$*"; exit 1; }

log "=== BAT DAU BACKUP ==="
mkdir -p "$BAK_DIR"

# ── 1. Tạo backup CÓ enckey ────────────────────────────────────
#    Cờ -e là bắt buộc. Không có nó, backup vô dụng khi restore.
if ! pi-manage backup create -e -d "$BAK_DIR" \
       -c /etc/privacyidea/ -r /etc/freeradius/3.0 >>"$LOG" 2>&1; then
    fail "pi-manage backup create loi"
fi

RAW=$(find "$BAK_DIR" -maxdepth 1 -name 'privacyidea-backup-*.tgz' -newermt '-5 minutes' \
      | sort | tail -1)
[[ -n "$RAW" ]] || fail "Khong tim thay file backup vua tao"
log "Da tao: $RAW ($(du -h "$RAW" | cut -f1))"

# ── 2. Kiểm tra file backup THỰC SỰ chứa enckey ────────────────
#    Đây là bước xác minh quan trọng nhất của script.
if ! tar tzf "$RAW" | grep -q 'enckey'; then
    fail "BACKUP KHONG CHUA ENCKEY - VO DUNG KHI RESTORE. Kiem tra co -e"
fi
log "Xac nhan: backup CO chua enckey"

# ── 3. Mã hoá bằng GPG public key ──────────────────────────────
#    Chỉ người giữ private key mới mở được -> server bị chiếm
#    cũng không giải mã được backup cũ.
ENC="$BAK_DIR/privacyidea-$STAMP.tgz.gpg"
gpg --batch --yes --trust-model always \
    --encrypt --recipient "$GPG_RECIPIENT" \
    --output "$ENC" "$RAW" || fail "GPG ma hoa loi"
shred -u "$RAW"                      # xoá bản chưa mã hoá
chmod 600 "$ENC"
log "Da ma hoa: $ENC"

# ── 4. Checksum để kiểm tra toàn vẹn khi restore ───────────────
sha256sum "$ENC" > "$ENC.sha256"
log "SHA256: $(cut -d' ' -f1 < "$ENC.sha256")"

# ── 5. Nhân bản ra 2 nơi khác (quy tắc 3-2-1) ──────────────────
for DEST in "$REMOTE" "$STANDBY"; do
    if rsync -a --timeout=60 "$ENC" "$ENC.sha256" "$DEST" 2>>"$LOG"; then
        log "Da copy sang $DEST"
    else
        log "CANH BAO: khong copy duoc sang $DEST"
        logger -p daemon.warning -t pi-backup "Khong copy duoc backup sang $DEST"
    fi
done

# ── 6. Dọn bản cũ ──────────────────────────────────────────────
find "$BAK_DIR" -name 'privacyidea-*.tgz.gpg*' -mtime +$RETAIN_DAYS -print -delete \
    | while read -r f; do log "Xoa ban cu: $f"; done

log "=== BACKUP THANH CONG ==="
SCRIPT

sudo chmod 700 /usr/local/bin/backup-privacyidea.sh

Tạo khoá GPG cho backup (chạy trên một máy khác, không phải OTP01):

Copy# Trên máy quản trị của bạn
gpg --full-generate-key
# Chọn: RSA and RSA, 4096 bit, không hết hạn
# Real name: OTP Backup
# Email: [email protected]

# Export PUBLIC key mang sang OTP01
gpg --armor --export [email protected] > /tmp/otp-backup-pub.asc

# ⭐ Export PRIVATE key và cất vào KÉT / password manager của công ty.
#    Đây là thứ duy nhất mở được backup.
gpg --armor --export-secret-keys [email protected] > otp-backup-private.asc

Copy# Trên OTP01 — CHỈ import public key
sudo gpg --import /tmp/otp-backup-pub.asc
sudo gpg --list-keys

Đăng ký cron:

Copyecho '0 1 * * * root /usr/local/bin/backup-privacyidea.sh >/dev/null 2>&1' \
  | sudo tee /etc/cron.d/privacyidea-backup

# Chạy thử ngay
sudo /usr/local/bin/backup-privacyidea.sh
sudo tail -20 /var/log/privacyidea-backup.log

Giám sát backup — một backup thất bại âm thầm còn tệ hơn không có backup:

Copysudo tee /usr/local/bin/check-backup-age.sh > /dev/null <<'EOF'
#!/bin/bash
# Cảnh báo nếu backup mới nhất cũ hơn 26 giờ
LATEST=$(find /var/backups/privacyidea -name '*.tgz.gpg' -mtime -1.1 | head -1)
if [[ -z "$LATEST" ]]; then
    logger -p daemon.crit -t pi-backup "KHONG CO BACKUP trong 26 gio qua"
    echo "CRITICAL: khong co backup moi"; exit 2
fi
echo "OK: backup moi nhat $LATEST"; exit 0
EOF
sudo chmod +x /usr/local/bin/check-backup-age.sh
echo '0 8 * * * root /usr/local/bin/check-backup-age.sh' | sudo tee -a /etc/cron.d/privacyidea-backup

9.5. Quy trình restore — viết ra và diễn tập

Kịch bản: OTP01 hỏng hoàn toàn, dựng lại từ backup.

Copy# ══ B1: Dựng Ubuntu 24.04 mới, ĐẶT ĐÚNG hostname và IP CŨ ══════
#    Đổi IP nghĩa là phải sửa cấu hình ở TẤT CẢ client.
sudo hostnamectl set-hostname otp01.lab.local
# ... cấu hình netplan như mục 1.5.2 ...

# ══ B2: Đồng bộ thời gian TRƯỚC KHI làm gì tiếp ════════════════
sudo apt install -y chrony
sudo chronyc makestep
chronyc tracking          # PHẢI đồng bộ trước khi restore

# ══ B3: Cài privacyIDEA (chưa cấu hình gì) ═════════════════════
#    ... theo Phần 2.1 - 2.2 ...
sudo apt install -y privacyidea-apache2 freeradius freeradius-utils

# ══ B4: KIỂM TRA TOÀN VẸN file backup TRƯỚC khi dùng ═══════════
cd /var/backups/privacyidea
sha256sum -c privacyidea-20260801-010000.tgz.gpg.sha256 \
  || { echo "CHECKSUM SAI - FILE BACKUP HONG"; exit 1; }

# ══ B5: Giải mã (cần PRIVATE key GPG từ két) ══════════════════
gpg --import /media/usb/otp-backup-private.asc
gpg --decrypt --output privacyidea-restore.tgz privacyidea-20260801-010000.tgz.gpg

# ══ B6: XÁC NHẬN backup có enckey trước khi restore ═══════════
tar tzf privacyidea-restore.tgz | grep enckey \
  || { echo "BACKUP KHONG CO ENCKEY - KHONG THE KHOI PHUC SEED"; exit 1; }

# ══ B7: Restore ═══════════════════════════════════════════════
#    ⚠️ Lệnh này giải nén thẳng ra / — KHÔNG chọn được thư mục đích.
#    Chỉ chạy trên máy sạch.
sudo pi-manage backup restore privacyidea-restore.tgz

#    Nếu DB URI trên máy mới khác với trong backup:
#    sudo pi-manage backup restore privacyidea-restore.tgz --keep-db-uri

# ══ B8: Khôi phục dịch vụ ═════════════════════════════════════
sudo systemctl restart apache2 mariadb freeradius
sudo ufw allow 443/tcp && sudo ufw allow 1812/udp && sudo ufw allow 1813/udp

# ══ B9: VERIFY — bước không được bỏ qua ═══════════════════════
sudo pi-manage config realm list          # đủ realm?
sudo pi-manage config resolver list       # đủ resolver?
sudo pi-manage admin list                 # đủ admin?
sudo mysql pi -e "SELECT COUNT(*) AS so_token FROM token;"

Verify bằng một token thật — đây mới là bằng chứng restore thành công:

Copy# Trên OTP01
curl -s -k -X POST https://otp01.lab.local/validate/check \
  -d "user=hoangnv" -d "realm=lab" -d "pass=<mat-khau><OTP-that-tu-dien-thoai>" \
  | jq '.result.value'
# PHẢI là true. Nếu false -> enckey không đúng -> seed không giải mã được.

# Từ LNX01
radtest hoangnv '<mat-khau><OTP>' 192.168.10.10:1812 0 'SECRET'
# Access-Accept

# Từ WINSRV02: RDP vào -> phải hỏi OTP và đăng nhập được

Chỉ tiêu RTO/RPO:

9.6. Node thứ hai (OTP02) — HA và failover

privacyIDEA hỗ trợ nhiều app node dùng chung một database. Đây là điểm hơn rõ rệt so với multiOTP (nơi HA là tính năng trả phí).

9.6.1. Kiến trúc

9.6.2. Dựng OTP02

Copy# Trên OTP02 — cài y hệt OTP01
sudo apt install -y privacyidea-apache2 freeradius freeradius-utils

# ⭐ Copy các file KHOÁ từ OTP01 — bắt buộc phải GIỐNG HỆT.
#    Khác enckey = không giải mã được seed trong DB chung.
sudo scp [email protected]:/etc/privacyidea/enckey      /etc/privacyidea/
sudo scp [email protected]:/etc/privacyidea/private.pem /etc/privacyidea/
sudo scp [email protected]:/etc/privacyidea/public.pem  /etc/privacyidea/
sudo scp [email protected]:/etc/privacyidea/pi.cfg      /etc/privacyidea/

sudo chown privacyidea:root /etc/privacyidea/{enckey,private.pem,public.pem,pi.cfg}
sudo chmod 600 /etc/privacyidea/enckey /etc/privacyidea/private.pem
sudo chmod 640 /etc/privacyidea/pi.cfg

Sửa pi.cfg trên OTP02 trỏ vào DB chung:

CopySQLALCHEMY_DATABASE_URI = 'mysql+pymysql://pi:<mat-khau>@192.168.10.50/pi?charset=utf8'
PI_BASE_URL = 'https://otp02.lab.local'

# ⭐ Bắt buộc khi dùng Galera Cluster
PI_DB_SAFE_STORE = True

Copysudo systemctl restart apache2
curl -s -k -X POST https://otp02.lab.local/auth \
  -d "username=admin" -d "password=<pw>" | jq '.result.value.role'
# -> "admin"

Copy cấu hình FreeRADIUS:

Copysudo scp [email protected]:/etc/privacyidea/rlm_perl.ini /etc/privacyidea/
sudo scp -r [email protected]:/etc/freeradius/3.0/clients.conf /etc/freeradius/3.0/
sudo scp [email protected]:/etc/freeradius/3.0/mods-available/privacyidea /etc/freeradius/3.0/mods-available/
sudo ln -sf ../mods-available/privacyidea /etc/freeradius/3.0/mods-enabled/privacyidea
# ... sửa sites-available/default như mục 5.5.2 ...
sudo systemctl restart freeradius

Sửa URL trong rlm_perl.ini trên OTP02 trỏ về chính nó:

CopyURL = https://otp02.lab.local/validate/check

9.6.3. Nếu không muốn HA đầy đủ — chế độ warm standby

Đơn giản hơn nhiều: OTP02 cài sẵn phần mềm nhưng dùng DB riêng, đồng bộ định kỳ từ OTP01.

Copysudo tee /usr/local/bin/sync-to-otp02.sh > /dev/null <<'EOF'
#!/bin/bash
# Đồng bộ OTP01 -> OTP02 mỗi 15 phút (một chiều)
set -euo pipefail
STANDBY="[email protected]"

# 1. Dump DB rồi nạp sang standby
mysqldump --single-transaction --skip-lock-tables pi \
  | ssh "$STANDBY" "mysql pi" || { logger -t pi-sync "Sync DB THAT BAI"; exit 1; }

# 2. Đồng bộ các file khoá (chỉ khi thay đổi)
rsync -a /etc/privacyidea/{enckey,private.pem,public.pem} "$STANDBY:/etc/privacyidea/"

logger -t pi-sync "Da dong bo sang OTP02"
EOF
sudo chmod 700 /usr/local/bin/sync-to-otp02.sh
echo '*/15 * * * * root /usr/local/bin/sync-to-otp02.sh >/dev/null 2>&1' \
  | sudo tee /etc/cron.d/pi-sync

9.6.4. Cấu hình failover ở từng loại client

Chuẩn bị DNS để đổi nhanh:

Copyotp.lab.local.   60   IN   A   192.168.10.10

Đặt TTL = 60 giây ngay từ đầu, và cấu hình mọi client trỏ vào otp.lab.local chứ không phải IP. Khi sự cố, chỉ cần đổi một bản ghi DNS.

9.7. Kịch bản sự cố

Kịch bản 1 — OTP01 chết lúc 9h sáng

Copy1. Xác nhận:  curl -sk https://otp01.lab.local/  -> không phản hồi

2. Các client CÓ failover tự chuyển sau ~10 giây, không cần làm gì:
   · Linux pam_radius   -> sang OTP02
   · Windows CP         -> sang fallback_hostname
   · Web app            -> sang URL thứ 2 trong danh sách
   · Thiết bị mạng      -> sang RADIUS server thứ 2

3. Với client CHƯA cấu hình failover:
   · Đổi bản ghi DNS otp.lab.local -> 192.168.10.11 (TTL 60s đã đặt sẵn)

4. Thông báo người dùng: "MFA đang chạy trên hệ thống dự phòng, có thể chậm hơn"

5. Khôi phục OTP01 theo quy trình 9.5

6. ⚠️ Sau khi OTP01 sống lại: nếu dùng warm standby, phải SYNC NGƯỢC
   từ OTP02 về OTP01 — nếu không sẽ mất token enroll trong lúc sự cố

Kịch bản 2 — Cả OTP01 và OTP02 đều chết

Copy1. Dùng đường vào BREAK-GLASS đã chuẩn bị:
   · Windows : tài khoản trong excluded_account
   · Linux   : SSH key admin + Match User bỏ qua OTP, hoặc console qua IPMI
   · Web app : không có -> đây là lý do phải fail closed một cách CÓ CHỦ Ý

2. Nếu cần mở khẩn cấp cho nhiều người:
   · Windows : GPO đẩy registry cpus_logon="3d"   (3 = TẮT HOÀN TOÀN)
               ⚠️ KHÔNG phải 0 — giá trị 0 nghĩa là BẬT cho cả remote lẫn local
   · Linux   : comment dòng pam_radius trong /etc/pam.d/sshd (qua Ansible/console)

3. Khôi phục từ backup off-site theo 9.5

4. Sau sự cố: viết post-mortem, ghi lại thời gian THỰC TẾ của từng bước
   để hiệu chỉnh lại RTO

Kịch bản 3 — Người dùng mất/hỏng/đổi điện thoại

Đây là việc xảy ra hằng tuần, nên quy trình phải rõ ràng và có bước xác minh danh tính.

CopyB1. XÁC MINH NGƯỜI YÊU CẦU
    🔴 Đây chính là lỗ hổng social engineering phổ biến nhất của MỌI hệ thống MFA.
    Kẻ tấn công gọi helpdesk, nói "tôi mất điện thoại", và được cấp token mới.

    · Gọi lại theo số điện thoại có trong hệ thống HR (KHÔNG gọi số họ cung cấp)
    · Hoặc: quản lý trực tiếp xác nhận qua kênh riêng
    · Hoặc: gặp mặt trực tiếp, xem thẻ nhân viên
    · Ghi lại: ai yêu cầu, ai xác minh, lúc mấy giờ, bằng cách nào

B2. VÔ HIỆU HOÁ TOKEN CŨ NGAY
    Điện thoại có thể đang trong tay người khác.
    WebUI -> Tokens -> chọn token -> Disable (hoặc Delete)
    Hoặc API:
      curl -k -X POST $PI_URL/token/disable -H "PI-Authorization: $PI_TOKEN" \
           -d "serial=TOTP0001A2B3"

B3. CẤP TOKEN MỚI
    · Ưu tiên: gửi link self-service để user tự enroll (seed không qua tay admin)
    · Hoặc admin enroll qua WebUI khi user có mặt

B4. Ghi log vào hệ thống ticket

B5. Nếu NGHI NGỜ điện thoại bị đánh cắp có chủ đích:
    · Đổi mật khẩu AD của user
    · Kiểm tra audit log 30 ngày gần nhất tìm hoạt động bất thường:
      curl -sk -G $PI_URL/audit/ -H "PI-Authorization: $PI_TOKEN" \
        --data-urlencode "user=hoangnv" --data-urlencode "page_size=100" | jq
    · Thu hồi mọi session đang hoạt động

Bốn cách giảm tải cho helpdesk:

9.8. Tài khoản break-glass

Copy# ══ Linux ══════════════════════════════════════════════════════
sudo useradd -m -s /bin/bash brk-glass
sudo usermod -aG sudo brk-glass
sudo -u brk-glass ssh-keygen -t ed25519 -f /home/brk-glass/.ssh/id_ed25519 -C "break-glass"
# Cất private key vào USB trong két, xoá khỏi server

Copy# /etc/ssh/sshd_config
Match User brk-glass
    AuthenticationMethods publickey
    PubkeyAuthentication yes
    KbdInteractiveAuthentication no

Copy# ══ Windows ════════════════════════════════════════════════════
PS> $pw = ConvertTo-SecureString (-join ((33..126) | Get-Random -Count 28 | %{[char]$_})) -AsPlainText -Force
PS> New-LocalUser -Name "brk-glass" -Password $pw -PasswordNeverExpires
PS> Add-LocalGroupMember -Group "Administrators" -Member "brk-glass"
PS> Set-ItemProperty -Path "HKLM:\SOFTWARE\Netknights GmbH\PrivacyIDEA-CP" `
      -Name "excluded_account" -Type String -Value "$env:COMPUTERNAME\brk-glass"

Cảnh báo khi tài khoản này được dùng:

Copy# Linux — gửi cảnh báo qua syslog/SIEM khi brk-glass đăng nhập
sudo tee /etc/pam.d/sshd.d-brkglass-alert > /dev/null <<'EOF'
session optional pam_exec.so /usr/local/bin/alert-breakglass.sh
EOF

sudo tee /usr/local/bin/alert-breakglass.sh > /dev/null <<'EOF'
#!/bin/bash
[[ "$PAM_USER" == "brk-glass" ]] && \
  logger -p auth.crit -t breakglass "CANH BAO: tai khoan break-glass dang nhap tu $PAM_RHOST"
exit 0
EOF
sudo chmod +x /usr/local/bin/alert-breakglass.sh

Checklist quản lý break-glass:

• Mật khẩu ≥ 25 ký tự ngẫu nhiên, niêm phong trong két hoặc password manager có audit trail
• Ít nhất 2 người biết cách truy cập (tránh bus factor = 1)
• Alert tự động khi tài khoản được sử dụng, gửi tới điện thoại admin
• Đổi mật khẩu sau mỗi lần dùng
• Kiểm tra định kỳ 3 tháng/lần xem có còn đăng nhập được không
• Ghi vào runbook DR: ai giữ, giữ ở đâu, dùng thế nào

9.9. Tóm tắt Phần 9

Các bước chính:

1. 🔴 pi-manage backup create PHẢI có cờ -e — mặc định không kèm enckey.
2. Script backup tự kiểm tra file backup có chứa enckey không, và fail nếu không có.
3. Mã hoá bằng GPG public key — private key cất ở nơi khác, server bị chiếm không giải mã được backup cũ.
4. Nhân bản ra ≥ 2 nơi (quy tắc 3-2-1), có checksum, có giám sát tuổi backup.
5. Restore giải nén thẳng ra / — chỉ chạy trên máy sạch.
6. Verify restore bằng một token thật, không chỉ đếm số dòng trong DB.
7. Dựng OTP02 dùng chung DB (HA thật) hoặc warm standby (đơn giản hơn). Copy enckey giống hệt.
8. Cấu hình failover ở từng loại client, và đặt DNS TTL = 60 giây.
9. Quy trình reset token bắt buộc có bước xác minh danh tính.
10. Break-glass: có, test, alert, đổi mật khẩu sau mỗi lần dùng.

Lỗi thường gặp:

PHẦN 10. TROUBLESHOOTING VÀ PHỤ LỤC

10.1. Phương pháp debug — đi từ trong ra ngoài

Khi có sự cố, đừng đoán. Kiểm tra theo đúng thứ tự này, mỗi tầng loại trừ một nhóm nguyên nhân:

CopyTầng 1: THỜI GIAN        chronyc tracking                      ← luôn kiểm tra đầu tiên
   ↓
Tầng 2: ENGINE OTP       curl /validate/check ngay trên OTP01
   ↓
Tầng 3: MẠNG             tcpdump / ss / ufw status
   ↓
Tầng 4: RADIUS           freeradius -X + radtest
   ↓
Tầng 5: CLIENT           PAM / Credential Provider / web app

Bộ lệnh chẩn đoán nhanh trên OTP01:

Copysudo tee /usr/local/bin/pi-diag.sh > /dev/null <<'EOF'
#!/bin/bash
echo "═══ 1. THOI GIAN ══════════════════════════════════════"
timedatectl status | grep -E 'Local time|synchronized|Time zone'
chronyc tracking | grep -E 'System time|Leap status'

echo; echo "═══ 2. DICH VU ════════════════════════════════════════"
for s in apache2 mariadb freeradius chrony; do
    printf "%-12s : %s\n" "$s" "$(systemctl is-active $s)"
done

echo; echo "═══ 3. CONG LANG NGHE ═════════════════════════════════"
ss -tlnp 2>/dev/null | grep -E ':443|:3306' | awk '{print $4, $6}'
ss -ulnp 2>/dev/null | grep -E ':1812|:1813' | awk '{print $4, $6}'

echo; echo "═══ 4. FIREWALL ═══════════════════════════════════════"
ufw status | head -12

echo; echo "═══ 5. PHIEN BAN ══════════════════════════════════════"
apt-cache policy privacyidea 2>/dev/null | grep Installed
freeradius -v 2>/dev/null | head -1

echo; echo "═══ 6. QUYEN FILE QUAN TRONG ══════════════════════════"
ls -l /etc/privacyidea/{enckey,pi.cfg,private.pem} 2>/dev/null

echo; echo "═══ 7. LOG GAN NHAT (loi) ═════════════════════════════"
tail -15 /var/log/privacyidea/privacyidea.log 2>/dev/null | grep -iE 'error|fail|warn' || echo "(khong co loi gan day)"

echo; echo "═══ 8. BACKUP GAN NHAT ════════════════════════════════"
ls -lht /var/backups/privacyidea/*.gpg 2>/dev/null | head -3 || echo "(KHONG CO BACKUP!)"

echo; echo "═══ 9. DUNG LUONG ═════════════════════════════════════"
df -h / | tail -1
EOF
sudo chmod +x /usr/local/bin/pi-diag.sh
sudo /usr/local/bin/pi-diag.sh

10.2. Bảng lỗi tổng hợp toàn hệ thống

10.3. Giám sát và cảnh báo

Cần alert khi:

Giám sát truy cập file enckey bằng auditd:

Copysudo apt install -y auditd
sudo auditctl -w /etc/privacyidea/enckey -p rwa -k pi_enckey
echo '-w /etc/privacyidea/enckey -p rwa -k pi_enckey' | sudo tee -a /etc/audit/rules.d/privacyidea.rules
sudo systemctl restart auditd

# Xem ai đã đọc file
sudo ausearch -k pi_enckey --start today

Đẩy log về SIEM:

Copysudo tee /etc/rsyslog.d/50-privacyidea.conf > /dev/null <<'EOF'
# Gửi log privacyIDEA và auth về SIEM
module(load="imfile")
input(type="imfile"
      File="/var/log/privacyidea/privacyidea.log"
      Tag="privacyidea"
      Severity="info")
auth,authpriv.*    @@192.168.10.70:514
:syslogtag, contains, "privacyidea"  @@192.168.10.70:514
EOF
sudo systemctl restart rsyslog

Health-check tổng hợp cho Nagios/Zabbix/Icinga:

Copysudo tee /usr/local/bin/check-privacyidea.sh > /dev/null <<'EOF'
#!/bin/bash
# Exit: 0=OK 1=WARNING 2=CRITICAL
ERR=(); WARN=()

# 1. API sống
curl -sf -o /dev/null --max-time 5 https://otp01.lab.local/ || ERR+=("API khong phan hoi")

# 2. Dịch vụ
for s in apache2 mariadb freeradius; do
    systemctl is-active --quiet "$s" || ERR+=("$s DUNG")
done

# 3. Thời gian
OFF=$(chronyc tracking 2>/dev/null | awk '/System time/ {print ($4<0)?-$4:$4}')
awk -v a="${OFF:-99}" 'BEGIN{exit !(a>5)}' && ERR+=("Dong ho lech ${OFF}s")

# 4. RADIUS phản hồi (Access-Reject cũng là sống)
echo "User-Name=hc,User-Password=0" | radclient -t 3 -r 1 127.0.0.1:1812 auth testing123 2>&1 \
  | grep -qE "Access-(Accept|Reject|Challenge)" || WARN+=("RADIUS khong phan hoi")

# 5. Backup gần đây
find /var/backups/privacyidea -name '*.gpg' -mtime -1.1 | grep -q . || ERR+=("Khong co backup 26h qua")

# 6. Disk
USE=$(df / | awk 'NR==2{print $5}' | tr -d '%')
(( USE > 85 )) && WARN+=("Disk day ${USE}%")

if (( ${#ERR[@]} )); then printf 'CRITICAL: %s\n' "${ERR[*]}"; exit 2; fi
if (( ${#WARN[@]} )); then printf 'WARNING: %s\n' "${WARN[*]}"; exit 1; fi
echo "OK - privacyIDEA hoat dong binh thuong"; exit 0
EOF
sudo chmod +x /usr/local/bin/check-privacyidea.sh
sudo /usr/local/bin/check-privacyidea.sh

10.4. Bảo trì định kỳ

Quy trình nâng cấp an toàn:

Copy# 1. Backup TRƯỚC
sudo /usr/local/bin/backup-privacyidea.sh

# 2. Snapshot VM

# 3. Đọc READ_BEFORE_UPDATE.md của TẤT CẢ các version bạn nhảy qua
#    https://github.com/privacyidea/privacyidea/blob/master/READ_BEFORE_UPDATE.md

# 4. Nâng cấp (postinst tự chạy privacyidea-schema-upgrade)
sudo apt update && sudo apt install --only-upgrade privacyidea privacyidea-apache2

# 5. Kiểm tra
sudo /usr/local/bin/pi-diag.sh
sudo /usr/local/bin/check-privacyidea.sh

# 6. Test bằng token thật

10.5. Lộ trình rollout theo giai đoạn

Đừng bật MFA cho cả tổ chức cùng lúc. Đây là công thức chắc chắn dẫn tới sự cố.

Chuẩn bị trước khi bắt đầu GĐ1:

• Tài liệu hướng dẫn user (1 trang, có ảnh chụp màn hình, tiếng Việt)
• Video hướng dẫn cài app OTP (2–3 phút)
• Helpdesk đã được đào tạo, có quy trình reset token kèm bước xác minh danh tính
• Kênh hỗ trợ riêng cho giai đoạn rollout
• Email thông báo trước 1 tuần, nhắc lại trước 1 ngày
• Tài khoản break-glass đã test và niêm phong
• Monitoring + alert đã chạy và đã test bằng cách gây lỗi giả
• Backup đã chạy và đã restore thử thành công ít nhất một lần

Kiểm soát phạm vi bằng group AD:

CopyPS> New-ADGroup -Name "MFA-Wave1" -GroupScope Global -GroupCategory Security
PS> Add-ADGroupMember -Group "MFA-Wave1" -Members it-admin1,it-admin2
# Dùng Security Filtering của GPO theo group này

10.6. Hướng mở rộng

10.7. Checklist bàn giao

Hạ tầng - [ ] OTP01 chạy privacyIDEA ≥ 3.13.1 trên Ubuntu 24.04 (máy chuyên dụng) - [ ] chrony đồng bộ, lệch < 0,1 giây, có cron giám sát độ lệch - [ ] Time sync của hypervisor đã tắt - [ ] Firewall mở đúng 4 port, đóng phần còn lại - [ ] Chứng chỉ TLS từ CA nội bộ, SAN có cả DNS lẫn IP - [ ] CA nội bộ đã push vào Trusted Root của mọi client - [ ] PI_BASE_URL, PI_FORCE_HTTPS, PI_ENABLE_CSP đã đặt - [ ] Cron challenge cleanup đã bật

User và token - [ ] Resolver AD dùng LDAPS, UIDTYPE=objectGUID, NOREFERRALS=1 - [ ] Resolver nội bộ đã tạo (nếu cần) - [ ] Realm lab là mặc định, gộp đủ resolver - [ ] otppin đã quyết định và cấu hình - [ ] verify_enrollment đã bật - [ ] max_active_token_per_user=2 - [ ] Max failcount = 6, timeWindow phù hợp - [ ] fail2ban chạy và regex đã đối chiếu với log thật

RADIUS - [ ] 7 Perl module đã cài (nhớ liburi-encode-perl) - [ ] Module ở /usr/share/privacyidea/freeradius/, ini ở /etc/privacyidea/ - [ ] SSL_CHECK = true (đúng chữ thường) - [ ] Client khai riêng từng thiết bị, secret ≥ 24 ký tự, require_message_authenticator = yes - [ ] Client localhost mặc định đã xoá hoặc đổi secret - [ ] freeradius -X in Config File ... found!

Windows - [ ] Credential Provider 3.8 cài trên máy đích - [ ] Registry đúng HKLM\SOFTWARE\Netknights GmbH\PrivacyIDEA-CP - [ ] enable_filter = 1 - [ ] cpus_logon đúng giá trị (1d để bắt đầu) - [ ] fallback_hostname trỏ OTP02 - [ ] excluded_account đúng định dạng và đã test - [ ] Test RDP: có OTP ✅ / mã sai bị từ chối ✅ / replay bị từ chối ✅ - [ ] Có đường vào console qua hypervisor

Linux - [ ] radtest ra Access-Accept từ mọi máy Linux - [ ] /etc/pam.d/sshd: common-auth trước, pam_radius force_prompt sau - [ ] Failover sang OTP02 đã test - [ ] Backup /etc/pam.d/sshd và sshd_config đã lưu - [ ] Automation dùng key, không bị OTP chặn, authorized_keys đã siết

Web - [ ] Code đọc result.value, không đọc result.status - [ ] Không retry POST xác thực - [ ] verify TLS bật với CA nội bộ - [ ] Fail closed khi OTP server chết - [ ] Rate limiting ở nginx + policy giới hạn IP + API key - [ ] Session chỉ cấp sau khi qua yếu tố 2, có session.clear()

Backup / DR - [ ] Backup tự động hằng ngày, có cờ -e, script tự kiểm tra có enckey - [ ] Mã hoá bằng GPG public key, private key cất ở nơi khác, ≥ 2 người biết - [ ] Nhân bản ra ≥ 2 nơi, có checksum - [ ] Giám sát tuổi backup - [ ] ⭐ Đã restore thử thành công vào VM cách ly ít nhất một lần - [ ] Runbook DR viết ra, có trong wiki, và in ra để trong tủ server - [ ] Lịch diễn tập DR 6 tháng/lần đã vào calendar

Vận hành - [ ] Quy trình reset token có bước xác minh danh tính - [ ] Helpdesk đã đào tạo - [ ] Tài liệu hướng dẫn user tiếng Việt, có ảnh minh hoạ - [ ] Alert đã cấu hình và đã test bằng cách gây lỗi giả - [ ] Log đã đẩy về SIEM - [ ] Break-glass: đã tạo, đã test, có alert, ≥ 2 người biết - [ ] Có owner chịu trách nhiệm chính cho hệ thống OTP

PHẦN 11. PROXMOX VE, VMWARE VÀ ỨNG DỤNG WEB BÊN THỨ BA

Câu hỏi hay gặp nhất sau khi dựng xong OTP server: "Cái này gắn được vào Proxmox, vào vCenter, vào mấy con web app của hãng khác không?"

Câu trả lời ngắn: được — nhưng không phải cái nào cũng cùng một đường, và có đúng một trường hợp thực sự không làm được.

11.1. Trả lời nhanh trước khi đọc chi tiết

11.2. Nguyên tắc: đi theo thứ mà ứng dụng đã biết nói

Đừng hỏi "privacyIDEA hỗ trợ Proxmox chưa". Hãy hỏi ngược lại: ứng dụng này biết nói giao thức xác thực nào? privacyIDEA nói được gần hết, nên nút thắt luôn nằm ở phía ứng dụng.

11.3. Proxmox VE

11.3.1. Proxmox có sẵn những gì

Cần biết rõ trước khi chọn đường:

Ba đường khả thi, xếp theo mức khuyến nghị:

11.3.2. Cách A — PAM realm + pam_radius (nhanh nhất, ~20 phút)

Realm "Linux PAM standard authentication" của Proxmox xác thực qua PAM service common-auth. Chèn pam_radius vào đó là web UI của Proxmox sẽ hỏi privacyIDEA.

Copy# Trên node Proxmox
apt update && apt install -y libpam-radius-auth

Copynano /etc/pam_radius_auth.conf

Copy# server[:port]   shared_secret   timeout(giây)
192.168.10.10:1812   MatKhauRadiusRatManh   5

Copychmod 600 /etc/pam_radius_auth.conf

Thêm OTP01 vào danh sách client trên FreeRADIUS (xem 5.4) với đúng secret trên, rồi sửa PAM:

Copycp /etc/pam.d/common-auth /root/common-auth.bak-$(date +%F)
nano /etc/pam.d/common-auth

Đặt dòng đầu tiên, trước pam_unix.so:

Copyauth  [success=done new_authtok_reqd=done default=ignore]  pam_radius_auth.so
auth  requisite   pam_deny.so
auth  required    pam_permit.so
# ... phần cũ giữ nguyên phía dưới

Test — luôn test từ máy khác, giữ nguyên phiên hiện tại:

Copy# Trên OTP01: xem RADIUS có nhận request không
tail -f /var/log/freeradius/radius.log

# Trên máy khác: đăng nhập web Proxmox, realm "Linux PAM standard authentication"
# hoặc test bằng radtest cho nhanh:
radtest hoangnv 'MatKhauAD123456' 192.168.10.10 0 MatKhauRadiusRatManh

11.3.3. Cách B — Realm OpenID Connect qua Keycloak (đẹp nhất về lâu dài)

Proxmox nói OIDC nguyên bản, và privacyIDEA có keycloak-provider chính thức. Chuỗi:

CopyProxmox VE  ──OIDC──►  Keycloak  ──REST──►  privacyIDEA
   realm oidc            + privacyIDEA           OTP01
                          provider (2FA)

Các bước lớn:

1. Dựng Keycloak (container hoặc VM riêng), tạo realm và client cho Proxmox.
2. Cài keycloak-provider của privacyIDEA vào Keycloak, trỏ về https://otp01.lab.local.
3. Sửa authentication flow của Keycloak: sau bước password, thêm bước privacyIDEA OTP.
4. Trên Proxmox: Datacenter → Permissions → Realms → Add → OpenID Connect Server, điền Issuer URL, Client ID, Client Key, bật Autocreate Users nếu muốn.

Ưu điểm: có ô nhập OTP riêng (không phải nối chuỗi), SSO dùng lại được cho Grafana / GitLab / Nextcloud, và không đụng vào PAM của node. Nhược điểm: thêm một thành phần phải vận hành và backup (Keycloak). Chỉ đáng làm khi bạn có từ ~3 ứng dụng trở lên cần SSO.

11.3.4. Cách C — Yubico OTP trỏ thẳng về privacyIDEA

Ít người biết: TFA kiểu Yubico OTP của Proxmox cho phép chỉ định URL của validation server. privacyIDEA có sẵn endpoint theo Yubico Validation Protocol V2.0 tại /ttype/yubikey, và có thể expose thêm đường /wsapi/2.0/verify cho đúng chuẩn Yubico:

Copy# Trên OTP01 — bật rewrite trong vhost privacyIDEA
sudo nano /etc/apache2/sites-available/privacyidea.conf

CopyRewriteEngine on
RewriteRule "^/wsapi/2.0/verify"  "/ttype/yubikey"  [PT]

Copysudo apache2ctl configtest && sudo systemctl reload apache2

Sau đó trong Proxmox: Datacenter → Options → TFA → Yubico, điền API URL trỏ về https://otp01.lab.local/wsapi/2.0/verify.

11.3.5. Chọn cách nào

11.4. VMware

11.4.1. Sự thật cần biết trước: vCenter không nói RADIUS

Đây là điểm hay bị nhầm nhất. vCenter Single Sign-On hỗ trợ:

Danh sách Identity Provider được hỗ trợ chính thức, theo phiên bản:

11.4.2. Đường đi thực tế cho môi trường on-premise

CopyvCenter 7/8  ──Identity Federation (OIDC)──►  AD FS  ──►  privacyIDEA
                                            (Windows)      OTP01
                                          + plugin MFA

Các bước lớn:

1. Dựng AD FS trên Windows Server (yêu cầu có AD — nếu bạn theo kịch bản không AD ở 3.4 thì đường này không dùng được).
2. Cài plugin xác thực privacyIDEA cho AD FS, trỏ về https://otp01.lab.local.
3. Trong AD FS, bật plugin làm Additional Authentication Method cho relying party của vCenter.
4. Trên vCenter: Administration → Single Sign On → Configuration → Identity Provider → Change Provider → Microsoft ADFS, điền Client ID / Secret / OpenID Address.

11.4.3. ESXi host: không có MFA, và không nên cố

ESXi (Host Client, SSH, DCUI) không có cơ chế MFA nào. Đừng tìm plugin — không tồn tại. Cách xử lý đúng là giảm bề mặt thay vì thêm lớp xác thực:

Nói thẳng: MFA cho ESXi = MFA cho đường vào ESXi, không phải MFA trên chính ESXi.

11.4.4. VMware Horizon — trường hợp dễ nhất

Horizon Connection Server hỗ trợ RADIUS nguyên bản. Vào Connection Server → Authentication → Advanced Authentication → 2-factor authentication → RADIUS, trỏ về 192.168.10.10:1812, dùng secret đã đặt ở Phần 5. Horizon có xử lý được challenge-response, nên ở đây bạn có ô nhập OTP riêng.

11.5. Ứng dụng web bên thứ ba

11.5.1. App nói RADIUS — không có gì phải làm thêm

Fortigate, pfSense, OPNsense, Cisco ASA/ISE, nhiều NAS (Synology, QNAP), Grafana Enterprise, Zabbix, GLPI... Chỉ cần thêm client vào FreeRADIUS:

Copysudo nano /etc/freeradius/3.0/clients.conf

Copyclient fw-hq {
    ipaddr = 192.168.10.60
    secret = MotSecretRatDaiVaNgauNhien
    require_message_authenticator = auto
    nas_type = other
}

Copysudo systemctl restart freeradius

Kiểm tra thiết bị đó có xử lý Access-Challenge không: nếu có thì người dùng có ô nhập OTP riêng; nếu không thì quay lại quy tắc nối chuỗi ở 11.2.

11.5.2. App nói LDAP — dùng privacyIDEA LDAP-Proxy

Nhiều app cũ chỉ biết bind LDAP. privacyIDEA có LDAP-Proxy: nó đứng giữa, nhận bind request, tách phần OTP ra kiểm tra với privacyIDEA, phần mật khẩu chuyển tiếp về LDAP/AD thật.

CopyApp  ──LDAP bind (mật khẩu+OTP)──►  privacyIDEA LDAP-Proxy  ──►  AD thật
                                              │
                                              └──REST──►  privacyIDEA

Dùng khi: GitLab bản cũ, Jira/Confluence Server, NAS, các app nội bộ viết từ lâu. Lưu ý proxy này chạy như một service riêng — nhớ đưa vào giám sát và backup cấu hình.

11.5.3. App nói SAML / OIDC — Keycloak đứng giữa

Đây là cách sạch nhất cho môi trường nhiều ứng dụng. privacyIDEA có plugin cho Keycloak, simpleSAMLphp, Shibboleth, Gluu và AD FS.

CopyGrafana · GitLab · Nextcloud · Proxmox (OIDC) · Jenkins
        └──────── SAML/OIDC ────────►  Keycloak  ──►  privacyIDEA

Làm một lần, dùng cho tất cả. Đổi lại bạn phải vận hành thêm Keycloak — nó trở thành thành phần critical ngang privacyIDEA, nên phải backup và HA tương ứng.

11.5.4. App đã có plugin sẵn

Không cần trung gian, cài thẳng plugin của privacyIDEA:

11.5.5. App không hỗ trợ gì — chặn bằng reverse proxy

Ứng dụng nội bộ tự viết, dashboard cũ, giao diện quản trị thiết bị... Đặt một lớp xác thực phía trước nó.

Cách đơn giản nhất — Apache + mod_auth_radius:

Copysudo apt install -y libapache2-mod-auth-radius
sudo a2enmod auth_radius

Copy<VirtualHost *:443>
    ServerName dashboard.lab.local

    AddRadiusAuth 192.168.10.10:1812 MotSecretRatDaiVaNgauNhien 5:3
    AddRadiusCookieValid 60

    <Location />
        AuthType Basic
        AuthName "Dang nhap: mat khau + ma OTP"
        AuthBasicProvider radius
        Require valid-user
    </Location>

    ProxyPass        / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>

Với nginx: dùng auth_request trỏ tới một endpoint kiểm tra nội bộ (viết bằng thư viện client ở Phần 8), hoặc dùng plugin nginx (lua) của privacyIDEA. nginx không có module RADIUS dựng sẵn như Apache, nên đường này tốn công hơn.

Copyss -tlnp | grep 8080          # phải là 127.0.0.1:8080, KHÔNG phải 0.0.0.0:8080

11.5.6. Bảng tra nhanh

11.6. Bốn cái bẫy chung của mọi tích hợp

PHỤ LỤC A. LỆNH THAM CHIẾU NHANH

Copy# ══ Quản trị viên ══════════════════════════════════════════════
sudo pi-manage admin add <user> -e <email>
sudo pi-manage admin list
sudo pi-manage admin change <user> --password <PW>
sudo pi-manage admin delete <user>

# ══ Resolver ═══════════════════════════════════════════════════
sudo pi-manage config resolver list
sudo pi-manage config resolver create <ten> ldapresolver <file.py>
sudo pi-manage config resolver create_internal <ten>
# Loại: ldapresolver | sqlresolver | httpresolver | passwdresolver | scimresolver

# ══ Realm ══════════════════════════════════════════════════════
sudo pi-manage config realm list                    # dấu '*' = mặc định
sudo pi-manage config realm create <realm> <res1> [<res2>...]
sudo pi-manage config realm set_default <realm>
sudo pi-manage config realm delete <realm>

# ══ Policy ═════════════════════════════════════════════════════
sudo pi-manage config policy list
sudo pi-manage config policy create <ten> <scope> "<action>"
sudo pi-manage config policy enable|disable|delete <ten>
# Scope: authentication authorization admin user enrollment webui
#        audit token container register hardening

# ══ Setup / khoá ═══════════════════════════════════════════════
sudo pi-manage setup create_enckey
sudo pi-manage setup create_audit_keys [-k 2048]
sudo pi-manage setup create_tables
sudo pi-manage setup encrypt_enckey /etc/privacyidea/enckey

# ══ Backup ═════════════════════════════════════════════════════
sudo pi-manage backup create -e                     # ⭐ -e = KÈM enckey
sudo pi-manage backup create -e -d <dir> -c /etc/privacyidea/ -r /etc/freeradius/3.0
sudo pi-manage backup restore <file.tgz> [--keep-db-uri]

# ══ Audit ══════════════════════════════════════════════════════
sudo pi-manage audit rotate --age 180
sudo pi-manage audit dump

# ══ Export / import cấu hình ═══════════════════════════════════
sudo pi-manage config export -f yaml -o cfg.yaml --censor
sudo pi-manage config import -i cfg.yaml [--skip-invalid]

# ══ Bảo trì ════════════════════════════════════════════════════
sudo pi-manage config challenge cleanup --age 60
sudo pi-manage api createtoken -r validate -u <ten_dinh_danh>   # -u BAT BUOC
sudo privacyidea-get-unused-tokens
sudo privacyidea-token-janitor

# ══ Dịch vụ ════════════════════════════════════════════════════
sudo systemctl restart apache2 mariadb freeradius
sudo freeradius -X                                  # debug foreground
radtest <user> <pass+otp> <server>:1812 0 <secret>

PHỤ LỤC B. REST API THAM CHIẾU

Copyexport PI_URL="https://otp01.lab.local"

# ── Lấy JWT ────────────────────────────────────────────────────
export PI_TOKEN=$(curl -sk -X POST $PI_URL/auth \
  -d "username=admin" -d "password=<pw>" | jq -r '.result.value.token')

# ⚠️ Header: PI-Authorization: <JWT>   — JWT THÔ, KHÔNG có "Bearer"

# ── Xác thực (không cần JWT) ───────────────────────────────────
curl -sk -X POST $PI_URL/validate/check \
  -d "user=hoangnv" -d "realm=lab" -d "pass=<matkhau><OTP>"
# ⭐ Đọc result.value, KHÔNG đọc result.status

# ── Xác thực kiểu RADIUS (204=OK, 400=fail, body rỗng) ─────────
curl -sk -o /dev/null -w "%{http_code}\n" -X POST $PI_URL/validate/radiuscheck \
  -d "user=hoangnv" -d "realm=lab" -d "pass=<matkhau><OTP>"

# ── Enroll token TOTP ──────────────────────────────────────────
curl -sk -X POST $PI_URL/token/init -H "PI-Authorization: $PI_TOKEN" \
  -d "type=totp" -d "user=hoangnv" -d "realm=lab" -d "genkey=1" \
  -d "otplen=6" -d "hashlib=sha1" -d "timeStep=30"

# ── Liệt kê token của user ─────────────────────────────────────
curl -sk -G $PI_URL/token/ -H "PI-Authorization: $PI_TOKEN" \
  --data-urlencode "user=hoangnv" --data-urlencode "realm=lab" | jq '.result.value.tokens'

# ── Vô hiệu hoá / bật / xoá / reset failcount ──────────────────
curl -sk -X POST $PI_URL/token/disable -H "PI-Authorization: $PI_TOKEN" -d "serial=TOTP0001"
curl -sk -X POST $PI_URL/token/enable  -H "PI-Authorization: $PI_TOKEN" -d "serial=TOTP0001"
curl -sk -X POST $PI_URL/token/reset   -H "PI-Authorization: $PI_TOKEN" -d "serial=TOTP0001"
curl -sk -X DELETE $PI_URL/token/TOTP0001 -H "PI-Authorization: $PI_TOKEN"

# ── Quản lý user (resolver editable) ───────────────────────────
curl -sk -G $PI_URL/user/ -H "PI-Authorization: $PI_TOKEN" \
  --data-urlencode "realm=lab" --data-urlencode "username=hoangnv"
curl -sk -X POST $PI_URL/user/ -H "PI-Authorization: $PI_TOKEN" \
  -d "user=nhathau01" -d "resolver=local_users" -d "[email protected]" -d "password=..."

# ── Audit log ──────────────────────────────────────────────────
curl -sk -G $PI_URL/audit/ -H "PI-Authorization: $PI_TOKEN" \
  --data-urlencode "page_size=20" --data-urlencode "user=hoangnv" \
  | jq '.result.value.auditdata[] | {date, action, success, user, serial, client}'
# Cột IP nguồn tên là "client", không phải "client_ip"

PHỤ LỤC C. FILE VÀ ĐƯỜNG DẪN QUAN TRỌNG

PHỤ LỤC D. GIÁ TRỊ DỄ NHẦM — BẢNG TRA NHANH

Tài liệu này biên soạn cho môi trường lab dựa trên privacyIDEA 3.13.x, FreeRADIUS 3.2.5 và Ubuntu 24.04 LTS. Trước khi áp dụng vào production, hãy chạy đủ chu trình test và diễn tập DR đã mô tả. Cú pháp lệnh có thể thay đổi giữa các phiên bản — luôn đối chiếu với pi-manage --help và tài liệu của đúng bản bạn đang chạy.