Cấu hình SSO cho app không có đăng nhập với oauth2-proxy
Dùng forward auth để đặt app không có login sau OIDC provider. Cấu hình oauth2-proxy với nginx hoặc Traefik, tránh lỗi cookie và vòng lặp redirect.
Xác thực chuyển tiếp: cách cho một ứng dụng không có đăng nhập dùng SSO
oauth2-proxy cung cấp single sign-on cho một ứng dụng không có chức năng đăng nhập riêng. Cơ chế này hoạt động vì reverse proxy đứng trước ứng dụng sẽ chặn mọi request, hỏi oauth2-proxy xem request có session hợp lệ hay không, rồi chỉ chuyển request đến upstream khi nhận được câu trả lời có. Code của ứng dụng không cần thay đổi vì ứng dụng không bao giờ trực tiếp xử lý bước kiểm tra này.
Bước kiểm tra tạo thêm một HTTP request. Proxy gửi bản sao các request header nhận được đến /oauth2/auth và đọc status code. Mã 202 có nghĩa là bước kiểm tra đã thành công, vì vậy proxy chuyển request ban đầu đến app. Mã 401 có nghĩa là không có session hợp lệ, vì vậy proxy chuyển trình duyệt đến /oauth2/sign_in; mặc định trang này hiển thị trang đăng nhập. /oauth2/start bắt đầu quy trình đăng nhập OpenID Connect (OIDC) tại identity provider của bạn; skip_provider_button = true khiến /oauth2/sign_in tự động bắt đầu quy trình đó. OIDC là lớp identity xây dựng trên OAuth 2.0, còn provider là hệ thống bạn đang dùng để đăng nhập.
Mẫu này có tên tương ứng trong từng reverse proxy. Nginx gọi directive này là auth_request. Traefik gọi middleware này là forwardAuth. Caddy viết tên này là forward_auth. Service trả lời sub-request cũng có thể thay thế. oauth2-proxy là lựa chọn phổ biến vì nó hỗ trợ OIDC thuần và không cần database riêng.
Vẽ ranh giới tin cậy trước khi viết bất kỳ cấu hình nào
Sau khi kiểm tra thành công, oauth2-proxy trả về danh tính trong các response header, rồi reverse proxy sao chép chúng vào request gửi đến upstream. Khi bật set_xauthrequest, bạn nhận được X-Auth-Request-User và X-Auth-Request-Email. Ứng dụng đọc các header đó và tin cậy chúng.
Đó là toàn bộ mô hình bảo mật, vì vậy cần nói rõ hệ quả. Bất kỳ thứ gì có thể mở kết nối TCP đến cổng của ứng dụng đều có thể tự đặt các header đó và giả làm bất kỳ user nào. Chỉ một curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/ cũng đủ bypass hoàn toàn nếu request đó đến trực tiếp ứng dụng.
Vì vậy, ứng dụng không được truy cập theo cách nào khác ngoài thông qua proxy. Trong Docker Compose, xóa mapping ports: khỏi app service và để service này trên internal network, để chỉ proxy container có thể kết nối đến nó. Trên host độc lập, bind ứng dụng vào 127.0.0.1:3000 thay vì 0.0.0.0:3000. Sau đó kiểm tra chính xác những gì bạn đã expose:
sudo ss -tlnp | grep 3000Dòng có nội dung 0.0.0.0:3000 nghĩa là ứng dụng đang trả lời trên public IP và lớp kiểm soát của bạn chỉ mang tính hình thức. 127.0.0.1:3000 mới là cấu hình bạn cần. Firewall rule là một lớp bảo vệ thứ hai hữu ích, nhưng bind address mới là lớp vẫn còn hiệu lực nếu một công cụ khác flush ruleset của bạn.
Cài đặt oauth2-proxy
Tính đến tháng 10 năm 2026, bản release hiện tại là v7.15.5, được phát hành vào ngày 1 tháng 10 năm 2026. Bản này sửa 2 advisory bảo mật nghiêm trọng, trong đó có một lỗi bypass skip_auth_routes ảnh hưởng đến mọi release sau v7.5.0, vì vậy không được cài bản cũ hơn. Cài binary và xác minh file đã tải xuống:
cd /tmp
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
sha256sum -c oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
tar -xzf oauth2-proxy-v7.15.5.linux-amd64.tar.gz
sudo install -m 755 oauth2-proxy-v7.15.5.linux-amd64/oauth2-proxy /usr/local/bin/oauth2-proxy
oauth2-proxy --versionsha256sum -c phải in ra một dòng kết thúc bằng OK. Nếu in ra FAILED, hãy dừng lại và tải lại thay vì chạy binary.
Trong Docker, image là quay.io/oauth2-proxy/oauth2-proxy và bạn nên pin tag: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5. Để tag ở latest sẽ biến một docker compose pull định kỳ thành việc upgrade ngoài kế hoạch cho process đang bảo vệ mọi app trên máy chủ.
Tạo cookie secret
Session cookie được mã hóa, và cookie_secret là key. Key mã hóa phải có chính xác 16, 24 hoặc 32 byte vì nó được dùng làm key AES (advanced encryption standard). oauth2-proxy chấp nhận giá trị base64 an toàn cho URL và giải mã được thành một trong các độ dài đó, hoặc secret thô có một trong các độ dài đó. Nếu không, oauth2-proxy sẽ từ chối khởi động và ghi rõ cookie secret trong lỗi khởi động. Lệnh dưới đây tạo ra một giá trị dài 44 ký tự, mã hóa một key 32 byte.
openssl rand -base64 32 | tr -- '+/' '-_'tr không chỉ mang tính hình thức. Nó chuyển base64 chuẩn sang bảng ký tự an toàn cho URL mà oauth2-proxy dùng khi giải mã secret.
Có 2 quy tắc cho giá trị này. Dùng secret khác nhau cho từng deployment. Nếu chạy nhiều instance oauth2-proxy phía sau cùng một domain, hãy cấp cho tất cả instance cùng một secret, vì cookie được một instance mã hóa phải được các instance khác đọc được.
Viết cấu hình oauth2-proxy
Giữ các thiết lập trong một file thay vì dùng một command line dài, để client secret không xuất hiện trong output của ps.
# /etc/oauth2-proxy/oauth2-proxy.cfg
http_address = "127.0.0.1:4180"
reverse_proxy = true
provider = "oidc"
oidc_issuer_url = "https://id.example.com/application/o/myapp/"
client_id = "REPLACE_ME"
client_secret = "REPLACE_ME"
redirect_url = "https://app.example.com/oauth2/callback"
cookie_secret = "REPLACE_ME"
cookie_secure = true
cookie_domains = [".example.com"]
whitelist_domains = [".example.com"]
email_domains = ["*"]
set_xauthrequest = true
upstreams = ["static://202"]reverse_proxy = true yêu cầu oauth2-proxy tin cậy các header X-Forwarded-* do proxy phía trước gửi. Nếu không có thiết lập này, oauth2-proxy sẽ coi địa chỉ của chính proxy là địa chỉ client và có thể xác định sai request có đi qua HTTPS hay không.
trusted_proxy_ips giới hạn các peer được phép cung cấp những header đó. Mặc định, thiết lập này tin cậy mọi nguồn. Cách này chỉ an toàn ở đây vì http_address giữ oauth2-proxy trên 127.0.0.1. Nếu oauth2-proxy lắng nghe trên một Docker network, hãy đặt nó thành địa chỉ của reverse proxy.
upstreams = ["static://202"] khiến oauth2-proxy trả về 202 cho request đã xác thực và không proxy gì cả. Đây chính xác là điều forward auth cần, vì reverse proxy sẽ thực hiện việc proxy. Kiểu triển khai còn lại đặt oauth2-proxy trực tiếp trên đường đi của request với upstreams = ["http://127.0.0.1:3000"] và hoàn toàn không có auth_request. Cách đó đơn giản hơn cho một app nhưng không mở rộng tốt lên ten app.
email_domains = ["*"] cho phép mọi địa chỉ mà provider của bạn xác thực. Hãy giới hạn vào domain của bạn, hoặc tốt hơn, giới hạn quyền truy cập bằng group binding trong provider, vì đây là nơi bạn đã quản lý người dùng.
Chạy nó dưới systemd bằng một user riêng:
# /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network-online.target
Wants=network-online.target
[Service]
User=oauth2-proxy
Group=oauth2-proxy
ExecStart=/usr/local/bin/oauth2-proxy --config=/etc/oauth2-proxy/oauth2-proxy.cfg
Restart=on-failure
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true
[Install]
WantedBy=multi-user.targetsudo useradd --system --no-create-home --shell /usr/sbin/nologin oauth2-proxy
sudo install -d -m 750 /etc/oauth2-proxy
sudo chown -R oauth2-proxy:oauth2-proxy /etc/oauth2-proxy
sudo chmod 600 /etc/oauth2-proxy/oauth2-proxy.cfg
sudo systemctl daemon-reload
sudo systemctl enable --now oauth2-proxy
curl -s http://127.0.0.1:4180/ping/ping in ra OK nghĩa là process đã khởi động và nạp cấu hình. Đây là health endpoint của oauth2-proxy và endpoint này không bao giờ yêu cầu session. Nếu không có phản hồi, hãy đọc journalctl -u oauth2-proxy -n 50, vì issuer URL sai và cookie secret có độ dài không đúng đều khiến quá trình khởi động fail, và log đều sẽ nêu rõ nguyên nhân.
Đăng ký redirect URI với provider
Tạo một ứng dụng OIDC trong provider và đặt redirect URI chính xác bằng redirect_url trong config: https://app.example.com/oauth2/callback. “Chính xác” nghĩa là scheme, host, port và path phải khớp từng ký tự. Dấu gạch chéo ở cuối sẽ làm URI trở thành một URI khác.
Đây là lỗi thường gặp nhất trong toàn bộ quá trình thiết lập. Lỗi xảy ra trước khi oauth2-proxy được gọi. Provider từ chối yêu cầu authorisation và hiển thị trang lỗi của chính nó, nên trong log của oauth2-proxy không có gì xuất hiện. Dấu hiệu nhận biết là thanh địa chỉ: trình duyệt vẫn đang ở domain của provider, còn query string chứa error=invalid_request hoặc trang hiển thị trực tiếp tên redirect_uri. Khi gặp trường hợp này, hãy sửa bản ghi ứng dụng trong provider, không phải proxy config.
Hãy copy issuer URL từ provider thay vì tự nhập. oauth2-proxy nối /.well-known/openid-configuration vào oidc_issuer_url rồi fetch discovery document đó khi khởi động. Trước tiên, hãy tự kiểm tra URL này:
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400JSON có key authorization_endpoint là bước kiểm tra đầu tiên. issuer trong document cũng phải khớp chính xác với oidc_issuer_url. HTTP 404 hoặc trang lỗi HTML cho biết URL bị sai. oauth2-proxy cũng sẽ fail khi khởi động với đúng lỗi 404 đó. Nếu bạn chưa chọn provider, bài so sánh Keycloak, Authentik và Zitadel phân tích các đánh đổi, còn cách chạy Authentik làm SSO server riêng trình bày phần provider của đúng mô hình này.
Nginx: auth_request
Nginx thực hiện xác thực chuyển tiếp bằng auth_request. Directive này tạo một sub-request nội bộ rồi rẽ nhánh dựa trên status code của nó.
# in the http context, next to your other maps
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name app.example.com;
location /oauth2/ {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Auth-Request-Redirect $request_uri;
}
location = /oauth2/auth {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Uri $request_uri;
proxy_set_header Content-Length "";
proxy_pass_request_body off;
}
location / {
auth_request /oauth2/auth;
error_page 401 = @oauth2_signin;
auth_request_set $user $upstream_http_x_auth_request_user;
auth_request_set $email $upstream_http_x_auth_request_email;
proxy_set_header X-User $user;
proxy_set_header X-Email $email;
auth_request_set $auth_cookie $upstream_http_set_cookie;
add_header Set-Cookie $auth_cookie;
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
location @oauth2_signin {
return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
}
}Ba chi tiết trong cấu hình này đều cần thiết. proxy_pass_request_body off đi cùng Content-Length rỗng để ngăn nginx chuyển request body đến endpoint xác thực, vì endpoint này chỉ cần các header.
Cặp auth_request_set $auth_cookie và add_header Set-Cookie chuyển session cookie mới về browser. Nếu bỏ qua cặp này, cookie_refresh sẽ âm thầm không làm gì vì nginx loại bỏ Set-Cookie của sub-request, còn browser tiếp tục dùng giá trị cũ cho đến khi session hết hạn. Cặp này xử lý một cookie. Nếu session được tách thành nhiều cookie, cần xử lý bổ sung cho các phần còn lại hoặc dùng Redis để lưu session.
error_page 401 = @oauth2_signin chuyển một lần kiểm tra thất bại thành thao tác đăng nhập. Nếu không có directive này, visitor chưa xác thực sẽ chỉ nhận trang 401 Authorization Required trống và không có cách tiếp tục.
Luôn kiểm tra trước khi reload:
sudo nginx -t && sudo systemctl reload nginxNếu bạn chưa quen với các directive xung quanh, phân tích cấu trúc của cấu hình nginx reverse proxy trình bày lớp bên dưới cấu hình này.
Traefik: middleware forwardAuth
Traefik cần hai middleware cho cùng một mục đích. Một middleware thực hiện kiểm tra. Middleware còn lại hiển thị trang đăng nhập khi kiểm tra thất bại.
# dynamic configuration
http:
middlewares:
oauth-auth:
forwardAuth:
address: https://oauth.example.com/oauth2/auth
trustForwardHeader: true
oauth-errors:
errors:
status:
- "401-403"
service: oauth-backend
query: "/oauth2/sign_in?rd={url}"Gắn cả hai middleware vào router đứng trước app, theo thứ tự oauth-errors trước oauth-auth, và publish oauth2-proxy trên router riêng tại oauth.example.com, vì trình duyệt phải truy cập /oauth2/sign_in và /oauth2/callback mà không đi qua bước kiểm tra. Với login host riêng này, đặt redirect_url thành https://oauth.example.com/oauth2/callback và đăng ký URI đó với provider.
Với cấu hình oauth2-proxy ở trên, /oauth2/sign_in sẽ hiển thị trang đăng nhập. Để tự động redirect thay vì vậy, đặt skip_provider_button = true trong oauth2-proxy và thêm statusRewrites: {"401": 302} vào phần cấu hình errors của Traefik. Nếu không có rewrite này, Traefik trả về automatic redirect cùng status 401, nên trình duyệt không follow redirect đó. Chỉ thêm rewrite không tự khởi động login flow.
trustForwardHeader: true tin cậy các header X-Forwarded-* gửi vào; Traefik cung cấp host và URI ban đầu cho oauth2-proxy. Tùy chọn này đã deprecated trong tài liệu Traefik hiện tại. Đặt whitelist_domains để bao phủ cả host đó; nếu không, oauth2-proxy sẽ loại bỏ tham số rd vì coi đó là rủi ro open redirect, và mọi người sẽ được đưa đến / sau khi đăng nhập. Một máy chủ Traefik thường đứng trước nhiều app cùng lúc, và định tuyến nhiều app Docker Compose qua một instance Traefik trình bày layout router mà cấu hình này tích hợp vào.
Caddy: forward_auth
app.example.com {
handle /oauth2/* {
reverse_proxy 127.0.0.1:4180 {
header_up X-Real-IP {remote_host}
header_up X-Forwarded-Uri {uri}
}
}
handle {
forward_auth 127.0.0.1:4180 {
uri /oauth2/auth
header_up X-Real-IP {remote_host}
copy_headers X-Auth-Request-User X-Auth-Request-Email
@error status 401
handle_response @error {
redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
}
}
reverse_proxy 127.0.0.1:3000
}
}Thứ tự ở đây rất quan trọng. Block /oauth2/* phải đứng trước và không có forward_auth, vì visitor chưa đăng nhập phải truy cập được các path sign-in và callback. Nếu đặt bước kiểm tra trước các path đó, login sẽ redirect về chính nó cho đến khi browser tự dừng.
copy_headers là phần đưa identity vào request gửi đến upstream, và chỉ tạo ra các giá trị khi oauth2-proxy chạy với set_xauthrequest = true. Việc chọn proxy nào là một câu hỏi riêng; phần so sánh nginx, Caddy và Traefik sẽ phân tích vấn đề này.
Vì sao đăng nhập lại quay về trang đăng nhập?
Bạn đăng nhập tại provider, provider chuyển bạn quay lại, rồi oauth2-proxy lại chuyển bạn về trang đăng nhập. Vòng lặp này có nghĩa là oauth2-proxy không chấp nhận session hợp lệ ở request tiếp theo. Cookie session có thể bị thiếu, hoặc có thể vẫn tồn tại nhưng không vượt qua bước xác thực, chẳng hạn khi các instance dùng cookie secret khác nhau. Mở developer tools của trình duyệt, tìm request đến /oauth2/callback ngay sau khi redirect quay lại từ provider, rồi đọc response header Set-Cookie. Cookie được set ở đó nhưng thiếu trong request tiếp theo chính là cookie mà trình duyệt đang từ chối. Nếu cookie vẫn có mặt, kiểm tra server log để tìm các lỗi xác thực như cookie signature not valid và xác nhận mọi instance dùng cùng một secret.
Khi cookie bị mất là CSRF cookie do oauth2-proxy set trong lúc chuyển hướng đi, flow sẽ không lặp. Flow dừng tại callback và log sẽ ghi rõ trường hợp này:
No cookies were found in OAuth callback.hoặc khi một cookie khác đã được gửi nhưng cookie đúng thì không:
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF là cross-site request forgery. Cookie này tồn tại để liên kết callback với lần đăng nhập đã khởi tạo callback đó. Trình duyệt hiển thị trang lỗi 403 có nội dung:
Login Failed: Unable to find a valid CSRF token. Please try again.Các cookie bị thiếu có chung 3 nguyên nhân đầu tiên bên dưới; clock drift là một nguyên nhân khác gây lỗi xác thực. Kiểm tra 4 nguyên nhân này theo thứ tự.
cookie_secure = truetrong khi trình duyệt truy cập site qua HTTP thuần. Ngoại trừ localhost, trình duyệt sẽ không lưu cookie có thuộc tínhSecuretrên originhttp://, nên cookie này không bao giờ được gửi lại. Hãy cấu hình TLS (transport layer security) đúng cách, hoặc chỉ đặtcookie_secure = falsekhi test trên localhost.- Giá trị
cookie_domainskhông bao phủ hostname trong address bar..example.combao phủapp.example.comvà hoàn toàn không có tác dụng vớiapp.example.net. - Trình duyệt đang loại bỏ cookie. Extension tăng cường privacy hoặc cơ chế chặn third-party cookie có thể xóa
_oauth2_proxy_csrfgiữa outbound redirect và callback, hoặc xóa session cookie sau đó. - Clock drift. Nếu clock của server chạy nhanh hơn đáng kể so với provider, ID token có thể bị xem là đã hết hạn và không vượt qua bước xác thực.
timedatectlphải báo cáoSystem clock synchronized: yes.
Một nguyên nhân khác có thể tạo lỗi CSRF dù không có cấu hình nào sai. Theo mặc định, oauth2-proxy giữ một CSRF cookie duy nhất, nên 2 tab bắt đầu đăng nhập cùng lúc sẽ ghi đè cookie của nhau. cookie_csrf_per_request = true tạo cookie riêng cho từng lần đăng nhập.
Hãy theo dõi quá trình này từ phía server thay vì đoán:
sudo journalctl -u oauth2-proxy -fMở app trong cửa sổ private. Mọi request đều được ghi log cùng với status của nó, vì vậy callback ngay sau đó được chuyển hướng tiếp về trang đăng nhập chính là vòng lặp này trong log.
Các path phải bỏ qua bước đăng nhập: API, webhook và websocket
Forward auth giả định browser đang giữ một cookie. Client không có browser sẽ bị lỗi.
API client gửi Authorization: Bearer <token> không có cookie, nên các cấu hình proxy ở trên sẽ chuyển nó đến trang đăng nhập của oauth2-proxy, trừ khi đã bật xác thực bằng bearer token. Có 2 cách xử lý rõ ràng. Đặt skip_jwt_bearer_tokens = true để oauth2-proxy chấp nhận bearer token JWT (JSON web token) hợp lệ từ issuer đã cấu hình, với audience được chấp nhận cho client này. Cách này phù hợp khi API client đã nhận được token phù hợp từ provider. aud của token phải khớp với client_id hoặc một audience được cấu hình qua extra_jwt_issuers. Nếu không, hãy miễn xác thực cho path:
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]Mỗi giá trị là một regular expression được đối chiếu với path đã giải mã, không gồm query parameter, và có thể có tiền tố là HTTP method cùng với =. POST=^/webhook/ để webhook receiver nhận request POST mà không cần đăng nhập, trong khi người dùng truy cập cùng path bằng browser vẫn phải qua bước đăng nhập, với điều kiện authentication request giữ nguyên method ban đầu. Nginx auth_request và Caddy forward_auth thực hiện kiểm tra bằng GET, nên các exemption theo method cần được định tuyến riêng tại reverse proxy trong các cấu hình đó. Mỗi entry là một lỗ hổng trong lớp bảo vệ của bạn, vì vậy hãy neo các expression bằng ^ và giới hạn phạm vi của chúng ở mức hẹp nhất mà caller cho phép.
Hãy chạy v7.15.5 hoặc mới hơn trước khi dựa vào các thiết lập này. Các release trước đó, từ v7.5.0 trở đi, có thể bị đánh lừa để miễn xác thực cho một path được bảo vệ bằng request sử dụng dot segment, doubled leading slash hoặc semicolon (advisory GHSA-63jm-59jj-478j); việc neo các expression cũng không ngăn được lỗi này. Release đã sửa lỗi sẽ từ chối miễn xác thực cho các path không rõ ràng như vậy, vì thế hãy kiểm tra các public route vẫn match sau khi upgrade.
Websocket là trường hợp thường bị cấu hình sai. Request upgrade là một HTTP GET thông thường và mang cùng cookie như các request khác, nên vẫn qua bước kiểm tra bình thường và không cần exemption. Vấn đề nằm ở phần proxying xung quanh nó. Nếu location được bảo vệ không có các header Upgrade và Connection, quá trình upgrade sẽ không hoàn tất và client của app sẽ retry vô hạn, kèm thông báo WebSocket connection ... failed trong browser console. Miễn xác thực cho path không giải quyết được vấn đề này vì request đã được authorize.
Có một giới hạn thực tế cần lưu ý. Bước kiểm tra chỉ chạy một lần, tại thời điểm upgrade. Websocket mở trong nhiều giờ sẽ không được kiểm tra lại, vì vậy việc xóa user khỏi provider không đóng socket mà user đó đã mở. Hãy restart app để ngắt các connection đang hoạt động.
Lưu trữ session và cookie phình quá lớn
Theo mặc định, toàn bộ session nằm trong cookie và được mã hóa bằng cookie_secret. Cách này giúp oauth2-proxy không cần lưu trạng thái và không cần thêm service. Tuy nhiên, cookie có giới hạn vì trình duyệt thường giới hạn kích thước cookie gần 4 KB. Khi ID token chứa danh sách dài các group claim, oauth2-proxy sẽ chia session thành _oauth2_proxy_0, _oauth2_proxy_1 và các phần tiếp theo. Khi có quá nhiều phần, request header sẽ lớn đến mức nginx trả về 400 Request Header Or Cookie Too Large trước khi ứng dụng nhận được request.
Khi gặp trường hợp này, hãy chuyển session sang lưu phía server:
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"Khi đó, trình duyệt chỉ giữ một ticket ngắn, còn session đã mã hóa nằm trong Redis. Đổi lại, bạn phải duy trì một service luôn hoạt động. Nếu Redis ngừng hoạt động, oauth2-proxy không thể tải session. Nếu dữ liệu session đã lưu bị mất, tất cả người dùng phải đăng nhập lại. Cookie store cũng có một vấn đề riêng: hai request cùng refresh một session tại cùng thời điểm có thể xung đột và buộc người dùng đăng nhập lại.
Forward auth không cung cấp những gì
Đây là cổng kiểm soát ở phía trước. Nó không phải là cơ chế phân quyền bên trong ứng dụng. Sự khác biệt này quyết định cách tiếp cận có phù hợp với trường hợp của bạn hay không.
Sau khi người dùng đi qua cổng, ứng dụng vẫn thấy đúng những gì nó luôn thấy. Nếu ứng dụng có role riêng, forward auth không tự điền các role đó, trừ khi ứng dụng hỗ trợ xác thực dựa trên header và ánh xạ một header vào một account. Grafana hỗ trợ việc này thông qua các thiết lập auth.proxy. Phần lớn ứng dụng tự host không hỗ trợ, nên mọi người đi qua cổng đều là cùng một identity duy nhất đối với ứng dụng. Identity đó thường là admin.
Forward auth cũng không bảo vệ các API token riêng của ứng dụng. Personal access token do ứng dụng cấp dùng để xác thực với ứng dụng, không phải với oauth2-proxy. Vì vậy token sẽ ngừng hoạt động ngay khi cổng được đặt phía trước nó. Nếu exempt API path để token hoạt động lại, token đó trở thành thứ duy nhất bảo vệ path. Khi đó, bạn chạy hai hệ thống xác thực trên cùng một service và SSO chỉ bao phủ một trong hai hệ thống.
Revocation là khoảng trống thứ ba. Xóa user khỏi provider sẽ chặn các lần đăng nhập mới, nhưng oauth2-proxy không kiểm tra session hiện tại với provider cho đến khi cookie_refresh đến hạn. Khi tắt refresh, session cookie vẫn hợp lệ cho đến khi hết hạn. cookie_expire mặc định là 168 hours, tức có thể cho người vừa bị xóa tiếp tục truy cập trong một tuần. Đặt cookie_refresh thành một khoảng ngắn, chẳng hạn một giờ. Khi provider từ chối refresh vì refresh token của user không còn hợp lệ, oauth2-proxy sẽ xóa session và buộc đăng nhập lại trong request tiếp theo có thực hiện refresh. Không phải provider nào cũng hỗ trợ refresh, nên hãy kiểm tra với provider bạn đang dùng.
Audit trail cũng chỉ dừng ở cổng. oauth2-proxy ghi log ai đã đi qua và vào thời điểm nào. Ứng dụng ghi log một session không có tên. Nếu cần xác định ai đã thay đổi một thiết lập, header identity trong ứng dụng là mức tối thiểu. Câu trả lời đúng về mặt vận hành là dùng account riêng cho từng user.
Khi trả phí cho SSO là lựa chọn tốt hơn
Forward auth phù hợp khi ứng dụng hoàn toàn không có đăng nhập hoặc chỉ dùng chung một mật khẩu, và bạn muốn có một nơi duy nhất để thêm hoặc xóa người dùng. Cách này mất khoảng một buổi chiều để triển khai và cần thêm một process, nhưng hoạt động với mọi ứng dụng dùng HTTP.
Forward auth không phù hợp khi những người khác nhau cần các quyền khác nhau trong cùng một ứng dụng. Một lớp kiểm soát không thể diễn đạt rằng “Ana được sửa các dashboard còn Bo chỉ được xem”. Nếu vendor bán gói SSO, tính năng ánh xạ group sang role thường là thứ bạn thực sự đang mua. Tự dựng lại bằng header và proxy rule dễ lỗi hơn so với việc trả phí cho tính năng đó. Mô hình giá đứng sau các gói SSO này đáng đọc trước khi bạn quyết định.
Mọi ứng dụng có mobile client hoặc desktop client không gửi kèm browser cookie sẽ phải xác thực với lớp kiểm soát này trong từng request.
FAQ
Forward auth là gì?
Forward auth là một mô hình trong đó reverse proxy hỏi một authentication service riêng về từng request đến trước khi chuyển tiếp request đó đến upstream. Proxy gửi request header đến một endpoint như /oauth2/auth rồi đọc status code. 202 nghĩa là được phép, nên request ban đầu được chuyển tiếp đến application. 401 nghĩa là không có session hợp lệ, nên proxy redirect browser đến trang đăng nhập. Nginx triển khai tính năng này bằng directive auth_request, Traefik dùng middleware forwardAuth, còn Caddy dùng forward_auth.
Vì sao oauth2-proxy redirect tôi quay lại trang đăng nhập theo vòng lặp?
Session cookie bị thiếu hoặc không vượt qua bước xác thực, nên mỗi lần kiểm tra đều không tìm thấy session hợp lệ và đưa bạn quay lại trang đăng nhập. Các instance dùng cookie secret khác nhau sẽ từ chối cookie của nhau. Một nguyên nhân khác là cookie_secure = true trên một site mà browser truy cập qua HTTP thuần, vì ngoài localhost, browser sẽ không lưu cookie Secure trên một origin http://. Bạn cũng cần kiểm tra giá trị cookie_domains có bao phủ hostname trong thanh địa chỉ hay không. Đọc header Set-Cookie trên response /oauth2/callback trong developer tools của browser để xem cookie nào bị thiếu. Nếu cookie được gửi lại, hãy kiểm tra server log để tìm lỗi xác thực. Nếu cookie CSRF bị thiếu, bạn sẽ nhận trang 403 với nội dung Login Failed: Unable to find a valid CSRF token. Please try again. thay vì gặp vòng lặp, và log sẽ ghi No cookies were found in OAuth callback. khi không có cookie nào được gửi đến.
Làm thế nào để cho phép API client hoặc webhook đi qua oauth2-proxy?
Dùng skip_auth_routes với regular expression có anchor, có thể giới hạn theo một HTTP method, ví dụ POST=^/webhook/, và chạy v7.15.5 hoặc mới hơn. Bản này đã sửa một lỗi bypass nghiêm trọng liên quan đến các exemption này. Exemption theo method yêu cầu authentication request giữ nguyên method ban đầu. Các ví dụ cho nginx và Caddy thực hiện check bằng GET, nên hãy xử lý các exemption đó trong routing của reverse proxy. Nếu API client của bạn đã có JWT hợp lệ do provider đã cấu hình phát hành và có audience được chấp nhận, skip_jwt_bearer_tokens = true sẽ chấp nhận các token đó thay cho cookie và vẫn bảo vệ path. Audience phải khớp với client_id hoặc audience được cấu hình qua extra_jwt_issuers. Mọi thứ được liệt kê trong skip_auth_routes đều không cần authentication đối với tất cả mọi người, nên hãy giữ mỗi expression hẹp nhất theo phạm vi caller cho phép.
oauth2-proxy có cấp quyền theo từng user cho application không?
Không. Nó là một cổng kiểm soát, không phải hệ thống authorisation. Nó quyết định ai được truy cập application. Với application, mọi người đã qua cổng đều giống nhau, trừ khi application đọc identity header và ánh xạ chúng vào các account. Grafana hỗ trợ việc này qua các setting auth.proxy. Phần lớn self-hosted app không hỗ trợ, nên mọi người qua được cổng sẽ dùng chung identity duy nhất mà app đang chạy.
Có thể bypass oauth2-proxy bằng cách tự đặt identity header không?
Có, nếu họ truy cập trực tiếp được vào application. Identity được truyền dưới dạng header thuần như X-Auth-Request-Email, và application tin mọi giá trị nhận được. Bất kỳ ai mở được connection đến application port đều có thể gửi header đó và giả danh bất kỳ user nào. Hãy bind app vào 127.0.0.1, hoặc giữ app trên một internal Docker network không có published port, rồi xác nhận bằng sudo ss -tlnp.