자체 JWT 구현부터 취약점 실험, Keycloak 마이그레이션까지의 실제 절차
HS256/RS256 발급 서버 구현, alg:none·서명 미검증 같은 취약점을 직접 뚫어보는 실험 방법, 검증 로직을 서비스마다 복붙했을 때 생기는 문제 재현, Keycloak+Envoy Gateway로 옮기는 절차까지.
목표
이 시리즈는 순서가 고정이다 - Keycloak을 먼저 붙이지 않는다. 자체 JWT 구현 → 취약점 직접 체험 → 분산의 고통 재현 → Keycloak 마이그레이션 → ISMS-P 관점 비교 순서로 진행해야, 왜 게이트웨이 레벨 인증이 필요한지가 몸에 남는다.
개념: JWT란 무엇인가
로그인에 성공했다는 사실을 서버가 어떻게 "기억"할까? 전통적인 방식은 서버가 세션을 저장하고 클라이언트에는 세션 ID만 쿠키로 준다 - 서버는 그 ID로 "누구인지"를 매번 DB/메모리에서 찾아본다. JWT(JSON Web Token)는 이 반대다 - "누구인지" 정보 자체를 토큰 안에 담아서 클라이언트에게 통째로 넘겨준다. 서버는 이후 그 정보를 다시 조회할 필요 없이, 토큰이 위조되지 않았다는 것만 서명으로 확인하면 된다(그래서 "stateless" 인증이라 부른다).
JWT는 점(.)으로 구분된 세 부분으로 이뤄진다.
eyJhbGciOiJIUzI1NiJ9 . eyJzdWIiOiJ1c2VyMSJ9 . SflKxwRJSMeKKF2QT4fw...
Header Payload Signature
(서명 알고리즘) (sub, iss, aud, exp 등 (Header+Payload를
담긴 실제 클레임 데이터) 비밀키로 서명한 값)
Header와 Payload는 암호화되지 않고 그냥 Base64로만 인코딩되어 있다 - 누구나 디코딩해서 내용을 읽을 수 있다는 뜻이다(비밀번호 같은 민감 정보를 넣으면 안 되는 이유). 진짜 보안은 Signature에 있다 - 이 서명이 없으면, 또는 검증하는 쪽이 서명을 확인하지 않으면, 누구나 Payload를 마음대로 조작한 토큰을 만들 수 있다. 아래 실험(2번)이 바로 이 지점을 직접 뚫어본다.
실제 구축 절차
1. 자체 JWT 발급 서버 (auth-server) - HS256 vs RS256
서명을 만들고 검증하는 방식은 크게 두 갈래다 - **대칭키(발급자와 검증자가 같은 키를 공유)**와 비대칭키(발급자만 개인키를 갖고, 검증자는 공개키만 가짐). 이 차이가 "검증하는 서비스가 여러 개로 늘어날 때" 어떤 파장을 낳는지가 이 절의 핵심이다.
HS256 (대칭키): 발급자와 검증자가 같은 비밀키를 공유한다. 구현은 간단하지만, 검증하는 모든 서비스가 서명 키를 알아야 한다는 게 문제다.
import jwt, datetime
SECRET = "shared-secret" # 모든 검증 서비스가 이 값을 알아야 함
def issue_hs256(user_id: str):
payload = {
"sub": user_id,
"iss": "auth-server",
"aud": "api-server",
"exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1),
}
return jwt.encode(payload, SECRET, algorithm="HS256")
RS256 (비대칭키): 발급자만 개인키를 갖고, 검증자는 공개키만 있으면 된다. 공개키가 유출돼도 위조 토큰을 만들 수 없다는 게 채택 이유다.
with open("private.pem") as f:
PRIVATE_KEY = f.read()
def issue_rs256(user_id: str):
payload = {
"sub": user_id,
"iss": "auth-server",
"aud": "api-server",
"exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1),
}
return jwt.encode(payload, PRIVATE_KEY, algorithm="RS256")
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem
이 프로젝트는 RS256으로 채택한다 - 검증 서비스가 늘어날 걸 감안하면(시리즈 2의 여러 서비스), 비밀키를 여러 곳에 뿌리는 HS256보다 공개키만 배포하면 되는 RS256이 안전하다.
2. 취약점을 직접 뚫어보는 실험
검증 로직을 제대로 구현하지 않으면 뚫리는 지점들을 의도적으로 만들고, 실제로 공격해본다.
# 취약한 검증 - 이렇게 짜면 안 된다는 걸 확인하기 위한 예시
def verify_vulnerable(token: str):
return jwt.decode(token, options={"verify_signature": False}) # 서명 검증 생략
# alg:none 공격 재현
import base64, json
header = base64.urlsafe_b64encode(json.dumps({"alg": "none", "typ": "JWT"}).encode()).rstrip(b"=")
payload = base64.urlsafe_b64encode(json.dumps({"sub": "admin", "iss": "auth-server"}).encode()).rstrip(b"=")
forged_token = header + b"." + payload + b"." # 서명 부분이 비어있음
# verify_vulnerable(forged_token) 을 호출하면 서명 없이 통과되는지 확인
# 올바른 검증 - alg 화이트리스트, iss/aud 필수 확인
def verify_correct(token: str):
return jwt.decode(
token,
PUBLIC_KEY,
algorithms=["RS256"], # alg 화이트리스트 - "none"이 여기 없으면 위조 토큰은 거부됨
audience="api-server",
issuer="auth-server",
)
verify_vulnerable로 위조 토큰이 통과하는 걸 먼저 확인하고, verify_correct로 바꾸면 InvalidAlgorithmError가 나는 걸 대조 확인한다 - 이 순서로 해야 화이트리스트 검증이 왜 필요한지가 실감된다.
3. 토큰 폐기 불가 문제 재현
JWT는 발급 즉시 서버가 통제권을 잃는다 - 로그아웃해도 만료 전까지는 유효하다. 이걸 먼저 재현한 다음 우회 방법을 붙인다.
# 문제 재현: 로그아웃 API를 호출해도 같은 토큰으로 여전히 요청이 통과하는지 확인
# 우회: Redis 블랙리스트
import redis
r = redis.Redis()
def logout(token: str, exp_timestamp: int):
ttl = exp_timestamp - int(time.time())
r.setex(f"blacklist:{token}", ttl, "1") # 토큰 만료 시각까지만 블랙리스트에 유지
def verify_with_blacklist(token: str):
if r.exists(f"blacklist:{token}"):
raise Exception("revoked token")
return verify_correct(token)
이 우회가 근본적 해결이 아니라는 점을 짚어야 한다 - JWT의 원래 강점은 서버가 상태를 들고 있지 않아도 검증이 끝난다는 것(stateless)인데, 블랙리스트는 결국 "폐기된 토큰 목록"이라는 상태를 서버가 다시 들고 있는 것이다. 즉 JWT를 쓰면서도 세션 기반 인증이 갖던 상태 관리 부담을 그대로 다시 짊어지는 셈이다 - 다만 그 상태를 "활성 사용자 전체"가 아니라 "로그아웃·탈취 등으로 명시적으로 폐기된 토큰만"으로 줄였을 뿐이다.
또는 access token은 짧게(예: 5분), refresh token으로 재발급하는 구조로 바꿔 "폐기 불가"의 영향 범위 자체를 줄이는 방법도 함께 구현해본다.
두 방법은 트레이드오프가 다르다 - 블랙리스트는 즉시 폐기가 가능하지만 검증할 때마다 조회 비용(Redis 왕복)이 붙고, 그 저장소 자체가 다시 단일 장애점이 된다. 짧은 만료+refresh는 조회 비용이 없지만 "즉시" 폐기가 아니라 "최대 5분 이내" 폐기이고, refresh token 자체도 어딘가(DB)에 상태로 남아 있어야 나중에 그걸 폐기할 수 있다. 결국 완전한 stateless는 "폐기가 필요 없다고 가정할 수 있는 짧은 순간"에만 성립하고, 실제 서비스는 이 둘을 조합해 상태 관리 범위를 최소화하는 선에서 타협한다.
4. 검증 로직 분산의 고통 재현
verify_correct를 서비스 2~3개(예: api-server, inference-worker)에 그대로 복붙한 뒤, 정책을 하나 바꿔본다 - 예를 들어 RS256에서 키를 로테이션하거나, aud 값을 서비스별로 다르게 요구하도록 변경.
1. 서명 키 로테이션 시나리오: 새 키 쌍을 만들고, 발급 서버는 새 키로 서명하도록 바꾼다.
2. 검증 서비스들이 여전히 예전 공개키를 하드코딩하고 있다면? → 전부 검증 실패
3. 서비스마다 새 공개키를 수동으로 배포해야 하는 절차를 실제로 밟아본다
4. 여기서 자연스럽게 "공개키를 서비스가 각자 들고 있지 않고, 표준 엔드포인트에서 매번 가져오면 되지 않을까"라는 질문이 나온다 → **JWKS(JSON Web Key Set)**: 발급자가 `/.well-known/jwks.json` 같은 고정 URL에 현재 유효한 공개키 목록을 올려두고, 검증하는 쪽은 그 URL에서 키를 받아와 캐싱해 쓰는 방식. 키가 로테이션되면 이 URL의 내용만 바뀌고, 각 서비스는 캐시 만료 후 자동으로 새 키를 받는다 - 수동 배포 절차 자체가 없어진다.
이 실험의 목적은 "복붙된 코드 3벌을 동시에 고치는 게 얼마나 번거로운가"를 직접 재는 것이다 - 이 번거로움이 다음 단계(게이트웨이 레벨 인증)로 넘어가는 이유가 된다.
JWKS를 실제로 구현할 때 놓치기 쉬운 지점이 하나 있다 - JWKS 문서에는 키가 하나만 올라가는 게 아니라 배열로 여러 개가 동시에 노출된다.
{
"keys": [
{ "kid": "2026-01", "kty": "RSA", "n": "...", "e": "AQAB", "use": "sig" },
{ "kid": "2026-07", "kty": "RSA", "n": "...", "e": "AQAB", "use": "sig" }
]
}
이유는 로테이션 중간 상태 때문이다 - 새 키(2026-07)로 서명을 시작한 순간에도, 그 이전에 옛 키(2026-01)로 발급되어 아직 만료되지 않은 토큰들이 여전히 클라이언트 쪽에 떠돌고 있다. 그 토큰들이 검증에 실패하지 않게 하려면, 옛 키가 만료 시각을 다 지날 때까지는 JWKS에서 내려가면 안 된다 - 그래서 발급자는 새 키로 넘어간 뒤에도 "옛 키가 서명한 토큰의 최장 TTL"만큼 옛 공개키를 계속 같이 노출해야 한다.
검증 쪽도 공개키를 하나로 고정해두는 방식에서, JWT Header의 kid 값으로 여러 키 중 무엇을 써야 하는지 먼저 찾는 방식으로 바뀐다.
import requests
_jwks_cache = {}
def get_signing_key(kid: str):
if kid not in _jwks_cache:
jwks = requests.get("https://auth-server/.well-known/jwks.json").json()
_jwks_cache.update({k["kid"]: k for k in jwks["keys"]})
return _jwks_cache[kid] # 캐시에도 없으면 진짜 위조/알 수 없는 kid로 처리
def verify_with_jwks(token: str):
header = jwt.get_unverified_header(token)
key = get_signing_key(header["kid"])
public_key = jwt.algorithms.RSAAlgorithm.from_jwk(key)
return jwt.decode(
token, public_key, algorithms=["RS256"],
audience="api-server", issuer="auth-server",
)
kid가 캐시에 없을 때(방금 로테이션되어 새로 생긴 키일 수 있다) 캐시를 한 번 더 갱신해보고, 그래도 없으면 그때 위조로 처리한다 - 이 캐시 무효화 로직이 JWKS 방식에서 실제로 신경 써서 구현해야 하는 부분이다.
5. Keycloak + Envoy Gateway 마이그레이션
OIDC(OpenID Connect)란: OAuth 2.0은 원래 "이 앱이 내 데이터에 접근해도 되는가(인가)"를 다루는 표준이었다. OIDC는 그 위에 "이 요청을 보낸 사람이 누구인가(인증)"를 표준화해 얹은 것이다. 핵심 역할이 셋 있다 - 신원을 검증하고 토큰을 발급하는 IdP(Identity Provider), 그 토큰을 받아 신뢰하는 쪽, 실제로 보호되는 API. 지금까지 만든 auth-server가 사실상 이 IdP 역할을 자체 구현한 것이었다.
Keycloak이란: 오픈소스 IdP다. Realm(사용자·클라이언트를 담는 격리 단위) 안에 클라이언트를 등록해두면, 로그인 화면·비밀번호 정책·MFA·세션 관리·표준 OIDC 엔드포인트를 전부 대신 제공한다 - 지금까지 auth-server에 직접 구현했던 것들(그리고 못 구현했던 MFA 같은 것들)을 설정만으로 얻는다.
여기서 짚어야 할 트레이드오프가 있다 - Keycloak은 세션도 서버 측에서 관리한다(로그인 세션, refresh token 세션). 이게 자체 auth-server가 갖고 있던 완전한 stateless JWT와 다른 지점이다. 세션 상태가 있으니 관리자가 콘솔에서 "이 사용자 강제 로그아웃"을 누르면 즉시 반영된다 - 3번에서 재현한 "폐기 불가" 문제가 세션 레벨에서는 실제로 해결된 것처럼 보인다.
그런데 이 즉시성이 access token 자체에는 그대로 적용되지 않는다. Envoy Gateway가 JWKS로 오프라인 검증(서명만 확인하고 Keycloak에 매 요청마다 물어보지 않는 방식)을 하는 한, 이미 발급된 access token은 세션이 끊긴 뒤에도 만료 전까지는 여전히 유효하다 - 이건 시리즈 앞부분에서 자체 구현한 JWT와 정확히 같은 한계다. 즉시 폐기가 꼭 필요하면 오프라인 JWKS 검증 대신 토큰 introspection(요청마다 Keycloak에 "이 토큰 아직 유효해?"라고 되묻는 방식)으로 바꿔야 하는데, 이러면 매 요청이 Keycloak을 한 번 더 타는 것이므로 stateless JWT가 주려던 확장성 이점(검증 서비스가 발급자에게 매번 물어보지 않고 자체 완결적으로 검증하는 것)을 스스로 포기하는 셈이다. 이 프로젝트는 access token은 계속 오프라인 JWKS 검증으로 두고, "즉시 폐기가 필요한 대상"은 세션·refresh token 레벨(로그아웃, 관리자 강제 만료)로 한정한다 - 완전한 즉시성 대신 확장성을 지키는 절충이다.
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install keycloak bitnami/keycloak --set auth.adminPassword=<시크릿>
Realm과 클라이언트를 만든 뒤, Envoy Gateway의 SecurityPolicy로 OIDC를 붙인다.
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
name: api-oidc
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: api-route
oidc:
provider:
issuer: "https://keycloak.local/realms/devops-lab"
clientID: "api-server"
clientSecret:
name: keycloak-api-secret
forwardAccessToken: true
이 SecurityPolicy를 붙였다고 해서 auth-server를 하루아침에 내릴 수는 없다 - 이미 발급되어 클라이언트가 들고 있는 자체 JWT들이 만료 전까지 남아 있고, 배포 순서상 일부 서비스는 아직 게이트웨이 뒤로 옮기지 못했을 수도 있다. 그래서 전환 기간 동안은 두 발급자(auth-server, Keycloak)가 만든 토큰을 동시에 검증해야 하는 dual-issuer 구간이 생긴다.
구분 기준은 iss 클레임이다. 두 발급자가 서로 다른 iss 값을 쓰도록 하고, 검증 로직은 토큰을 열어 iss부터 확인한 뒤 그에 맞는 키 소스로 분기한다.
def verify_dual_issuer(token: str):
claims = jwt.decode(token, options={"verify_signature": False})
iss = claims.get("iss")
if iss == "auth-server":
return jwt.decode(token, PUBLIC_KEY, algorithms=["RS256"],
audience="api-server", issuer="auth-server")
elif iss == "https://keycloak.local/realms/devops-lab":
key = get_signing_key(jwt.get_unverified_header(token)["kid"]) # Keycloak JWKS에서 조회
public_key = jwt.algorithms.RSAAlgorithm.from_jwk(key)
return jwt.decode(token, public_key, algorithms=["RS256"],
audience="api-server", issuer=iss)
else:
raise Exception("unknown issuer")
서명 검증 전에 iss만 먼저 읽는 게 위조 위험처럼 보일 수 있는데, 이 단계에서는 아직 아무것도 신뢰하지 않는다 - iss는 분기용 힌트일 뿐이고, 실제 신뢰는 분기 이후 각 브랜치가 그 발급자에 맞는 키로 서명을 검증하는 순간에 생긴다. 순서는 자체 auth-server의 신규 토큰 발급을 먼저 중단하고, 기존에 뿌려진 토큰들의 최장 만료 시간이 다 지나간 뒤에야 이 분기 로직과 auth-server 자체를 함께 제거하는 식으로 잡는다.
서비스 쪽 verify_correct 호출을 전부 제거하고, 게이트웨이가 전달한 헤더의 클레임만 읽도록 바꾼다. 클라이언트 시크릿은 SealedSecret으로 감싸 Git에 커밋한다.
kubeseal --format yaml < keycloak-api-secret.yaml > keycloak-api-secret.sealed.yaml
6. ISMS-P 관점 비교
자체 JWT 구조로는 못 보여줬을 증적을 Keycloak Admin Console에서 확인하고 캡처해둔다 - 비밀번호 정책 화면, MFA 설정 화면, 활성 세션 목록, 로그인 시도 이력. 이게 시리즈 11(ISMS-P 매핑)에서 "2.5 인증 및 권한관리" 항목의 실제 증적이 된다.
검증 방법
- 위조 토큰(
alg:none, 서명 없음, 만료된 토큰, 잘못된aud)이 각각 어느 단계에서 거부되는지 케이스별로 확인 - 로그아웃 후 같은 토큰으로 요청 시 거부되는지 확인 (단, 이미 발급된 access token은 만료 전까지 유효할 수 있음을 함께 확인 - 세션 폐기 ≠ access token 즉시 무효화)
- 키 로테이션 중 옛
kid로 발급된 토큰과 새kid로 발급된 토큰이 둘 다 같은 JWKS 문서로 검증되는지 확인 - Keycloak 마이그레이션 후 서비스 코드에 JWT 검증 로직이 완전히 제거됐는지 grep으로 확인 (
import jwt등이 남아있지 않아야 함) - 전환 기간 중 auth-server 발급 토큰과 Keycloak 발급 토큰이
iss분기로 둘 다 검증되는지 확인
체크리스트
- 5-1: HS256/RS256 자체 발급 서버 구현, 취약점 실험, 토큰 폐기 우회 구현, stateless 재발급 vs 블랙리스트 트레이드오프 정리
- 5-2: 서비스 2~3개에 검증 복붙 → 정책 변경 시나리오 → JWKS 개념 도출 (kid 기반 다중 키 로테이션 구현)
- 5-3: Keycloak + Envoy Gateway 마이그레이션, dual-issuer 전환 구간 구현, 서비스 내 검증 코드 제거, SealedSecret
- 5-4: ISMS-P 관점 회고 - 증적 화면 캡처 정리, 세션 관리 vs stateless JWT 트레이드오프 정리