# Keycloak 로컬 구성과 OIDC PKCE 로그인: 코드 가로채기 방어 확인

> Docker로 Keycloak을 띄워 realm, client, 테스트 사용자를 구성하고, Flask 클라이언트가 Authorization Code와 PKCE로 로그인해 ID 토큰의 iss, aud, exp, nonce를 검증합니다. PKCE를 요구하지 않는 client에서는 가로챈 인가 코드가 토큰으로 교환되는 것을 재현하고, PKCE S256을 필수로 켜서 code_verifier 없는 교환이 거부되는 것을 확인합니다.

- 주소: https://copyandrun.com/blog/keycloak-oidc-pkce-local-login/
- 분야: 시큐어코딩
- 발행일: 2026-10-27
- 태그: Keycloak, OIDC, PKCE, OAuth, Flask, Docker

OIDC 로그인에서 브라우저는 인가 코드(authorization code)를 들고 클라이언트로 돌아옵니다. 이 코드가 중간에서 새면, 코드를 가진 쪽이 토큰으로 바꿀 수 있는지가 문제입니다. PKCE(Proof Key for Code Exchange)는 로그인을 시작한 쪽만 코드를 토큰으로 바꿀 수 있게 묶어 주는 장치입니다. 이 글에서는 내 컴퓨터의 Docker에 Keycloak을 띄우고, Flask 클라이언트로 PKCE 로그인을 해 보고, PKCE를 요구하지 않는 client와 요구하는 client를 같은 공격 스크립트로 비교합니다.

비밀번호 없는 로그인은 [Flask에서 패스키(WebAuthn) 로그인 구현하고 피싱 방어 확인하기](/blog/passkey-webauthn-flask-virtual-authenticator/)에서, 비밀번호 저장은 [Python 비밀번호 해시와 비밀값 다루기](/blog/python-password-hash-and-secrets/)에서 다룹니다. 이 글은 위임 인증(OIDC)에서 인가 코드를 어떻게 지키는지에 집중합니다. Keycloak은 개발 모드(`start-dev`)로 띄우는 실습용 구성이며, 운영 구성이 아닙니다.

## 준비물

| 항목 | 버전 | 용도 |
|---|---|---|
| Docker | 29.5.3 (Docker Desktop) | Keycloak 실행 |
| Keycloak | `quay.io/keycloak/keycloak:26.8.1` (2026-10-27에 받은 최신 안정판) | 인증 서버 |
| Python | 3.12.10 | Flask 클라이언트와 확인 스크립트 |
| Flask, requests, PyJWT, cryptography | 3.1.3, 2.34.2, 2.15.1, 50.0.0 | 로그인 클라이언트, ID 토큰 서명 검증 |

명령은 Windows의 Git Bash에서 확인했고, 리눅스와 macOS에서는 실행하지 않았습니다. 예상 소요 시간은 20분 안팎이며, 처음에는 Keycloak 이미지를 받는 시간이 더해집니다. 이 글의 코드는 모두 본문에 전체를 실었고, 글 맨 위의 실습 코드 내려받기에서도 같은 파일을 받을 수 있습니다.

글에 나오는 `lab-admin-pass`와 `lab-user-pass`는 실습용 임시 값이며 실제 비밀번호가 아닙니다. 두 값은 compose 파일과 realm 가져오기 파일에 그대로 적혀 있으므로, 이 구성을 인터넷에 열린 서버에 쓰지 마십시오. 포트는 호스트의 `127.0.0.1`에만 열고, Keycloak은 5480, Flask는 5481을 씁니다. 이미 쓰는 포트라면 compose 파일과 코드의 포트를 함께 바꿉니다.

## 1. Keycloak 띄우기

<!-- files: docker-compose.yml, realm-lab.json -->

compose 파일은 컨테이너 이름을 `cr-keycloak`, 데이터 볼륨 이름을 `cr-keycloak-data`로 고정합니다. 관리자 계정은 `KC_BOOTSTRAP_ADMIN_*` 환경 변수로 만들고, realm은 시작할 때 `--import-realm`으로 가져옵니다.

```yaml
name: cr-keycloak

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.8.1
    container_name: cr-keycloak
    command: ["start-dev", "--import-realm"]
    environment:
      # 실습용 임시 값입니다. 실제 비밀번호가 아닙니다.
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: lab-admin-pass
    ports:
      - "127.0.0.1:5480:8080"
    volumes:
      - data:/opt/keycloak/data
      - ./realm-lab.json:/opt/keycloak/data/import/realm-lab.json:ro

volumes:
  data:
    name: cr-keycloak-data
```

realm 가져오기 파일은 realm `lab`에 사용자 `lab-user`와 client 두 개를 만듭니다. 두 client는 같은 구성이고 `lab-pkce`에만 `pkce.code.challenge.method: S256` 속성이 있습니다. `lab-vuln`이 수정 전, `lab-pkce`가 수정 후입니다. 사용자 프로필 설정(`components`)은 이메일을 선택 항목으로 바꾸는 부분입니다. 이메일 없는 사용자로 실습하려고 넣었고, 이 설정 없이 이메일을 뺀 realm으로 시도했을 때는 로그인 뒤에 인가 코드가 발급되지 않아 아래 확인 스크립트가 멈췄습니다.

```json
{
  "realm": "lab",
  "enabled": true,
  "sslRequired": "none",
  "components": {
    "org.keycloak.userprofile.UserProfileProvider": [
      {
        "providerId": "declarative-user-profile",
        "config": {
          "kc.user.profile.config": [
            "{\"attributes\":[{\"name\":\"username\",\"validations\":{\"length\":{\"min\":3,\"max\":255},\"username-prohibited-characters\":{},\"up-username-not-idn-homograph\":{}},\"permissions\":{\"view\":[\"admin\",\"user\"],\"edit\":[\"admin\",\"user\"]}},{\"name\":\"email\",\"validations\":{\"email\":{},\"length\":{\"max\":255}},\"permissions\":{\"view\":[\"admin\",\"user\"],\"edit\":[\"admin\",\"user\"]}},{\"name\":\"firstName\",\"permissions\":{\"view\":[\"admin\",\"user\"],\"edit\":[\"admin\",\"user\"]}},{\"name\":\"lastName\",\"permissions\":{\"view\":[\"admin\",\"user\"],\"edit\":[\"admin\",\"user\"]}}],\"groups\":[]}"
          ]
        }
      }
    ]
  },
  "users": [
    {
      "username": "lab-user",
      "enabled": true,
      "firstName": "Lab",
      "lastName": "User",
      "credentials": [
        {
          "type": "password",
          "value": "lab-user-pass",
          "temporary": false
        }
      ]
    }
  ],
  "clients": [
    {
      "clientId": "lab-vuln",
      "name": "lab-vuln (PKCE 필수 아님)",
      "enabled": true,
      "publicClient": true,
      "standardFlowEnabled": true,
      "directAccessGrantsEnabled": false,
      "redirectUris": [
        "http://localhost:5481/callback"
      ],
      "webOrigins": [
        "http://localhost:5481"
      ],
      "attributes": {}
    },
    {
      "clientId": "lab-pkce",
      "name": "lab-pkce (PKCE S256 필수)",
      "enabled": true,
      "publicClient": true,
      "standardFlowEnabled": true,
      "directAccessGrantsEnabled": false,
      "redirectUris": [
        "http://localhost:5481/callback"
      ],
      "webOrigins": [
        "http://localhost:5481"
      ],
      "attributes": {
        "pkce.code.challenge.method": "S256"
      }
    }
  ]
}
```

```bash
docker compose up -d
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:5480/realms/lab/.well-known/openid-configuration
```

처음 시작할 때는 20초 안팎이 걸리고, 두 번째 줄이 `200`을 돌려주면 준비된 것입니다. 로그에 `Realm 'lab' imported`가 나오는지도 확인합니다.

```bash
docker logs cr-keycloak 2>&1 | grep -E "imported|started in"
```

## 2. 관리 콘솔에서 realm과 client 확인하기

`http://localhost:5480/admin/`에 `admin` / `lab-admin-pass`로 로그인한 뒤 왼쪽 위에서 realm을 `lab`으로 바꾸고 Clients 메뉴를 엽니다. 가져온 client 두 개가 목록에 보입니다. 상단의 노란 줄은 임시 관리자 계정을 쓰고 있다는 Keycloak의 안내입니다.

![Clients 목록에 가져온 lab-pkce와 lab-vuln 두 client가 보이는 것을 확인합니다.](https://copyandrun.com/img/keycloak-oidc-pkce-local-login/01-clients.png)

client 이름을 눌러 Settings 탭의 Capability config에서 PKCE 설정을 봅니다. 수정 전인 `lab-vuln`은 Require PKCE가 꺼져 있고 경고 아이콘이 붙어 있습니다. Client authentication도 꺼져 있어서 client secret이 없는 공개 client입니다. 브라우저 앱과 모바일 앱이 이 형태이고, 코드를 가로챈 쪽을 막아 줄 것이 PKCE뿐이라는 점이 이 글의 전제입니다.

![lab-vuln의 Capability config에서 Require PKCE가 Off로 꺼져 있는 것을 확인합니다.](https://copyandrun.com/img/keycloak-oidc-pkce-local-login/05-client-vuln.png)

## 3. Flask 클라이언트로 PKCE 로그인하기

Flask 앱은 로그인을 시작할 때 네 가지 값을 만들고, `code_challenge`를 뺀 세 가지를 세션에 둡니다. `code_verifier`(무작위 값), 그 해시인 `code_challenge`, 응답이 내 요청의 것인지 가르는 `state`와 `nonce`입니다. 인가 요청에는 `code_challenge`만 보내고, 코드를 토큰으로 바꿀 때 `code_verifier` 원본을 보냅니다. 서버는 받은 값을 해시해서 처음의 `code_challenge`와 같은지 확인합니다.

콜백에서는 ID 토큰의 서명을 Keycloak이 공개하는 JWKS 키로 검증하고, `iss`(발급자), `aud`(대상 client), `exp`(만료)를 PyJWT가 확인하게 한 다음, `nonce`는 세션에 둔 값과 직접 비교합니다. 결과는 표로 화면에 보여 줍니다.

```python
"""Authorization Code + PKCE 로 Keycloak 에 로그인하는 작은 Flask 클라이언트.

실행: CLIENT_ID=lab-pkce python app.py  (기본값 lab-pkce)
"""
import base64
import hashlib
import html
import json
import os
import secrets
import time
from urllib.parse import urlencode

import jwt
import requests
from flask import Flask, redirect, request, session

ISSUER = os.environ.get("ISSUER", "http://localhost:5480/realms/lab")
CLIENT_ID = os.environ.get("CLIENT_ID", "lab-pkce")
REDIRECT_URI = "http://localhost:5481/callback"

app = Flask(__name__)
app.secret_key = "lab-only-session-key"  # 실습용 값입니다. 실제 서비스에서는 무작위 비밀값을 환경 변수로 받습니다.

PAGE = """<!doctype html><meta charset="utf-8"><title>OIDC 클라이언트</title>
<style>
body{{font-family:'Malgun Gothic',sans-serif;margin:32px;color:#222}}
table{{border-collapse:collapse;min-width:760px}}
th,td{{border:1px solid #ccc;padding:8px 14px;text-align:left}}
th{{background:#f2f4f7}} .ok{{background:#dff5e1;color:#14692a;font-weight:700}}
.bad{{background:#fde1e1;color:#a11919;font-weight:700}} code{{font-size:13px}}
a.btn{{display:inline-block;padding:10px 22px;background:#1a5fb4;color:#fff;text-decoration:none;border-radius:4px}}
</style>{body}"""


def b64url(raw):
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()


def discovery():
    return requests.get(f"{ISSUER}/.well-known/openid-configuration", timeout=5).json()


@app.get("/")
def index():
    body = (f"<h1>OIDC 클라이언트</h1><p>client_id: <code>{html.escape(CLIENT_ID)}</code> / "
            f"issuer: <code>{html.escape(ISSUER)}</code></p>"
            '<p><a class="btn" href="/login">Keycloak 으로 로그인</a></p>')
    return PAGE.format(body=body)


@app.get("/login")
def login():
    verifier = b64url(secrets.token_bytes(32))
    challenge = b64url(hashlib.sha256(verifier.encode()).digest())
    session["verifier"] = verifier
    session["state"] = secrets.token_urlsafe(16)
    session["nonce"] = secrets.token_urlsafe(16)
    query = urlencode({
        "client_id": CLIENT_ID, "response_type": "code", "scope": "openid profile",
        "redirect_uri": REDIRECT_URI, "state": session["state"], "nonce": session["nonce"],
        "code_challenge": challenge, "code_challenge_method": "S256",
    })
    return redirect(discovery()["authorization_endpoint"] + "?" + query)


@app.get("/callback")
def callback():
    if request.args.get("state") != session.get("state"):
        return PAGE.format(body="<h1>state 가 맞지 않습니다</h1>"), 400
    if "code" not in request.args:
        return PAGE.format(body=f"<h1>인증 실패</h1><p>{html.escape(request.args.get('error_description', '-'))}</p>"), 400
    conf = discovery()
    resp = requests.post(conf["token_endpoint"], data={
        "grant_type": "authorization_code", "code": request.args["code"],
        "redirect_uri": REDIRECT_URI, "client_id": CLIENT_ID,
        "code_verifier": session["verifier"],
    }, timeout=5)
    if resp.status_code != 200:
        return PAGE.format(body=f"<h1>토큰 교환 실패</h1><pre>{html.escape(resp.text)}</pre>"), 400
    id_token = resp.json()["id_token"]
    key = jwt.PyJWKClient(conf["jwks_uri"]).get_signing_key_from_jwt(id_token).key
    claims = jwt.decode(id_token, key, algorithms=["RS256"], audience=CLIENT_ID, issuer=ISSUER)
    checks = [
        ("iss", claims["iss"], claims["iss"] == ISSUER, f"기대값 {ISSUER}"),
        ("aud", claims["aud"], claims["aud"] == CLIENT_ID, f"기대값 {CLIENT_ID}"),
        ("exp", time.strftime("%H:%M:%S", time.localtime(claims["exp"])),
         claims["exp"] > time.time(), "지금보다 뒤"),
        ("nonce", claims.get("nonce"), claims.get("nonce") == session["nonce"], "로그인 시작 때 보낸 값과 같음"),
    ]
    rows = "".join(
        f"<tr><td>{n}</td><td><code>{html.escape(str(v))}</code></td>"
        f"<td class='{'ok' if ok else 'bad'}'>{'통과' if ok else '실패'}</td><td>{html.escape(why)}</td></tr>"
        for n, v, ok, why in checks)
    body = (f"<h1>로그인 성공: {html.escape(claims.get('preferred_username', '-'))}</h1>"
            f"<h3>ID 토큰 검증</h3><table><tr><th>클레임</th><th>값</th><th>결과</th><th>기준</th></tr>{rows}</table>"
            f"<h3>전체 클레임</h3><pre>{html.escape(json.dumps(claims, indent=2, ensure_ascii=False))}</pre>")
    return PAGE.format(body=body)


if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5481)
```

패키지 목록은 `requirements.txt`입니다.

```text
flask==3.1.3
requests==2.34.2
pyjwt==2.15.1
cryptography==50.0.0
```

```bash
python -m venv .venv && . .venv/Scripts/activate
python -m pip install -r requirements.txt
CLIENT_ID=lab-pkce python app.py
```

리눅스와 macOS에서는 가상 환경 활성화 명령이 `. .venv/bin/activate`입니다. 브라우저에서 `http://localhost:5481/`을 엽니다. `127.0.0.1`이 아니라 `localhost`로 열어야 합니다. 리디렉션 주소와 토큰의 발급자가 `localhost` 기준으로 등록되어 있기 때문입니다.

![클라이언트 시작 화면에 client_id lab-pkce와 issuer 주소, 로그인 버튼이 보이는 것을 확인합니다.](https://copyandrun.com/img/keycloak-oidc-pkce-local-login/02-client-start.png)

로그인 버튼을 누르면 Keycloak 로그인 화면으로 이동합니다. 주소창의 인가 요청에는 `code_challenge`와 `code_challenge_method=S256`이 실려 있습니다. 여기서 `lab-user` / `lab-user-pass`를 입력합니다.

![Keycloak 로그인 화면에서 사용자 이름과 비밀번호를 입력하는 칸이 보이는 것을 확인합니다.](https://copyandrun.com/img/keycloak-oidc-pkce-local-login/03-keycloak-login.png)

로그인이 끝나면 Flask가 코드를 `code_verifier`와 함께 토큰으로 바꾸고, ID 토큰을 검증한 결과를 보여 줍니다. `iss`는 realm 주소, `aud`는 client 이름, `exp`는 발급 5분 뒤, `nonce`는 로그인을 시작할 때 만든 값과 같아야 통과입니다. 아래 `exp` 시각은 이 컴퓨터의 현지 시각이며, `nonce`와 `sub`는 로그인할 때마다 달라집니다.

![ID 토큰 검증 표에서 iss, aud, exp, nonce 네 항목이 모두 통과로 표시되고 전체 클레임이 보이는 것을 확인합니다.](https://copyandrun.com/img/keycloak-oidc-pkce-local-login/04-claims.png)

## 4. 발견: PKCE를 요구하지 않으면 가로챈 코드가 토큰이 됩니다

앱이 PKCE를 쓰는 것과 서버가 PKCE를 요구하는 것은 다릅니다. 서버가 요구하지 않으면 `code_challenge` 없이 시작된 로그인도 받아 주고, 그렇게 만들어진 코드는 `code_verifier` 없이 토큰으로 바뀝니다. 오래된 클라이언트, PKCE를 구현하지 않은 모바일 앱, 인가 요청 주소가 변조되어 `code_challenge`가 빠진 경우가 여기에 해당합니다.

`attack.py`는 코드가 중간에서 샌 상황을 흉내 냅니다. 연습용 사용자로 직접 로그인해 리디렉션 주소의 코드를 꺼낸 뒤, 그 코드를 `code_verifier` 없이 토큰 엔드포인트에 냅니다. 로그인을 시작한 쪽의 비밀(verifier)을 모르는 상태에서 교환을 시도하는 것이므로, 코드를 가로챈 공격자와 같은 입장입니다. 악성 동작은 하지 않고 토큰이 발급되는지만 확인합니다.

```python
"""코드 가로채기 재현: 사용자가 로그인해 받은 인가 코드를 다른 쪽이 대신 토큰으로 바꿔 봅니다.

실행: python attack.py lab-vuln   또는   python attack.py lab-pkce
연습용 사용자와 연습용 Keycloak 에만 사용합니다.
"""
import base64
import hashlib
import re
import secrets
import sys
from html import unescape
from urllib.parse import parse_qs, urlencode, urlparse

import requests

BASE = "http://localhost:5480/realms/lab/protocol/openid-connect"
REDIRECT = "http://localhost:5481/callback"
CLIENT = sys.argv[1]


def b64url(raw):
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()


def get_code(use_pkce):
    """사용자 대신 로그인해서 리디렉션 주소에 실린 인가 코드를 꺼냅니다(가로채기 흉내)."""
    verifier = b64url(secrets.token_bytes(32))
    params = {"client_id": CLIENT, "response_type": "code", "scope": "openid",
              "redirect_uri": REDIRECT, "state": "x"}
    if use_pkce:
        params["code_challenge"] = b64url(hashlib.sha256(verifier.encode()).digest())
        params["code_challenge_method"] = "S256"
    s = requests.Session()
    r = s.get(f"{BASE}/auth?{urlencode(params)}", allow_redirects=False, timeout=10)
    if r.status_code != 200:
        return None, verifier, r
    # Keycloak 은 http 에서도 Secure 쿠키를 보냅니다. 브라우저는 localhost 를 안전한 곳으로 보지만
    # requests 는 아니므로, 이 실습 스크립트에서만 Secure 표시를 끕니다.
    for c in s.cookies:
        c.secure = False
    action = unescape(re.search(r'action="([^"]+)"', r.text).group(1))
    r = s.post(action, data={"username": "lab-user", "password": "lab-user-pass"},
               allow_redirects=False, timeout=10)
    code = parse_qs(urlparse(r.headers["Location"]).query)["code"][0]
    return code, verifier, r


def exchange(code, verifier=None):
    data = {"grant_type": "authorization_code", "code": code,
            "redirect_uri": REDIRECT, "client_id": CLIENT}
    if verifier:
        data["code_verifier"] = verifier
    return requests.post(f"{BASE}/token", data=data, timeout=10)


def show(label, r):
    body = r.json()
    if r.status_code == 200:
        print(f"{label}: HTTP 200 토큰 발급됨 ({', '.join(k for k in body if k.endswith('token'))})")
    else:
        print(f"{label}: HTTP {r.status_code} {body.get('error')} / {body.get('error_description')}")


print(f"== client_id={CLIENT}")
# 1) PKCE 를 쓰지 않는 요청: 코드만 가로채면 verifier 없이 교환할 수 있는지
code, _, r = get_code(use_pkce=False)
if code is None:
    reason = parse_qs(urlparse(r.headers.get("Location", "")).query).get("error_description", ["-"])[0]
    print(f"PKCE 없는 인증 요청: HTTP {r.status_code} 거부 ({reason})")
else:
    show("PKCE 없이 받은 코드를 code_verifier 없이 교환", exchange(code))
# 2) PKCE 를 쓰는 요청: 코드를 가로챘어도 verifier 가 없으면 교환이 되는지
code, verifier, _ = get_code(use_pkce=True)
show("PKCE 로 받은 코드를 code_verifier 없이 교환", exchange(code))
code, verifier, _ = get_code(use_pkce=True)
show("PKCE 로 받은 코드를 엉뚱한 code_verifier 로 교환", exchange(code, b64url(secrets.token_bytes(32))))
code, verifier, _ = get_code(use_pkce=True)
show("PKCE 로 받은 코드를 올바른 code_verifier 로 교환", exchange(code, verifier))
```

```bash
python attack.py lab-vuln
```

![lab-vuln에서 PKCE 없이 받은 코드가 code_verifier 없이 교환되어 HTTP 200으로 토큰이 발급되는 것을 확인합니다.](https://copyandrun.com/img/keycloak-oidc-pkce-local-login/07-attack-vuln.png)

첫 줄이 문제입니다. PKCE 없이 시작한 로그인의 코드가 verifier 없이 교환되어 `access_token`, `refresh_token`, `id_token`이 모두 발급되었습니다. 나머지 세 줄은 요청 때 `code_challenge`를 보낸 경우이고, 이때는 verifier가 없거나 틀리면 거부됩니다. 즉 PKCE를 쓴 로그인은 이미 보호되지만, 서버가 PKCE를 요구하지 않으니 PKCE 없는 요청이 우회로로 남습니다.

## 5. 원인: 서버가 PKCE를 요구하는 설정이 없었습니다

Keycloak은 client에 PKCE 방식이 지정되어 있지 않으면 `code_challenge`가 없는 인가 요청을 그대로 받습니다. 코드와 토큰 사이를 묶는 값이 처음부터 없으므로, 코드를 가진 쪽은 누구든 토큰을 받을 수 있습니다. 공개 client는 client secret이 없어서 코드 외에 교환을 막을 수단이 없습니다. 원인은 코드나 Keycloak의 결함이 아니라, `lab-vuln`의 속성에 `pkce.code.challenge.method`가 비어 있는 설정입니다.

## 6. 수정: PKCE S256을 필수로 켜기

수정은 client 속성 하나입니다. realm 가져오기 파일에서는 `lab-pkce`에 아래 속성이 들어 있습니다.

```json
"attributes": {
  "pkce.code.challenge.method": "S256"
}
```

관리 콘솔의 같은 위치(Clients, 해당 client, Settings, Capability config)에서는 Require PKCE가 켜지고 PKCE Method가 S256으로 보입니다. 이 화면은 가져오기 파일로 설정한 client를 연 것이고, 이미 있는 client에서 화면의 토글을 눌러 같은 속성이 저장되는지는 이 글에서 따로 실행하지 않았습니다.

![lab-pkce의 Capability config에서 Require PKCE가 On이고 PKCE Method가 S256으로 설정된 것을 확인합니다.](https://copyandrun.com/img/keycloak-oidc-pkce-local-login/06-client-pkce.png)

`S256`을 쓰는 이유는 `plain`(challenge와 verifier가 같은 값)이 verifier를 요청 주소에 그대로 싣기 때문입니다. 요청이 새면 verifier도 함께 새므로 PKCE가 아무것도 막지 못합니다.

## 7. 재확인: 같은 스크립트를 수정한 client에 돌립니다

```bash
python attack.py lab-pkce
```

![lab-pkce에서 PKCE 없는 인증 요청은 거부되고 code_verifier 없는 교환은 invalid_grant로 거부되며 올바른 verifier로만 토큰이 발급되는 것을 확인합니다.](https://copyandrun.com/img/keycloak-oidc-pkce-local-login/08-attack-pkce.png)

결과가 달라진 곳은 첫 줄입니다. PKCE 없는 인증 요청 자체가 `Missing parameter: code_challenge_method`로 거부되어, 코드가 만들어지지 않습니다. 인증 요청이 거부될 때 Keycloak은 오류를 리디렉션 주소의 쿼리로 돌려보내므로 스크립트에는 HTTP 302로 보입니다. 나머지 줄은 수정 전과 같습니다. verifier 없이 교환하면 `PKCE code verifier not specified`, 엉뚱한 verifier를 내면 `PKCE verification failed: Code mismatch`로 `invalid_grant` 거부가 나오고, 로그인을 시작한 쪽이 가진 올바른 verifier로만 HTTP 200이 나옵니다. 3단계의 Flask 로그인이 `lab-pkce`로 성공한 것이 이 마지막 줄과 같은 경로입니다.

## 자주 막히는 곳

**Keycloak 컨테이너가 바로 종료됩니다**
`docker logs cr-keycloak`의 마지막 `ERROR` 줄을 봅니다. 이 글을 쓰면서 사용자 프로필에서 `email` 속성을 지웠더니 `The attribute 'email' can not be removed`로 시작에 실패했습니다. 이메일은 지우지 않고 선택 항목으로만 바꿀 수 있습니다.

**`attack.py`가 `KeyError: 'code'`로 멈춥니다**
로그인 뒤 리디렉션 주소에 코드가 없는 경우입니다. 이메일이 필수인 사용자 프로필 설정에서 이메일 없는 사용자로 로그인했을 때 이렇게 멈췄습니다. realm 가져오기 파일의 `components` 부분이 그 설정입니다. 가져오기는 realm이 없을 때만 적용되므로, 파일을 고친 뒤에는 `docker compose down -v`로 볼륨을 지우고 다시 올립니다.

**`attack.py`가 `KeyError: 'location'`으로 멈추고 Keycloak 로그에 `cookie_not_found`가 남습니다**
Keycloak은 `http`에서도 `Secure` 쿠키를 보냅니다. 브라우저는 `localhost`를 안전한 곳으로 취급해 저장하지만 `requests`는 이 쿠키를 다시 보내지 않아서 로그인 요청이 거부됩니다. 스크립트가 쿠키의 `Secure` 표시를 끄는 이유이고, 이 우회는 실습 스크립트에서만 씁니다.

**관리 콘솔에서 PKCE 설정을 Advanced 탭에서 찾게 됩니다**
Keycloak 26.8.1에서는 Settings 탭의 Capability config에 있습니다. Advanced 탭의 Advanced settings에는 PKCE 항목이 없었습니다.

## 한계

- **ID 토큰 검증은 이 글의 네 항목이 전부가 아닙니다.** 서명 알고리즘을 `RS256`으로 고정하고 `iss`, `aud`, `exp`를 확인했지만, `at_hash` 확인과 시계 오차 허용, 키 교체 때의 JWKS 갱신은 다루지 않았습니다. 운영에서는 검증된 OIDC 라이브러리를 쓰십시오.
- **가로채기는 흉내입니다.** `attack.py`는 코드를 실제로 훔치지 않고 직접 로그인해 코드를 얻었습니다. 모바일 앱의 사용자 지정 URI 스킴처럼 코드가 실제로 새는 경로는 재현하지 않았습니다. 이 글에서 확인한 것은 서버가 verifier 없는 교환을 받아 주는지입니다.
- **PKCE는 코드 가로채기만 막습니다.** XSS로 토큰이 탈취되는 경우, 피싱 사이트에 비밀번호를 입력하는 경우, 리디렉션 주소 검증이 느슨한 경우는 막지 못합니다. 리디렉션 주소는 정확한 값으로만 등록하십시오.
- **기밀 client에서도 PKCE는 권장됩니다.** 이 글은 client secret이 없는 공개 client만 다뤘습니다. OAuth 2.0 보안 권고(RFC 9700)는 기밀 client에도 PKCE를 쓰라고 하지만, secret이 있는 client에서의 동작은 실행하지 않았습니다.
- **개발 모드와 임시 값입니다.** `start-dev`, `http`, 코드에 적힌 관리자 비밀번호, Flask의 고정 `secret_key`는 모두 실습용입니다. 운영에서는 TLS, 별도 데이터베이스, 환경 변수나 비밀 저장소의 비밀값을 씁니다.
- **Keycloak 26.8.1 기준입니다.** 관리 콘솔 메뉴 위치와 프로필 설정 방식은 버전마다 다를 수 있습니다.

## 정리하기

실습이 끝나면 만든 것을 지웁니다. 아래 명령은 이 글에서 만든 이름만 지정합니다.

```bash
docker compose down -v
```

`docker compose down -v`가 `cr-keycloak` 컨테이너와 `cr-keycloak-data` 볼륨, 네트워크를 지웁니다. 받아 둔 이미지는 `docker rmi quay.io/keycloak/keycloak:26.8.1`로 지웁니다. Flask는 실행한 터미널에서 Ctrl+C로 끕니다.

## 이어서 해 볼 것

- 인가 요청에서 `nonce`를 빼거나 콜백의 `state`를 바꿔서, Flask 앱이 어떻게 반응하는지 확인해 봅니다.
- `plain` 방식으로 `lab-plain` client를 하나 더 만들어, challenge와 verifier가 같은 값이라 인가 요청 주소에서 verifier가 그대로 보이는 것을 확인해 봅니다.
- Client authentication을 켜서 secret이 있는 기밀 client로 바꾸고, PKCE 없는 교환이 어떻게 달라지는지 비교해 봅니다.

## 확인 범위

- **해 본 것:** 1~7단계 명령을 Windows의 Git Bash와 Docker Desktop(Docker 29.5.3)에서 Keycloak 26.8.1로 직접 실행했습니다. 화면은 같은 실행에서 얻은 것입니다. 브라우저 화면은 Chrome에서 확인했습니다.
- **해 보지 않은 것:** Linux와 macOS에서의 실행. 다른 브라우저. 관리 콘솔에서 PKCE 토글을 눌러 저장하는 경로. 기밀 client. `plain` 방식. 실제 네트워크에서의 코드 가로채기.
- **읽을 때 주의:** 토큰의 `sub`, `sid`, `nonce`, `exp` 값은 실행할 때마다 달라집니다.
