[keycloak 맛보기 #1] Keycloak 로컬에서 띄우고 Realm 개념 이해하기

 

개요

Keycloak은 오픈소스(Apache License2.0) ID 및 엑세스 관리 솔루션이다.
이것만 알고 일단 시작해보자

 

Keycloak 도커로 띄워보기

Keycloak은 설치 매뉴얼이 정말 잘되어있다. 
공식문서에 정말 자세히 잘 작성되어있어 문서에 따라 진행해보자.

docker run -p 8080:8080 \
          -e KEYCLOAK_ADMIN=admin \
          -e KEYCLOAK_ADMIN_PASSWORD=admin \
          quay.io/keycloak/keycloak:24.0.4 \
          start-dev

docker run 명령어를 통해 쉽게 keycloak을 띄울 수 있다. 
http://localhost:8080 에 접속하고 로그인해보자. (id/pw: admin/admin)

로그인후 바로 만나게 되는것이 master realm이다.
master realm이 뭔지 생소한데, 개념을 조금 살펴보고 지나가자.

 

Realm이 뭔지 이해하기  🤪

keycloak덕분에 이 익숙치 않은 단어 realm, "렐름".. 익숙해져간다.. 

keycloak에서 realm이란 논리적으로 나누어진 관리 영역을 말한다.
realm이란 "왕국" 이라는 뜻으로, 말 그대로 하나 하나의 realm은 각자의 자원이 나뉘어져있어, 사용자, 정책 등 완전히 분리하여 각각 관리가 가능하다. 

 

master realm

그중에 master realm은, keyclock설치 시 기본으로 제공되는 최상위 realm이다.

• master realm 의 역할
  • 관리: Master realm은 Keycloak 인스턴스 전체를 관리하는데 사용되며, 다른 realm의 생성, 삭제, 설정 등을 관리함
  • 관리자 사용자: Master realm에는 Keycloak 관리자 사용자가 포함됨
  • 목적: 보안 및 분리된 관리를 위해 실제 애플리케이션과는 분리되어, 시스템 전체 설정을 다루기 위한 목적으로 주로 사용됨

즉, master realm이란 어플리케이션하고 연결하는 목적이 아닌, keyclock 자체를 운영하기 위한 영역이다.

 

realm

그렇다면 realm에는 무엇이 포함되어있고, 어떻게 사용하는지 확인해보자.

• realm의 구성요소 
  • 사용자(User): 각 realm은 논리적으로 분리된, 자체 사용자 데이터베이스를 가짐
  • 그룹(Group): 사용자를 그룹으로 묶어 역할이나 권한을 그룹 단위로 관리할 수 있음
  • 클라이언트(Client): 클라이언트는 Keycloak에 의해 보호되는 애플리케이션이나 서비스를 말하며, 각 realm에서 클라이언트를 독립적으로 연결함
  • 역할(Role):사용자가 애플리케이션에서 수행할 수 있는 작업을 정의함
  • 아이덴티티 제공자(Identity Providers): 각 realm은 외부 아이덴티티 제공자(예: Google, Facebook 등)와 통합할 수 있음
  • 정책(Policies): 각 realm은 인증 및 권한 부여 정책을 설정할 수 있음

realm에는 독립적인 사용자, 그룹, 클라이언트, 역할 등을 정의하며 멀티테넌시 환경이나 환경분리(개발/프로덕션), 또는 서비스 기준으로 나누어 관리 가능하다.

 

Realm 만들어 써보기

Realm 만들기 (myservice)

위에서 realm 개념에 대해 설정해봤으니, realm을 하나 만들어보자.
엄청 간단하다, keycloak 옆의 화살표를 클릭하면 Create realm이 나온다. 

서비스 이름을 입력하고 (myservice) create 하면 된다.

이제 myservice라는 realm이 만들어졌다.
위에서 설명한 user, group, client, role, identity providers, polices를 하나씩 살펴보자

 

사용자(user) 만들기

먼저 위에서 생성한 myservice realm에서 사용자를 만들어보자.
왼쪽 메뉴 [Users] -> [create new user] 에서 일단 username을 넣고 create 한다.   

사용자를 생성하면 아래 화면과 같이 사용자에 대한 설정확인할 수 있다.

각 탭들은 아래의 정보를 확인하고 수정할 수 있다.

• Details (세부 정보): 사용자 UUID, 생성 시간, 로그인 시 수행해야 할 작업, 이메일 검증 여부 등.
• Credentials (자격증명): 비밀번호, 사용자의 자격 증명 목록.
• Role mapping (역할 매핑): 사용자가 부여받은 전역 역할, 특정 클라이언트에 대한 역할 매핑.
• Groups (그룹): 사용자가 속한 그룹 목록, 그룹 추가 및 제거.
• Consents (동의): 사용자가 부여한 동의 목록, 동의 철회.
• Identity provider links (아이덴티티 제공자 링크): 외부 아이덴티티 제공자와의 연결 정보, 연결 추가 및 제거.
• Sessions (세션): 현재 사용자의 활성 세션 목록, 세션 로그아웃 및 세션 세부 정보.

사용자(user) 로그인 하기

먼저 사용자로 로그인하기 위해서는 비밀번호 설정이 필요하다.
user01의 Credentials 탭에서 비밀번호를 등록해준다.

등록이 완료되었다면, 아래처럼 비밀번호 설정된것이 확인된다.

keycloak은 기본 사용자페이지를 제공한다.

* 사용자 로그인페이지: http://localhost:8080/realms/myservice/account

이제 위에서 생성한 사용자 user01로 로그인한다.

사용자로 로그인했다면 사용자정보, 계정 보안설정, 그리고 연결된 어플리케이션 목록을 확인할 수 있다.

지금은 아무것도 연결되어있지 않아 어플리케이션이 없다.

 

[참고] 사용자(user) 로그인 페이지 설정 변경

기본 사용자 페이지는 realm settings 에서 수정할 수 있다.
사용자가 스스로 리소스 권한관리할 수 있도록 사용자 관리 액세스를 허용해준다거나, 사용자 가입, 비밀번호 찾기 , 비밀번호 기억하기 기능, 이메일 설정, 테마변경 등 다양한 기능을 제공하니 한번 쭉 확인해보는게 좋다.  

 

Clients 연결해보기

이제 Keycloak에서 제공하는 테스트 페이지와 연결을 해보자

먼저, [Clients] -> [Create client]를 클릭한다. 

첫번째 단계에서는 ClientID: keycloak_test를 입력한다.

두번째 단계는 손댈게 없다. 다음으로 바로 넘어간다.

세번째 단계에서는 값을 각각 입력해준다.

• Valid redirect URIs: https://www.keycloak.org/app/*
• Web origins: https://www.keycloak.org

keycloak_test Clients가 생성되었다.

이제, KeyCloak에서 제공해주는 테스트 페이지(https://www.keycloak.org/app/)에 접속하고,
realm 이름(= myservice)와 Client(= keycloak_test)를 입력한다.

이제 [Sign in]을 클릭해서 Keycloak 계정으로 로그인 되는지 한번 해보자!

[Sign in] 을 클릭하면 http://localhost:8080/realms/myservice/protocol/openid-connect/auth?client_id=keycloak_test 으로 리디렉션 되며, 로그인 정보를 입력하게 된다.

올바른 정보를 입력했다면, 아래와 같이 Hello, 사용자 가 보일것이다.

 

 

Keycloak 맛보기 #1에서는 공식문서를 따라서 진행하면서, 추가적으로 알면 좋은것들을 작성해봤다.
이제 맛보기 #2에서는 google suite랑 연결하고, AWS계정이나 VPN 등을 연결해볼 예정이다.

오늘도 화이팅🎉 내일도 화이팅🎉