자습서-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
  • Java 버전은 11 이상 이 설치 되어야 합니다.
$ java -version
openjdk version "18.0.2-ea" 2022-07-19

OpenJDK Runtime Environment (build 18.0.2-ea+9-Ubuntu-222.04)

OpenJDK 64-Bit Server VM (build 18.0.2-ea+9-Ubuntu-222.04, 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/
  • Keycloak를 시작하기 전에 초기 관리자 계정을 생성 해야 합니다.
$ export KEYCLOAK_ADMIN=admin
$ export KEYCLOAK_ADMIN_PASSWORD=123
  • 내보낸 환경 변수를 적용하여 keycloak을 실행 합니다.
$ sudo -E bin/kc.sh start-dev
  • 이제 웹 브라우저를 열고 URL http://your-server-ip:8080 을 사용하여 Keycloak 웹 인터페이스에 액세스합니다.
  • 아래의 페이지가 나오면 Adminnistration Console 탭을 클릭해 줍니다.
  • 초기에 생성한 관리자 계정과 패스워드를 입력합니다.
  • 로그인에 성공하면 아래처럼 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를 사용하였습니다.
keycloak root url
  • 로그인한 User의 Session을 보면 IP와 로그인 정보를 알 수 있습니다.

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

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

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

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