해당 글에서는 Keycloak Admin REST API를 기반으로 User 활용 방법 및 예시를 확인해 봅니다.
1) Keycloak Admin REST API : Users
💡 Keycloak Admin REST API : Users - Users 엔드포인트는 사용자 관리를 위한 종합적인 REST API 인터페이스를 제공합니다. - RESTful 아키텍처 원칙을 따르는 표준 HTTP 메서드 사용하며 JSON 형식의 요청/응답 데이터 구조를 가지고 있습니다. - Bearer 토큰 기반의 인증 방식이며 페이지네이션과 필터링을 통한 효율적인 데이터 조회를 수행합니다.
💡 [참고] 아래에서 다루지 않는 API에 대해서는 공식 API 문서를 참고하시면 도움이 됩니다.
- 사용자 관리와 관련된 다양한 작업을 수행할 수 있는 API를 제공합니다. - 사용자 관리, 보안 및 인증 관리(비밀번호 재설정, 세션 관리), 권한 및 그룹 관리에 사용할 수 있습니다. - 이러한 API들은 REST 방식으로 구현되어 있어 HTTP 메서드를 통해 직관적으로 사용할 수 있으며, JSON 형식으로 데이터를 주고받을 수 있습니다.
사용자 접근 권한 설정 - manageGroupMembership: 그룹 멤버십 관리 권한 - view: 조회 권한 - mapRoles: 역할 매핑 권한 - impersonate: 사용자 대리 권한 - manage: 관리 권한
2. 새로운 사용자 생성([POST] /admin/realms/{realm}/users)
💡 새로운 사용자 생성([POST] /admin/realms/{realm}/users)
- 새로운 사용자를 생성하는 API입니다. - 사용자의 기본 정보(사용자명, 이메일, 비밀번호 등)와 추가 속성을 설정할 수 있습니다. - POST 메서드를 사용하며 JSON 형식으로 사용자 정보를 전달합니다.
// format
POST /admin/realms/{realm}/users
// example
POST <http://localhost:9001/admin/realms/dev-realm/users>
// request body
{
"username": "newuser",
"email": "newuser@example.com",
"enabled": true,
"firstName": "New",
"lastName": "User",
"credentials": [{
"type": "password",
"value": "password123",
"temporary": false
}]
}
2.1. 요청 파라미터
💡 요청 파라미터
- 해당 요청 정보는 import org.keycloak.representations.idm.UserRepresentation;를 import 하여서 해당 값들을 객체로 구성하여 요청합니다.
Parameter
Type
Required
Description
username
string
Yes
사용자 로그인 아이디
email
string
No
사용자 이메일 주소
enabled
boolean
No
계정 활성화 여부
firstName
string
No
사용자 이름
lastName
string
No
사용자 성
credentials
array
No
사용자 인증 정보(비밀번호 등)
attributes
object
No
사용자 추가 속성
/**
* 사용자 등록
*/
@PostMapping("/users")
void createUser(
@RequestHeader("Authorization") String bearerToken,
@RequestBody UserRepresentation userRepresentation
);
2.2. 응답
💡 응답
- 성공적인 사용자 생성인 경우 201 Created 상태 코드가 반환됩니다.
응답 코드
응답 상태
Description
201
Created
성공적인 등록
3. 특정 사용자 정보 조회([GET] /admin/realms/{realm}/users/{id})
💡 특정 사용자 정보 조회([GET] /admin/realms/{realm}/users/{id})
- 특정 사용자의 상세 정보를 조회하는 API입니다. - 사용자 ID를 기반으로 해당 사용자의 모든 정보를 반환합니다. - 사용자의 기본 정보, 속성, 그룹 멤버십 등을 확인할 수 있습니다.
// format
// /admin/realms/{realm}/users/{id}
// example
// http://localhost:9001/admin/realms/dev-realm/users/affe220c-b622-44d4-88d0-339bef7edff3
3.1. 요청 파라미터
Parameter
Type
Required
Description
realm
string
Yes
대상 Realm 이름
id
string
Yes
조회할 사용자의 고유 식별자
/**
* 아이디 기반 특정 사용자 조회
*/
@GetMapping("/{id}}")
void selectKeycloakUserDetail(
@RequestHeader("Authorization") String bearerToken,
@PathVariable String id
);
3.2. 응답
💡 응답
- 성공적인 조회의 경우 200 OK 상태 코드와 함께 사용자 정보가 JSON 형식으로 반환됩니다. - 사용자를 찾을 수 없는 경우 404 Not Found 상태 코드가 반환됩니다.
응답 코드
응답 정보
설명
200
OK
성공적인 조회
404
Not Found
조회 실패
4. 사용자 정보 수정([PUT] /admin/realms/{realm}/users/{id})
💡 사용자 정보 수정([PUT] /admin/realms/{realm}/users/{id})
- 기존 사용자의 정보를 업데이트하는 API입니다. - 사용자의 기본 정보, 속성, 설정 등을 수정할 수 있습니다. - PUT 메서드를 사용하며 JSON 형식으로 업데이트할 정보를 전달합니다.
// format
// [PUT] /admin/realms/{realm}/users/{id}
// example
// [PUT] http://localhost:9001/admin/realms/dev-realm/users/affe220c-b622-44d4-88d0-339bef7edff3
// request body
{
"firstName": "Updated",
"lastName": "User",
"email": "updated@example.com",
"enabled": true,
"emailVerified": true,
"attributes": {
"customField": ["value"]
}
}
4.1. 요청 파라미터
💡 요청 파라미터
- 해당 전송하는 파라미터의 경우는 id 값을 제외하고는 UserRepresentation 객체로 구성하여서 전달을 합니다.
Parameter
Type
Required
Description
realm
string
Yes
대상 Realm 이름
id
string
Yes
수정할 사용자의 고유 식별자
username
string
No
사용자 로그인 아이디
email
string
No
사용자 이메일 주소
firstName
string
No
사용자 이름
lastName
string
No
사용자 성
enabled
boolean
No
계정 활성화 여부
emailVerified
boolean
No
이메일 인증 여부
attributes
object
No
사용자 추가 속성
/**
* 사용자 수정
*/
@PutMapping("/users/{id}")
void updateUser(
@RequestHeader("Authorization") String bearerToken,
@PathVariable String id,
@RequestBody UserRepresentation userRepresentation
);
4.2. 응답
응답 코드
응답 설명
설명
204
No Content
성공적인 업데이트
404
Not Found
사용자를 찾을 수 없음
400
Bad Request
요청 본문이 유효하지 않음
5. 사용자 삭제([DELETE] /admin/realms/{realm}/users/{id})
💡 사용자 삭제([DELETE] /admin/realms/{realm}/users/{id})
- 특정 사용자를 시스템에서 삭제하는 API입니다. 삭제된 사용자는 복구할 수 없으며, 관련된 모든 데이터가 함께 삭제됩니다. - DELETE 메서드를 사용합니다.
// format
// DELETE /admin/realms/{realm}/users/{id}
// example
// DELETE http://localhost:9001/admin/realms/dev-realm/users/affe220c-b622-44d4-88d0-339bef7edff3
5.1. 요청 파라미터
Parameter
Type
Required
Description
realm
string
Yes
대상 Realm 이름
id
string
Yes
삭제할 사용자의 고유 식별자
/**
* 사용자 삭제
*/
@DeleteMapping("/users/{id}")
void deleteUser(
@RequestHeader("Authorization") String bearerToken,
@PathVariable String id
);
5.2. 응답
응답 코드
응답 상태
설명
204
No Content
성공적인 삭제
404
Not Found
사용자를 찾을 수 없음
6. 사용자 비밀번호 재설정([PUT] /admin/realms/{realm}/users/{id}/reset-password)
💡 사용자 비밀번호 재설정([PUT] /admin/realms/{realm}/users/{id}/reset-password)
- 특정 사용자의 비밀번호를 재설정하는 API입니다. - 임시 비밀번호를 설정하거나 영구 비밀번호로 변경할 수 있습니다. - PUT 메서드를 사용하며 JSON 형식으로 새 비밀번호 정보를 전달합니다.
// format
// PUT /admin/realms/{realm}/users/{id}/reset-password
// example
// PUT http://localhost:9001/admin/realms/dev-realm/users/97204aa2-1160-4243-903b-81ba2be14de0/reset-password
// request body
{
"type": "password",
"value": "newPassword123",
"temporary": false
}
6.1. 요청 파라미터
💡 요청 파라미터
- 해당 값은 id 값을 제외하고는 import org.keycloak.representations.idm.CredentialRepresentation; 를 import 하여서 객체를 구성하여 전달합니다.
7. 사용자 그룹 조회([GET] /admin/realms/{realm}/users/{id}/groups)
💡 사용자 그룹 조회([GET] /admin/realms/{realm}/users/{id}/groups)
- 특정 사용자가 속한 모든 그룹을 조회하는 API입니다. - 사용자의 그룹 멤버십을 확인하고 관리하는 데 사용됩니다. - GET 메서드를 사용하며 JSON 형식으로 그룹 정보를 반환합니다.
// format
// GET /admin/realms/{realm}/users/{id}/groups
// example
// GET http://localhost:9001/admin/realms/dev-realm/users/97204aa2-1160-4243-903b-81ba2be14de0/groups
7.1. 요청 파라미터
Parameter
Type
Required
Description
realm
string
Yes
대상 Realm 이름
id
string
Yes
그룹을 조회할 사용자의 고유 식별자
/**
* 사용자의 그룹 목록 조회
*/
@GetMapping("/users/{id}/groups")
List<GroupRepresentation> getUserGroups(
@RequestHeader("Authorization") String bearerToken,
@PathVariable String id
);
7.2. 응답
응답 코드
응답 상태
설명
200
OK
성공적인 그룹 목록 조회
404
Not Found
사용자를 찾을 수 없음
8. 사용자 그룹 추가([PUT] /admin/realms/{realm}/users/{id}/groups/{groupId})
💡 사용자 그룹 추가([PUT] /admin/realms/{realm}/users/{id}/groups/{groupId})
- 특정 사용자를 지정된 그룹에 추가하는 API입니다. - 사용자의 그룹 멤버십을 관리하는데 사용됩니다. - PUT 메서드를 사용하며 별도의 요청 본문이 필요하지 않습니다.
// format
// PUT /admin/realms/{realm}/users/{id}/groups/{groupId}
// example
// PUT http://localhost:9001/admin/realms/dev-realm/users/97204aa2-1160-4243-903b-81ba2be14de0/groups/f8293f24-5832-4841-9f23-b85e0c4c6e44
8.1. 요청 파라미터
Parameter
Type
Required
Description
realm
string
Yes
대상 Realm 이름
id
string
Yes
그룹에 추가할 사용자의 고유 식별자
groupId
string
Yes
사용자를 추가할 그룹의 고유 식별자
/**
* 사용자를 그룹에 추가
*/
@PutMapping("/users/{id}/groups/{groupId}")
void addUserToGroup(
@RequestHeader("Authorization") String bearerToken,
@PathVariable String id,
@PathVariable String groupId
);
8.2. 반환 값
응답 코드
Status Code
설명
204
No Content
성공적인 그룹 추가
404
Not Found
사용자 또는 그룹을 찾을 수 없음
9. 사용자 역할 매핑 조회([GET] /admin/realms/{realm}/users/{id}/role-mappings)
💡 사용자 역할 매핑 조회([GET] /admin/realms/{realm}/users/{id}/role-mappings)
- 특정 사용자에게 할당된 모든 역할(role)을 조회하는 API입니다. - 사용자의 권한과 접근 제어를 관리하는데 사용됩니다. - GET 메서드를 사용하며 JSON 형식으로 역할 정보를 반환합니다.
// format
// GET /admin/realms/{realm}/users/{id}/role-mappings
// example
// GET http://localhost:9001/admin/realms/dev-realm/users/97204aa2-1160-4243-903b-81ba2be14de0/role-mappings
9.1. 요청 파라미터
Parameter
Type
Required
Description
realm
String
Yes
대상 Realm 이름
id
String
Yes
역할을 조회할 사용자의 고유 식별자
/**
* 사용자의 역할 매핑 조회
*/
@GetMapping("/users/{id}/role-mappings")
MappingsRepresentation getRoleMappings(
@RequestHeader("Authorization") String bearerToken,
@PathVariable String id
);
9.2. 반환 값
응답 코드
응답 상태
설명
200
OK
성공적인 역할 매핑 조회
404
Not Found
사용자를 찾을 수 없음
10. 사용자 로그아웃([POST] /admin/realms/{realm}/users/{id}/logout)
💡 사용자 로그아웃([POST] /admin/realms/{realm}/users/{id}/logout)
- 특정 사용자의 모든 활성 세션을 종료하는 API입니다. - 강제 로그아웃이 필요한 경우나 보안상의 이유로 세션을 종료해야 할 때 사용됩니다. - POST 메서드를 사용하며 별도의 요청 본문이 필요하지 않습니다.
// format
// POST /admin/realms/{realm}/users/{id}/logout
// example
// POST http://localhost:9001/admin/realms/dev-realm/users/97204aa2-1160-4243-903b-81ba2be14de0/logout
10.1. 요청 파라미터
Parameter
Type
Required
Description
realm
string
Yes
대상 Realm 이름
id
string
Yes
로그아웃할 사용자의 고유 식별자
/**
* 사용자 로그아웃
*/
@PostMapping("/users/{id}/logout")
void logoutUser(
@RequestHeader("Authorization") String bearerToken,
@PathVariable String id
);
