llm-wiki/raw/official-docs/oauth2-proxy-endpoints-official.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created, last_reviewed

title	source_type	url	archive_url	related_branches	related_projects	tags	created	last_reviewed
OAuth2 Proxy — Endpoints (Official Docs)	official-doc	https://oauth2-proxy.github.io/oauth2-proxy/features/endpoints/		feature-keycloak-nginx-auth-request-integration feature-keycloak-edge-forwardauth-no-google feature-keycloak-oauth2-proxy-oidc-flow	keycloak-patterns	official-doc keycloak-patterns auth oauth2-proxy nginx	2026-07-17	2026-07-17

OAuth2 Proxy — Endpoints (Official Docs)

Layer: raw/official-docs/ — oauth2-proxy 공식 문서의 endpoint 목록 페이지. 각 /oauth2/* endpoint 가 무엇을 하는지에 대한 1차 출처. P1A 패턴에서 location /oauth2/ prefix block 이 왜 필요한지(브라우저가 도달해야 하는 endpoint 들이 존재하기 때문)의 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-nginx-auth-request-integration	D7 — oauth2-proxy 의 endpoint 별 용도와 호출 주체. /oauth2/start·/oauth2/callback·/oauth2/sign_in·/oauth2/sign_out·/oauth2/userinfo·/oauth2/static/* 이 브라우저가 도달해야 하는 endpoint 라는 근거, /oauth2/auth 는 이 목록에서 nginx auth_request 용도로 별도 명시된다는 근거. location /oauth2/ prefix block 이 필요한 이유의 1차 출처.

출처 / Source

• 원본 URL: https://oauth2-proxy.github.io/oauth2-proxy/features/endpoints/
• 아카이브 URL: (미수집)
• 저자 / 조직: oauth2-proxy maintainers
• 발행일: rolling docs (버전 표시: 7.15.x)
• 마지막 확인일: 2026-07-17

왜 저장했는지 / Why archived

P1A 패턴에서 nginx location /oauth2/ prefix block 을 왜 만들어야 하는지는 "oauth2-proxy 가 응답하는 endpoint 가 무엇인지"에 달려있다. 이 페이지는 oauth2-proxy 가 직접 응답하는 모든 endpoint 의 공식 목록이며, /oauth2/auth 만 nginx auth_request 전용으로 별도 기술된다는 것을 확인하는 1차 근거.

핵심 인용 / Key quotes (verbatim, 3~5문장)

[§Endpoints] "OAuth2 Proxy responds directly to the following endpoints. All other endpoints will be proxied upstream when authenticated. The /oauth2 prefix can be changed with the --proxy-prefix config variable."

[§Endpoints] "/oauth2/start - a URL that will redirect to start the OAuth cycle"

[§Endpoints] "/oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url."

[§Endpoints] "/oauth2/sign_in - the login page, which also doubles as a sign-out page (it clears cookies)"

[§Endpoints] "/oauth2/sign_out - this URL is used to clear the session cookie"

[§Endpoints] "/oauth2/userinfo - the URL is used to return user's email from the session in JSON format."

[§Endpoints] "/oauth2/static/* - stylesheets and other dependencies used in the sign_in and error pages"

[§Endpoints] "/oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the Nginx auth_request directive"

[§Auth] "This endpoint returns 202 Accepted response or a 401 Unauthorized response."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
O2EP-C1	/oauth2/start 은 OAuth cycle 을 시작하기 위해 redirect 시키는 URL 이다	[§Endpoints] "/oauth2/start - a URL that will redirect to start the OAuth cycle"	official-vendor-doc	oauth2-proxy 가 응답하는 endpoint 목록	이 endpoint 를 누가 호출해야 하는지(브라우저 vs 서버 vs SPA JS)는 원문이 명시하지 않음 — "redirect 시키는 URL" 이라는 표현은 브라우저 navigation 대상임을 강하게 시사하나, "브라우저 전용"이라는 제약을 원문이 직접 선언하지는 않음
O2EP-C2	/oauth2/callback 은 OAuth cycle 종료 시점에 쓰이는 URL 이며, OAuth app(=IdP client 등록) 에 이 URL 이 callback url 로 설정된다	[§Endpoints] "/oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url."	official-vendor-doc	OAuth/OIDC client 등록 시 redirect_uri 설정 대상	"the oauth app will be configured with this as the callback url" 은 IdP(예: Keycloak) 가 authorization 완료 후 브라우저를 이 URL 로 리다이렉트한다는 것을 함의한다 — OAuth callback/redirect_uri 메커니즘상 IdP 는 브라우저의 user-agent 를 통해 리다이렉트를 수행하기 때문. 단, 이 문서 자체가 "브라우저가 리다이렉트한다"는 문장을 직접 쓰지는 않으며, 그 함의는 OAuth 표준 redirect_uri 동작에 대한 일반 지식과 결합한 추론이다 — 이 함의의 범위를 넘어 nginx location block 구성 같은 세부 구현까지 증명하지 않음
O2EP-C3	/oauth2/sign_in 은 로그인 페이지이며, 동시에 cookie 를 지우는 sign-out 페이지 역할도 겸한다	[§Endpoints] "/oauth2/sign_in - the login page, which also doubles as a sign-out page (it clears cookies)"	official-vendor-doc	oauth2-proxy 가 응답하는 endpoint 목록	이 endpoint 가 항상 사람이 볼 수 있는 HTML 페이지 형태로만 존재한다는 것 이상은(예: 커스터마이징 옵션 상세) 증명하지 않음
O2EP-C4	/oauth2/sign_out 은 세션 cookie 를 지우는 데 사용되는 URL 이다	[§Endpoints] "/oauth2/sign_out - this URL is used to clear the session cookie"	official-vendor-doc	oauth2-proxy 세션 종료	IdP(예: Keycloak) 측 세션까지 종료시키는지는 이 문장만으로 증명 안 됨 — 문서 하단 "Sign out" 섹션은 별도로 "이 endpoint 는 oauth2-proxy 자신의 cookie 만 지우며 사용자는 여전히 인증 provider 에 로그인된 상태일 수 있다"고 부연하지만, 그 부연은 별도 claim(O2EP 범위 밖, 본 raw 는 endpoint 목록 문장만 claim 화)
O2EP-C5	/oauth2/userinfo 는 세션에 저장된 사용자의 email 을 JSON 형식으로 반환하는 데 쓰인다	[§Endpoints] "/oauth2/userinfo - the URL is used to return user's email from the session in JSON format."	official-vendor-doc	oauth2-proxy 세션에서 사용자 정보 조회	이 endpoint 를 SPA 프론트엔드가 JS fetch 로 호출하는 용도라는 것은 원문이 말하지 않는다 — "무엇을 반환하는지"만 명시할 뿐 "누가 호출하는지"는 미진술. email 외 다른 claim(예: groups)도 포함하는지 이 문장만으로는 증명 안 됨
O2EP-C6	/oauth2/static/* 은 sign_in 페이지와 error 페이지에서 사용되는 stylesheet 및 기타 의존성을 제공한다	[§Endpoints] "/oauth2/static/* - stylesheets and other dependencies used in the sign_in and error pages"	official-vendor-doc	oauth2-proxy 정적 자산 서빙	이 자산들이 브라우저에 의해서만 요청된다는 것을 명시적으로 선언하지는 않음 — 다만 "sign_in/error 페이지에서 사용되는 리소스"라는 용도 설명 자체가 브라우저 렌더링 맥락을 강하게 시사
O2EP-C7	/oauth2/auth 는 202 Accepted 또는 401 Unauthorized 응답만 반환하며, nginx auth_request directive 와 함께 사용하기 위한 것이다. Auth 섹션에서도 동일하게 "This endpoint returns 202 Accepted response or a 401 Unauthorized response" 라고 재확인한다	[§Endpoints] "/oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the Nginx auth_request directive" / [§Auth] "This endpoint returns 202 Accepted response or a 401 Unauthorized response."	official-vendor-doc	/oauth2/auth 의 응답 계약 및 용도(nginx auth_request 결합)	원문은 /oauth2/auth 가 "nginx auth_request 용도"라고만 말할 뿐, "브라우저가 직접 호출해서는 안 된다" 또는 "subrequest 전용으로만 제한되어야 한다"는 제약을 명시적으로 선언하지 않는다 — internal; 지시자를 붙여도 안전한지는 이 문서에서 확인 불가 (사용자 추론 영역)
O2EP-C8	이 페이지의 endpoint 목록 전체가 /oauth2 접두어를 사용하며, 이 접두어는 --proxy-prefix 설정 변수로 변경 가능하다고 명시한다	[§Endpoints] "OAuth2 Proxy responds directly to the following endpoints. All other endpoints will be proxied upstream when authenticated. The /oauth2 prefix can be changed with the --proxy-prefix config variable."	official-vendor-doc	/oauth2/* 라우팅 접두어의 출처 및 변경 가능성	원문은 "/oauth2 가 --proxy-prefix 의 기본값(default)"이라는 단어를 직접 쓰지 않는다 — 이 페이지의 모든 예시가 /oauth2 를 일관되게 사용한다는 정황과 "변경 가능하다"는 서술을 결합한 합리적 추론일 뿐, "default value: /oauth2" 라는 명시적 진술은 이 페이지에서 찾지 못함 (NOT FOUND as literal statement — see 보고)

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • O2EP-C1~C6, C8: oauth2-proxy 가 직접 응답하는 각 /oauth2/* endpoint 의 용도, /oauth2 prefix 가 --proxy-prefix 로 변경 가능하다는 사실
  • O2EP-C7: /oauth2/auth 의 응답 계약(202/401) 과 nginx auth_request 결합 용도
• 이 자료가 증명하지 않는 것:
  • nginx 에서 이 endpoint 들을 어떤 location block 으로 노출해야 하는지 (그건 raw/official-docs/oauth2-proxy-nginx-integration-official#O2PN-C2/C5 담당)
  • /oauth2/auth 에 internal; 을 붙여도 안전한지 (공식 문서 미진술 — 사용자 추론 영역, internal; 은 nginx 자체 지시자이며 oauth2-proxy 문서 범위 밖)
  • --proxy-prefix 의 리터럴 기본값이 정확히 /oauth2 라는 명시적 진술 (정황 추론 — O2EP-C8 does-not-prove 참조)
  • 각 endpoint 를 누가 호출하는지(브라우저 사용자 navigation vs 서버 간 호출 vs SPA JS fetch)에 대한 명시적 구분 — 대부분 "무엇을 하는지"만 서술
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • nginx.conf 실제 location /oauth2/ prefix block 작성 시 각 sub-path 의 허용/차단 정책 (예: /oauth2/auth 만 internal;)
  • --proxy-prefix 를 실제로 변경할 계획이 있는지 (변경 시 nginx location 경로도 동일하게 갱신 필요)

메모 / Notes

나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기에 두지 말 것.

• 이 페이지는 endpoint 별 "무엇을 하는지"는 명확히 말하지만 "누가 호출하는지"는 대체로 침묵한다. D7 의 "브라우저가 도달해야 하는 endpoint" 결론은 각 문장의 함의(예: /oauth2/start = "redirect 시키는 URL", /oauth2/callback = "OAuth app 의 callback url") 로부터의 추론이며, 이 raw 문서의 Claim 컬럼에는 원문 진술만 남기고 그 추론은 Does not prove 또는 branch-note 쪽 Decision Evidence Map 에서 다뤄야 한다.
• /oauth2/auth 만 유일하게 "nginx auth_request 용도"라는 명시적 라벨이 붙어있다 — 다른 6개 endpoint 는 그런 라벨이 없다. 이 비대칭 자체가 D7 의 핵심 근거 구조.
• 추가로 봐야 할 동일 출처 페이지: --proxy-prefix 플래그의 리터럴 기본값은 Configuration Overview 페이지(/oauth2-proxy/configuration/overview)의 flag 표에 있을 가능성 높음 — 별도 dispatch 필요 (이번 raw 는 endpoints 페이지 1개로 범위 한정).

Related / 관련

• 같은 주제 다른 official-doc:
  • raw/official-docs/oauth2-proxy-nginx-integration-official
  • raw/official-docs/oauth2-proxy-overview-config-official
  • raw/official-docs/nginx-auth-request-module-official
• 이 자료를 인용한 wiki 요약: (생성 시)