Keycloak (OIDC) - CWP

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

개요

Genian ZTNA와 Keycloak 솔루션의 OIDC APP 연동을 통하여 Genian ZTNA 자체 사용자DB를 관리할 필요가 없이 Keycloak을 통해 사용자 인증을 수행할 수 있습니다.

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

권장버전

제품명(구성요소)

버전

비고

Genian ZTNA(정책서버)

V6.0 이상

2025.10 이후 Release 버전

Keycloak

20.0 이상

2025.10 현재 연동가능

연동의 목적

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

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

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

  • 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/Roles 연동

연동 설정 방법

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

Step 1: Keycloak Realm 생성 및 설정

  1. Keycloak Admin Console (http://localhost:8080/admin) 에 접속하여 관리자 계정으로 로그인합니다.

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

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

    • Realm name: "genian-ztna-users" 입력

    • Enabled: 체크 상태 유지

    • Create 버튼을 클릭합니다.

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

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

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

    • User registration: 필요에 따라 설정 (CWP 사용자 등록 허용 시 활성화)

Step 2: Keycloak Client 생성 (CWP용)

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

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

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

    • Client type: "OpenID Connect" 선택

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

    • Name: "Genian ZTNA CWP" 입력

    • 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 예시: xyz987uvw654rst321opq098mno765lk

Step 3: Keycloak 사용자 및 그룹 설정

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

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

  3. 사용자 그룹 정보를 입력합니다.

    • Name: "ztna-users" 입력

    • Description: "ZTNA 일반 사용자 그룹" 입력

    • Create 버튼을 클릭합니다.

  4. 추가 권한 그룹을 생성합니다. (선택사항)

    • Name: "ztna-vip-users" 입력

    • Description: "ZTNA VIP 사용자 그룹" 입력

    • Create 버튼을 클릭합니다.

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

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

  7. 테스트 사용자 계정 정보를 입력합니다.

    • Username: "testuser" 입력

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

    • First name: "Test" 입력

    • Last name: "User" 입력

    • Email verified: 'On' 체크

    • Enabled: 'On' 체크

    • Create 버튼을 클릭합니다.

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

    • Set password 를 클릭합니다.

    • Password: 임시 비밀번호 입력

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

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

    • Save 버튼을 클릭합니다.

Step 4: Genian ZTNA OIDC 설정

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

    • Provider 이름 - "Keycloak" 입력

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

    • Client ID - "genian-ztna-cwp"

    • Client Secret - Keycloak의 Client secret

    • Scope - "openid profile email" 입력

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

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

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

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

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

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

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

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

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

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

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

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

주석

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

Step 5: Keycloak Client Mappers 설정 (그룹 정보 매핑)

CWP 사용자 권한 매핑을 위한 Groups 클레임 설정을 추가합니다.

  1. Keycloak Admin Console에서 생성한 Client("genian-ztna-cwp")를 선택합니다.

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

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

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

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

    • Name: "group membership" 입력

    • Token Claim Name: "groups" 입력

    • Full group path: 'Off' (그룹 이름만 포함)

    • Add to ID token: 'On' 체크

    • Add to access token: 'On' 체크

    • Add to userinfo: 'On' 체크

    • Save 버튼을 클릭합니다.

인증연동 테스트 방법

Genian ZTNA Web콘솔에서 테스트하는 방법 (SP-initiated SSO)

  1. Web콘솔에 접속하여 설정 > 사용자인증 > 인증연동 > 인증테스트 항목에 테스트 버튼을 클릭합니다.

  2. 팝업창에서 인증정보 저장소를 OIDC 를 선택합니다.

  3. Provider 선택 화면에서 설정한 "Keycloak" Provider를 선택합니다.

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

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

  6. '인증에 성공하였습니다.' 메시지가 표시되면 정상적으로 인증연동이 되었습니다.

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

  1. 노드정책의 인증정책의 인증방식을 OIDC 로 설정합니다.

  2. Genian ZTNA CWP페이지에 접속합니다.

  3. CWP페이지에 인증 버튼을 클릭합니다.

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

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

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

  7. 인증 성공 시 JWT ID Token과 Access Token을 받아 사용자 정보를 추출하고 ZTNA CWP에 로그인됩니다.

주석

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

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