[OpenSource] Keycloak 이해하기 -3 : 기본 환경 구성 및 로그인/로그아웃 구현

해당 글에서는 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

 

 

2) 기본 환경 구성하기

---

💡 기본 환경 구성

- 아래의 Docker를 통해서 인증서버로 Keycloak을 구성하였습니다.

[Docker] Docker Compose를 이용한 Keycloak 환경 구성 및 실행 방법

 

 

 

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) 종류

 

 

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	필수	사용자의 로그인에 사용될 고유한 식별자입니다.
Email	선택	사용자의 이메일 주소를 입력하는 필드입니다.
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

 

 

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

 

 

 

 

 

오늘도 감사합니다 😀