oauth2-proxy로 모든 앱에 SSO 적용하기
로그인 기능이 없는 애플리케이션을 OIDC 기반 SSO 환경으로 전환하는 방법을 설명합니다. Nginx와 Traefik에서 Forward Auth를 설정하여 쿠키와 리다이렉트 오류를 방지하고, 안전하게 인증을 처리하는 구체적인 아키텍처와 보안 주의사항을 확인하십시오.
Forward auth: 로그인 기능이 없는 애플리케이션에 SSO 적용하기
oauth2-proxy는 자체 로그인 기능이 없는 애플리케이션에 single sign-on을 제공한다. 이 방식은 애플리케이션 앞의 리버스 프록시가 모든 요청을 중단하고, 해당 요청에 유효한 세션이 있는지 oauth2-proxy에 확인한 다음, 확인 결과가 성공인 경우에만 upstream으로 요청을 전달하기 때문에 동작한다. 애플리케이션은 이 확인 절차를 전혀 인식하지 않으므로 애플리케이션 코드를 변경할 필요가 없다.
확인 과정에는 추가 HTTP 요청이 1개 필요하다. 프록시는 수신한 요청 헤더의 복사본을 /oauth2/auth으로 보내고 상태 코드를 읽는다. 202이면 확인이 통과된 것이므로 프록시는 원래 요청을 애플리케이션으로 전달한다. 401이면 유효한 세션이 없는 것이므로 프록시는 브라우저를 /oauth2/sign_in으로 보낸다. /oauth2/sign_in은 기본적으로 로그인 페이지를 표시한다. /oauth2/start은 identity provider에서 OpenID Connect (OIDC) 로그인을 시작한다. skip_provider_button = true을 사용하면 /oauth2/sign_in이 자동으로 로그인을 시작한다. OIDC는 OAuth 2.0 위에 구축된 identity layer이며, provider는 이미 로그인에 사용 중인 시스템이면 된다.
이 패턴은 모든 리버스 프록시에서 고유한 이름으로 제공된다. Nginx에서는 directive를 auth_request이라고 한다. Traefik에서는 middleware를 forwardAuth이라고 한다. Caddy에서는 forward_auth으로 표기한다. Sub-request에 응답하는 서비스도 서로 교체할 수 있다. oauth2-proxy가 일반적으로 사용되는 이유는 별도의 데이터베이스 없이 일반 OIDC를 지원하기 때문이다.
구성을 작성하기 전에 신뢰 경계를 그린다
검사가 성공하면 oauth2-proxy는 응답 헤더로 ID를 반환하고, 리버스 프록시는 이 헤더를 upstream 요청에 복사한다. set_xauthrequest을 활성화하면 X-Auth-Request-User과 X-Auth-Request-Email을 얻는다. 애플리케이션은 이 헤더를 읽고 신뢰한다.
이것이 전체 보안 모델이므로 그 결과를 명확히 밝혀야 한다. 애플리케이션 포트에 TCP 연결을 열 수 있는 대상은 누구나 이 헤더를 직접 설정하고 임의의 사용자가 될 수 있다. curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/ 하나만 애플리케이션에 직접 도달해도 인증을 완전히 우회할 수 있다.
따라서 애플리케이션은 프록시를 통해서만 연결할 수 있어야 한다. Docker Compose에서는 앱 서비스의 ports: 매핑을 삭제하고 앱을 내부 네트워크에만 둔다. 그러면 프록시 컨테이너만 앱에 연결할 수 있다. 베어 호스트에서는 앱을 0.0.0.0:3000 대신 127.0.0.1:3000에 바인딩한다. 그런 다음 실제로 무엇을 외부에 노출했는지 확인한다.
sudo ss -tlnp | grep 30000.0.0.0:3000로 표시된 행은 앱이 공인 IP에서 응답한다는 뜻이며, 이 경우 게이트는 장식에 불과하다. 원하는 값은 127.0.0.1:3000이다. 방화벽 규칙은 유용한 두 번째 방어 계층이지만, 다른 도구가 규칙 세트를 초기화한 뒤에도 유지되는 것은 바인드 주소다.
oauth2-proxy 설치
2026년 10월 기준으로 최신 릴리스는 2026년 10월 1일에 배포된 v7.15.5입니다. 이 버전은 두 가지 치명적인 보안 권고 사항을 해결하며, 그중 하나는 v7.5.0 이후의 모든 릴리스에 영향을 미치는 skip_auth_routes 우회 취약점이므로 이전 버전을 설치하지 마십시오. 바이너리를 설치하고 다운로드 파일을 검증합니다.
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은 OK로 끝나는 행을 출력해야 합니다. 만약 FAILED가 출력된다면, 작업을 중단하고 바이너리를 실행하는 대신 다시 다운로드하십시오.
Docker 환경에서의 이미지는 quay.io/oauth2-proxy/oauth2-proxy이며, 태그를 quay.io/oauth2-proxy/oauth2-proxy:v7.15.5로 고정해야 합니다. 태그를 latest로 두면 일상적인 docker compose pull 작업이 서버의 모든 애플리케이션을 보호하는 프로세스에 대한 예기치 않은 업그레이드로 변질될 수 있습니다.
쿠키 시크릿 생성
세션 쿠키는 암호화되며, cookie_secret이 암호화 키입니다. 암호화 키는 AES(advanced encryption standard) 키로 사용되므로 정확히 16, 24 또는 32바이트여야 합니다. oauth2-proxy는 디코딩 결과가 이 길이 중 하나가 되는 URL-safe base64 값이나, 이 길이 중 하나인 원시 시크릿을 허용합니다. 그렇지 않으면 쿠키 시크릿을 명시하는 시작 오류와 함께 시작을 거부합니다. 아래 명령은 32바이트 키를 인코딩한 44자 값을 생성합니다.
openssl rand -base64 32 | tr -- '+/' '-_'tr은 단순한 형식 지정이 아닙니다. 이 값은 표준 base64를 oauth2-proxy가 시크릿을 디코딩할 때 사용하는 URL-safe 알파벳으로 변환합니다.
이 값에는 두 가지 규칙이 있습니다. 배포마다 다른 시크릿을 사용해야 합니다. 또한 동일한 도메인 뒤에서 oauth2-proxy 인스턴스를 2개 이상 실행하는 경우에는 모든 인스턴스에 동일한 시크릿을 지정해야 합니다. 한 인스턴스가 암호화한 쿠키를 다른 인스턴스가 읽어야 하기 때문입니다.
oauth2-proxy 설정 작성하기
긴 명령줄 대신 파일에 설정을 유지하여 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은 oauth2-proxy가 앞단 프록시에서 전달된 X-Forwarded-* 헤더를 신뢰하도록 지시합니다. 이 설정이 없으면 oauth2-proxy는 프록시의 주소를 클라이언트 주소로 간주하며, 요청이 HTTPS를 통해 전달되었는지 잘못 판단할 수 있습니다.
trusted_proxy_ips은 해당 헤더를 제공할 수 있는 피어를 제한합니다. 기본값은 모든 소스를 신뢰하는데, 여기서는 http_address이 oauth2-proxy를 127.0.0.1에 유지하기 때문에 안전합니다. oauth2-proxy가 Docker 네트워크에서 수신 대기하는 경우에는 이를 리버스 프록시의 주소로 설정하십시오.
upstreams = ["static://202"]은 인증된 요청에 대해 oauth2-proxy가 202를 응답하고 아무것도 프록시하지 않게 만듭니다. 리버스 프록시가 프록시 역할을 수행하므로 이는 forward auth에 정확히 필요한 동작입니다. 다른 배포 형태는 oauth2-proxy를 upstreams = ["http://127.0.0.1:3000"]와 함께 요청 경로에 직접 배치하며 auth_request를 전혀 사용하지 않습니다. 이는 단일 애플리케이션에는 더 간단하지만 10개 이상의 서비스로 확장하기에는 적합하지 않습니다.
email_domains = ["*"]은 제공자가 인증할 모든 주소를 허용합니다. 이를 자신의 도메인으로 좁히거나, 더 나은 방법으로 제공자 측의 그룹 바인딩을 통해 접근을 제한하십시오. 사용자 관리는 이미 제공자 측에서 수행하고 있기 때문입니다.
systemd 하에서 별도의 사용자로 실행하십시오:
# /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이 OK을 출력한다면 프로세스가 시작되었고 설정이 로드되었음을 의미합니다. 이는 oauth2-proxy 자체의 상태 확인 엔드포인트이며 세션을 요구하지 않습니다. 아무런 응답이 없다면 journalctl -u oauth2-proxy -n 50를 읽어보십시오. 잘못된 발급자 URL이나 잘못된 길이의 쿠키 비밀값은 시작 시 실패를 유발하며, 로그에 그 이유가 기록됩니다.
제공자에 리디렉션 URI 등록
제공자에서 OIDC 애플리케이션을 만들고 리디렉션 URI를 구성의 redirect_url, 즉 https://app.example.com/oauth2/callback과 정확히 일치하도록 설정한다. 정확히 일치한다는 것은 스킴, 호스트, 포트, 경로가 문자 단위로 모두 같아야 한다는 뜻이다. 후행 슬래시 하나만 있어도 다른 URI로 간주된다.
이 문제는 전체 설정에서 가장 흔한 실패 원인이다. 또한 oauth2-proxy가 전혀 관여하기 전에 실패한다. 제공자는 인증 요청을 거부하고 자체 오류 페이지를 표시하므로 oauth2-proxy 로그에는 아무것도 나타나지 않는다. 주소 표시줄을 보면 이를 확인할 수 있다. 브라우저가 여전히 제공자의 도메인에 있고, 쿼리 문자열에 error=invalid_request가 포함되어 있거나 페이지에 redirect_uri가 직접 표시된다. 이 경우 프록시 설정이 아니라 제공자의 애플리케이션 레코드를 수정한다.
issuer URL은 직접 입력하지 말고 제공자에서 복사한다. oauth2-proxy는 oidc_issuer_url에 /.well-known/openid-configuration을 추가하고 시작할 때 해당 discovery 문서를 가져온다. 먼저 직접 확인한다.
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400authorization_endpoint 키가 포함된 JSON인지 먼저 확인한다. 문서의 issuer도 oidc_issuer_url과 정확히 일치해야 한다. 404 또는 HTML 오류 페이지가 반환되면 잘못된 URL이다. oauth2-proxy도 동일한 404에서 시작하지 못한다. 아직 제공자를 선택하지 않았다면 Keycloak, Authentik, Zitadel 비교에서 각 선택지의 장단점을 확인할 수 있다. Authentik을 자체 SSO 서버로 운영하기에서는 이 설정에서 제공자 부분을 단계별로 설명한다.
Nginx: auth_request
Nginx는 auth_request을 사용해 forward auth를 수행한다. 이 지시어는 내부 sub-request를 실행하고 상태 코드에 따라 분기한다.
# 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;
}
}여기에는 중요한 세부 사항이 3가지 있다. 빈 Content-Length과 함께 사용하는 proxy_pass_request_body off은 nginx가 인증 엔드포인트로 request body를 전달하지 않도록 한다. 인증 엔드포인트에는 헤더만 필요하다.
auth_request_set $auth_cookie와 add_header Set-Cookie의 조합은 갱신된 session cookie를 브라우저로 전달한다. 이를 생략하면 cookie_refresh은 조용히 아무 작업도 하지 않는다. nginx가 sub-request의 Set-Cookie을 버리기 때문이다. 그러면 session이 만료될 때까지 브라우저에는 이전 값이 남는다. 이 조합은 cookie 1개를 처리한다. session cookie를 여러 개로 나누어 사용하는 경우 다른 부분을 처리하려면 추가 설정이 필요하거나 Redis session storage를 사용해야 한다.
error_page 401 = @oauth2_signin은 실패한 검사를 login으로 전환한다. 이 설정이 없으면 인증되지 않은 방문자에게 내용이 없는 401 Authorization Required 페이지만 표시되며, 진행할 방법이 없다.
항상 reload하기 전에 테스트한다.
sudo nginx -t && sudo systemctl reload nginx주변 지시어가 익숙하지 않다면 nginx reverse proxy 설정의 구성에서 이 계층의 기반을 설명한다.
Traefik: forwardAuth 미들웨어
Traefik에는 같은 작업을 위해 2개의 미들웨어가 필요하다. 하나는 검사를 수행한다. 다른 하나는 검사가 실패할 때 로그인 페이지를 제공한다.
# 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}"애플리케이션 앞에 있는 router에 두 미들웨어를 모두 연결하되, oauth-errors을 oauth-auth보다 앞에 배치한다. 또한 oauth2-proxy를 oauth.example.com에서 별도의 router로 공개해야 한다. 브라우저가 검사 없이 /oauth2/sign_in 및 /oauth2/callback에 접근해야 하기 때문이다. 이 별도의 로그인 호스트에는 redirect_url을 https://oauth.example.com/oauth2/callback으로 설정하고, 해당 URI를 provider에 등록한다.
위의 oauth2-proxy 설정을 사용하면 /oauth2/sign_in이 로그인 페이지를 렌더링한다. 대신 자동 리디렉션을 사용하려면 oauth2-proxy에서 skip_provider_button = true을 설정하고 Traefik의 errors 설정 아래에 statusRewrites: {"401": 302}을 추가한다. 이 재작성 설정이 없으면 Traefik은 자동 리디렉션을 401 상태로 반환하며 브라우저는 이를 따르지 않는다. 재작성만으로는 로그인 흐름이 시작되지 않는다.
trustForwardHeader: true은 수신된 X-Forwarded-* 헤더를 신뢰한다. Traefik은 원래 host와 URI를 oauth2-proxy에 제공한다. 현재 Traefik 문서에서는 이 옵션을 deprecated로 분류한다. 해당 호스트도 포함하도록 whitelist_domains을 설정해야 한다. 그렇지 않으면 oauth2-proxy가 open redirect 위험을 이유로 rd 매개변수를 삭제하며, 로그인 후 모든 사용자가 /에 도착한다. Traefik 서버는 보통 여러 애플리케이션을 동시에 앞단에서 처리하며, 여러 Docker Compose 애플리케이션을 하나의 Traefik 인스턴스로 라우팅하기에서 이 설정이 연결되는 router 구성을 설명한다.
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
}
}여기서는 순서가 중요하다. /oauth2/* 블록이 먼저 오며 forward_auth가 없다. 로그인하지 않은 방문자도 sign-in 및 callback 경로에 도달해야 하기 때문이다. 이 경로 앞에 검사를 배치하면 브라우저가 포기할 때까지 로그인 리다이렉트가 자기 자신을 반복한다.
copy_headers는 upstream 요청에 identity를 전달한다. 단, oauth2-proxy가 set_xauthrequest = true와 함께 실행될 때만 값을 생성한다. 프록시 중 하나를 선택하는 문제는 별도로 다뤄야 하며, nginx, Caddy 및 Traefik 비교에서 이를 설명한다.
로그인이 로그인 페이지로 계속 돌아가는 이유는 무엇입니까?
인증 제공자에서 로그인하면 인증 제공자가 사용자를 다시 돌려보내고, oauth2-proxy가 다시 로그인 페이지로 보냅니다. 이 루프는 다음 요청에서 oauth2-proxy가 유효한 세션을 받아들이지 않는다는 뜻입니다. 세션 쿠키가 없거나, 쿠키가 있어도 검증에 실패할 수 있습니다. 예를 들어 인스턴스마다 다른 쿠키 비밀값을 사용할 때 발생합니다. 브라우저의 개발자 도구를 열고, 인증 제공자가 리디렉션한 뒤 /oauth2/callback로 전송되는 요청을 찾은 다음 해당 응답의 Set-Cookie 헤더를 확인합니다. 여기서 설정되었지만 다음 요청에 없는 쿠키가 브라우저에서 거부한 쿠키입니다. 쿠키가 있다면 서버 로그에서 cookie signature not valid와 같은 검증 오류를 확인하고, 모든 인스턴스가 동일한 비밀값을 사용하는지 확인합니다.
없어진 쿠키가 oauth2-proxy가 리디렉션을 시작할 때 설정한 CSRF 쿠키라면 흐름이 루프를 이루지 않습니다. 콜백에서 중단되며 로그에 다음 사례가 기록됩니다.
No cookies were found in OAuth callback.다른 쿠키는 도착했지만 필요한 쿠키가 도착하지 않은 경우에는 다음과 같이 기록됩니다.
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF는 사이트 간 요청 위조를 뜻합니다. 이 쿠키는 콜백을 해당 로그인을 시작한 요청과 연결하기 위해 존재합니다. 브라우저에는 다음 내용이 포함된 403 오류 페이지가 표시됩니다.
Login Failed: Unable to find a valid CSRF token. Please try again.쿠키 누락의 첫 3가지 원인은 아래와 같습니다. 시계 오차는 검증 실패를 일으키는 또 다른 원인입니다. 다음 4가지를 순서대로 확인합니다.
- 브라우저가 일반 HTTP로 사이트에 접속했는데
cookie_secure = true이 설정된 경우입니다. localhost가 아니면 브라우저는http://origin에서Secure로 표시된 쿠키를 저장하지 않으므로 쿠키가 다시 전송되지 않습니다. TLS(transport layer security)를 올바르게 종료하거나, localhost에서 테스트할 때만cookie_secure = false을 설정합니다. - 주소 표시줄의 호스트 이름을 포함하지 않는
cookie_domains값입니다..example.com은app.example.com을 포함하지만app.example.net에는 전혀 적용되지 않습니다. - 브라우저가 쿠키를 삭제하는 경우입니다. 엄격한 개인정보 보호 확장 기능이나 타사 쿠키 차단 기능이 리디렉션 시작과 콜백 사이에
_oauth2_proxy_csrf을 삭제할 수 있습니다. 그 이후에는 세션 쿠키도 삭제할 수 있습니다. - 시계 오차입니다. 서버 시계가 인증 제공자보다 크게 앞서 있으면 ID 토큰이 만료된 것으로 판단되어 검증에 실패할 수 있습니다.
timedatectl에서System clock synchronized: yes을 보고해야 합니다.
구성이 잘못되지 않았는데도 CSRF 오류가 발생하는 원인이 하나 더 있습니다. 기본적으로 oauth2-proxy는 CSRF 쿠키 하나만 유지하므로, 두 탭이 동시에 로그인을 시작하면 서로의 쿠키를 덮어씁니다. cookie_csrf_per_request = true을 사용하면 로그인마다 별도의 쿠키가 생성됩니다.
추측하지 말고 서버 측에서 실제 발생 과정을 확인합니다.
sudo journalctl -u oauth2-proxy -f비공개 창에서 애플리케이션을 엽니다. 모든 요청이 상태 코드와 함께 로그에 기록되므로, 콜백 직후 다시 로그인으로 리디렉션되는 요청을 로그에서 확인할 수 있습니다. 해당 요청이 바로 이 루프입니다.
로그인을 건너뛰어야 하는 경로: API, 웹훅, 웹소켓
Forward auth는 쿠키를 보유한 브라우저를 전제로 한다. 브라우저를 사용하지 않는 호출자는 정상적으로 처리되지 않는다.
Authorization: Bearer <token>를 전송하는 API 클라이언트에는 쿠키가 없다. 따라서 bearer-token 인증을 활성화하지 않으면 위의 프록시 설정은 해당 클라이언트를 oauth2-proxy의 로그인 페이지로 보낸다. 해결 방법은 2가지다. skip_jwt_bearer_tokens = true을 설정하면 oauth2-proxy가 구성된 issuer에서 발급되고 이 클라이언트에 허용된 audience를 포함하는 유효한 JWT(JSON 웹 토큰) bearer token을 수락한다. API 클라이언트가 이미 provider에서 적절한 토큰을 받는 경우에 적합하다. 토큰의 aud은 client_id 또는 extra_jwt_issuers를 통해 구성한 audience와 일치해야 한다. 그렇지 않으면 해당 경로를 예외로 처리한다.
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]각 값은 쿼리 매개변수를 제외하고 디코딩된 경로에 대조하는 정규 표현식이다. 정규 표현식 앞에는 HTTP method와 =을 선택적으로 지정할 수 있다. POST=^/webhook/을 사용하면 웹훅 수신기는 POST 요청에 대해 열어 두면서, 동일한 경로를 브라우저에서 방문한 사용자는 로그인 절차를 거치게 할 수 있다. 단, authentication request가 원래 method를 보존해야 한다. Nginx의 auth_request와 Caddy의 forward_auth은 GET 검사를 수행하므로, 이러한 설정에서 method별 예외를 적용하려면 reverse proxy에서 별도의 라우팅이 필요하다. 모든 항목은 게이트에 생기는 예외이므로, 표현식에 ^을 사용해 양쪽을 고정하고 호출자에게 필요한 범위로 최대한 좁게 유지한다.
이 기능을 사용하기 전에 v7.15.5 이상을 실행한다. v7.5.0 이후의 이전 release에서는 점 세그먼트, 중복된 선행 슬래시 또는 세미콜론을 포함한 요청으로 보호된 경로를 예외 처리하도록 속일 수 있었다(GHSA-63jm-59jj-478j advisory). 표현식을 고정해도 이를 막을 수 없었다. 수정된 release에서는 이러한 모호한 경로를 예외 처리하지 않으므로, upgrade 후 공개 경로가 여전히 일치하는지 확인한다.
웹소켓은 자주 잘못 처리되는 부분이다. upgrade 요청은 다른 요청과 동일한 쿠키를 포함하는 일반 HTTP GET이므로 정상적으로 검사를 통과하며 예외가 필요하지 않다. 문제는 그 주변의 proxy 설정에서 발생한다. 보호된 location에 Upgrade 및 Connection header가 없으면 upgrade가 완료되지 않는다. 그 결과 애플리케이션의 client가 계속 재시도하고 브라우저 console에 WebSocket connection ... failed 메시지가 표시된다. 이 경우 요청은 이미 인증된 상태이므로 경로를 예외 처리해도 문제가 해결되지 않는다.
실제로 적용되는 한 가지 제한이 있다. 검사는 upgrade 시점에 한 번만 실행된다. 몇 시간 동안 열린 websocket은 다시 검사하지 않으므로 provider에서 사용자를 제거해도 이미 해당 사용자가 보유한 socket은 닫히지 않는다. 연결을 종료하려면 애플리케이션을 재시작한다.
세션 저장소와 너무 커지는 쿠키
기본적으로 전체 세션은 cookie_secret로 암호화되어 쿠키 안에 저장된다. 따라서 oauth2-proxy는 상태 비저장 방식으로 동작하며 별도의 서비스가 필요하지 않다. 그러나 브라우저가 쿠키 크기를 약 4 KB로 제한하므로 한계가 있다. ID 토큰에 group claim이 긴 목록으로 포함되면 oauth2-proxy는 세션을 _oauth2_proxy_0, _oauth2_proxy_1 및 그 이후의 쿠키로 분할한다. 분할된 쿠키가 몇 개를 넘으면 요청 헤더가 너무 커져 애플리케이션이 요청을 받기도 전에 nginx가 400 Request Header Or Cookie Too Large을 반환한다.
이 경우 세션을 서버 측으로 이동한다.
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"그러면 브라우저에는 짧은 티켓만 저장되고 암호화된 세션은 Redis에 저장된다. 대신 계속 실행되어야 하는 서비스가 필요하다. Redis가 중단되면 oauth2-proxy가 세션을 불러올 수 없다. 저장된 세션 데이터가 손실되면 모든 사용자가 다시 로그인해야 한다. 쿠키 저장소에도 고유한 문제가 있다. 같은 세션을 갱신하는 두 요청이 동시에 처리되면 충돌이 발생하여 다시 로그인해야 할 수 있다.
forward auth가 제공하지 않는 것
이것은 출입구의 게이트다. 애플리케이션 내부의 권한 부여는 아니다. 이 차이에 따라 이 방식이 사용 사례에 적합한지가 결정된다.
사용자가 게이트를 통과하면 애플리케이션은 이전과 같은 정보만 확인한다. 애플리케이션에 자체 역할이 있어도 forward auth가 이를 자동으로 채워 주지는 않는다. 애플리케이션이 헤더 기반 인증을 지원하고 헤더를 계정에 매핑하는 경우는 예외다. Grafana는 auth.proxy 설정을 통해 이를 지원한다. 대부분의 self-hosted 애플리케이션은 지원하지 않는다. 따라서 게이트를 통과한 모든 사용자는 애플리케이션에서 동일한 단일 ID로 취급되며, 이 ID가 관리자 계정인 경우가 많다.
애플리케이션 자체의 API 토큰도 보호하지 않는다. 애플리케이션이 발급한 personal access token은 oauth2-proxy가 아니라 애플리케이션에 인증한다. 따라서 게이트를 그 앞에 두는 순간 토큰은 작동하지 않는다. API 경로를 예외 처리해 토큰을 다시 사용하면, 해당 경로를 보호하는 수단은 그 토큰 하나뿐이 된다. 이제 하나의 서비스에서 2개의 인증 시스템을 운영하게 되며, SSO는 그중 하나에만 적용된다.
세 번째 공백은 폐기다. provider에서 사용자를 삭제하면 새 로그인을 차단할 수 있다. 그러나 oauth2-proxy는 cookie_refresh 시점이 될 때까지 기존 세션을 provider에 확인하지 않는다. refresh를 끄면 세션 쿠키는 만료될 때까지 유효하다. cookie_expire의 기본값은 168시간이므로, 방금 삭제한 사용자가 일주일 동안 계속 접근할 수 있다. cookie_refresh를 1시간처럼 짧은 값으로 설정한다. provider가 사용자의 refresh token이 더 이상 유효하지 않아 refresh를 거부하면 oauth2-proxy는 세션을 삭제한다. 이후 refresh를 시도하는 다음 요청에서 새 로그인을 요구한다. 모든 provider가 refresh를 지원하는 것은 아니므로 사용 중인 provider에서 테스트해야 한다.
감사 추적도 게이트에서 끝난다. oauth2-proxy는 누가 언제 통과했는지 기록한다. 애플리케이션은 이름이 없는 세션을 기록한다. 누가 설정을 변경했는지 확인해야 한다면, 애플리케이션에서 헤더의 ID를 기록하는 것이 최소 조건이다. 사용자별 실제 계정이 가장 정확한 해결책이다.
SSO 비용을 지불하는 편이 더 나은 경우
애플리케이션에 로그인 기능이 전혀 없거나 공용 비밀번호 하나만 있고, 사용자를 한 곳에서 추가하고 제거하려면 forward auth가 적합하다. 설정에 반나절과 별도의 프로세스 1개가 필요하지만, HTTP를 사용하는 모든 애플리케이션에서 동작한다.
같은 애플리케이션 안에서 사용자마다 서로 다른 권한이 필요하다면 적합하지 않다. 게이트만으로는 "Ana는 대시보드를 편집할 수 있고 Bo는 읽기만 할 수 있다"는 정책을 표현할 수 없다. 공급업체가 SSO 요금제를 판매한다면 일반적으로 실제로 구매하는 것은 그룹과 역할의 매핑이다. 이를 헤더와 프록시 규칙으로 다시 구현하는 것은 비용을 지불하는 것보다 더 취약하다. 어느 쪽을 선택할지 결정하기 전에 이러한 SSO 요금제의 가격 책정 방식을 읽어 보는 것이 좋다.
브라우저 쿠키를 전달하지 않는 모바일 또는 데스크톱 클라이언트가 있는 애플리케이션은 모든 요청에서 게이트와 충돌한다.
FAQ
전달 인증이란 무엇입니까?
전달 인증은 리버스 프록시가 모든 수신 요청을 upstream으로 전달하기 전에 별도의 인증 서비스에 인증 여부를 묻는 방식이다. 프록시는 요청 헤더를 /oauth2/auth 같은 엔드포인트로 보내고 상태 코드를 확인한다. 202는 허용을 의미하므로 원래 요청이 애플리케이션으로 전달된다. 401은 유효한 세션이 없다는 의미이므로 프록시는 브라우저를 로그인 페이지로 리다이렉트한다. Nginx에서는 auth_request 지시어로 구현하고, Traefik에서는 forwardAuth 미들웨어로 구현하며, Caddy에서는 forward_auth로 구현한다.
oauth2-proxy가 로그인 페이지로 계속 리다이렉트되는 이유는 무엇입니까?
세션 쿠키가 없거나 검증에 실패하므로, 모든 확인에서 유효한 세션이 없는 것으로 판단해 로그인 페이지로 돌려보낸다. 서로 다른 cookie secret을 사용하는 인스턴스는 상대방의 쿠키를 거부한다. 또 다른 원인은 브라우저가 일반 HTTP로 접속한 사이트에서 cookie_secure = true이 설정된 경우다. localhost를 제외하면 브라우저는 http:// origin에서 Secure 쿠키를 저장하지 않는다. 주소 표시줄의 호스트 이름을 포함하지 않는 cookie_domains 값이 설정되었는지도 확인한다. 브라우저 개발자 도구에서 /oauth2/callback 응답의 Set-Cookie 헤더를 확인하면 어떤 쿠키가 누락되는지 알 수 있다. 쿠키가 반환된다면 서버 로그에서 검증 오류를 확인한다. 누락된 쿠키가 CSRF 쿠키라면 루프 대신 Login Failed: Unable to find a valid CSRF token. Please try again.라고 표시되는 403 페이지가 나타난다. 쿠키가 하나도 전달되지 않았을 때 로그에는 No cookies were found in OAuth callback.이 기록된다.
API 클라이언트나 웹훅이 oauth2-proxy를 통과하도록 하려면 어떻게 해야 합니까?
skip_auth_routes을 앵커가 적용된 정규 표현식과 함께 사용한다. 필요하면 하나의 HTTP 메서드에만 적용할 수 있다. 예를 들면 POST=^/webhook/와 같이 설정하고, 이러한 예외의 치명적인 우회 문제를 수정한 v7.15.5 이상을 실행한다. 메서드별 예외를 사용하려면 인증 요청이 원래 메서드를 유지해야 한다. nginx와 Caddy 예제는 GET 확인을 수행하므로, 이러한 예외는 리버스 프록시의 라우팅에서 처리한다. API 클라이언트가 이미 구성된 provider가 발급한 유효한 JWT를 보유하고 있고 허용된 audience를 포함한다면, skip_jwt_bearer_tokens = true은 쿠키 대신 해당 토큰을 허용하므로 경로를 계속 보호할 수 있다. audience는 client_id과 일치하거나 extra_jwt_issuers을 통해 구성한 audience와 일치해야 한다. skip_auth_routes에 나열된 항목은 누구에게나 인증 없이 허용되므로, 각 표현식을 호출자가 허용하는 범위 내에서 최대한 좁게 유지한다.
oauth2-proxy가 애플리케이션에 사용자별 권한을 제공합니까?
아니다. oauth2-proxy는 관문이지 권한 부여 시스템이 아니다. 누가 애플리케이션에 도달할 수 있는지를 결정할 뿐이다. 애플리케이션이 identity header를 읽고 이를 계정에 매핑하지 않는 한, 도달한 모든 사용자는 애플리케이션에서 동일하게 보인다. Grafana는 auth.proxy 설정을 통해 이를 처리할 수 있다. 대부분의 self-hosted 애플리케이션은 이를 지원하지 않으므로, 관문을 통과한 모든 사용자는 애플리케이션이 사용하는 하나의 동일한 identity를 공유한다.
사용자가 직접 identity header를 설정해 oauth2-proxy를 우회할 수 있습니까?
그렇다. 사용자가 애플리케이션에 직접 접근할 수 있다면 가능하다. identity는 X-Auth-Request-Email 같은 일반 헤더로 전달되고, 애플리케이션은 수신한 값을 그대로 신뢰한다. 애플리케이션 포트에 연결할 수 있는 사람은 누구나 해당 헤더를 보내 원하는 사용자로 가장할 수 있다. 애플리케이션을 127.0.0.1에 바인딩하거나, published port가 없는 내부 Docker 네트워크에서 실행한다. 그런 다음 sudo ss -tlnp으로 이를 확인한다.