해당 글에서는 Keycloak의 주요 요소 Realm, Client, User, Group, Role을 구성하고 구성환경에 로그인/로그아웃을 수행하는 방법에 대해 알아봅니다

💡 [참고] Keycloak 초기 구성에서부터 활용방법에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.
분류 | 주제 | URL |
Docker | Docker Compose를 이용한 Keycloak 환경 구성 및 실행 방법 | https://adjh54.tistory.com/644 |
환경설정 | Google Cloud Console OAuth 2.0 API 액세스 환경 설정하기 | https://adjh54.tistory.com/657 |
이해하기 | Keycloak 이해하기 -1 : 구성 요소, 인증 처리과정, 주요 기능 | https://adjh54.tistory.com/645 |
이해하기 | Keycloak 이해하기 -2 : SAML/OIDC 프로토콜, 인증 흐름(Authentication flow) 종류 | https://adjh54.tistory.com/646 |
이해하기 | Keycloak 이해하기 -3 : 기본 환경 구성 및 로그인/로그아웃 구현 | https://adjh54.tistory.com/647 |
이해하기 | Keycloak 이해하기 -4 : Keycloak 권한 및 종류 | https://adjh54.tistory.com/655 |
구성하기 | Spring Boot 환경에서 Keycloak 활용하기 -1 : OIDC 인증 흐름 구현(Standard Flow) | https://adjh54.tistory.com/648 |
구성하기 | Spring Boot 환경에서 Keycloak 활용하기 -2 : OIDC 인증 흐름 구현(Direct Access Grants, Implicit Flow) | https://adjh54.tistory.com/649 |
구성하기 | Spring Boot 환경에서 Keycloak 활용하기 -3 : OIDC 인증 흐름 구현(Service Accounts Roles) | https://adjh54.tistory.com/654 |
구성하기 | Spring Boot 환경에서 Keycloak 활용하기 -4 : Identity providers Social 소셜 로그인 구현(Google) | https://adjh54.tistory.com/658 |
Github | Spring Boot Keycloak 관련 Repository | https://github.com/adjh54ir/blog-codes/tree/main/spring-boot-keycloakhttps://github.com/adjh54ir/blog-codes/tree/main/spring-boot-keycloak-sub |
1) Keycloak
💡 Keycloak
- Red Hat에서 개발한 오픈소스 Identity and Access Management(IAM) 솔루션입니다. 현대적인 애플리케이션과 서비스를 위한 인증 및 권한 부여 기능을 제공하는 인증 서버(Authentication Server)의 기능을 수행합니다.
- Keycloack에서는 여러 플랫폼에서 중앙 집중식 인증 서버로 동작을 합니다. 주요한 기능은 서로 다른 도메인에서 실행되는 애플리케이션 간의 SSO를 지원하거나 REST API 기반에 접근제어 토큰에 대한 인증 제공 및 세션 타임아웃, 동시 로그인 제한과 같은 다양한 세션 기능을 담당합니다.

Keycloak
Single-Sign On Users authenticate with Keycloak rather than individual applications. This means that your applications don't have to deal with login forms, authenticating users, and storing users. Once logged-in to Keycloak, users don't have to login again
www.keycloak.org
2) 기본 환경 구성하기
💡 기본 환경 구성
- 아래의 Docker를 통해서 인증서버로 Keycloak을 구성하였습니다.

[Docker] Docker Compose를 이용한 Keycloak 환경 구성 및 실행 방법
해당 글에서는 Docker Compose를 통해서 Keycloak을 구성하는 방법에 대해 알아봅니다.💡[참고] 이전에 작성한 Docker 관련 글들을 읽으시면 도움이 됩니다.분류설명링크이해하기Docker 환경 설치 및 실
adjh54.tistory.com
1. Realm 생성하기
💡 Realm 생성하기
- Docker에서 지정한 포트를 기반으로 접근하여, 최초 지정한 아이디/패스워드인 ‘admin/admin’을 입력하면 아래와 같이 관리자 페이지가 출력이 됩니다.
- 최초 접근을 하면 master realm이 구성됨을 확인할 수 있습니다. 이는 독립적인 영역인 realm으로 생성이 되었습니다.
- 이 과정에서 새로운 realm을 구성해봅니다.

[ 더 알아보기 ]
💡 Master Realm에서 작업을 해도 되지 않을까? 추가 Realm을 생성하는 이유는 뭘까?
- 추가적인 realm을 만드는 이유는 Master Realm 내에서는 '슈퍼 관리자 계정'이 포함되어 있습니다. 이 슈퍼 관리자 계정은 다른 realm들의 생성, 수정, 삭제와 같은 관리 작업을 수행할 수 있습니다.
- 해당 공간에서는 보안상의 이유로 일반 사용자의 인증용으로는 사용하지 않는 것이 권장이 되며, 실제 서비스를 위해서는 별도의 realm에서 생성하고 사용해야 합니다.

1.1. Create realm을 누릅니다.

1.2. Create realm
💡 Create realm
- 기존에 설정된 정보를 JSON 파일 형태로 업로드해서 새롭게 구성하거나 완전히 새로운 Realm을 구성할 수 있습니다.
분류 | 설명 |
리소스 파일(Resource file) | 기존 Realm 설정을 JSON 파일로 업로드하여 새로운 Realm을 생성할 수 있습니다. |
영역 이름(Realm name) | 새로 생성할 Realm의 고유한 이름을 지정합니다. 필수 입력 항목입니다. |
활성화(Enabled) | Realm의 활성화 여부를 설정합니다. 체크하면 즉시 사용 가능한 상태가 됩니다. |

💡 [참고] Realm settings > Action으로 이동하면 기존의 Realm에 대한 정보가 export가 됩니다.
- Include groups and roles : 그룹 및 역할을 포함한
- export - Include clients : Client를 포함한 export

2. Client 생성하기
💡 Client 생성하기
- 구성한 Realm내에 애플리케이션 또는 서비스에 해당하는 Client를 생성합니다.
2.1. Create client를 선택합니다.
💡 Create client를 선택합니다.
- 새롭게 구성한 realm 내에 client를 생성합니다.

2.2. General settings
💡 General settings
- Client를 생성할 때 기본적인 설정을 하는 단계입니다.
설정 | 항목 | 설정 설명 |
Client ID | - | 클라이언트를 식별하는 고유한 ID입니다. 필수 입력 항목입니다. |
Name | - | 클라이언트의 표시 이름입니다. 관리자 콘솔에서 보여지는 이름입니다. |
Description | - | 클라이언트에 대한 설명을 입력할 수 있습니다. |
Always display in console | - | 관리자 콘솔에 항상 표시할지 여부를 설정합니다. |
Client Type | OpenID Connect | OAuth 2.0을 기반으로 하는 인증 프로토콜로, JWT(JSON Web Token)를 사용하여 사용자 인증 정보를 안전하게 전달합니다. 주로 모던 웹/모바일 애플리케이션에서 사용됩니다. |
Client Type | SAML | Security Assertion Markup Language의 약자로, XML 기반의 보안 표준입니다. 주로 엔터프라이즈 환경에서 사용되며, 조직 간 SSO(Single Sign-On)를 구현하는 데 널리 활용됩니다. |
💡 기본적으로 사용되는 OIDC(OpenId Connect)를 이용하여서 구성하며, 클라이언트 아이디를 입력하였습니다.

2.2. Capability config
💡 Capability config
- Client의 기능과 관련된 설정을 구성하는 단계입니다.
분류 | 상세 분류 | 설명 |
Client authentication | - | 클라이언트 인증을 활성화합니다. 보안을 위해 클라이언트 시크릿이 필요합니다. |
Authorization | - | 세밀한 권한 제어가 필요한 경우 활성화합니다. 리소스, 정책, 권한 등을 관리할 수 있습니다. |
Authentication flow | Standard Flow | OAuth 2.0의 Authorization Code Flow를 사용하는 전통적인 웹 애플리케이션에서 사용되는 표준 인증 방식입니다. |
Authentication flow | Direct Access Grants | 사용자 이름과 비밀번호를 직접 사용하여 토큰을 얻는 방식으로, 신뢰할 수 있는 애플리케이션에서 사용됩니다. |
Authentication flow | Implicit Flow | 브라우저 기반 애플리케이션을 위한 간소화된 OAuth 2.0 흐름입니다. |
Authentication flow | Service Accounts Roles | 클라이언트 자체가 직접 API를 호출할 때 사용하는 인증 방식입니다. |
Authentication flow | OAuth 2.0 Device Authorization Grant | 스마트 TV나 IoT 기기와 같이 제한된 입력 기능을 가진 디바이스를 위한 인증 흐름입니다.. |
Authentication flow | OIDC CIBA Grant | Client Initiated Backchannel Authentication 흐름으로, 클라이언트가 사용자 장치를 통하지 않고 인증을 시작할 수 있게 합니다. |
💡 테스트를 위해서 우선, 모든 OIDC 인증 플로어 종류를 선택하였습니다.
- 해당 인증 플로어를 이해하고 선택을 해야 합니다.

💡 [참고] 해당 OIDC 인증흐름 종류에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.
[OpenSource] Keycloak 이해하기 -2 : SAML/OIDC 프로토콜, 인증 플로우(Authentication flow) 종류
해당 글에서는 SAML/OIDC 통신 프로토콜에 대해 이해하고 OIDC 인증 플로우의 종류에 대해서 알아봅니다. 💡 [참고] Keycloak 초기 구성에서부터 활용 방법에 대해 궁금하시면 아래의 글을 참고하
adjh54.tistory.com
2.3. Login settings
💡 Login settings
- 클라이언트의 로그인 관련 설정을 구성하는 단계입니다.
설정 항목 | 설명 |
Root URL | 클라이언트 애플리케이션의 기본 URL입니다. 다른 URL들의 기준점이 됩니다. |
Home URL | 클라이언트의 홈페이지 URL입니다. 로그인 후 리다이렉트되는 기본 페이지로 사용될 수 있습니다. |
Valid redirect URIs | 인증 후 사용자가 리다이렉트될 수 있는 유효한 URL 패턴 목록입니다. 보안을 위해 정확하게 설정해야 합니다. |
Valid post logout redirect URIs | 로그아웃 후 리다이렉트될 수 있는 유효한 URL 패턴 목록입니다. |
Web origins | CORS 설정을 위한 허용된 오리진 목록입니다. 클라이언트의 도메인을 지정합니다. |
Admin URL | 백엔드 서비스의 관리자 URL입니다. 푸시 알림이나 어댑터 설정에 사용됩니다. |
💡 해당 설정은 추후 다시 변경을 하도록 하겠습니다.

2.4. 생성 확인
💡 생성 확인
- 구성한 Client가 생성됨을 확인하였습니다.

3. User 생성하기
💡 User 생성하기
- 지정한 Realm 공간 내에 접근이 가능한 사용자를 생성해 봅니다.
- 해당 사용자의 경우는 Client 내에서 생성, 수정, 삭제를 위한 목적으로 사용되지만, 테스트를 위해 임의의 사용자를 생성해 봅니다.
3.1. Create new user
💡 Create new user
- Client 단위가 아닌 Realm 단위의 사용자를 생성합니다.

3.2. Create user
💡 Create user
- 사용자들을 구분하기 위한 Username에 해당하는 부분은 로그인에 사용될 고유한 식별자입니다. 그렇기에 중복이 불가능하며 필수요소입니다.
항목 | 필수 여부 | 설명 |
Required user actions | 선택 | 사용자에게 요구되는 필수 작업들을 설정하는 항목입니다. 예를 들어 비밀번호 변경이나 이메일 인증 등의 작업을 지정할 수 있습니다. |
Email verified | 선택 | 사용자의 이메일 주소가 인증되었는지 여부를 나타내는 상태 표시입니다. |
Username | 필수 | 사용자의 로그인에 사용될 고유한 식별자입니다. |
선택 | 사용자의 이메일 주소를 입력하는 필드입니다. | |
First name | 선택 | 사용자의 이름을 입력하는 필드입니다. |
Last name | 선택 | 사용자의 성을 입력하는 필드입니다. |
Groups | 선택 | 사용자가 속할 그룹을 지정하는 필드입니다. 그룹을 통해 여러 사용자에게 공통된 권한을 한 번에 부여할 수 있습니다. |

💡 [참고] 사용자 생성 시 항목들을 바꿀 수 있는가?
- Realm settings > User Profile 탭을 확인하면, 사용자가 입력을 할 때 필요로 하는 항목들을 관리할 수 있습니다. 예를 들어서 성별을 입력하는 부분을 추가하거나 할 수 있습니다.

3.3. User Detail
💡 User Detail
- 사용자가 생성되면 고유한 ID가 발급이 됩니다.

3.4. User Credentials
💡 User Credentials
- 사용자의 비밀번호를 지정합니다.

3.5. Set password for
💡 Set password for
- 사용자의 비밀번호를 지정합니다. 항목 중에 Temporary는 사용자가 처음 로그인할 때 반드시 비밀번호를 변경하도록 강제할지 여부를 설정하는 옵션입니다.
- 즉 On으로 설정되면 사용자는 첫 로그인 시 새로운 비밀번호를 설정해야 핮만 서비스를 이용할 수 있습니다.
💡 아래와 같이 Temporary 속성은 꺼둔 상태로 비밀번호만 변경해 두었습니다.

💡 아래와 같이 비밀번호가 생성되었음을 확인하였습니다.

3.6. 관리자 페이지에 로그인할 계정을 만들려면?
💡 관리자 페이지에 로그인할 계정을 만들려면?
- 관리자 페이지로 admin을 통해 최초 생성한 사용자만 접근이 가능합니다. 이에 대해서 추가 관리자 아이디로 계정을 만들기 위해서는 ‘master realm’ 내에 사용자를 만들고 role을 부여해야 합니다.
💡 아래와 같이 ‘master realm’ 내에 접근하여서 Users 탭 내에 사용자를 생성합니다.

💡 Role mapping > Assign role을 선택해서 접근을 위한 권한을 부여합니다.

💡 아래와 같이 모든 권한을 부여하였습니다.

💡 생성한 계정으로 로그인을 접속합니다.

💡 아래와 같이 모든 권한이 허용된 사용자가 추가됨을 확인할 수 있습니다.

4. Group 생성하기
💡 Group 생성하기
- 사용자들을 그룹화하여 관리하기 위한 목적으로 사용됩니다.
- 그룹에 권한을 부여하면 해당 그룹에 속한 모든 사용자에게 동일한 권한이 적용됩니다.

4.1. Create a group
💡 Create a group
- 최상위 그룹으로 개발팀(dev-team)을 구성하였습니다.

4.2. Create a group
💡 Create a group
- 최상위 그룹 하위에 Child Groups로 프런트엔드 개발팀(front-end-team)과 백엔드 개발팀(back-end-team)을 하위에 구성하였습니다.


4.3. Add member
💡 Add member
- 그룹 내의 사용자를 추가합니다.

4.3. Group Detail
💡 Group Details
- 그룹이 생성되면 멤버 관리, 역할 할당, 속성 관리 등을 수행할 수 있습니다.
- 하위 그룹을 생성하여 계층 구조를 만들 수 있습니다.

5. Realm roles 생성하기
💡 Realm roles 생성하기
- Realm 수준에서 정의되는 글로벌 역할입니다.
- 모든 클라이언트에서 공통적으로 사용할 수 있는 권한을 정의합니다.
5.1. Create role
💡 Create role
- Realm roles 메뉴에서 'Create role' 버튼을 클릭하여 새로운 역할을 생성합니다.

5.3. Create role

5.4. Associated roles > Assign role
💡 Associated roles > Assign role
- 생성한 권한에 대해 역할을 부여합니다.

5.4. Assign roles to
💡 Assign roles to
- 생성한 권한에 대해서 상세 권한들을 부여할 수 있습니다.

권한 분류 | 권한명 | 설명 |
Account | delete-account | 계정 삭제 |
Account | manage-account | 계정 관리 |
Account | manage-account-links | 계정 링크 관리 |
Account | manage-consent | 동의 관리 |
Account | view-applications | 애플리케이션 조회 |
Account | view-consent | 동의 내역 조회 |
Account | view-groups | 그룹 조회 |
Account | view-profile | 프로필 조회 |
Broker | read-token | 토큰 읽기 |
Realm Management | create-client | 클라이언트 생성 |
Realm Management | impersonation | 사용자 위장 |
Realm Management | manage-authorization | 권한 관리 |
Realm Management | manage-clients | 클라이언트 관리 |
Realm Management | manage-events | 이벤트 관리 |
Realm Management | manage-identity-providers | ID 제공자 관리 |
Realm Management | manage-realm | 렐름 관리 |
Realm Management | manage-users | 사용자 관리 |
Realm Management | query-clients | 클라이언트 조회 |
Realm Management | query-groups | 그룹 조회 |
Realm Management | query-realms | 렐름 조회 |
Realm Management | query-users | 사용자 조회 |
Realm Management | realm-admin | 렐름 관리자 |
Realm Management | view-authorization | 권한 조회 |
Realm Management | view-clients | 클라이언트 조회 |
Realm Management | view-events | 이벤트 조회 |
Realm Management | view-identity-providers | ID 제공자 조회 |
Realm Management | view-realm | 렐름 조회 |
Realm Management | view-users | 사용자 조회 |
3) 로그인 수행
💡 로그인 수행
- 구성한 Realm과 Client 및 User를 기반으로 로그인을 수행해 봅니다.
1. Client Redirect URL 설정
💡 Client Redirect URL 설정
- Client내에 로그인을 성공하였을 때, 리다이렉트 되는 URL을 지정합니다.
💡 Client > 특정 Client 선택 > Access settings 탭
- 아래와 같이 로그인을 성공하면 해당 리다이렉트 URL로 Access Token을 반환해 주는 구조입니다.

💡 아래와 같은 임시의 REST API를 구성하였습니다.
@RestController
@RequestMapping("/api/v1/keycloak")
public class KeycloakController {
/**
* Keycloak 로그인 성공 이후 후 처리
*
* @param code
* @param state
* @param session_state
* @param error
* @param error_description
* @return
*/
@GetMapping("/callback")
public ResponseEntity<String> loginCallback(
@RequestParam String code,
@RequestParam(required = false) String state,
@RequestParam(required = false) String session_state,
@RequestParam(required = false) String error,
@RequestParam(required = false) String error_description
) {
System.out.println("code :: " + code);
System.out.println("state :: " + state);
System.out.println("session_state :: " + session_state);
System.out.println("error :: " + error);
System.out.println("error_description :: " + error_description);
return new ResponseEntity<>(code, HttpStatus.OK);
}
}
2. Login Settings 상세 설정
💡 Login Settings 상세 설정
- 간단하게 Keycloak에서 제공해 주는 테마만 선택하고 저장합니다.
설정 항목 | 설명 |
Login theme | 로그인 페이지의 테마를 설정합니다. |
Consent required | 클라이언트 접근 시 사용자 동의가 필요한지 여부를 설정합니다. Off로 설정 시 동의 화면이 표시되지 않습니다. |
Display client on screen | 동의 화면에서 클라이언트 정보를 표시할지 여부를 설정합니다. Off로 설정 시 클라이언트 정보가 표시되지 않습니다. |
Consent screen text | 동의 화면에 표시될 사용자 정의 텍스트를 설정할 수 있습니다. 비어있을 경우 기본 텍스트가 표시됩니다. |

3. 로그인 페이지 엔드포인트 구성
💡 로그인 페이지 엔드포인트 구성
- 아래의 엔드포인트로 접근하고 파라미터로 값들을 전달하면 특정 Realm의 Client에 접근하여서 로그인을 수행할 수 있습니다.
// 기본구조
http(s)://{keycloak-host}/realms/{realm-name}/protocol/openid-connect/auth?client_id={client_id}&response_type={response_type}&redirect_uri={redirect_uri}

💡 openid-connect/auth 엔드포인트로 요청하는 파라미터들입니다.
파라미터 | 설명 | 필수여부 |
client_id | Keycloak 클라이언트 ID | 필수 |
response_type | 인증 응답 타입 (code, token 등) | 필수 |
redirect_uri | 인증 성공 후 리다이렉트될 URL | 필수 |
scope | 요청할 권한 범위 (openid, profile, email 등) | 선택 |
state | CSRF 공격 방지를 위한 임의의 문자열 | 권장 |
prompt | 로그인 프롬프트 동작 방식 (none, login, consent 등) | 선택 |
login_hint | 사용자 ID 미리 입력 | 선택 |
ui_locales | UI 언어 설정 | 선택 |
💡 openid-connect/auth 엔드포인트 응답 파라미터입니다.
파라미터 | 설명 | 데이터 타입 |
code | 인증 코드 (authorization code) | string |
state | 요청 시 전달한 state 값 (CSRF 방지용) | string |
session_state | Keycloak 세션 상태 식별자 | string |
error | 인증 실패 시 오류 코드 | string |
error_description | 오류에 대한 상세 설명 | string |
4. 로그인 엔드포인트 접근
💡 로그인 엔드포인트 접근
- 브라우저 내에 해당 엔드포인트로 접근하여서 로그인을 수행합니다.
// 접속 경로
http://localhost:9001/realms/test-loc-realm/protocol/openid-connect/auth?client_id=react-app&response_type=code&redirect_uri=http://localhost:8080/api/v1/keycloak/callback
💡 위에 구성한 경로로 접근하였을 때 test-loc-realm이라는 realm에 접근하는 로그인 화면이 출력되었습니다.

5. 로그인 수행
💡 로그인 수행
- 로그인 실행 시 아래와 같은 인가 토큰이 발급됨을 확인하였습니다.

💡 API 서버 콘솔 내에서도 아래와 같이 출력됨을 확인하였습니다.
- 해당 값을 통해서 Standard Flow의 accessToken을 발급합니다.

4) 로그아웃 수행
1. 로그아웃 엔드포인트 접근
💡 로그아웃 엔드포인트 접근
- 로그아웃은 Keycloak의 openid-connect/logout 엔드포인트를 사용합니다.
http(s)://{keycloak-host}/realms/{realm-name}/protocol/openid-connect/logout?redirect_uri={redirect_uri}&client_id={client_id

💡 openid-connect/logout 엔드포인트 내에 파라미터들입니다.
파라미터 | 설명 | 필수 여부 |
client_id | 로그아웃을 수행할 클라이언트의 ID | 필수 |
redirect_uri | 로그아웃 후 리다이렉트될 URL | 필수 |
id_token_hint | 로그인 시 발급받은 ID 토큰 | 선택 |
post_logout_redirect_uri | 로그아웃 후 리다이렉트될 대체 URL | 선택 |
state | 로그아웃 요청과 응답을 매칭하기 위한 임의의 문자열 | 선택 |
💡 openid-connect/logout 엔드포인트의 응답 파라미터들입니다.
파라미터 | 설명 |
state | 로그아웃 요청 상태를 식별하기 위한 임의의 문자열 |
error | 로그아웃 처리 중 발생한 오류 코드 |
error_description | 오류에 대한 상세 설명 |
2. 로그아웃 수행
💡 로그아웃 수행
- 위에 구성한 경로로 접근하였을때 test-loc-realm이라는 realm에 접근하는 로그아웃 화면이 출력되었습니다.
// 경로 접근
http://localhost:9001/realms/test-loc-realm/protocol/openid-connect/logout?redirect_uri=http://localhost:8080/api/v1/keycloak/logout&client_id=react-app

💡 아래와 같이 정상적으로 로그아웃이 수행됨을 확인하였습니다.

오늘도 감사합니다 😀

'OpenSource > Keycloak' 카테고리의 다른 글
[OpenSource/API] Keycloak OIDC(OpenID Connect) Endpoint API (0) | 2025.02.09 |
---|---|
[OpenSource] Keycloak 이해하기 -4 : Keycloak 권한 및 종류 (0) | 2025.02.06 |
[OpenSource] Keycloak 이해하기 -2 : SAML/OIDC 프로토콜, 인증 흐름(Authentication flow) 종류 (1) | 2025.01.27 |
[OpenSource] Keycloak 이해하기 -1 : 주요 기능, 구성 요소, 로그인 과정 (0) | 2025.01.21 |