Keycloak 설치 구성

Keycloak 설치 구성

Keycloak 은 현대의 애플리케이션과 서비스에 초점을 둔 ID 및 접근 관리(Access Management)에 통합 인증(SSO)을 허용하는 오픈 소스 소프트웨어로 Kubernetes 또는 MSA 환경에 최적화 된 솔루션 입니다. 쉽게 말하면 인증(Authentification)과 인가(Authorization)를 쉽게 해주고 SSO(Single-Sign-On)를 가능하게 해주는 것 입니다.

기능

• 표준 프로토콜 지원(OpenID Connect, OAuth 2.0, SAML)
• 통합 인증(Single Sign-On, SSO)
• 관리자 / 계정관리 콘솔 제공
• ID 중개 와 소셜 로그인 (OpenID, SAML, GitHub, Google 등)
• 사용자 UI 정의
• Client Adapters (다수의 플랫폼과 프로그래밍 언어가 사용 가능한 adapter)

이번 포스트에서는 ubuntu에서 Keycloak 설치 및 테스트 하는 단계를 살펴 보겠습니다.

목차

1. Ubuntu 에 Keycloak 설치 구성
1단계: 시스템 업데이트
2단계: Java 설치
3단계: Keycloak 다운 및 관리자 계정 생성
4단계: Keycloak 사용자 아이디와 클라이언트 생성
5단계: 테스트

1. Ubuntu 에 Keycloak 설치 구성

우선 Ubuntu에 Keycloak을 설치 및 구성하여 테스트하는 몇 가지 단계를 알아보겠습니다.

우분투 버전은 Ubuntu 22.04.1 LTS 입니다.

1단계: 시스템 업데이트

$ sudo apt-get update

2단계: Java 설치

$ sudo apt install openjdk-18-jdk

 혹은 다른 방법으로는 아래와 같이 설치 합니다. 
 다른 블로그에는 아래 경로를 보시면 latest 로 되어 있는데 음.. 제가 테스트 할때는 에러가 발생합니다. 
 그래서 archive 로 설치 하는것이 좋습니다. 
 참고하시길 바랍니다. 
  $wget https://download.oracle.com/java/18/latest/jdk-18_linux-x64_bin.deb
   
  $sudo apt -y install wget curl
    
  $wget https://download.oracle.com/java/18/archive/jdk-18_linux-x64_bin.deb

• Java 버전은 11 이상 이 설치 되어야 합니다.

$ java -version

java version "18" 2022-03-22
Java(TM) SE Runtime Environment (build 18+36-2087)
Java HotSpot(TM) 64-Bit Server VM (build 18+36-2087, mixed mode, sharing)

3단계: Keycloak 다운 및 관리자 계정 생성

$ wget https://github.com/keycloak/keycloak/releases/download/17.0.0/keycloak-17.0.0.tar.gz

• 버전 17.0.0로 진행됩니다. 은 다운로드가 완료되면 파일의 압축을 풉니다.

$ tar -zxvf keycloak-17.0.0.tar.gz

• 추출된 디렉터리로 이동합니다.

$cd keycloak-17.0.0/

#제가 설치한 위치는 아래와 같네요 
/opt/jdk-18/keycloak-17.0.0
참고 하시길 바랍니다. 
그리고 설치한 keyclokc-17.0.0 위치를 잘~~ 확인해보시길 바랍니다.

 

• Keycloak를 시작하기 전에 초기 관리자 계정을 생성 해야 합니다.

$ export KEYCLOAK_ADMIN=admin
$ export KEYCLOAK_ADMIN_PASSWORD=123


기본적인 ID 와 passwd 는 123 이니 잘 기억 하시길 바랍니다.

• 내보낸 환경 변수를 적용하여 keycloak을 실행 합니다.

$ sudo -E bin/kc.sh start-dev

• 이제 웹 브라우저를 열고 URL http://your-server-ip:8080 을 사용하여 Keycloak 웹 인터페이스에 액세스합니다.
• 아래의 페이지가 나오면 Adminnistration Console 탭을 클릭해 줍니다.
• ifconfig 해서 나오는 아이피:port 입력 하시면 됩니다. 
•  
•  

http://172.22.21.226:8080

아래와 같이 화면이 뜨면 성공

 

 

• 초기에 생성한 관리자 계정과 패스워드를 입력합니다. admin / 123 아까 위에 설정한 부분 기억 나시죠 ?

• 로그인에 성공하면 아래처럼 keycloak 대시보드가 표시 되어야 합니다.

4단계: Keycloak 사용자 아이디와 클라이언트 생성

• 왼쪽 상단의 Master 위에 마우스를 놓고 add realm을 클릭합니다.
•  

• name을 정하고 create를 눌러 다음으로 넘어갑니다.

• 다음으로 Keycloak에 대한 새 사용자를 생성해야 합니다.  왼쪽 Manage -> Users를 클릭하고 Add user를 클릭합니다.

• 사용자 정보를 입력하고 Save를 클릭합니다.
•  

•  
• Credentials 탭을 클릭하여 사용자의 암호를 설정, Temporary를 OFF 후 Set Password를 클릭합니다.

• 다음으로 application을 보호하기 위해 Keycloak 인스턴스에 application을 등록해야 합니다.
• Configure -> Clients에서 Create를 클릭합니다.
•  

• ID 와 Root URL를 설정하고 Save을 클릭합니다.
•  

• 아래와 같이 자동으로 세팅이 되기 때문에 바로 Save를 클릭하고 세팅을 마칩니다.

5단계: 테스트

• 테스트 방법은 Keycloak의 접속 정보를 직접 입력하는 방식으로 접근을 해야 합니다. 아래와 같은 형식으로 입력하면 됩니다. (주황색 부분을 본인이 설정한 값으로 정의해 주면 됩니다.)

http://KeyCloak URL/realms/KeyCloak Realm/protocol/openid-connect/auth?response_type=code&client_id=KeyCloak Client ID&state=12345

ex) Realm과 client_id는 대소문자를 구분하니 주의하십시오.

http://192.168.219.107:8080/realms/Test/protocol/openid-connect/auth?response_type=code&client_id=myclient&state=12345

• 위 링크로 접속하여 Username과 패스워드를 입력합니다.
• 초기 로그인 후 새로운 패스워드를 변경(Update password)해야 합니다.

• 로그인이 완료되면 설정한 192.168.219.107 URI로 넘어가게 됩니다.
• 아래 페이지는 Redirect되는 것을 확인하기 위해 NGINX를 사용하였습니다.

• 로그인한 User의 Session을 보면 IP와 로그인 정보를 알 수 있습니다.

여기까지 Keycloak 기본 구성입니다.

더 나아가 NGINX API Gateway와 Keycloak을 이용하여 통합 인증을 구현 할 수 있습니다.

다음 포스트 에선 NGINX API Gateway + Keycloak 연동에 대한 모범 사례를 다룰 예정입니다.

NGINX API Gateway를 자세히 알고 싶으시면 NGINX API Gateway – API 정의 및 인증 구현 을 참조 하시면 됩니다.

keycloak은 17버전 이후로 WildFly에서 Quarkus로 변경되었습니다. (https://www.keycloak.org/migration/migrating-to-quarkus)
17버전 이전과 설정 방법이 다르고 정보 또한 부족하여 많은 시행 착오를 겪었습니다. Keycloak을 사용하시는 분들께 도움이 되고자 작업했던 내용들을 정리하려고 합니다.

 

Keycloak이란

keycloak은 웹 앱, Restful 웹 서비스를 위한 SSO 솔루션입니다. Keycloak은 로그인, 등록, 관리 및 계정 관리를 위한 사용자 정의 가능한 사용자 인터페이스를 제공합니다.  Keycloak을 통합 플랫폼으로 사용하여 기존 LDAP 및 Active Directory 서버에 연결할 수도 있습니다. Facebook 및 Google과 같은 타사 ID 제공업체에 인증을 위임할 수도 있습니다.

 

특징

• 브라우저 애플리케이션을 위한 Single Sign On / Single Sign Out
• OpenID / SAML 지원.
• 소셜 로그인 - Google, GitHub, Facebook, Twitter 및 기타 소셜 네트워크로 로그인할 수 있습니다.
• 테마 지원 - 기본 Keycloak에서 제공해주는 페이지들을 커스텀 할 수 있습니다.
• 로그인 흐름 - 선택적 사용자 자체 등록, 비밀번호 복구, 이메일 확인, 비밀번호 업데이트 필요 등
• 세션 관리 - 관리자와 사용자가 사용자 세션을 보고 관리할 수 있습니다.
• 토큰 매퍼 - 사용자 속성, 역할 등을 원하는 방식으로 토큰과 명령문에 매핑합니다.

 

설치 

설치는 Keycloak을 직접 다운 받는 방법 (공부 할때 추천) 과, Docker Compose를 이용하는 방법 두가지로 진행하겠습니다.
OpenJDK 11버전 이상이 설치되어 있어야 합니다. 설치 환경은 Mac 기준입니다.

 

1. Keycloak을 직접 다운로드

https://www.keycloak.org/downloads 에 접속하여 아래 Zip 파일을 다운 받습니다.

이후에 압축을 풀고 keycloak의 폴더에서 다음 커맨드를 입력합니다.

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

 

 

---

 

2. Docker Compose로 설치

# docker-compose.yml

 

version: "3.8"

services:

keycloak:

image: quay.io/keycloak/keycloak:18.0.2

container_name: keycloak

environment:

- KEYCLOAK_ADMIN=admin

- KEYCLOAK_ADMIN_PASSWORD=admin

ports:

- "8080:8080"

command: start-dev

healthcheck:

test: "curl -f http://localhost:8080/admin || exit 1"

 

 

이후에 다음 커맨드를 입력해 줍니다.

$ docker-compose up -d

 

 

---

 

Admin 계정 생성과 로그인

http://localhost:8080에 접속합니다.

 

위의 화면에서 최초 admin 계정을 생성합니다.
저는 아이디: admin, 비밀번호: admin으로 설정하겠습니다. (Docker Compose의 경우 이미 admin/admin으로 생성되어 있습니다.)

 

빨간색으로 표시된 부분을 클릭하고, 로그인을 합니다.

수고하셨습니다. 다음 포스트에서는 Realm, Client 그리고 User 생성을 해보겠습니다.