Document toolboxDocument toolbox

1. Keycloak

Owned by 임기환
Last updated: Mar 16, 2023
4 min read

 

1. Keycloak 개요

오픈소스 ID 및 액세스 관리 솔루션으로 SSO(Single Sign On)를 지원하며 ID 중계 소셜 로그인 및 User Federation를 제공하며 관리 콘솔을 제공합니다.

 

Keycloak 주요 기능

  • Single-Sign On : keycloak 인증을 사용한 어플리케이들에서 단일 로그인/로그아웃 지원

  • Identity Brokering and Social Login : 소셜 네크워크를 통한 로그인을 지원하며 OpenID Connect, SAML 2.0 ID 공급자를 사용할 수 있음

  • User Federation : LDAP, Active Directory 서버 연결 지원

  • Admin Console : 관리 콘솔을 제공하여 다양한 기능을 활성/비활성화 할 수 있으며 세분화 된 인증 정책을 적용할 수 있으며 사용자 관리도 할 수 있음

  • Account Management Console : 계정 관리 콘솔을 제공하여 사용자의 프로필을 업데이트 하고 암호변경 이중 인증을 설정할 수 있음

  • Standard Protocols : 표준 프로토콜을 기반으로 하며 OpenID Connect, OAuth 2.0 및 SAML을 지원

  • Authorization Services : Role 기반 인증이 요구 사항을 충족하지 못하는 경우 세분화된 인증 서비스도 제공

 

2. Keycloak 사용

cli 명령으로 관리할 수 있지만 많은 설정을 직관적으로 파악하고 사용할 수 있는 Web UI 를 기반으로 사용법을 작성하였습니다.

 

관리자 로그인

  1. Web Console 접속

  2. Adminstration Console 클릭 <그림 1-1>

  3. 사전에 설정된 관리자 계정 정보를 이용하여 로그인

  4. Playce Cloud 시스템에서 자동으로 생성된 playcecloud realm 으로 접속 <그림 1-2>

<그림 1-1> Keycloak 메인화면

 

Realm 추가

Keycloak 에서는 Realm 단위로 인증 그룹을 구성합니다. Realm 내에서 여러 Client (어플리케이션)들은 SSO를 공유합니다.
Playce Cloud 시스템에서는 playcelcoud 라는 realm을 자동으로 생성하지만 추가로 생성도 가능합니다.

 

  1. 왼쪽 Realm 이름에 있는 드롭다운 메뉴에서 Add realm 클릭

  2. Name 필드에 이름을 넣어서 생성 <그림 2-1>

    1. realm 에 대한 정보를 미리 만들어서 import 할 수도 있다

  3. realm 생성 후 성격에 맞게 Client/User 등 인증/인가 관련 설정 등록

 

계정/그룹 추가

realm 내에서 여러 계정을 추가 할 수 있으며 계정 마다 그룹 및 여러 mapper 를 이용하여 인증/인가 정보를 설정할 수 있습니다.

계정 추가

  1. 왼쪽 Manage - Users 클릭

  2. 오른쪽 상단 Add User 클릭

  3. 필수 필드인 Username 에 계정명 추가 <그림 3-1>

  4. 나머지 필드는 선택적으로 추가

  5. Save 클릭

  6. 상단 Credentials 클릭 <그림 3-2>

  7. password/password 확인 필드 입력

  8. Temporary Off (로그인이 변경하도록 하려면 ON)

  9. Set Password 클릭

 

그룹 추가

  1. 왼쪽 Manage - Groups 클릭

  2. 오른쪽 상단 New 클릭

  3. Name 필드 입력 후 Save <그림 4-1>

 

Client(어플리케이션) 추가

Keycloak 에서는 인증을 받는 어플리케이션별로 Client를 생성합니다.

어플리케이션에 따라 Access Type, Mappers 등을 설정해 인증 방법 및 응답 json 데이터 등을 결정하여 사용합니다.

 

추가 예제

  • Access Type : confidential, User Attribute Mapper

  1. Configure - Clients 클릭

  2. 오른쪽 상단 Create 클릭

  3. Client ID 입력, Client Protocol : openid-connect 선택 <그림 5-1>

  4. Save 클릭

  5. Access Type : confidential 선택 <그림 5-2>

  6. Save 클릭

  7. 상단 Mappers 클릭

  8. 오른쪽 상단 Create 클릭

  9. Name 필드 입력

  10. Mapper Type : User Attribute 선택 <그림 5-3>

  11. User Attribute 에 사용할 Attribute 명 입력 <그림 5-4>

  12. Token Claim Name 에 응답시의 Token 이름 입력 (보통 User Attribute와 같은 값)

  13. add to Userinfo ON 확인

  14. Save 클릭

Client 사용 및 User Info

  • Access Type 이 confidential 인 경우 어플리케이션에서 client 이름과 secret 을 요구하는데 secret은 상단의 Credentials 탭에서 확인할 수 있습니다.

  • 어플리케이션에 따라 기본적으로 응답하는 유저 정보는 sub, name, preferred_username, email 등 이며 mapper 설정에 따라 추가됩니다.

 

인증/인가 연동

Keycloak 은 다른 인증 Provider 및 소셜 로그인을 지원하며 LDAP, keberos 등의 연동을 지원합니다.

OpenID Connect 및 소셜 로그인

  1. Configure - Identity Providers 클릭

  2. OpenID connect 및 다른 Keycloak 연동 선택 또는 소셜 로그인 클릭

  3. 각 메뉴에 따라 필드값 입력

User Federation

  1. Configure - User Federation 클릭

  2. keberos 또는 ldap 선택

  3. 각 메뉴에 따라 필드값 입력

 

3. 릴리즈 노트

4. 참고 문서