1) OICD(OpenID Connect) Keycloak Endpoint API Document
💡 OICD(OpenID Connect) Keycloak Endpoint API Document
- Keycloak에서 제공하는 OpenID Connect(OIDC) 프로토콜의 주요 엔드포인트들에 대한 상세 API 문서입니다. 이 문서는 인증(Authentication)과 인가(Authorization)를 위한 다양한 엔드포인트들의 사용법과 파라미터들을 설명합니다.
- 각 엔드포인트는 OAuth 2.0과 OpenID Connect 표준을 준수하며, RESTful API 형태로 제공됩니다.
- 이 엔드포인트는 OAuth 2.0/OpenID Connect의 Authorization Code Flow에서 사용되는 인증 엔드포인트입니다. 사용자를 인증하고 권한을 부여받기 위한 첫 단계로 사용됩니다. - 인증 코드(Authentication Code)를 먼저 발급받은 후, 이를 통해 액세스 토큰을 얻는 2단계 인증과정에서 사용합니다.
// format
// [GET] /realms/{realm-name}/protocol/openid-connect/auth
// example
// http://localhost:9001/realms/dev-realm/protocol/openid-connect/auth?client_id=spring-boot-app&response_type=code&redirect_uri=http://localhost:8080/api/v1/keycloak/callback
1.1. 요청 파라미터
파라미터
필수 여부
설명
client_id
필수
클라이언트 식별자
response_type
필수
code로 설정
redirect_uri
필수
인증 코드를 전달받을 리다이렉트 URL
scope
권장
요청하는 권한 범위 (openid, profile 등)
state
권장
CSRF 방지를 위한 임의의 문자열
prompt
선택
인증 프롬프트 동작 설정 (none, login, consent 등)
nonce
권장
재생 공격 방지를 위한 임의의 문자열
code_challenge
선택
PKCE를 위한 코드 챌린지
code_challenge_method
선택
코드 챌린지 생성 방식 (S256 또는 plain)
1.2. 응답 파라미터
파라미터
설명
code
발급된 인증 코드
state
요청 시 전달한 state 값과 동일한 값
session_state
키클록 세션 상태 식별자
error
오류 발생 시 오류 코드
error_description
오류에 대한 상세 설명
2. 인증 엔드포인트 : response_type=token
💡 인증 엔드포인트 : response_type=token
- 엔드포인트는 OAuth 2.0/OpenID Connect의 Implicit Flow에서 사용되는 인증 엔드포인트입니다. 사용자 인증 후 액세스 토큰을 즉시 클라이언트에게 전달하는 단순화된 인증 방식을 제공합니다.
- response_type=token과 다르게, 단일 요청으로 액세스 토큰을 직접 받을 수 있으며 별도의 토큰 교환 단계가 필요로 하지 않습니다. - 토큰이 URL 프래그먼트를 통해 전달되어 보안에 취약할 수 있습니다.
// format
// [GET] /realms/{realm-name}/protocol/openid-connect/auth
// example
// http://localhost:9001/realms/dev-realm/protocol/openid-connect/auth?client_id=spring-boot-app&response_type=token&redirect_uri=http://localhost:3000/login/callback
2.1. 요청 파라미터
파라미터
필수 여부
설명
client_id
필수
클라이언트 식별자
response_type
필수
token으로 설정
redirect_uri
필수
토큰을 전달받을 리다이렉트 URL
scope
권장
요청하는 권한 범위 (openid, profile 등)
state
권장
CSRF 방지를 위한 임의의 문자열
2.2. 응답 파라미터
파라미터
설명
access_token
발급된 액세스 토큰
token_type
토큰 타입 (일반적으로 "Bearer")
expires_in
토큰 만료 시간 (초 단위)
scope
부여된 권한 범위
state
요청 시 전달한 state 값과 동일한 값
4) 토큰 발급(openid-connect/token)
💡 토큰 발급(openid-connect/token)
- 토큰 발급의 종류는 grant_type에 따라서 각기 다른 처리를 수행합니다.
Grant Type
설명
사용 상황
보안 수준
authorization_code
인증 코드를 통해 토큰을 발급받는 방식
일반적인 웹 애플리케이션
높음
password
사용자의 아이디/비밀번호로 직접 토큰을 발급받는 방식
레거시 애플리케이션, 신뢰할 수 있는 자체 애플리케이션
낮음
client_credentials
클라이언트 자격증명만으로 토큰을 발급받는 방식
서버 간 통신, 백그라운드 작업
중간
refresh_token
리프레시 토큰을 사용하여 새로운 액세스 토큰을 발급받는 방식
액세스 토큰 갱신이 필요한 경우
중간
implicit
단일 요청으로 토큰을 즉시 발급받는 방식
SPA(Single Page Application), 모바일 앱
매우 낮음
1. 토큰 발급 : grant_type=password
💡 토큰 발급 : grant_type=password
- 사용자의 username과 password를 직접 사용하여 토큰을 발급받는 방식입니다. 이 방식은 보안상 위험하므로 특별한 경우에만 사용해야 합니다. - Password Grant Type은 레거시 애플리케이션을 위한 것으로, 새로운 애플리케이션에서는 권장되지 않습니다.
// format
// [POST] /realms/{realm-name}/protocol/openid-connect/token
// example
// http://localhost:9001/realms/dev-realm/protocol/openid-connect/token
// curl example
curl -X POST "http://localhost:9001/realms/dev-realm/protocol/openid-connect/token" \\
-H "Content-Type: application/x-www-form-urlencoded" \\
-d "grant_type=password" \\
-d "client_id=spring-boot-app" \\
-d "client_secret=oDq9fBBGRbpkCsZP3dhsS84TBfyjJk1h" \\
-d "username=adjh54" \\
-d "password=test1234"
1.1. 요청 파라미터
파라미터
필수 여부
설명
grant_type
필수
password로 설정
username
필수
사용자 아이디
password
필수
사용자 비밀번호
client_id
필수
클라이언트 식별자
client_secret
조건부
클라이언트 비밀키 (confidential 클라이언트의 경우)
scope
선택
요청하는 권한 범위 (openid, profile 등)
code
선택
인증 엔드포인트에서 받은 인증 코드
redirect_uri
선택
인증 코드를 받을 때 사용한 리다이렉트 URI와 동일해야 함
code_verifier
선택
PKCE 사용 시 필수 (code_challenge에 대응되는 값)
2.2. 응답 파라미터
파라미터
설명
access_token
발급된 액세스 토큰
token_type
토큰 타입 (Bearer)
expires_in
액세스 토큰 만료 시간 (초)
refresh_token
리프레시 토큰
scope
발급된 토큰의 권한 범위
2. 토큰 발급 : grant_type=authorization_code
💡 토큰 발급 : grant_type=authorization_code
- OAuth 2.0의 가장 일반적이고 안전한 인증 방식입니다. 즉, 사용자가 인증을 완료한 후 받은 인증 코드(authorization code)를 액세스 토큰으로 교환하는 방식입니다. - 클라이언트는 인증 코드를 안전하게 토큰으로 교환할 수 있으며, 리프레시 토큰도 함께 받을 수 있습니다.
// format
// [POST] /realms/{realm-name}/protocol/openid-connect/token
// example
// http://localhost:9001/realms/dev-realm/protocol/openid-connect/token
// curl example
curl -X POST "http://localhost:9001/realms/dev-realm/protocol/openid-connect/token" \\
-H "Content-Type: application/x-www-form-urlencoded" \\
-d "grant_type=authorization_code" \\
-d "client_id=spring-boot-app" \\
-d "client_secret=WnmQEGAOzEJ7Kyr2UCJha5AXKCjwnGpB" \\
-d "code=c6266a3a-1875-4125-86bf-0d438dcf3241.141a70b8-9fd9-4544-9496-383a0b74b39a.3c756e38-7bf1-47ac-bf36-06d97345b59c" \\
-d "redirect_uri=http://localhost:8080/api/v1/keycloak/callback"
2.1. 요청 파라미터
파라미터
필수 여부
설명
grant_type
필수
authorization_code로 설정
code
필수
인증 엔드포인트에서 받은 인증 코드
client_id
필수
클라이언트 식별자
client_secret
조건부
클라이언트 비밀키 (confidential 클라이언트의 경우 필수)
redirect_uri
필수
인증 코드를 받을 때 사용한 리다이렉트 URI와 동일해야 함
code_verifier
조건부
PKCE 사용 시 필수 (code_challenge에 대응되는 값)
username
선택
사용자 아이디
password
선택
사용자 비밀번호
scope
선택
요청하는 권한 범위 (openid, profile 등)
2.2. 응답 파라미터
파라미터
설명
access_token
발급된 액세스 토큰
token_type
토큰 타입 (일반적으로 "Bearer")
expires_in
액세스 토큰 만료 시간 (초 단위)
refresh_token
리프레시 토큰 (scope에 offline_access가 포함된 경우)
id_token
OpenID Connect 사용 시 발급되는 ID 토큰
expires_in
액세스 토큰 만료 시간 (초)
scope
발급된 토큰의 권한 범위
3. 토큰 발급 : grant_type=client_credentials
💡 토큰 발급 : grant_type=client_credentials
- 클라이언트가 자신의 자격증명을 사용하여 직접 액세스 토큰을 얻는 방식입니다. - 이 방식은 사용자 컨텍스트가 필요 없는 서버 간 통신이나 백그라운드 작업에 적합합니다. - 클라이언트 인증 정보만으로 토큰을 발급받기 때문에, 높은 보안이 요구되는 confidential 클라이언트에서만 사용해야 합니다.
// format
// [POST] /realms/{realm-name}/protocol/openid-connect/token
// example
// http://localhost:9001/realms/dev-realm/protocol/openid-connect/token
// curl example
curl -X POST "http://localhost:9001/realms/dev-realm/protocol/openid-connect/token" \\
-H "Content-Type: application/x-www-form-urlencoded" \\
-d "grant_type=client_credentials" \\
-d "client_id=spring-boot-app" \\
-d "client_secret=WnmQEGAOzEJ7Kyr2UCJha5AXKCjwnGpB"
3.1. 요청 파라미터
파라미터
필수 여부
설명
grant_type
필수
client_credentials로 설정
client_id
필수
클라이언트 식별자
client_secret
필수
클라이언트 비밀키
scope
선택
요청하는 권한 범위
code
선택
인증 엔드포인트에서 받은 인증 코드
redirect_uri
선택
인증 코드를 받을 때 사용한 리다이렉트 URI와 동일해야 함
code_verifier
선택
PKCE 사용 시 필수 (code_challenge에 대응되는 값)
username
선택
사용자 아이디
password
선택
사용자 비밀번호
scope
선택
요청하는 권한 범위 (openid, profile 등)
3.2. 응답 파라미터
파라미터
설명
access_token
발급된 액세스 토큰
token_type
토큰 타입 (Bearer)
expires_in
액세스 토큰 만료 시간 (초)
scope
발급된 토큰의 권한 범위
5) 로그아웃(openid-connect/logout)
💡 로그아웃(openid-connect/logout)
- 사용자의 세션을 종료하고 인증 상태를 해제하는 데 사용됩니다. 이 엔드포인트를 호출하면 Keycloak은 사용자의 세션을 무효화하고, 발급된 토큰들을 취소합니다.
1. 로그아웃 엔드포인트
💡 로그아웃 엔드포인트
- 로그아웃 후에는 기존에 발급된 모든 토큰이 무효화됩니다. - Single Sign-Out이 구성된 경우, 연결된 모든 애플리케이션에서도 로그아웃이 수행됩니다. - 프론트엔드 애플리케이션의 경우, 로그아웃 후 로컬 저장소의 토큰도 삭제해야 합니다.
// format
// [GET] /realms/{realm-name}/protocol/openid-connect/logout
// example
// http://localhost:9001/realms/dev-realm/protocol/openid-connect/logout?redirect_uri=http://localhost:8080/api/v1/keycloak/logout&client_id=spring-boot-app
1.1. 요청 파라미터
파라미터
필수 여부
설명
redirect_uri
필수
로그아웃 후 리다이렉트될 URL
client_id
필수
클라이언트 식별자
client_secret
조건부
클라이언트 비밀키 (confidential 클라이언트의 경우 필수)
6) 토큰 검증(openid-connect/token/introspect)
💡 토큰 검증(openid-connect/token/introspect)
- 토큰의 유효성을 검사하고 토큰에 대한 메타데이터를 조회하는 엔드포인트입니다. - 토큰이 유효한지, 만료되었는지, 어떤 권한을 가지고 있는지 등의 정보를 확인할 수 있습니다. - 리소스 서버에서 클라이언트가 제시한 토큰의 유효성을 검증할 때 사용됩니다.
// format
// [POST] /realms/{realm-name}/protocol/openid-connect/token/introspect
// example
// <http://localhost:9001/realms/dev-realm/protocol/openid-connect/token/introspect>
// curl example
curl -X POST \\
'http://localhost:9001/realms/dev-realm/protocol/openid-connect/token/introspect' \\
-H 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'token=sdjkhfsdkjfhg' \\
--data-urlencode 'client_id=spring-boot-app' \\
--data-urlencode 'client_secret=WnmQEGAOzEJ7Kyr2UCJha5AXKCjwnGpB'
1.1. 요청 파라미터
파라미터
필수 여부
설명
token
필수
검증할 토큰 (액세스 토큰 또는 리프레시 토큰)
client_id
필수
클라이언트 식별자
client_secret
조건부
클라이언트 비밀키 (confidential 클라이언트의 경우 필수)
token_type_hint
선택
토큰 타입 힌트 (access_token 또는 refresh_token)
1.2. 응답 파라미터
필드
설명
active
토큰의 유효성 여부 (true/false)
exp
토큰 만료 시간 (Unix timestamp)
iat
토큰 발급 시간 (Unix timestamp)
aud
토큰의 대상 청중
sub
토큰 주체 (사용자 ID)
scope
토큰의 권한 범위
username
사용자 이름
email
사용자 이메일
name
사용자 전체 이름
7) 사용자 조회(opendi-connect/userinfo)
💡 사용자 조회(opendi-connect/userinfo) - 현재 인증된 사용자의 프로필 정보를 조회하는 엔드포인트입니다. - 액세스 토큰을 사용하여 사용자의 기본 정보 및 추가 클레임을 조회할 수 있습니다. - OAuth2.0/OpenID Connect 프로토콜의 표준 엔드포인트입니다.
1. 사용자 정보 조회 엔드포인트
// format
// [GET] /realms/{realm-name}/protocol/openid-connect/userinfo
// example
// localhost:9001/realms/dev-realm/protocol/openid-connect/userinfo
// curl example
curl -X GET \\
'<http://localhost:9001/realms/dev-realm/protocol/openid-connect/userinfo>' \\
-H 'Authorization: Bearer {access_token}'
- 토큰 검증에 사용되는 공개키 인증서를 조회하는 엔드포인트입니다. - JWT 토큰의 서명을 검증하는 데 사용됩니다. - 클라이언트는 이 인증서를 사용하여 토큰의 무결성을 확인할 수 있습니다.
// format
// [GET] /realms/{realm-name}/protocol/openid-connect/certs
// example
// <http://localhost:9001/realms/dev-realm/protocol/openid-connect/certs>
// curl example
curl -X GET '<http://localhost:9001/realms/dev-realm/protocol/openid-connect/certs>'
1.1. 응답 파라미터
필드
설명
keys
JWKS(JSON Web Key Set) 형식의 공개키 목록
kid
키 식별자
kty
키 타입 (예: RSA)
alg
서명 알고리즘
use
키 사용 목적 (sig: 서명)
n
RSA 공개키의 모듈러스
e
RSA 공개키의 지수
9) 클라이언트 등록(clients-registrations/openid-connect)
💡 클라이언트 등록(clients-registrations/openid-connect)
- 새로운 OAuth2.0/OpenID Connect 클라이언트를 등록하는 엔드포인트입니다. - 동적 클라이언트 등록 프로토콜을 구현합니다. - 클라이언트 정보와 설정을 등록할 수 있습니다.
// format
// [POST] /realms/{realm-name}/clients-registrations/openid-connect
// example
// http://localhost:9001/realms/dev-realm/clients-registrations/openid-connect
// curl example
curl -X POST \\
'http://localhost:9001/realms/dev-realm/clients-registrations/openid-connect' \\
-H 'Content-Type: application/json' \\
-d '{
"client_name": "My Client",
"redirect_uris": ["<http://localhost:8080/callback>"],
"grant_types": ["authorization_code"]
}'
1.1. 요청 파라미터
파라미터
필수여부
설명
client_name
필수
클라이언트의 이름
client_uri
선택
클라이언트 웹사이트 URI
redirect_uris
필수
인증 후 리다이렉트될 URI 목록
grant_types
선택
사용할 권한 부여 유형 (예: authorization_code, refresh_token)
response_types
선택
지원하는 응답 유형 (예: code)
client_secret
선택
클라이언트 비밀키
scope
선택
요청할 권한 범위
token_endpoint_auth_method
선택
토큰 엔드포인트 인증 방식
application_type
선택
애플리케이션 유형 (web, native)
contacts
선택
관리자 연락처 이메일
logo_uri
선택
클라이언트 로고 이미지 URI
policy_uri
선택
개인정보 처리방침 URI
tos_uri
선택
서비스 이용약관 URI
jwks_uri
선택
JSON Web Key Set URI
subject_type
선택
subject 식별자 유형
1.2. 응답 파라미터
필드
설명
client_id
생성된 클라이언트의 고유 식별자
client_secret
클라이언트 인증을 위한 비밀키
registration_access_token
클라이언트 설정 관리를 위한 토큰
registration_client_uri
클라이언트 설정 관리 엔드포인트 URI
client_id_issued_at
클라이언트 생성 시간
client_secret_expires_at
클라이언트 시크릿 만료 시간 (0은 만료되지 않음)
10) 토큰 폐기(openid-connect/revoke)
💡 토큰 폐기(openid-connect/revoke)
- 발급된 토큰을 무효화하는 엔드포인트입니다. - 더 이상 사용하지 않을 토큰을 명시적으로 폐기할 수 있습니다. - 보안상의 이유로 토큰을 즉시 무효화해야 할 때 사용됩니다.
// format
// [POST] /realms/{realm-name}/protocol/openid-connect/revoke
// example
// http://localhost:9001/realms/dev-realm/protocol/openid-connect/revoke
// example curl
curl -X POST \\
'http://localhost:9001/realms/dev-realm/protocol/openid-connect/revoke' \\
-H 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'token=your_token_here' \\
--data-urlencode 'client_id=your_client_id' \\
--data-urlencode 'client_secret=your_client_secret'
1.1. 요청 파라미터
파라미터
필수 여부
설명
token
필수
폐기할 토큰 (액세스 토큰 또는 리프레시 토큰)
client_id
필수
클라이언트 ID
client_secret
필수
클라이언트 시크릿
1.2. 응답 상태
상태
설명
200 OK
토큰이 성공적으로 폐기됨
400 Bad Request
잘못된 요청 (유효하지 않은 토큰 또는 클라이언트 인증 실패)
401 Unauthorized
클라이언트 인증 실패
11) 디바이스 인증(openid-connect/auth/device)
💡 디바이스 인증(openid-connect/auth/device)
- 입력이 제한된 디바이스에서 사용하는 인증 플로우를 처리하는 엔드포인트입니다. - 스마트 TV나 IoT 디바이스와 같이 키보드 입력이 어려운 환경에서 사용됩니다. - 사용자는 다른 디바이스에서 인증 코드를 입력하여 인증을 완료할 수 있습니다.
// format
// [POST] /realms/{realm-name}/protocol/openid-connect/auth/device
// example
// http://localhost:9001/realms/dev-realm/protocol/openid-connect/auth/device
// example curl
curl -X POST \\
'http://localhost:9001/realms/dev-realm/protocol/openid-connect/auth/device' \\
-H 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'client_id=your_client_id'
1.1. 요청 파라미터
파라미터
필수 여부
설명
client_id
필수
클라이언트 식별자
scope
선택
요청하는 권한 범위 (예: openid profile email)
resource
선택
접근하고자 하는 리소스의 URI
binding_message
선택
사용자에게 표시될 바인딩 메시지
user_code
선택
사용자가 입력할 인증 코드
1.2. 응답 파라미터
파라미터
설명
device_code
디바이스 인증을 위한 고유 코드
user_code
사용자가 입력해야 하는 검증 코드
verification_uri
사용자가 방문해야 하는 검증 페이지 URL
verification_uri_complete
user_code가 포함된 완전한 검증 URL
expires_in
device_code의 유효 기간 (초)
interval
폴링 간격 (초)
12) CIBA 인증(openid-connect/ext/ciba/auth)
💡 CIBA 인증(openid-connect/ext/ciba/auth)
- Client Initiated Backchannel Authentication을 처리하는 엔드포인트입니다. - 디바이스 간 인증을 위한 백 채널 통신을 지원합니다. - 사용자 상호작용 없이 인증을 완료할 수 있는 방법을 제공합니다.
// format
// [POST] /realms/{realm-name}/protocol/openid-connect/ext/ciba/auth
// example
// <http://localhost:9001/realms/dev-realm/protocol/openid-connect/ext/ciba/auth>
// example curl
curl -X POST \\
'<http://localhost:9001/realms/dev-realm/protocol/openid-connect/ext/ciba/auth>' \\
-H 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'client_id=your_client_id' \\
--data-urlencode 'login_hint=user@example.com'
