콘텐츠로 이동

Keycloak 싱글 사인온(배포 플랜)


개요

Guance 배포 플랜은 OpenID Connect 및 OAuth 2.0 두 가지 프로토콜 기반의 싱글 사인온 방식을 지원합니다. 본 문서에서는 Keycloak 로그인을 예시로 설명합니다.

Keycloak은 현대적인 애플리케이션과 분산 서비스를 위한 오픈 소스 ID 및 액세스 관리 솔루션입니다. Guance 배포 플랜은 OpenID Connect 프로토콜을 기반으로 기업의 Keycloak 계정을 사용하여 Guance 플랫폼에 싱글 사인온하고 해당 워크스페이스 리소스에 액세스할 수 있도록 지원합니다. 별도로 기업/팀의 Guance 계정을 생성할 필요가 없습니다.

참고: 본 문서는 OpenID Connect 프로토콜을 사용하며 Keycloak 버전이 18.0.2 이하인 경우에 적용됩니다.

개념

용어 설명
Realm 영역(realm)입니다. 워크스페이스와 유사하며 사용자, 자격 증명, 역할 및 사용자 그룹을 관리합니다. 영역 간에는 격리됩니다.
Clients 클라이언트는 Keycloak에 사용자 인증을 요청할 수 있는 애플리케이션 또는 서비스입니다.
Users 시스템에 로그인할 수 있는 사용자 계정입니다. 로그인 이메일 및 자격 증명(Credentials)을 구성해야 합니다.
Credentials 사용자 신원을 확인하는 자격 증명입니다. 사용자 계정의 로그인 비밀번호를 설정하는 데 사용할 수 있습니다.
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) 생성 및 openid-connect 프로토콜 구성

참고: 이 단계에서는 Keycloak 클라이언트를 생성하고 openid-connect 프로토콜을 구성하여 Keycloak과 Guance 간의 신뢰 관계를 구축합니다.

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

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

클라이언트 생성 후 아래 스크린샷과 같이 구성하고 Save를 클릭합니다.

  • Client Protocol: openid-connect
  • Access Type: confidential
  • Standard Flow Enabled: ON
  • Direct Access Grants Enabled: ON
  • Service Accounts Enabled: ON
  • Valid Redirect URIs: *

3. Keycloak 사용자 구성

4. Guance Launcher 구성

1) Guance Launcher 네임스페이스: forethought-core > core에서 Keycloak 기본 정보를 구성합니다.

# OIDC 클라이언트 구성(이 구성 항목에 wellKnowURL이 구성된 경우 KeyCloakPassSet 구성 항목은 자동으로 비활성화됨)
OIDCClientSet:
  # OIDC Endpoints 구성 주소, 즉 전체 `https://xxx.xxx.com/xx/.well-known/openid-configuration` 주소.
  wellKnowURL:
  # 인증 서비스에서 제공하는 클라이언트 ID
  clientId:
  # 클라이언트 시크릿 키
  clientSecret:
  # 인증 방식, 현재는 authorization_code만 지원
  grantType: authorization_code
  verify: false
  # 데이터 액세스 범위
  scope: "openid profile email address"
  # 인증 서버 인증 성공 후 콜백 주소
  innerUrl: "{}://{}/oidc/callback"
  # 인증 서버 인증 성공 후 DF 시스템으로 콜백되면, DF 시스템이 사용자 정보를 가져와 프론트엔드 중간 페이지로 이동하는 주소
  frontUrl: "{}://{}/tomiddlepage?uuid={}"
  # 인증 서비스에서 가져온 계정 정보와 DF 시스템 계정 간의 매핑 구성. 필수 항목: username, email, exterId
  mapping:
    # 인증 서비스의 로그인 계정 사용자 이름, 필수 항목. 값이 없으면 email 사용
    username: preferred_username
    # 인증 서비스의 로그인 계정 이메일, 필수 항목
    email: email
    # 인증 서비스의 로그인 계정 휴대폰 번호 필드 이름, 선택 항목
    mobile: phone_number
    # 인증 서비스의 로그인 계정 고유 식별자, 필수 항목
    exterId: sub

참고 예시 이미지:

위 예시 이미지의 "wellKnowURL:"은 Realm Settings > General > Endpoints에서 가져올 수 있습니다.

또는

예시 이미지의 "clientSecret:"은 Client > Client ID (예: Guance) > Credentials에서 가져올 수 있습니다.

2) Guance Launcher 네임스페이스: forethought-webclient > frontNginx에서 리디렉션 정보를 구성합니다.

        # =========OIDC 프로토콜 리디렉션 관련 구성 시작=========
        # Inner API로 직접 리디렉션하는 요청 =========시작=========
        # 이 주소는 타사 로그인 시 접근 주소입니다. 상황에 따라 변경할 수 있지만 proxy_pass의 라우팅 주소는 변경할 수 없습니다.
        location /oidc/login {
            proxy_connect_timeout 5;
            proxy_send_timeout 5;
            proxy_read_timeout 300;
            proxy_http_version 1.1;
            proxy_set_header Connection "keep-alive";
            add_header Access-Control-Allow-Origin *;
            add_header Access-Control-Allow-Headers X-Requested-With;
            add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
            proxy_pass http://inner.forethought-core:5000/api/v1/inner/oidc/login;
        }

        # 이 주소는 타사 서비스가 OIDC 프로토콜 인증을 통과한 후 이 서비스의 현재 주소로 콜백하는 주소입니다. 이 주소는 [3.2.1] 구성의 OIDCClientSet 항목 아래 innerUrl 구성과 직접 연결됩니다. 이 주소가 변경되면 innerUrl도 함께 변경해야 합니다. proxy_pass 값은 변경할 수 없습니다.
        location /oidc/callback {
            proxy_connect_timeout 5;
            proxy_send_timeout 5;
            proxy_read_timeout 300;
            proxy_http_version 1.1;
            proxy_set_header Connection "keep-alive";
            add_header Access-Control-Allow-Origin *;
            add_header Access-Control-Allow-Headers X-Requested-With;
            add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
            proxy_pass http://inner.forethought-core:5000/api/v1/inner/oidc/callback;
       }
       # =========OIDC 프로토콜 리디렉션 관련 구성 종료=========

참고 예시 이미지:

3) Guance Launcher 네임스페이스: forethought-webclient > frontWeb에서 Keycloak 사용자가 Guance 배포 플랜에 로그인하기 위한 진입 주소를 구성합니다.

window.DEPLOYCONFIG = {

    ......

    paasCustomLoginInfo:[
        {url:"http://Guance의 배포 도메인/oidc/login",label:"Keycloak 로그인"}
    ],
    paasCustomLoginUrl: "https://<고객이 제공한 로그아웃 주소>?redirect_url=https://Guance 웹 로그인 도메인 주소/oidc/login"


    ......

};

참고 예시 이미지:

4) 구성이 완료되면 업데이트된 구성 수정을 선택하고 재시작을 확인합니다.

5. Keycloak 계정으로 Guance에 싱글 사인온

모든 구성이 완료되면 Guance에 싱글 사인온할 수 있습니다.

1) Guance 배포 플랜 로그인 주소를 열고 로그인 페이지에서 Keycloak 싱글 사인온을 선택합니다.

2) Keycloak에 구성된 이메일 주소를 입력합니다.

3) 로그인 비밀번호를 업데이트합니다.

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

Warning
  • "현재 계정이 어떤 워크스페이스에도 속해 있지 않습니다. 관리 백엔드로 이동하여 이 계정을 워크스페이스에 추가하십시오."라는 메시지가 표시되면 Guance 관리 백엔드에 로그인하여 사용자에게 워크스페이스를 추가해야 합니다.

자세한 내용은 배포 플랜 워크스페이스 관리 문서를 참조하십시오.

Guance 관리 백엔드에서 사용자에게 워크스페이스를 추가하면 사용자가 Guance을 사용할 수 있습니다.

문서 평가

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