Keycloak과 OAuth2 / OIDC
1️⃣ Authorization Code Flow
1. OAuth2 Authorization Code Flow란?
사용자가 Keycloak을 통해 로그인하면, 애플리케이션이 Authorization Code를 받고, 이를 통해 Access Token을 발급받는 표준적인 인증 방식입니다.
이 흐름은 서버 사이드 앱이나 보안이 중요한 SPA + Backend 구조에서 많이 사용됩니다.
2. 아키텍처 및 플로우
사용자 ─────▶ 앱(클라이언트)
│
▼
Keycloak 로그인 페이지
│
▼
사용자 로그인 후 Authorization Code 발급
│
▼
앱이 Authorization Code로 Access Token 요청
│
▼
Keycloak에서 Access Token 발급
3. 요청 예시
GET /auth/realms/myrealm/protocol/openid-connect/auth?
client_id=myapp&
response_type=code&
redirect_uri=https://myapp.com/callback&
scope=openid응답 예시:
https://myapp.com/callback?code=abc1232️⃣ Implicit Flow, Client Credentials Flow
1. Implicit Flow
과거 SPA(Pure JS) 앱에서 사용하던 방식.
Access Token을 직접 URL로 발급받아 보안상 취약하여 현재는 거의 사용 ❌
response_type=tokenKeycloak에서는 기본적으로 비활성화되어 있음 (보안상 권장 X)
2. Client Credentials Flow
서버 간 통신 또는 머신 간 인증 시 사용.
사용자 없이 Client ID/Secret으로 인증하여 토큰을 받습니다.
📦 예: 백엔드 API → Keycloak → 토큰 → 다른 서비스 API 호출
curl -X POST \
https://keycloak.example.com/auth/realms/myrealm/protocol/openid-connect/token \
-d "grant_type=client_credentials" \
-d "client_id=myclient" \
-d "client_secret=abc123"응답 예시:
{
"access_token": "eyJhbGciOi...",
"expires_in": 300
}3️⃣ 토큰 구조 (Access Token, Refresh Token, ID Token)
1. Access Token
- API에 접근할 때 사용
- JWT 형식 (Base64 인코딩)
- 예:
{
"sub": "user123",
"preferred_username": "alice",
"exp": 1712345678,
"realm_access": {
"roles": ["user", "admin"]
}
}2. Refresh Token
- Access Token이 만료되었을 때 재발급 요청에 사용
- 보통 길게 유지됨 (15분 ~ 30일)
3. ID Token
- 사용자 프로필 정보 포함 (OIDC 전용)
- 클라이언트가 사용자의 이름, 이메일, 로그인 시간 등을 확인할 때 사용
예:
{
"name": "Alice Kim",
"email": "alice@example.com",
"auth_time": 1712345600
}4️⃣ Token Introspection 및 사용자 정보 엔드포인트
1. Token Introspection
토큰 유효성 확인을 위한 API.
사용 예: 리소스 서버가 외부에서 받은 토큰을 검증할 때
요청:
curl -X POST \
-d "token=eyJhbG..." \
-u "client_id:client_secret" \
https://keycloak.example.com/auth/realms/myrealm/protocol/openid-connect/token/introspect응답:
{
"active": true,
"username": "alice",
"exp": 1712345678
}2. 사용자 정보 엔드포인트
ID 토큰과 별개로 사용자 정보를 조회 가능
요청:
curl -H "Authorization: Bearer ACCESS_TOKEN" \
https://keycloak.example.com/auth/realms/myrealm/protocol/openid-connect/userinfo응답:
{
"sub": "user-uuid",
"name": "Alice Kim",
"preferred_username": "alice",
"email": "alice@example.com"
}🔚 요약
| 항목 | 설명 |
|---|---|
| Authorization Code Flow | 가장 안전하고 표준적인 로그인 방식 |
| Implicit Flow | 현재는 거의 사용 안 함 (보안 취약) |
| Client Credentials Flow | 백엔드 간 인증 시 사용 |
| Access Token | API 접근 권한 |
| Refresh Token | Access Token 재발급 |
| ID Token | 사용자 정보 포함 |
| Introspection | 토큰 유효성 검증 |
| UserInfo Endpoint | 사용자 정보 조회 API |
마지막 수정일자