.. _oidc-keycloak: Keycloak (OIDC) - CWP ====================== 본 가이드는 Keycloak 와 네트워크 접근제어 시스템인 Genian NAC의 인증연동 기능을 수행하기 위한 설정 방법을 안내합니다. 개요 ------ Genian NAC와 Keycloak 솔루션의 OIDC APP 연동을 통하여 Genian NAC 자체 사용자DB를 관리할 필요가 없이 Keycloak을 통해 사용자 인증을 수행할 수 있습니다. 사용자 인증을 위해 Genian NAC CWP 페이지에서 OIDC (OpenID Connect) 프로토콜을 이용하여 Keycloak 인증을 호출하고 Keycloak에서 사용자 인증 여부를 확인하여 정상적인 SSO가 이루어집니다. 권장버전 ---------- .. csv-table:: :header: 제품명(구성요소),버전,비고 :class: longtable :widths: 30 30 40 Genian NAC(정책서버),V5.0 이상,2025.10 이후 Release 버전 Keycloak,20.0 이상,2025.10 현재 연동가능 연동의 목적 -------------- Genian NAC와 Keycloak 연동은 다음의 효과를 제공합니다. - NAC, Keycloak 개별 인증을 위한 사용자 DB 관리가 필요하지 않습니다. - Keycloak 계정을 이용하여 SSO로 NAC를 인증할 수 있습니다. - 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 NAC와 Keycloak 설정 방법은 연동을 위한 필수 항목만을 안내합니다. 최초 1회 설정 이후 자동으로 적용됩니다. Step 1: Keycloak Realm 생성 및 설정 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Keycloak Admin Console (http://localhost:8080/admin) 에 접속하여 관리자 계정으로 로그인합니다. #. 좌측 메뉴에서 **Realm 선택** 드롭다운을 클릭하고 **Create realm** 을 선택합니다. #. Realm 생성 정보를 입력합니다. - **Realm name**: "genian-NAC-users" 입력 - **Enabled**: 체크 상태 유지 - **Create** 버튼을 클릭합니다. #. 생성된 Realm이 선택된 상태에서 좌측 메뉴의 **Realm settings** 를 클릭합니다. #. **General** 탭에서 Realm 기본 설정을 확인합니다. - **Require SSL**: "External requests" 또는 "All requests" 선택 (HTTPS 환경 권장) - **User registration**: 필요에 따라 설정 (CWP 사용자 등록 허용 시 활성화) Step 2: Keycloak Client 생성 (CWP용) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. 좌측 메뉴에서 **Clients** 를 클릭합니다. #. **Create client** 버튼을 클릭합니다. #. **General settings** 에서 다음을 입력합니다. - **Client type**: "OpenID Connect" 선택 - **Client ID**: "genian-NAC-cwp" 입력 - **Name**: "Genian NAC CWP" 입력 - **Description**: "Genian NAC 사용자 포털 OIDC 연동" 입력 - **Next** 버튼을 클릭합니다. #. **Capability config** 에서 다음을 설정합니다. - **Client authentication**: 'On' 체크 (Confidential client) - **Authorization**: 'Off' (일반적으로 불필요) - **Standard flow**: 'On' 체크 (Authorization Code Flow) - **Direct access grants**: 'Off' (보안상 권장) - **Next** 버튼을 클릭합니다. #. **Login settings** 에서 다음을 입력합니다. - **Root URL**: https://test.genians.net (NAC 서버 도메인) - **Home URL**: /cwp2/ - **Valid redirect URIs**: - https://test.genians.net/cwp2/faces/oidc/oidcCallback.xhtml - **Web origins**: https://test.genians.net - **Save** 버튼을 클릭합니다. #. 생성된 Client의 **Credentials** 탭에서 **Client secret** 를 복사합니다. - **Client secret** 예시: xyz987uvw654rst321opq098mno765lk Step 3: Keycloak 사용자 및 그룹 설정 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. 좌측 메뉴에서 **Groups** 를 클릭합니다. #. **Create group** 버튼을 클릭합니다. #. 사용자 그룹 정보를 입력합니다. - **Name**: "NAC-users" 입력 - **Description**: "NAC 일반 사용자 그룹" 입력 - **Create** 버튼을 클릭합니다. #. 추가 권한 그룹을 생성합니다. (선택사항) - **Name**: "NAC-vip-users" 입력 - **Description**: "NAC VIP 사용자 그룹" 입력 - **Create** 버튼을 클릭합니다. #. 좌측 메뉴에서 **Users** 를 클릭합니다. #. **Create new user** 버튼을 클릭합니다. #. 테스트 사용자 계정 정보를 입력합니다. - **Username**: "testuser" 입력 - **Email**: "testuser@company.com" 입력 - **First name**: "Test" 입력 - **Last name**: "User" 입력 - **Email verified**: 'On' 체크 - **Enabled**: 'On' 체크 - **Create** 버튼을 클릭합니다. #. 생성된 사용자의 **Credentials** 탭으로 이동합니다. - **Set password** 를 클릭합니다. - **Password**: 임시 비밀번호 입력 - **Password confirmation**: 동일한 비밀번호 재입력 - **Temporary**: 'Off' (사용자가 직접 변경하지 않도록) - **Save** 버튼을 클릭합니다. Step 4: Genian NAC OIDC 설정 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Genian NAC **Web콘솔 > 설정 > 사용자인증 > 인증연동 > OIDC 인증연동** 에 다음 각 항목의 값을 Keycloak에서 복사해서 입력하십시오. - **Provider 이름** - "Keycloak" 입력 - **Issuer** - https://{keycloak-server}/realms/{realm name} - **Client ID** - "genian-NAC-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 #. JIT provisioning 기능을 사용할려면 NAC에서 **JIT provisioning** 을 'On'으로 변경하십시오. - NAC UI의 **JIT provisioning > 추가정보** 에서 추가 버튼을 클릭해서 사용자 계정의 이름, 이메일을 설정하십시오. - 이름에 **{given_name} {family_name}** 입력하십시오. - 이메일에 **email** 을 입력하십시오. - OIDC Claims (given_name, family_name, email) 항목은 Keycloak에 이미 표준으로 정의되어 있습니다. #. Genian NAC CWP 인증 화면에서 표시할 Keycloak 인증버튼에 표시할 문구를 **로그인 버튼 문구** 에 입력합니다. - 예시: "Keycloak으로 로그인", "Sign in with Keycloak" #. Genian NAC Web 콘솔 설정 화면 하단 **수정** 버튼을 클릭합니다. .. note:: Client ID와 Client Secret이 올바르게 입력되었는지 확인하세요. 또한 Keycloak 서버의 Issuer URL이 NAC에서 접근 가능한지 확인하십시오. Step 5: Keycloak Client Mappers 설정 (그룹 정보 매핑) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CWP 사용자 권한 매핑을 위한 Groups 클레임 설정을 추가합니다. #. Keycloak Admin Console에서 생성한 Client("genian-NAC-cwp")를 선택합니다. #. **Client scopes** 탭으로 이동합니다. #. **genian-NAC-cwp-dedicated** 를 클릭합니다. #. **Mappers** 탭에서 **Add mapper** > **By configuration** 을 클릭합니다. #. **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 NAC Web콘솔에서 테스트하는 방법 (SP-initiated SSO)** #. Web콘솔에 접속하여 **설정 > 사용자인증 > 인증연동 > 인증테스트** 항목에 **테스트** 버튼을 클릭합니다. #. 팝업창에서 인증정보 저장소를 **OIDC** 를 선택합니다. #. Provider 선택 화면에서 설정한 "Keycloak" Provider를 선택합니다. #. 새로운 팝업창에 Keycloak 인증페이지가 표시됩니다. #. Keycloak 사용자명, 암호를 입력하여 인증합니다. #. '인증에 성공하였습니다.' 메시지가 표시되면 정상적으로 인증연동이 되었습니다. **Genian NAC CWP 페이지에서 테스트하는 방법 (SP-initiated SSO)** #. 노드정책의 인증정책의 인증방식을 **OIDC** 로 설정합니다. #. Genian NAC CWP페이지에 접속합니다. #. CWP페이지에 **인증** 버튼을 클릭합니다. #. 인증 화면에 위 Step4에서 설정한 인증버튼("Keycloak으로 로그인")을 클릭합니다. #. 새로운 팝업창에 Keycloak 인증페이지가 표시됩니다. #. Keycloak 사용자명, 암호를 입력하여 인증합니다. #. 인증 성공 시 JWT ID Token과 Access Token을 받아 사용자 정보를 추출하고 NAC CWP에 로그인됩니다. .. note:: 인증연동 설정 후 정책적용시 제어정책 권한에 Keycloak IdP 도메인을 추가해주어야 차단상태에서도 인증연동 창이 표시됩니다. .. code:: bash 1. 권한 추가 방법 2. 정책 > 객체 > 네트워크 3. 작업선택 > 생성 4. 기본정보 입력 5. 네트워크주소 > FQDN 선택 > IdP 도메인 입력 - keycloak-server (내부 도메인) - your-keycloak.company.com (외부 도메인) 6. 생성 클릭 7. 권한 메뉴로 이동 8. 생성한 네트워크객체를 이용하여 권한 생성 9. 단말 네트워크를 제어하는 제어정책에 생성한 권한 할당