Keycloak (OIDC) - Web 콘솔

본 가이드는 Keycloak 와 네트워크 접근제어 시스템인 Genian ZTNA의 인증연동 기능을 수행하기 위한 설정 방법을 안내합니다.

관리자 인증을 위해 Genian ZTNA Web 콘솔 페이지에서 OIDC (OpenID Connect) 프로토콜을 이용하여 Keycloak 인증을 호출하고 Keycloak에서 사용자인증여부를 확인하여 정상적인 SSO가 이루어집니다.

권장버전

제품명(구성요소)

버전

비고

Genian ZTNA(정책서버)

V6.0 이상

2025.10 이후 Release 버전

Keycloak

20.0 이상

2025.10 현재 연동가능

연동 전 필요한 사항

  • Keycloak 서버 설치 및 운영 (버전 20.0 이상)

  • Keycloak Admin Console 접근 권한

  • Genian ZTNA Web 콘솔 관리자 권한

  • 네트워크 연결 (Genian ZTNA ↔ Keycloak 서버 간 통신)

연동의 목적

Genian ZTNA와 Keycloak 연동은 다음의 효과를 제공합니다.

  • ZTNA, Keycloak 개별 인증을 위한 관리자 DB 관리가 필요하지 않습니다.

  • Keycloak 계정을 이용하여 SSO로 ZTNA Web 콘솔을 인증할 수 있습니다.

  • OIDC 표준 프로토콜을 통한 안전한 관리자 인증을 제공합니다.

  • Keycloak의 강력한 인증/권한 관리 기능을 활용할 수 있습니다.

  • 다중 Realm 및 Federation 기능을 통한 통합 관리가 가능합니다.

지원되는 기능

Keycloak OIDC 연동은 다음과 같은 기능을 지원합니다:

  • Authorization Code Flow (표준 OIDC 인증 플로우)

  • PKCE (Proof Key for Code Exchange) 보안 강화

  • JIT (Just-In-Time) Provisioning

  • Access Token 및 ID Token 검증

  • UserInfo Endpoint를 통한 관리자 정보 조회

  • Keycloak Groups 연동

연동 설정 방법

본 가이드에서 다루는 Genian ZTNA와 Keycloak 설정 방법은 연동을 위한 필수 항목만을 안내합니다. 최초 1회 설정 이후 자동으로 적용됩니다.

Step 1: Keycloak Realm 생성 및 설정

  1. Keycloak Admin Console에 접속하여 관리자 계정으로 로그인합니다.

  2. 좌측 메뉴에서 Realm 선택 드롭다운을 클릭하고 Create realm 을 선택합니다.

  3. Realm 생성 정보를 입력합니다.

    • Realm name: "genian-ztna" 입력

    • Enabled: 체크 상태 유지

    • Create 버튼을 클릭합니다.

  4. 생성된 Realm이 선택된 상태에서 좌측 메뉴의 Realm settings 를 클릭합니다.

  5. General 탭에서 Realm 기본 설정을 확인합니다.

    • Require SSL: "External requests" 또는 "All requests" 선택 (HTTPS 환경 권장)

    • User registration: 필요에 따라 설정 (일반적으로 비활성화)

Step 2: Keycloak Client 생성

  1. 좌측 메뉴에서 Clients 를 클릭합니다.

  2. Create client 버튼을 클릭합니다.

  3. General settings 에서 다음을 입력합니다.

    • Client type: "OpenID Connect" 선택

    • Client ID: "genian-ztna-adminconsole" 입력

    • Name: "Genian ZTNA Admin Console" 입력

    • Description: "Genian ZTNA 관리콘솔 OIDC 연동" 입력

    • Next 버튼을 클릭합니다.

  4. Capability config 에서 다음을 설정합니다.

    • Client authentication: 'On' 체크 (Confidential client)

    • Authorization: 'Off' (일반적으로 불필요)

    • Standard flow: 'On' 체크 (Authorization Code Flow)

    • Direct access grants: 'Off' (보안상 권장)

    • Next 버튼을 클릭합니다.

  5. Login settings 에서 다음을 입력합니다.

  6. 생성된 Client의 Credentials 탭에서 Client secret 를 복사합니다.

    • Client secret 예시: abc123def456ghi789jkl012mno345pq

Step 3: Keycloak 사용자

  1. 좌측 메뉴에서 Users 를 클릭합니다.

  2. Create new user 버튼을 클릭합니다.

  3. 관리자 계정 정보를 입력합니다.

    • Username: "admin" 입력

    • Email: "admin@company.com" 입력

    • First name: "Admin" 입력

    • Last name: "User" 입력

    • Email verified: 'On' 체크 (선택사항)

    • Create 버튼을 클릭합니다.

  4. 생성된 사용자의 Credentials 탭으로 이동합니다.

    • Set password 를 클릭합니다.

    • Password: 임시 비밀번호 입력

    • Password confirmation: 동일한 비밀번호 재입력

    • Temporary: 'Off' (사용자가 직접 변경하지 않도록)

    • Save 버튼을 클릭합니다.

Step 4: Keycloak Groups 생성

  1. 좌측 메뉴에서 Groups 를 클릭합니다.

  2. Create group 버튼을 클릭합니다.

    • Name: "_ADMINROLE_superAdmin_ZTNA" 와 같이 _ADMINROLE_ prefix와 roleId(superAdmin)는 반드시 포함되어야 합니다.

    • Save 버튼을 클릭합니다.

  3. 생성된 그룹의 Members 탭에서 Add member 을 클릭합니다.

    • _ADMINROLE_superAdmin_ZTNA 그룹에 적용할 사용자를 할당합니다.

Step 5: Genian ZTNA OIDC 설정

  1. Genian ZTNA Web콘솔 > 설정 > 환경설정 > 관리콘솔 > OIDC 인증 에 다음 각 항목의 값을 Keycloak에서 복사해서 입력하십시오.

    • Provider 이름 - "Keycloak" 입력

    • Issuer - https://{keycloak-server}/realms/{realm name}

    • Client ID - "genian-ztna-adminconsole"

    • Client Secret - Keycloak의 Client secret

    • Discovery 사용 - "Off" 선택 (자동 엔드포인트 검색이 동작안함)

      • Realm settings에서 General 탭의 Endpoints 클릭하면 관련 Endpoint 정보를 확인할 수 있습니다.

      • 아래의 URL로 접속하면 관련 Endpoint 정보를 확인할 수 있습니다.

        https://{keycloak-server}/realms/{Realm name}/.well-known/openid-configuration

    • Scope - "openid profile email" 입력

  2. JIT provisioning 기능을 사용할려면 ZTNA에서 JIT provisioning 을 'On'으로 변경하십시오.

    • ZTNA UI의 JIT provisioning > 추가정보 에서 추가 버튼을 클릭해서 관리자 계정의 이름, 이메일을 설정하십시오.

      • 이름에 {given_name} {family_name} 입력하십시오.

      • 이메일에 email 을 입력하십시오.

        • OIDC Claims (given_name, family_name, email) 항목은 Keycloak에 이미 표준으로 정의되어 있습니다.

    • JIT provisioning을 통해 생성되는 관리자의 기본 권한을 설정하십시오.

      • ZTNA UI의 JIT provisioning > 관리자 관리역할 에서 신규 관리자에게 할당할 관리 역할을 선택합니다.

      • Keycloak Groups를 통해 관리자별 차등 권한을 설정할 수 있습니다.

      • 관리자를 할당할 그룹명을 _ADMINROLE_superAdmin_ZTNA 처럼 _ADMINROLE_ prefix와 roleId(superAdmin)는 반드시 포함되어야 합니다.

        관리역할

        값

        superAdmin

        _ADMINROLE_superAdmin_ZTNA

  3. Genian ZTNA 관리콘솔 로그인 화면에서 표시할 Keycloak 인증버튼에 표시할 문구를 로그인 버튼 문구 에 입력합니다.

    • 예시: "Keycloak으로 로그인", "Sign in with Keycloak"

  4. Genian ZTNA Web 콘솔 설정 화면 하단 수정 버튼을 클릭합니다.

주석

Client ID와 Client Secret이 올바르게 입력되었는지 확인하세요. 또한 Keycloak 서버의 Issuer URL이 ZTNA에서 접근 가능한지 확인하십시오.

Step 5: Keycloak Client Mappers 설정 (고급)

JIT Provisioning을 위한 추가 그룹 정보 매핑을 설정할 수 있습니다.

  1. Keycloak Admin Console에서 생성한 Client를 선택합니다.

  2. Client scopes 탭으로 이동합니다.

  3. genian-ztna-adminconsole-dedicated 를 클릭합니다.

  4. Mappers 탭에서 Add mapper > By configuration 을 클릭합니다.

  5. Group Membership 을 선택하여 그룹 정보를 추가합니다.

    • Name에 적당한 이름을 설정합니다.

    • Token Claim Name에 "groups" 입력합니다.

    • Full group path Off하고 저장합니다.

    • Save 버튼을 클릭합니다.

인증연동 테스트 방법

Genian ZTNA 관리콘솔 페이지에서 테스트하는 방법 (SP-initiated SSO)

  1. Genian ZTNA 관리콘솔 로그인 페이지에 접속합니다.

  2. 로그인 화면에 위 Step4에서 설정한 인증버튼("Keycloak으로 로그인")을 클릭합니다.

  3. 새로운 팝업창에 Keycloak 인증페이지가 표시됩니다.

  4. Keycloak 사용자명, 암호를 입력하여 인증합니다.

  5. 인증 성공 시 JWT ID Token과 Access Token을 받아 관리자 정보를 추출하고 ZTNA 관리콘솔에 로그인됩니다.

주석

인증연동 설정 후 정책적용시 제어정책 권한에 Keycloak IdP 도메인을 추가해주어야 차단상태에서도 인증연동 창이 표시됩니다.

1. 권한 추가 방법
2. 정책 > 객체 > 네트워크
3. 작업선택 > 생성
4. 기본정보 입력
5. 네트워크주소 > FQDN 선택 > IdP 도메인 입력
   - keycloak-server (내부 도메인)
   - your-keycloak.company.com (외부 도메인)
6. 생성 클릭
7. 권한 메뉴로 이동
8. 생성한 네트워크객체를 이용하여 권한 생성
9. 관리콘솔을 제어하는 제어정책에 생성한 권한 할당