콘텐츠로 이동

Keycloak SSO 예시


Keycloak은 현대 애플리케이션과 분산 서비스를 위한 오픈 소스 ID 인증 및 액세스 제어 솔루션입니다.

이 문서에서는 직접 구축한 Keycloak 서버를 사용하여 SAML 2.0 프로토콜로 Keycloak 사용자가 Guance 관리 콘솔에 SSO 로그인하는 방법을 소개합니다.

OpenID Connect 프로토콜로 Keycloak 사용자가 Guance 관리 콘솔에 SSO 로그인하는 방법은 Keycloak SSO(배포 플랜)를 참조하세요.

사전 준비

Keycloak 서버가 구축되어 있고, 해당 서버에 로그인하여 구성할 수 있어야 합니다.

Keycloak 환경이 없는 경우 다음 단계에 따라 구축합니다.

sudo yum update         # 업데이트

sudo yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel      # JDK 설치

wget https://downloads.jboss.org/keycloak/11.0.2/keycloak-11.0.2.zip   # Keycloak 다운로드

yum install unzip       # 압축 해제 도구 설치

unzip keycloak-11.0.2.zip       # 다운로드한 Keycloak 압축 해제

cd keycloak-11.0.2/bin         # bin 디렉터리로 이동

./add-user-keycloak.sh -r master -u admin -p admin     # 서버 관리자 로그인 계정 및 비밀번호 생성

nohup bin/standalone.sh -b 0.0.0.0 &     # bin 디렉터리로 돌아가 백그라운드에서 Keycloak 시작 서비스 실행

Keycloak 환경 구축이 완료되면 브라우저에 https://IP地址:8443/auth를 입력하고 "Administration Console"을 클릭하여 Keycloak 관리 콘솔을 엽니다.

개념

다음은 KeyCloak 구성 과정에서 사용되는 기본 개념에 대한 설명입니다.

필드 설명
Realm 영역으로, 워크스페이스와 유사하며 사용자, 자격 증명, 역할, 사용자 그룹을 관리합니다. 영역 간에는 서로 격리됩니다.
Clients 클라이언트는 Keycloak에 사용자 인증을 요청할 수 있는 애플리케이션 또는 서비스입니다.
Users 시스템에 로그인할 수 있는 사용자 계정으로, 로그인 이메일과 Credentials를 구성해야 합니다.
Credentials 사용자 ID를 검증하는 자격 증명으로, 사용자 계정의 로그인 비밀번호를 설정하는 데 사용됩니다.
Authentication 사용자를 식별하고 검증하는 프로세스입니다.
Authorization 사용자에게 액세스 권한을 부여하는 프로세스입니다.
Roles 관리자, 일반 사용자 등 사용자의 ID 유형을 식별하는 데 사용됩니다.
User role mapping 사용자와 역할 간의 매핑 관계로, 한 명의 사용자는 여러 역할에 연결될 수 있습니다.
Groups 사용자 그룹을 관리하며, 역할을 그룹에 매핑할 수 있습니다.

작업 단계

1. Keycloak realm 생성

참고: Keycloak 자체에는 마스터 영역(Master)이 있으며, 새 영역(워크스페이스와 유사)을 생성해야 합니다.

1) Keycloak 관리 콘솔에서 Master > Add realm을 클릭합니다.

2) Add realm 페이지의 Name에 영역 이름(예: "gcy")을 입력하고 Create를 클릭하면 새 영역이 생성됩니다.

2. Client 생성 및 SAML 구성

참고: 이 단계에서는 Keycloak 클라이언트를 생성하고 SAML을 구성하여 Keycloak과 Guance 간에 상호 신뢰 관계를 수립합니다.

1) 새로 생성한 "gcy" 영역에서 Client를 클릭하고 오른쪽에서 Create를 클릭합니다.

2) Add Client 페이지에 다음 내용을 입력한 후 Save를 클릭합니다.

참고: 이번 구성은 다음 단계의 메타데이터 문서를 얻기 위한 임시 설정입니다. Guance에서 SSO 단일 로그인을 활성화한 후 올바른 엔터티 ID와 어서션 주소를 확인한 뒤 다시 교체해야 합니다.

Client를 생성하면 Settings에서 이전 단계에 입력한 엔터티 ID, 프로토콜, 어서션 주소를 확인할 수 있습니다. 다음 매개변수를 설정한 후 저장합니다.

  • Sign Assertions: ON(IdP가 전송하는 데이터의 변조를 방지하고 IdP에서 SP로 전송되는 데이터의 보안을 보장합니다.)

  • IDP Initiated SSO URL Name: "gcy" 등 임의로 입력할 수 있으며, 입력한 후 SSO 단일 로그인 주소가 생성됩니다(아래 그림 참조).
  • Base URL: 이전 매개변수에서 생성된 SSO 단일 로그인 주소를 입력합니다(예: /auth/realms/gcy/protocol/saml/clients/gcy). 주로 Keycloak Clients에서 액세스 링크를 생성하여 Guance로 바로 단일 로그인하는 데 사용됩니다.

3) Clients의 Mappers에서 Create를 클릭하여 이메일 매핑을 생성합니다. 이 부분은 필수 항목이며, 입력하지 않으면 SSO 단일 로그인을 구현할 수 없습니다.

Create Protocol Mapper 페이지에서 다음 내용을 입력한 후 저장합니다.

  • Name: "mail mapper" 등 임의로 입력할 수 있습니다.
  • Mapper Type: "User Property" 선택
  • Property: IdP가 지원하는 규칙에 따라 Email을 입력합니다.
  • SAML Attribute Name: 본 예시에서는 Email을 입력하며, 사용자 이메일을 전달하는 데 사용됩니다.

참고: Guance의 SAML 필드 매핑에서 이메일 매핑에 이 단계에서 반환된 속성 이름(본 예시에서는 Email)을 입력합니다. 또한 필수 항목인 사용자 이름 매핑을 구성하고, 휴대폰 번호 매핑은 필요에 따라 입력할 수 있습니다.

3. KeyCloak 메타데이터 문서 가져오기

참고: 이 단계에서는 Guance에서 IdP를 생성하는 데 필요한 메타데이터 문서를 얻을 수 있습니다.

1) Clients의 Installation에서 Mod Auth Mellon files를 선택하고 Download를 클릭하여 메타데이터 문서를 다운로드합니다.

2) 다운로드한 폴더에서 idp-metadata.xml을 선택합니다.

3) Keycloak의 메타데이터 문서는 영역 수준이므로 메타데이터 문서 idp-metadata.xml의 액세스 주소에 클라이언트 매개변수 /clients/<IDP Initiated SSO URL Name>을 추가해야 합니다. 이 문서에서는 IDP Initiated SSO URL Name: gcy로 설정했으므로 XML 파일에 /clients/gcy를 입력합니다(아래 그림 참조). 추가가 완료되면 XML 파일을 저장합니다.

4. Guance에서 SSO 단일 로그인 활성화

1) SSO 단일 로그인을 활성화하려면 Guance 워크스페이스의 관리 > 구성원 관리 > SSO 관리에서 활성화를 클릭합니다.

자세한 내용은 SSO 생성 문서를 참조하세요.

참고: 계정 보안을 위해 Guance는 워크스페이스당 SSO를 하나만 구성할 수 있습니다. 이전에 SAML 2.0을 구성한 경우, 마지막으로 업데이트한 SAML 2.0 구성이 최종 단일 로그인 인증 진입점으로 간주됩니다.

2) 3단계에서 다운로드한 메타데이터 문서를 업로드하고 도메인(이메일 접미사 도메인)을 구성한 후 역할을 선택하면 해당 IdP의 엔터티 ID와 어서션 주소를 확인할 수 있습니다. 로그인 주소를 복사하여 바로 로그인할 수도 있습니다.

참고: 도메인은 Guance와 IdP 간에 이메일 도메인 매핑을 수행하여 단일 로그인을 구현하는 데 사용됩니다. 즉, 사용자 이메일의 접미사 도메인은 Guance에 추가된 도메인과 동일해야 합니다.

5. KeyCloak에서 SAML 어서션 주소 교체

1) Keycloak으로 돌아가 2단계의 엔터티 ID와 어서션 주소를 업데이트합니다.

참고: Guance에서 단일 로그인을 구성할 때 IdP의 SAML에 구성된 어서션 주소는 Guance의 값과 동일해야 단일 로그인을 구현할 수 있습니다.

6. Keycloak 사용자 구성

참고: 이 단계에서는 Guance에서 IdP를 생성할 때 사용할 승인된 사용자 이메일 계정을 구성합니다. 구성된 Keycloak 사용자 이메일 계정으로 Guance 플랫폼에 단일 로그인할 수 있습니다.

1) 생성한 gcy 영역에서 User를 클릭하고 Add user를 클릭합니다.

2) Username과 Email을 입력합니다. Email은 필수 항목이며, Guance IdP 구성에서 사용자 허용 목록 이메일과 동일해야 합니다. 이메일 매핑이 일치하면 Guance에 로그인할 수 있습니다.

3) 사용자를 생성한 후 Credentials에서 사용자의 비밀번호를 설정합니다.

7. Keycloak 계정을 사용하여 Guance에 단일 로그인

모든 구성이 완료되면 두 가지 방법으로 Guance에 단일 로그인할 수 있습니다.

방법 1: Keycloak에서 Guance에 로그인

1) Keycloak의 Clients에서 오른쪽의 Base URL을 클릭합니다.

2) 구성된 사용자 이메일과 비밀번호를 입력합니다.

3) Guance의 해당 워크스페이스에 로그인합니다.

참고: 여러 워크스페이스에 동일한 IdP SSO 단일 로그인이 구성된 경우, 사용자는 SSO 단일 로그인으로 워크스페이스에 로그인한 후 Guance 왼쪽 상단의 워크스페이스 옵션을 클릭하여 다른 워크스페이스로 전환하고 데이터를 확인할 수 있습니다.

방법 2: Guance에서 Keycloak 계정으로 단일 로그인

1) SSO 구성이 완료되면 Guance 공식 사이트 또는 Guance 콘솔에서 로그인하고, 로그인 페이지에서 단일 로그인을 선택합니다.

2) SSO를 생성할 때 입력한 이메일 주소를 입력하고 로그인 주소 가져오기를 클릭합니다.

3) 링크를 클릭하여 기업 계정 로그인 페이지를 엽니다.

4) 기업 공용 이메일(Keycloak 및 Guance SSO 관리에서 구성한 기업 이메일 주소)과 비밀번호를 입력합니다.

5) Guance의 해당 워크스페이스에 로그인합니다.

참고: 여러 워크스페이스에 동일한 IdP SSO 단일 로그인이 구성된 경우, 사용자는 SSO 단일 로그인으로 워크스페이스에 로그인한 후 Guance 왼쪽 상단의 워크스페이스 옵션을 클릭하여 다른 워크스페이스로 전환하고 데이터를 확인할 수 있습니다.

문서 평가

이 페이지가 도움이 되었나요?