Keycloak 시작하기 1

1. keycloak 소개

Keycloak은 단일 페이지 애플리케이션(single-page applications), 모바일 애플리케이션 및 REST API와 같은 최신 애플리케이션에 초점을 맞춘 오픈소스 ID 및 접근관리 도구입니다.

 

Keycloak은 강력한 인증을 포함해 완전히 사용자가 원하는대로 설정할 수 있는 로그인 페이지를 제공합니다. 또한 암호 복구, 주기적인 암호 업데이트 설정, 이용약관 동의 등과 같은 다양한 기능을 제공합니다.  해당 기능들을 사용하기 위해 추가적인 설정이나 코딩을 할 필요없습니다. 사용자에게 표시되는 모든 페이지는 사용자의 테마를 지원하므로 페이지의 UI를 손쉽게 바꿀 수 있습니다. 

 

Keycloak을 통해 인증을 수행하면 애플리케이션의 서로 다른 인증 메커니즘이나 암호저장의 안정성에 대해 걱정할 필요가 없습니다. 이런 방법은 애플리케이션이 사용자 자격증명에 직접 접근하지 않고, 필요한 항목에만 접근할 수 있는 보안 토큰을 제공해 더 높은 수준의 보안을 제공합니다.

 

Keycloak은 세션 관리 기능뿐만아니라 SSO(Single Sign-On) 기능을 제공해 사용자가 한번만 인증하면 여러 애플리케이션에 접근할 수 있습니다. 사용자와 관리자 모두 사용자가 인증된 위치를 정확하게 파악할 수 있으며, 필요한 경우 원격으로 세션을 종료할 수 있습니다.

 

Keycloak은 OAuth 2.0, OpenID Connect 및  SAML 2.0을 지원하는 업계 표준 프로토콜을 기반으로 합니다. 업계 표준 프로토콜을 사용하는 것은 보안적인 측면과 기존 애플리케이션 및 신규 애플리케이션을 통합하는 측면에서 매우 중요합니다.

 

Keycloak은 자체 데이터베이스를 갖고 있기 떄문에 별다른 설정 없어도 사용할 수 있습니다. 또한 기존 인증 인프라스트럭처와 손쉽게 통합할 수 있습니다. ID 브로커링 기능을 통해 소셜 네트워크 또는 다른 엔터프라이즈 ID 공급자의 기존 사용자 디렉터리와 통합할 수 있습니다. 또한 액티브 디렉터리 및 LDAP 서버와 같은 기존 사용자 디렉터리와 통합 할 수 있습니다. 

 

Keycloak은 가볍고 설치하기 쉬운 솔루션입니다. 또한 높은 확장성을 갖고 클러스터링 기능을 통해 고가용성을 제공합니다. 좀 더 고도화된 이중화를 구현하는 경우 여러 데이터 센터에 대한 클러스터링도 지원합니다.

 

Keycloak을 손쉽게 설치하고 , 다양한 활용 사례를 구축함과 동시에 필요한 경우 높은 사용자 정의 및 확장성을 가집니다. Keycloak 사용자 정의 코드를 구현 배포 해 기존 동작을 수정하거나 완전히 새로운 기능을 추가할 수 있는 확장 가능한 부분이 많습니다. Keycloak에 적용할 수 있는 확장에는 사용자 정의 인증 메커니즘, 사용자 정의 사용자 저장소 그리고 사용자 정의 토큰 연동 등이 그 예시입니다. 또한 사용자 고유의  로그인 프로토콜을 사용할 수 있습니다.

 

2. keycloak 설치

Keycloak 설치 방법은 다음과 같습니다.

 - 도커에 컨테이너로 실행

 - 로컬에서 Keycloak 설치 및 진행

 - 쿠버네티스에서 Keycloak 실행

 - Keycloak Kubernetes operator 사용

 

도커에서 Keycloak 실행

https://www.keycloak.org/getting-started/getting-started-docker

Docker - Keycloak

docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.1.0 start-dev

 

Keycloak에는 디폴트 관리자 계정이 없으므로 KC_BOOTSTRAP_ADMIN_USERNAME,KC_BOOTSTRAP_ADMIN_PASSWORD 환경변수를 사용하면 초기 관리자 계정을 쉽게 생성할 수 있습니다. 또한 -p 8080을 통해 호스트에서 Keycloak 이 사용하는 포트를 설정해 Keycloak에 접근할 수 있도록합니다.

http://localhost:8080 에 접속하면 관리자 페이지가 나옵니다.

 

OpenJDK를 통한 keycloak 설치 및 실행

먼저 시스템 패키지를 업데이트하고 OpenJDK 17을 설치합니다.

sudo apt update
sudo apt install -y openjdk-17-jdk

 

설치가 완료되면, Java 버전을 확인하여 올바르게 설치되었는지 확인합니다.

java -version

 

설치된 Java의 기본 경로를 확인합니다.

기본 경로 예시:

/usr/lib/jvm/java-17-openjdk-amd64/bin/java

 

환경변수 파일 수정

sudo vi /etc/environment

 

파일에 JAVA_HOME 추가

JAVA_HOME="/usr/lib/jvm/java-17-openjdk-amd64"

 

source 명령어를 사용하여 변경된 내용을 적용하고, JAVA_HOME 환경변수가 올바르게 설정되었는지 확인합니다.

source /etc/environment
echo $JAVA_HOME

 

https://www.keycloak.org/downloads

downloads - Keycloak

 

Keycloak을 설치할 경로로 이동하여 wget으로 복사한 주소를 입력하여 Keycloak 다운로드합니다. 

cd /usr/local/etc/
wget https://github.com/keycloak/keycloak/releases/download/26.1.0/keycloak-26.1.0.tar.gz
tar xzvf keycloak-26.1.0.tar.gz

 

keycloak를 한번이라도 실행을 하면 환경 설정이 추가 되므로 삭제하여 초기화합니다.

cd keycloak-26.1.0
rm -rf   ./data

 

초기 관리자 아이디와 관리자 비밀번호를 세팅합니다.

export KC_BOOTSTRAP_ADMIN_USERNAME="admin"
export KC_BOOTSTRAP_ADMIN_PASSWORD="admin"
export KEYCLOAK_ADMIN="admin"
export KEYCLOAK_ADMIN_PASSWORD="admin"

 

 

Keycloak 실행

./bin/kc.sh   start-dev --verbose

 

http://localhost:8080/ 로 접속하여 설정한 관리자 아이디 ,비밀번호로 로그인합니다.

 

3.  Keycloak 관리 

Keycloak 관리자 콘솔은 관리자 및 개발자에게 편리하며 다양한 Keycloak 구성 및 관리 인터페이스를 제공합니다.

관리자 콘솔에 접근하려면 http://localhost:8080/ 로 접속하여 관리자로 로그인하면 콘솔로 이동됩니다.

 

애플리케이션 및 사용자에 대한 realm 을 생성해야합니다. Realm은 다른 realm 과 서로 완전히 독립적이며 각 realm은 고유의 설정과 애플리케이션 및 사용자를 갖습니다. 해당 특성을 통해 Keycloak을 다양한 목적으로 사용할 수 있습니다.

예를들어 내부 애플리케이션 및 직원을 위한 Realm과 외부 애플리케이션 및 고객을 위한 realm을 설정할 수 있습니다.

Realm 생성

신규 realm을 생성하려면 좌측 상단에 위치한 ▼ 아이콘을 클릭하면 Create realm 버튼이 나옵니다. 

 

Create realm 버튼 클릭

 

realm의 이름은 url에 사용됨으로 한글 또는 특수기호는 사용하지 않는것을 권장합니다.

 

사용자 생성

realm 생성 후 사용자를 추가합니다.

Users 메뉴 클릭 -> Create  new user 버튼 클릭

 

 

Required user actions : 을 통해 관리자는 사용자가 로그인시 초기 작업을 수행할 수 있도록 설정할 수 있습니다.

Email verified:  관라자는 해당 정보가 사용자의 유효한 이메일 주소임을 알고 있는 경우 선택합니다.

 

정보 입력 후 사용자를 생성합니다.

 

생성한 사용자의 초기비밀번호를 세팅하기 위해 Credentials탭 클릭 -> Set password를 클릭합니다.

Temporary 옵션이 활성화된 경우, 사용자는 처음 로그인할 때 패스워드를 변경해야합니다.해당 옵션은 관리자가 사용자를 생성할 경우에 주로 사용됩니다.

그룹 생성

Groups 메뉴 클릭 -> Create group 버튼 클릭

 

그룹명 입력 후 Create 버튼 클릭

 

 

생성한 그룹명 클릭

 

 

사용자는 자신이 속한 그룹의 모든 속성을 상속받습니다. 예를 들어 전체 사무실 직원이 속한 그룹이 있고, 해당 그룹의 직원 속성에 사무실 주소를 추가하는 경우에 유용합니다.

 

또한 그룹의 역할을 설정할 수 있으며, 해당 역할은 그룹의 모든 맴버가 상속받습니다.

사용자를 그룹에 추가하려면 Members 탭 클릭 -> Add member 버튼을 클릭하면 됩니다.

글로벌 역할 생성

글로벌 역할을 생성하려면 좌측 메뉴 Realm roles 버튼 클릭 -> Create role 버튼 클릭

 

역할명과 설명을 입력한 후 Save 버튼 클릭

 

Keycloak의 역할은 해당 역할에 다른 역할을 추가해 통합 역할이 될 수 있습니다. 통합 역할 권한을 가진 사용자는 통합 역할에 포함된 모든 역할이 동적으로 부여됩니다. 통합 역할은 다른 통합 역할도 포함할 수 있습니다. 해당기능은 주의할 점이 있습니다. 통합 역할은 관리가 어렵고, 특히 통합 역할의 계층이 많을 경우 성능 저하가 발생할 수 있습니다.

 

글로벌 역할을 설정하려면 다음의 절차를 거칩니다.

 

Users -> 역할을 지정할 사용자를 클릭

 

Role mapping 탭을 클릭 -> 추가할 글로벌 역할을 클릭하고 Assign role을 클릭하여 역할을 추가합니다.

 

 

애플리케이션의 보안과 관련된 초기 설정을 하였습니다. 이번에는 사용자가 자신의 계정을 관리할 수 있는 Keycloak계정정보를 알아보겠습니다. 

 

Keycloak 계정 콘솔은 다음 기능을 포함해 사용자가 자신의 계정을 관리할 수 있는 인터페이스를 제공합니다. 

- 사용자 프로파일 업데이트

- 사용자 패스워드 업데이트

- 이중 인증 활성화

- 애플리케이션 보기 

- 현재 세션 보기

 

Keycloak은 확장 관리자 콘솔과 애플리케이션 사용자가 자신의 계정을 관리 할 수 있는 자체 관리 콘솔도 제공합니다. 

 

다음글에서는 Keycloak 보안 관련 글을 작성하겠습니다.