콘텐츠로 이동

Keycloak SSO(배포 플랜)


소개

Guance 배포 플랜은 OpenID Connect 및 OAuth 2.0 두 가지 프로토콜을 기반으로 한 SSO(Single Sign-On) 방식을 지원합니다. 이 문서에서는 Keycloak 로그인을 예로 들어 설명합니다.

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

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

개념

용어 설명
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 생성 및 openid-connect 프로토콜 구성

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

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

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

Client가 생성된 후 아래 스크린샷과 같이 구성하고 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 엔드포인트 구성 주소, 즉 전체 `https://xxx.xxx.com/xx/.well-known/openid-configuration` 주소.
  wellKnowURL:
  # 인증 서비스에서 제공하는 클라이언트 ID
  clientId:
  # 클라이언트의 Secret key
  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로 직접 리다이렉트하는 인터페이스 =========시작=========
        # 이 주소는 제3자 로그인 시 사용되는 액세스 주소입니다. 상황에 따라 변경할 수 있지만 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;
        }

        # 이 주소는 제3자 서비스가 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://GuanceWeb端登录域名地址/oidc/login"


    ......

};

참고 이미지:

4) 구성 완료 후 업데이트된 구성 수정을 체크하고 재시작을 확인합니다.

5. Keycloak 계정으로 Guance에 SSO 로그인

모든 구성이 완료되면 SSO로 Guance에 로그인할 수 있습니다.

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

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

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

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

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

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

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

문서 평가

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