Keycloak SSO 예제¶

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

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

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

전제 조건¶

Keycloak 서버가 구축되어 있고, 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	영역(Realm) - 워크스페이스와 유사하며, 사용자, 자격 증명, 역할 및 사용자 그룹을 관리합니다. 영역 간에는 격리됩니다.
Clients	클라이언트(Client) - 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를 클릭합니다.

Client ID (엔터티 ID): https://auth.guance.com/saml/metadata.xml
Client Protocol: SAML 선택
Client SAML Endpoint (어설션 주소), 임시 사용: https://auth.guance.com/saml/assertion

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

클라이언트가 생성되면 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에 직접 SSO 로그인하는 데 사용됩니다.

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

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

Name: 임의로 입력 가능합니다(예: "mail mapper").
Mapper Type: "User Property" 선택
Property: ID 공급자가 지원하는 규칙에 따라 Email 입력
SAML Attribute Name: Email을 반드시 입력해야 합니다.

참고: Guance은 매핑 필드를 정의하며, ID 공급자의 사용자 이메일을 연결하기 위해 Email을 반드시 입력해야 합니다(즉, ID 공급자가 로그인 사용자의 이메일을 Email에 매핑합니다).

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

참고: 이 단계에서는 Guance에서 ID 공급자를 생성하기 위한 메타데이터 문서를 가져옵니다.

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

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

3) Keycloak의 메타데이터 문서는 영역(Realm) 수준이므로, 메타데이터 문서 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 구성을 최종 SSO 로그인 진입점으로 간주합니다.

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

참고: 도메인은 Guance과 ID 공급자 간의 이메일 도메인 매핑에 사용되어 SSO를 구현합니다. 즉, 사용자 이메일의 도메인 접미사가 Guance에 추가된 도메인과 일치해야 합니다.