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

---
title: OAuth2 Proxy — Endpoints (Official Docs)
source_type: official-doc
url: https://oauth2-proxy.github.io/oauth2-proxy/features/endpoints/
archive_url:
related_branches: [feature-keycloak-nginx-auth-request-integration, feature-keycloak-edge-forwardauth-no-google, feature-keycloak-oauth2-proxy-oidc-flow]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, auth, oauth2-proxy, nginx]
created: 2026-07-17
last_reviewed: 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 요약: (생성 시)