[Keycloak] Keycloak이란? & 간단한 설치 및 테스트

기술/Keycloak

[Keycloak] Keycloak이란? & 간단한 설치 및 테스트

yjkim_97 2023. 9. 11. 15:27

1️⃣ (What) Keycloak이란?

Keycloak은 RedHat 산하 IAM 솔루션이다.

❓ IAM 솔루션 (Identity and ACcess Management Soluthion)
회원가입, 로그인 인증, 인가, 로그인 이력관리, 회원 정보 수정, 탈퇴 등.. 인증/인가 기능들이 미리 다 구현되어 있는 솔루션을 말한다.
대표적으로 Keycloak, AWS Cognito같은 서비스가 있다.

1. 특징

SSO (Single-sign-on)를 제공한다.
Restful API 지원 및 Custom API를 추가할 수 있다.
Java로 개발된 오픈소스이다.
https://github.com/keycloak/keycloak\

2. 제공 기능

계정 등록
다중 프로토콜 지원 (OpenID Connect, OAuth 2.0 및 SAML 2.0)
SSO
SNS 로그인
LDAP 통합
2단계 인증 (2FA, Two-factor authentication)
Kerberos broker
Manager console
Database sync

❓ SSO (Single-sign-on)
여러 서비스(Application or Client)에 대한 통합 인증을 말한다.

❓ 커버로스 (KRB5, Kerberos)
Server와 Client 간의 네트워크 인증 프로토콜이다.
인증뿐만 아니라 통신을 암호화해 주며 SSO의 일종으로 여러 시스템의 통합 접근 관리 기능을 제공한다.

3. Keycloak 용어

Realm
'영역', '왕국'이라는 뜻으로 인증/인가가 적용되는 범위이며 Keycloak에서 가장 근본이 되는 데이터이다.
Realm 안에 여러 Client가 존재한다.
Client
인증/인가를 수행할 Applicatiion(Service)를 나타내는 단위이다.
Realm에 속하며 Realm의 관리자가 하위 Client들을 관리한다.
User
인증을 필요로 하는 사용자를 뜻하며 username, email, firstname, lastname을 기본속성으로 가지고 있다.
Role
User에게 부여할 권한이다.

2️⃣ (Why) Keycloak 사용이유

Keycloak을 사용하면 사용자관리 서비스를 분리가 가능해지며 서비스의 확장성과 관리의 용이성이 상승된다.

또한 기존에 서비스들 각각 인증 및 인가 절차를 거치지 않아도 되고, Keycloak에게 일괄 위임되면서 각 서비스들이 서로 인증/인가를 공유해 사용할 수 있다. 이를 SSO라고 부른다.

이렇게 IAM 솔루션을 사용하면 굉장히 유연한 서비스 구조를 가질 수 있게 된다.

3️⃣ (How) 간단한 설치 및 테스트 - Linux

ℹ️ 설치 환경
- Linux Centos7
- java v17
- Keycloak v22.0.1

1. Linux Java 버전 확인

Keycloak 공식 가이드 문서에는 OpenJDK 17 이상 버전을 요구하고 있다.

2. Download

1. https://www.keycloak.org/downloads 다운로드 사이트 접속

2. Keycloak Server zip 파일 다운로드

3. 압축 풀기

다운로드 경로 : ~/install/
다운로드 파일명 : keycloak-22.0.1.zip
설치(압축해제) 경로 : /opt/keycloak/

$ cd /opt/keycloak/

$ unzip ~/install/keycloak-22.0.1.zip

4. 결과 확인

3. Start Keycloak

설치된 경로 : /opt/keycloak/keycloak-22.0.1

Keycloak 가이드는 콘솔 시작으로 안내하고 있다. 이는 콘솔을 빠져나가게 되면 프로세스는 종료가 되기 대문에 상당히 불편하다.

때문에 백그라운드로 시작하고 종료될 수 있도록 아주 간단히 대충.. start 스크립트를 작성했다.

또 Keycloak 가이드에서 프로세스 pid를 찾아 kill 하라고 안내되어 있어 stop 스크립트도 대충 작성했다. (stop 명령이 따로 없는 듯하다... 내가 못 찾은 건가ㅠㅠ)

1. start, stop 스크립트 작성

경로 생성

$ mkdir /opt/keycloak/scripts/

스크립트 작성

$ echo '/opt/keycloak/keycloak-22.0.1/bin/kc.sh start-dev --log="file" --log-file="/opt/keycloak/logs/dev.log" 2>&1 & echo "$!" > /opt/keycloak/keycloak.pid &' > /opt/keycloak/scripts/start-kc
$ echo 'cat /opt/keycloak/keycloak.pid | xargs kill -TERM' > /opt/keycloak/scripts/stop-kc

$ chmod -R 744 /opt/keycloak/scripts/

start-kc ▶️ keycloak start 스크립트
--log="file" --log-file="{로그 파일 경로}" : 로그 파일 설정
2>&1 & echo "$2" > keycloak.pid : 실행된 프로세스의 PID를 keycloak.pid 파일에 덮어쓰기
stop-kcr ▶️ keycloak stop 스크립트
keycloak.pid에 저장된 프로세스 PID를 kill 한다.

2. keycloak 실행

$ /opt/keycloak/scripts/start-kc

3. start log 확인

$ tail -f /opt/keycloak/logs/dev.log

4. 사이트 접속 & admin 계정 생성

1. 사이트 접속

별다른 Port 설정을 하지 않았으므로 8080으로 붙으면 된다.

(나는 keycloak을 회사 vm에 설치해서 외부에서 접근하는 방식이다.)

2. admin 계정 생성

내부 localhost로 웹 사이트에 접근이 가능하다면 브라우저에서 편하게 Admin 계정을 생성할 수 있다.

그러나 외부 접근만 가능한 경우 Server 환경변수로 직접 설정 가능하다.

2-1. localhost 웹 사이트에서 설정 (Username, Password 입력 후 [Create] 클릭 )

2-2. Server 환경변수로 직접 설정

가) keycloak 중지

$ /opt/keycloak/scripts/stop-kc

나) KEYCLOAK_ADMIN, KEYCLOAK_ADMIN_PASSWORD 환경변수 추가

$ export KEYCLOAK_ADMIN={계정}
$ export KEYCLOAK_ADMIN_PASSWORD={비밀번호}

다) keycloak 시작

$ /opt/keycloak/scripts/start-kc

계정 생성 후 다시 keycloak에 접속하면'Administration Console' 이 활성화되어 있다.

5. 관리자 콘솔 로그인

1. 관리자 콘솔 접속 ( 초기에 생성한 ID와 비밀번호를 입력)

http://{keycloak url}/admin

2. 관리자 로그인 (로그인 성공시 keycloak 대시보드로 진입된다. )

6. Realm & 일반계정 생성

ℹ️ 생성할 Realm 정보
이름 : TEST-20230911
User : test

1. 왼쪽 상단 [master] 선택 → [Create Realm] 클릭

2. [Realm name]에 이름 입력 → [Create] 클릭

3. 새로 생성한 Realm 대시보드로 이동됨

4. 왼쪽 [Users] 메뉴 진입 → [Add user] 클릭

5. 사용자 계정 정보 입력 → [Create] 클릭

Required user actions : 로그인 이후 추가 요구 작업
- Verify email : 이메일 전송
- Update : 개인정보 업데이트 요청
- Update password : 비밀번호 업데이트 요청
- Configure OTP : 모바일 비밀번호(OTP) 생성 설정 요청
Username : 계정 아이디

6. [Credentials] 탭 클릭 → [Set password] 클릭 → 비밀번호 입력 & ‘Temporary’ Off → [Save] 클릭

Temporary : 임시 비밀번호 도움말

7. Realm에 Client(Application) 등록

ℹ️ 등록할 Client 정보
ID : test-client
이름 : TEST Client

1. 왼쪽 [Clients] 메뉴 진입 → [Create client] 클릭

2. ‘General Settings’ 정보 입력 → [Next] 클릭

Client ID : 아이디 (URL 또는 tokens에서 참조)
Name : 이름
Always display in UI : UI에 항상 표시 (세션 활성화 되지 않았어도 표시)

3. ‘Capability config’ 정보 선택 (기본 설정 그대로 진행했음) → [Next] 클릭

Client authentication : ‘ON’일 때 OpenID(OIDC)인 경우 인증된 접근만 허용, ‘OFF’일때는 public 접근
Authorization : Client 권한 활성화

4. ‘Login settings’ 정보 입력 → [Save] 클릭

Root URL : Client URL
Home URL : 인증완료 후 리다이렉트할 default URL
Valid redirect URLs : 로그인 완료후 리다이렉트 허용 URL 패턴 ( * 허용)
Valid port logout redirect URIs : 로그아웃 완료후 리다이렉트 허용 URL 패턴 ( * 허용)
Web origins : CORS origins 설정

5. 아래와 같이 나머지 정보 자동 세팅됨 → [Save] 클릭

8. 간단한 테스트

테스트 방법은 Keycloak의 접속 정보를 직접 입력하는 방식으로 접근해야한다.

1. 로그인

Account 관리 콘솔 접속
http://{keyclock URL}/realms/{Realm}/protocol/openid-connect/auth?client_id={client ID}&response_type=code&state=12345

http://surfinn.yj.com:8080/realms/TEST-20230911/protocol/openid-connect/auth?client_id=test-client&response_type=code&state=12345>

[Sinning in] 클릭 → Realm의 Username 과 비밀번호 입력 → [Sign in] 클릭
초기 로그인시에는 로그인 후 새로운 패스워드로 변경해야한다.

로그인이 완료되면 설정한 URL로 리다이렉트 된다.

2. 로그인한 User의 Session 확인

Realm 대시보드 접근 → 왼쪽 [Sessions] 메뉴
login ID, Session 시작, 마지막 로그인 일시, 로그인 IP 등 정보를 확인 할 수 있다.

Reference

저작자표시 비영리 변경금지