Hướng dẫn tích hợp

Dành cho người viết ứng dụng chạy trong mạng LAN, muốn dùng chung tài khoản và kho lưu trữ của hệ thống.

1. Cho app tự đăng nhập bằng tài khoản chung

Có hai cách, chọn theo việc app của bạn có sẵn hệ thống tài khoản hay không.

Cách A — App đã có đăng nhập riêng (dùng OIDC)

Phù hợp khi app của bạn có bảng user, phân quyền riêng. Authentik chỉ cấp danh tính, app giữ quyền hạn.

client_id và client_secret lấy trong Authentik → Applications → Providers.

Cách B — App không có đăng nhập (dùng forward-auth)

Phù hợp với công cụ nội bộ, trang quản trị, thứ bạn tự viết mà chưa làm phần đăng nhập. Reverse proxy chặn trước, app không cần biết gì.

app-cua-ban.authentik.vn {
    route {
        # Bắt buộc: đường dẫn outpost phải đi THẲNG tới Authentik
        reverse_proxy /outpost.goauthentik.io/* 10.10.0.2:9000 {
            header_up Host {http.request.host}
        }
        forward_auth 10.10.0.2:9000 {
            uri /outpost.goauthentik.io/auth/caddy
            copy_headers X-authentik-username X-authentik-groups X-authentik-email X-authentik-name X-authentik-uid
            header_up Host {http.request.host}
            trusted_proxies private_ranges
        }
        reverse_proxy 192.168.20.xx:port
    }
}

for p in /outpost.goauthentik.io/auth/caddy \
         /outpost.goauthentik.io/callback \
         /outpost.goauthentik.io/start; do
  curl -s -o /dev/null -w "$p -> %{http_code}\n" https://app-cua-ban.authentik.vn$p
done

2. Lấy thông tin người dùng

Nếu dùng forward-auth

Proxy đã chèn sẵn header vào mỗi request. App chỉ việc đọc:

# PHP
$user = $_SERVER['HTTP_X_AUTHENTIK_USERNAME'] ?? null;

# Python (Flask)
user = request.headers.get('X-authentik-username')

# Node (Express)
const user = req.headers['x-authentik-username'];

Nếu dùng OIDC

GET https://authentik.vn/application/o/userinfo/
Authorization: Bearer <access_token>

{ "sub":"...", "preferred_username":"tenuser",
  "email":"...", "name":"...", "groups":["nhom-a","nhom-b"] }

Dùng preferred_username để khớp với tài khoản trong app của bạn.

3. Đưa app của bạn lên tên miền

1. Báo địa chỉ nội bộ của app — ví dụ 192.168.20.50:8080
2. Tạo bản ghi DNS <ten>.authentik.vn
3. Trong Authentik: tạo Provider rồi tạo Application trỏ vào provider đó
4. Gắn provider vào embedded outpost — quên bước này thì forward-auth im lặng không chạy, không báo lỗi gì
5. Thêm khối cấu hình vào reverse proxy

Máy chạy app không cần IP public, không cần mở cổng — chỉ cần NAS với tới nó trong LAN.

Phân quyền ai được vào

Authentik → Applications → chọn app → Policy / Group / User Bindings. Không gán binding nào nghĩa là mọi người đã đăng nhập đều vào được. Muốn giới hạn thì tạo nhóm rồi gán nhóm đó.

4. Dùng kho lưu trữ NAS

Chia sẻ file kiểu thư mục (SMB)

smb://192.168.20.111/files
smb://192.168.20.111/media
smb://192.168.20.111/photos

Chỉ dùng được trong LAN hoặc khi đã bật VPN.

Kho đối tượng S3 (Garage)

Dành cho app cần lưu file bằng API thay vì thư mục — ảnh người dùng tải lên, bản sao lưu, tệp tạm.

Access key xin riêng cho từng app — đừng dùng chung một key.

import boto3
s3 = boto3.client('s3',
    endpoint_url='http://192.168.20.111:3900',
    aws_access_key_id='GK...',
    aws_secret_access_key='...',
    region_name='garage')
s3.put_object(Bucket='ten-bucket', Key='duong/dan.jpg', Body=data)

Truy cập từ xa

Bật WireGuard là vào được toàn bộ LAN như đang ngồi ở nhà. Xin file cấu hình khi cần.

5. Gọi API

API của Authentik

GET https://authentik.vn/api/v3/core/users/
Authorization: Bearer <token>

Tạo token trong Directory → Tokens. Có sẵn tài liệu OpenAPI tại /api/v3/schema/.

Dùng để: tạo user bằng script, gán nhóm, đọc nhật ký đăng nhập, dựng app mới tự động.

Nguyên tắc chung

• App nghe trên địa chỉ nội bộ, không mở ra 0.0.0.0
• Không tự làm đăng nhập — để Authentik lo
• Mỗi app một access key S3 riêng
• Bí mật để trong biến môi trường, không viết thẳng vào mã nguồn