Keycloak을 Kubernetes, ALB, oauth2-proxy, NGINX Ingress 같은 환경에 붙이다 보면 처음에는 단순히 “로그인 화면이 뜨는지”만 확인하게 됩니다. 하지만 실무에서 문제가 터지는 지점은 대부분 로그인 화면이 아니라 그 이후입니다.

예를 들면 다음과 같은 문제가 자주 발생합니다.

• 로그인은 성공했는데 다시 로그인 페이지로 돌아간다.
• Access Token은 살아 있는데 애플리케이션 세션은 끊겼다.
• Refresh Token이 만료되어 갑자기 401이 발생한다.
• 브라우저 쿠키를 지웠더니 Keycloak 로그인 상태도 풀린다.
• 로그아웃했는데 다른 서비스에서는 여전히 로그인된 것처럼 보인다.

이 글에서는 Keycloak 인증이 실제로 어떻게 동작하는지 세션, 토큰, 쿠키 관점에서 끝까지 분해해봅니다. 단순 설정값 설명이 아니라 브라우저, 애플리케이션, Keycloak 사이에서 어떤 데이터가 오가는지 기준으로 설명합니다.

1. 먼저 구분해야 할 것: 인증과 인가

Keycloak을 이해하려면 먼저 인증(Authentication)과 인가(Authorization)를 분리해야 합니다.

Keycloak은 사용자를 인증하고, 인증 결과를 토큰으로 발급합니다. 애플리케이션은 이 토큰을 보고 “이 사용자가 누구인지”, “어떤 권한을 가지고 있는지”를 판단합니다.

즉 Keycloak은 일반적으로 다음 역할을 합니다.

• 사용자 로그인 처리
• SSO 세션 관리
• ID Token, Access Token, Refresh Token 발급
• 클라이언트별 세션 관리
• 로그아웃 및 세션 종료 처리

2. Keycloak 인증 구조의 주요 구성요소

2.1 Browser

브라우저는 사용자가 접근하는 클라이언트입니다. 브라우저는 직접 토큰을 다루기도 하고, 경우에 따라 애플리케이션 서버나 oauth2-proxy가 토큰을 대신 보관하기도 합니다.

중요한 점은 브라우저가 항상 쿠키를 중심으로 상태를 유지한다는 것입니다. 브라우저는 요청할 때 도메인에 맞는 쿠키를 자동으로 전송합니다.

2.2 Application

애플리케이션은 실제 서비스를 제공하는 서버입니다. Spring Boot, Node.js, React + Backend API, Grafana, Argo CD 같은 서비스가 여기에 해당합니다.

애플리케이션은 직접 Keycloak과 OIDC 연동을 할 수도 있고, 앞단에 oauth2-proxy나 ALB OIDC를 두고 인증을 위임할 수도 있습니다.

2.3 Keycloak

Keycloak은 Identity Provider이자 OpenID Provider입니다. 사용자 인증을 수행하고, 인증 결과로 토큰을 발급합니다.

Keycloak은 단순히 로그인 화면만 제공하는 것이 아니라, 사용자 세션과 클라이언트 세션을 함께 관리합니다.

2.4 Client

Keycloak에서 말하는 Client는 애플리케이션을 의미합니다. 예를 들어 다음과 같은 단위가 모두 Client가 될 수 있습니다.

• grafana-client
• argocd-client
• spring-api-client
• oauth2-proxy-client
• alb-oidc-client

Client에는 redirect URI, client secret, allowed scope, token lifespan 같은 설정이 연결됩니다. 실무에서는 이 Client 설정이 틀려서 인증 오류가 발생하는 경우가 매우 많습니다.

3. Keycloak 인증의 기본 흐름

가장 일반적인 웹 로그인 방식은 Authorization Code Flow입니다. 이 방식에서는 브라우저가 바로 토큰을 받지 않습니다. 먼저 authorization code를 받고, 애플리케이션 또는 프록시가 그 code를 Keycloak의 Token Endpoint로 교환합니다.

[1] 사용자 → 애플리케이션 접속
[2] 애플리케이션 → 인증 필요 판단
[3] 브라우저 → Keycloak 로그인 페이지로 리다이렉트
[4] 사용자 → Keycloak에서 로그인
[5] Keycloak → authorization code 발급
[6] 브라우저 → redirect_uri로 code 전달
[7] 애플리케이션 또는 프록시 → code를 token endpoint로 교환
[8] Keycloak → ID Token, Access Token, Refresh Token 발급
[9] 애플리케이션 또는 프록시 → 자체 세션 쿠키 생성
[10] 사용자 → 로그인된 상태로 서비스 이용

여기서 핵심은 브라우저가 처음부터 Access Token을 들고 다니는 구조가 아닐 수 있다는 점입니다. 서버사이드 웹 애플리케이션이나 oauth2-proxy 구조에서는 토큰을 서버 또는 프록시가 관리하고, 브라우저는 세션 쿠키만 들고 다니는 경우가 많습니다.

4. 토큰 3종류: ID Token, Access Token, Refresh Token

4.1 ID Token

ID Token은 사용자의 신원을 나타내는 토큰입니다. 즉 “이 사용자가 누구인가?”에 대한 정보를 담습니다.

보통 다음과 같은 claim이 들어갑니다.

• sub: 사용자 고유 식별자
• preferred_username: 사용자 이름
• email: 이메일
• name: 표시 이름
• iss: 토큰 발급자
• aud: 토큰 대상 클라이언트
• exp: 만료 시간

ID Token은 주로 로그인 결과 확인과 사용자 프로필 확인에 사용합니다. API 권한 검사용으로 Access Token 대신 ID Token을 사용하는 것은 적절하지 않습니다.

4.2 Access Token

Access Token은 API 접근 권한을 나타내는 토큰입니다. 즉 “이 사용자가 어떤 리소스에 접근할 수 있는가?”에 더 가깝습니다.

API 서버는 Access Token을 검증해서 요청을 허용하거나 거부합니다. Keycloak Access Token에는 realm role, client role, scope 같은 권한 정보가 포함될 수 있습니다.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

일반적으로 Access Token은 짧게 유지하는 것이 좋습니다. 탈취되었을 때 피해 시간을 줄이기 위해서입니다.

4.3 Refresh Token

Refresh Token은 Access Token을 재발급받기 위한 토큰입니다. Access Token이 만료될 때마다 사용자가 다시 로그인하면 사용성이 매우 나빠지기 때문에 Refresh Token을 사용합니다.

Access Token 만료
→ Refresh Token으로 Keycloak에 새 Access Token 요청
→ 새 Access Token 발급
→ 사용자는 재로그인 없이 계속 서비스 이용

단, Refresh Token은 Access Token보다 훨씬 민감합니다. Refresh Token이 탈취되면 공격자가 새 Access Token을 계속 발급받을 수 있기 때문입니다. 따라서 브라우저 로컬 스토리지에 Refresh Token을 직접 저장하는 구조는 신중해야 합니다.

5. 세션은 하나가 아니다

Keycloak 인증에서 가장 많이 헷갈리는 부분이 세션입니다. 세션은 하나가 아니라 여러 계층에 존재합니다.

따라서 “로그아웃이 안 된다”는 말은 정확하지 않습니다. 어느 세션이 살아 있는지 확인해야 합니다.

• Keycloak SSO 세션이 살아 있는가?
• 애플리케이션 자체 세션이 살아 있는가?
• oauth2-proxy 세션 쿠키가 살아 있는가?
• 브라우저에 Keycloak 쿠키가 남아 있는가?
• Refresh Token이 아직 유효한가?

6. Keycloak SSO Session

Keycloak SSO Session은 사용자가 Keycloak Realm에 로그인한 상태를 의미합니다. 한 번 Keycloak에 로그인하면 같은 Realm에 연결된 다른 Client에 접근할 때 다시 로그인하지 않아도 되는 이유가 바로 이 SSO Session 때문입니다.

사용자 → Grafana 로그인
→ Keycloak SSO Session 생성

사용자 → Argo CD 접속
→ 같은 Realm의 Keycloak SSO Session 확인
→ 비밀번호 재입력 없이 인증 완료

이것이 SSO의 핵심입니다. 각 애플리케이션이 독립적으로 로그인 정보를 저장하는 것이 아니라, Keycloak이 중앙에서 로그인 상태를 관리합니다.

SSO Session Idle

SSO Session Idle은 사용자가 아무 활동을 하지 않았을 때 세션이 만료되는 시간입니다. 예를 들어 30분으로 설정하면, 일정 시간 동안 갱신 활동이 없을 때 세션이 만료됩니다.

SSO Session Max

SSO Session Max는 사용자가 계속 활동하더라도 세션이 유지될 수 있는 최대 시간입니다. 예를 들어 10시간으로 설정하면 사용자가 계속 서비스를 사용하더라도 10시간 이후에는 다시 인증이 필요할 수 있습니다.

실무에서는 Idle과 Max를 함께 봐야 합니다. Idle만 길게 잡으면 보안 위험이 커지고, Max만 짧게 잡으면 사용자가 업무 중 자주 재로그인하게 됩니다.

7. Client Session

Client Session은 특정 Client에 대한 로그인 상태입니다. Keycloak SSO Session이 “사용자가 Realm에 로그인되어 있다”는 의미라면, Client Session은 “이 사용자가 특정 애플리케이션에도 로그인되어 있다”는 의미입니다.

Keycloak SSO Session
 ├── grafana-client session
 ├── argocd-client session
 └── spring-api-client session

이 구조 때문에 하나의 사용자가 여러 애플리케이션에 로그인할 수 있습니다. 또한 특정 Client만 세션을 종료하거나, 전체 SSO 세션을 종료하는 식의 처리가 가능해집니다.

8. 쿠키는 어디에 쓰이는가?

브라우저 기반 인증에서 쿠키는 매우 중요합니다. 토큰이 아무리 중요해도 브라우저가 매 요청마다 상태를 기억하려면 결국 쿠키가 개입하는 경우가 많습니다.

8.1 Keycloak 도메인의 쿠키

Keycloak은 로그인 과정에서 자신의 도메인에 쿠키를 설정합니다. 이 쿠키는 사용자가 Keycloak에 이미 로그인되어 있는지 확인하는 데 사용됩니다.

auth.example.com
 └── Keycloak 관련 쿠키

사용자가 다른 애플리케이션으로 이동해도 다시 Keycloak으로 리다이렉트되면, Keycloak은 자신의 쿠키를 보고 기존 SSO Session을 확인할 수 있습니다.

8.2 애플리케이션 도메인의 쿠키

애플리케이션도 자체 세션 쿠키를 만들 수 있습니다. 예를 들어 Spring Security를 사용하는 서버사이드 애플리케이션이라면 JSESSIONID 같은 쿠키를 사용할 수 있습니다.

app.example.com
 └── JSESSIONID 또는 application session cookie

이 쿠키는 Keycloak 쿠키와 다릅니다. Keycloak에서 로그아웃하지 않아도 애플리케이션 세션만 만료될 수 있고, 반대로 애플리케이션 쿠키를 지워도 Keycloak SSO Session은 살아 있을 수 있습니다.

8.3 oauth2-proxy 쿠키

oauth2-proxy를 사용하는 경우 브라우저에는 oauth2-proxy가 발급한 세션 쿠키가 저장됩니다. oauth2-proxy는 이 쿠키를 보고 사용자가 이미 인증되었는지 판단합니다.

service.example.com
 └── _oauth2_proxy 쿠키

oauth2-proxy 구조에서는 애플리케이션이 OIDC를 몰라도 됩니다. 대신 oauth2-proxy가 앞단에서 인증을 처리하고, 인증된 사용자 정보만 헤더로 넘겨줍니다.

9. 실제 요청 흐름: 로그인 전

사용자가 보호된 서비스에 처음 접근한다고 가정해보겠습니다.

사용자 브라우저
  ↓
https://app.example.com
  ↓
애플리케이션 또는 프록시
  ↓
"인증 쿠키 없음"
  ↓
Keycloak 로그인 페이지로 리다이렉트

이때 애플리케이션은 사용자를 바로 서비스 화면으로 보내지 않습니다. 인증되지 않았기 때문에 Keycloak의 authorization endpoint로 리다이렉트합니다.

리다이렉트 URL에는 보통 다음 정보가 포함됩니다.

• client_id
• redirect_uri
• response_type=code
• scope=openid
• state
• nonce

여기서 redirect_uri가 Keycloak Client 설정과 정확히 일치하지 않으면 Invalid redirect_uri 오류가 발생합니다.

10. 실제 요청 흐름: 로그인 성공 후

사용자가 Keycloak 로그인 화면에서 인증에 성공하면 Keycloak은 바로 Access Token을 브라우저에 던지는 것이 아니라, authorization code를 redirect_uri로 전달합니다.

Keycloak
  ↓
https://app.example.com/callback?code=abc123&state=xyz

그 다음 애플리케이션 또는 oauth2-proxy는 이 code를 가지고 Keycloak Token Endpoint에 요청합니다.

POST /realms/{realm}/protocol/openid-connect/token

grant_type=authorization_code
code=abc123
client_id=my-client
client_secret=...
redirect_uri=https://app.example.com/callback

Keycloak은 code가 유효하면 토큰을 반환합니다.

{
  "access_token": "...",
  "expires_in": 300,
  "refresh_token": "...",
  "refresh_expires_in": 1800,
  "id_token": "...",
  "token_type": "Bearer"
}

이 순간부터 애플리케이션 또는 프록시는 인증된 사용자를 알 수 있습니다. 그리고 브라우저에는 자체 세션 쿠키를 내려줍니다.

11. 로그인 이후 요청 흐름

로그인 이후 사용자가 다시 app.example.com에 접근하면 매번 Keycloak으로 가지 않습니다. 일반적으로 먼저 애플리케이션 또는 프록시 세션을 확인합니다.

사용자 요청
  ↓
브라우저가 세션 쿠키 전송
  ↓
애플리케이션 또는 oauth2-proxy가 쿠키 검증
  ↓
세션 유효
  ↓
서비스 접근 허용

즉 매 요청마다 Keycloak에 로그인 검사를 요청하는 구조가 아닙니다. 이 점을 오해하면 성능 구조와 장애 포인트를 잘못 판단하게 됩니다.

다만 Access Token이 만료되었고 Refresh Token이 유효한 경우에는 백그라운드에서 토큰 갱신이 발생할 수 있습니다.

Access Token 만료
  ↓
Refresh Token으로 token endpoint 호출
  ↓
새 Access Token 발급
  ↓
사용자 요청 계속 처리

12. Access Token 만료와 세션 만료는 다르다

실무에서 매우 중요한 포인트입니다. Access Token 만료와 로그인 세션 만료는 같은 개념이 아닙니다.

예를 들어 Access Token이 5분짜리여도 Refresh Token이 살아 있으면 사용자는 계속 로그인 상태를 유지할 수 있습니다. 반대로 Access Token이 아직 살아 있어도 애플리케이션 세션 쿠키가 사라지면 다시 인증 흐름을 탈 수 있습니다.

13. 로그아웃은 왜 복잡한가?

로그아웃이 복잡한 이유는 로그인 상태가 여러 곳에 나뉘어 있기 때문입니다.

• 브라우저의 애플리케이션 쿠키
• 브라우저의 Keycloak 쿠키
• Keycloak SSO Session
• Keycloak Client Session
• 애플리케이션 서버 세션
• oauth2-proxy 세션
• Refresh Token

따라서 애플리케이션에서 로컬 쿠키만 삭제하면 Keycloak SSO Session은 살아 있을 수 있습니다. 이 상태에서 다시 로그인 버튼을 누르면 Keycloak 로그인 화면 없이 바로 로그인 완료될 수 있습니다. 사용자 입장에서는 “로그아웃이 안 됐다”고 느낍니다.

올바른 로그아웃 흐름

[1] 애플리케이션 세션 종료
[2] 애플리케이션 쿠키 삭제
[3] Keycloak logout endpoint로 리다이렉트
[4] Keycloak SSO Session 종료
[5] post_logout_redirect_uri로 복귀

SSO 환경에서는 “내 서비스에서만 로그아웃할 것인지”, “Keycloak 전체 SSO 세션까지 종료할 것인지”를 명확히 정해야 합니다.

14. ALB OIDC를 쓰는 경우

AWS ALB OIDC 인증을 사용하면 애플리케이션 앞단의 ALB가 OIDC Client 역할을 수행합니다. 이 경우 애플리케이션은 Keycloak과 직접 통신하지 않아도 됩니다.

Browser
  ↓
AWS ALB
  ↓ OIDC 인증 필요
Keycloak
  ↓ 인증 성공
AWS ALB 세션 쿠키 생성
  ↓
Target Application

이 구조에서는 ALB가 인증을 처리하고, 애플리케이션으로 사용자 정보를 헤더 형태로 전달할 수 있습니다.

장점은 애플리케이션 수정이 적다는 것입니다. 단점은 ALB가 제공하는 OIDC 처리 방식 안에서만 세부 제어가 가능하다는 점입니다. 세밀한 토큰 처리, 복잡한 권한 로직, 커스텀 세션 제어가 필요한 경우에는 제약이 생길 수 있습니다.

15. oauth2-proxy를 쓰는 경우

oauth2-proxy는 애플리케이션 앞단에서 인증을 처리하는 Reverse Proxy입니다. Keycloak과 OIDC 연동을 하고, 인증된 사용자만 내부 서비스로 전달합니다.

Browser
  ↓
oauth2-proxy
  ↓ 인증 필요
Keycloak
  ↓ 인증 성공
oauth2-proxy session 생성
  ↓
Upstream Application

oauth2-proxy를 사용하면 인증 기능이 없는 내부 서비스도 Keycloak으로 보호할 수 있습니다. 예를 들어 사내 대시보드, admin UI, legacy web app 등을 보호할 때 유용합니다.

하지만 oauth2-proxy의 세션 쿠키, Redis session store, cookie secret, refresh 설정을 제대로 이해하지 못하면 redirect loop나 세션 만료 문제가 발생할 수 있습니다.

16. SPA에서 주의할 점

React, Vue, Angular 같은 SPA는 브라우저에서 직접 OIDC 흐름을 처리할 수 있습니다. 하지만 이 경우 토큰 저장 위치가 매우 중요합니다.

보안 관점에서는 브라우저 JavaScript가 Refresh Token을 장기간 직접 들고 있는 구조를 신중히 봐야 합니다. 가능하다면 BFF 또는 서버사이드 세션 구조를 고려하는 것이 안전합니다.

17. 실무에서 권장하는 토큰/세션 설계

모든 서비스에 정답은 없지만, 일반적인 내부 업무 시스템 기준으로는 다음 방향이 안정적입니다.

• Access Token은 짧게 유지한다.
• Refresh Token은 서버사이드 또는 프록시 계층에서 안전하게 관리한다.
• 브라우저에는 가능하면 세션 쿠키 중심으로 상태를 유지한다.
• SSO Session Idle과 Max를 업무 패턴에 맞게 조정한다.
• 로그아웃은 애플리케이션 세션과 Keycloak SSO 세션을 분리해서 설계한다.
• 운영 환경에서는 HTTPS, Secure Cookie, SameSite 정책을 반드시 확인한다.

예시 설정 방향

단, 금융, 관리자 콘솔, 개인정보 처리 시스템은 더 짧은 세션 정책이 필요할 수 있습니다. 반대로 사내 대시보드처럼 민감도가 낮고 사용성이 중요한 시스템은 Idle 시간을 조금 길게 가져갈 수 있습니다.

18. 자주 발생하는 문제와 원인

18.1 Redirect Loop

증상은 로그인 후 다시 로그인 페이지로 돌아가는 것입니다.

주요 원인은 다음과 같습니다.

• redirect_uri 불일치
• 쿠키 도메인 불일치
• SameSite 쿠키 정책 문제
• HTTPS 설정 누락
• 프록시 뒤에서 X-Forwarded-Proto 처리 오류
• oauth2-proxy cookie secret 또는 session 설정 오류

18.2 401 Unauthorized

로그인은 된 것 같은데 API 호출이 401로 실패하는 경우입니다.

주요 원인은 다음과 같습니다.

• Access Token 만료
• audience 불일치
• issuer 불일치
• API 서버의 JWKS 검증 실패
• role 또는 scope 매핑 누락

18.3 로그아웃 후 자동 재로그인

애플리케이션 쿠키만 삭제하고 Keycloak SSO Session은 종료하지 않았을 때 발생합니다. Keycloak 세션이 살아 있으면 다시 authorization endpoint로 이동했을 때 로그인 화면 없이 code가 발급될 수 있습니다.

18.4 새로고침 후 로그인 풀림

SPA에서 토큰을 메모리에만 저장한 경우 새로고침 시 토큰이 사라질 수 있습니다. 반대로 localStorage에 저장하면 유지성은 좋아지지만 XSS 위험이 커집니다.

19. 전체 구조 요약

Browser
 ├── 애플리케이션 쿠키
 ├── oauth2-proxy 쿠키
 └── Keycloak 도메인 쿠키

Application / Proxy
 ├── 세션 검증
 ├── Access Token 보관 또는 검증
 ├── Refresh Token으로 갱신
 └── 사용자 정보 헤더 또는 서버 세션 관리

Keycloak
 ├── 사용자 인증
 ├── SSO Session 관리
 ├── Client Session 관리
 ├── ID Token 발급
 ├── Access Token 발급
 └── Refresh Token 발급

결국 Keycloak 인증은 단순히 “로그인 화면을 띄우는 기능”이 아닙니다. 브라우저 쿠키, 애플리케이션 세션, Keycloak SSO Session, Client Session, Access Token, Refresh Token이 함께 동작하는 구조입니다.

20. 결론

Keycloak을 실무에서 안정적으로 운영하려면 토큰만 보면 안 됩니다. 반대로 쿠키만 봐도 안 됩니다. 반드시 세션, 토큰, 쿠키를 함께 봐야 합니다.

핵심은 다음과 같습니다.

• ID Token은 사용자 신원 확인용이다.
• Access Token은 API 접근 권한 검증용이다.
• Refresh Token은 Access Token 재발급용이다.
• Keycloak SSO Session과 애플리케이션 세션은 다르다.
• 브라우저 쿠키는 인증 상태 전달의 핵심이다.
• 로그아웃은 로컬 세션 종료와 Keycloak SSO 세션 종료를 분리해서 봐야 한다.
• ALB OIDC, oauth2-proxy, 애플리케이션 직접 연동은 세션을 관리하는 위치가 다르다.

따라서 Keycloak 장애를 분석할 때는 항상 다음 순서로 확인하는 것이 좋습니다.

1. 브라우저 쿠키가 정상적으로 저장되는가?
2. redirect_uri가 정확히 일치하는가?
3. authorization code가 정상 발급되는가?
4. token endpoint에서 토큰 교환이 성공하는가?
5. Access Token의 iss, aud, exp, role이 맞는가?
6. Refresh Token으로 갱신이 가능한가?
7. Keycloak SSO Session과 애플리케이션 세션 중 어느 쪽이 만료되었는가?

이 기준으로 보면 대부분의 Keycloak 인증 문제는 훨씬 빠르게 원인을 좁힐 수 있습니다.

Keycloak이란 무엇인가

Keycloak은 인증(Authentication)과 권한 부여(Authorization)를 담당하는 서버입니다.

왜 Keycloak을 사용하는가

직접 인증을 구현하면:

• 보안 취약점 발생 가능
• 토큰 관리 복잡

Keycloak 사용자 관리 API

Keycloak에서 사용자 생성, 조회, 변경, 삭제는 Admin REST API를 사용합니다.
일반 로그인 API가 아니라, 관리자 권한을 가진 토큰이 필요합니다. Keycloak 공식 Admin REST API는 사용자 생성 POST /{realm}/users, 사용자 조회 GET /{realm}/users, 사용자 수 조회 GET /{realm}/users/count 등을 제공합니다.

1. Admin Token 발급

사용자 관리 API를 호출하려면 먼저 관리자용 Access Token을 받아야 합니다.

curl -X POST \
  https://keycloak.example.com/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=admin-cli" \
  -d "client_secret=<CLIENT_SECRET>"

운영 환경에서는 관리자 계정의 아이디/비밀번호를 코드에 넣는 방식보다, 권한이 제한된 관리자용 client를 만들고 client_credentials 방식으로 호출하는 구성이 더 안전합니다.

2. 사용자 생성 API

POST /admin/realms/{realm}/users

curl -X POST \
  https://keycloak.example.com/admin/realms/lab/users \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "testuser@example.com",
    "firstName": "Test",
    "lastName": "User",
    "enabled": true,
    "emailVerified": false
  }'

생성 성공 시 보통 응답 본문은 비어 있고, 201 Created가 반환됩니다. 생성된 사용자의 ID는 응답 헤더의 Location 값에서 확인하거나, username으로 다시 조회해서 확인합니다.

3. 사용자 목록 조회 API

GET /admin/realms/{realm}/users

curl -X GET \
  "https://keycloak.example.com/admin/realms/lab/users?first=0&max=20" \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"
  
  
  curl -X GET \
  "https://keycloak.example.com/admin/realms/lab/users?username=testuser&exact=true" \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

4. 사용자 상세 조회 API

사용자 상세 조회는 username이 아니라 user id 기준으로 호출합니다.

GET /admin/realms/{realm}/users/{user-id}

curl -X GET \
  https://keycloak.example.com/admin/realms/lab/users/<USER_ID> \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

응답 예시:

{
  "id": "c9b1...",
  "username": "testuser",
  "email": "testuser@example.com",
  "enabled": true,
  "emailVerified": false
}

5. 사용자 정보 변경 API

PUT /admin/realms/{realm}/users/{user-id}

curl -X PUT \
  https://keycloak.example.com/admin/realms/lab/users/<USER_ID> \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "new-email@example.com",
    "firstName": "New",
    "lastName": "User",
    "enabled": true
  }'

주의할 점은 변경 API는 부분 업데이트처럼 생각하면 안 됩니다. 기존 값 유지가 필요한 필드는 함께 보내는 것이 안전합니다.

6. 사용자 비밀번호 변경 API

사용자 기본 정보 변경과 비밀번호 변경은 API가 다릅니다.

PUT /admin/realms/{realm}/users/{user-id}/reset-password

curl -X PUT \
  https://keycloak.example.com/admin/realms/lab/users/<USER_ID>/reset-password \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "password",
    "value": "NewPassword123!",
    "temporary": false
  }'

temporary: true로 설정하면 사용자는 다음 로그인 시 비밀번호 변경을 요구받습니다.

7. 사용자 비활성화

사용자를 삭제하지 않고 로그인을 막고 싶다면 enabled를 false로 변경합니다.

curl -X PUT \
  https://keycloak.example.com/admin/realms/lab/users/<USER_ID> \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

8. 사용자 삭제 API

DELETE /admin/realms/{realm}/users/{user-id}

curl -X DELETE \
  https://keycloak.example.com/admin/realms/lab/users/<USER_ID> \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>"

이 구조를 왜 쓰는가

보통 서비스에 로그인 기능을 넣으려면:

• 로그인 API 개발
• 세션 관리
• 토큰 검증

이걸 서비스마다 반복해야 합니다.

이 구조는 다르게 접근합니다.

• 로그인은 Keycloak이 담당
• 인증 체크는 oauth2-proxy가 담당
• 서비스는 인증 여부만 전달받음

즉, 애플리케이션은 인증 로직을 몰라도 됩니다.

전체 흐름 

1. 사용자가 서비스 접속
2. Ingress가 oauth2-proxy로 요청 전달
3. 인증 안 되어 있으면 Keycloak으로 리다이렉트
4. 로그인 성공 후 다시 돌아옴 (/oauth2/callback)
5. oauth2-proxy가 쿠키 생성
6. 이후 요청은 인증된 상태로 서비스 전달

브라우저 쿠키 기반 인증 유지

구성방법

1. Keycloak 설정 

Client 생성

• Client ID: my-client
• Client Protocol: openid-connect
• Access Type: confidential

Redirect URI (가장 중요)

https://your-domain/oauth2/callback

2. oauth2-proxy 설정

args:
  - --provider=oidc
  - --oidc-issuer-url=https://keycloak.example.com/realms/<realm>
  - --client-id=my-client
  - --client-secret=<CLIENT_SECRET>
  - --redirect-url=https://your-domain/oauth2/callback
  - --cookie-secret=<BASE64_ENCODED_SECRET>
  - --cookie-secure=true
  - --cookie-samesite=lax
  - --email-domain=*
  - --upstream=http://your-service:80

issuer URL 수정

❌ 잘못된 예:

/auth/realms/<realm>

✅ 최신 Keycloak:

/realms/<realm>

cookie-secret

• 반드시 base64 인코딩된 값
• 32byte 이상 권장

upstream 설정

이 값이 없으면 인증 후 어디로 보낼지 모릅니다.

3. Ingress 설정 

Nginx Ingress 예시

annotations:
  nginx.ingress.kubernetes.io/auth-url: "http://oauth2-proxy.oauth2-proxy.svc.cluster.local/oauth2/auth"
  nginx.ingress.kubernetes.io/auth-signin: "https://your-domain/oauth2/start?rd=$request_uri"
  nginx.ingress.kubernetes.io/auth-response-headers: Authorization

auth-url은 내부 DNS 사용

oauth2-proxy.<namespace>.svc.cluster.local

/oauth2 path 반드시 열어야 함

Ingress에 아래 path 추가 필요:

- path: /oauth2
  pathType: Prefix
  backend:
    service:
      name: oauth2-proxy
      port:
        number: 80

4. 실제 동작 흐름 

브라우저 기준으로 보면:

1. 서비스 접속 → 로그인 안됨
2. Keycloak 로그인 페이지로 이동
3. 로그인 성공
4. 다시 서비스로 돌아옴
5. 쿠키 생성됨
6. 이후 로그인 없이 접근 가능

자주 발생하는 문제 

1. redirect_uri mismatch

• Keycloak
• oauth2-proxy

두 곳의 URL이 완전히 동일해야 합니다

2. 무한 리다이렉트

• cookie-secret 문제
• HTTPS 미사용

3. no such host

• 내부 DNS 설정 오류
• service 이름 틀림

4. 403 / 401 오류

• auth-url 접근 실패
• ingress annotation 오류

정리

Keycloak + oauth2-proxy 구조는
Kubernetes에서 인증을 표준화하는 강력한 방법입니다.

초기 설정은 복잡하지만,
구성 후에는 모든 서비스에 쉽게 인증을 붙일 수 있습니다.