.. _restapiserver: REST API Server ======================= Genian ZTNA는 REST API Server를 사용자 및 조직 정보의 소스로 사용할 수 있습니다. REST API Server 동기화를 통해 사용자 계정을 로컬에서 생성하여 관리 또는 정책에 사용 할 수 있습니다. REST API Server 요청은 HTTP GET 방식을 사용하여 호출하며, 응답데이터형식은 JSON Object 형식이어야 합니다. slack 에서 사용자정보는 users.list API를 통해서 가져올 수 있습니다. Method URL 은 https://slack.com/api/users.list 이며 요청은 GET 과 POST 방식을 지원합니다. ZTNA 에서 REST API 정보는 Swagger를 통해 제공합니다. :ref:`참고 - API 활용도구 제공: Swagger ` REST API 의 상세 내용은 :ref:`API 가이드 ` 를 통해 확인할 수 있습니다. 접속 테스트 하기 ---------------------- 접속 테스트를 수행하기 위해서는 다음에 기본값이 입력되어야 합니다. +--------------------+---------------------------------+--------------------------------------------------------+ | 항목 | 설정값 | 설명 | +====================+=================================+========================================================+ | REST API Server | 서버주소 | REST API를 호출할 서버 IP를 입력합니다. | + +---------------------------------+--------------------------------------------------------+ | | 페이지 파라미터 이름 | 다수의 출력값을 처리할 페이지 파라미터 이름을 | + + +--------------------------------------------------------+ | | | 설정합니다. | + +---------------------------------+--------------------------------------------------------+ | | 페이지 시작번호 | 페이지 시작번호를 설정합니다. | + +---------------------------------+--------------------------------------------------------+ | | 페이지 사이즈 파라미터 이름 | 한 페이지에 출력할 갯수를 지정하는 파라미터 이름을 | + + +--------------------------------------------------------+ | | | 설정합니다. | + +---------------------------------+--------------------------------------------------------+ | | 페이지 사이즈 | 한 페이지에 출력할 갯수를 설정합니다. | + +---------------------------------+--------------------------------------------------------+ | | 데이터소스 구분값 | 다수의 동기화 서버 사용 시 설정합니다. | +--------------------+---------------------------------+--------------------------------------------------------+ .. note:: 접속 테스트가 정상적으로 되지 않을 경우 **정책서버** 와 **동기화 서버** 간 정상적인 통신 여부를 우선적으로 확인하시기 바랍니다. 동기화 설정하기 ------------------------ #. 상단 항목의 **설정** 으로 이동합니다. #. 왼쪽 설정 항목에서 **사용자인증 > 정보 동기화** 로 이동합니다. #. **작업선택 > 생성** 을 클릭합니다. #. **ID** : 고유의 이름을 입력합니다. #. **동기화 수행주기** : 동기화에 대해 지정된 시간 또는주기적인 간격을 선택합니다. #. **정책적용여부** : 동기화 후 변경사항 반영을 위해 ``적용함`` 을 선택합니다 . 동기화 설정이 여러 개인 경우 ``적용안함`` 으로 설정하고 마지막 동기화만 사용하도록 설정 할 수 있습니다. #. **환경변수 설정** : 기본적인 동기화 작업 시에는 입력할 필요가 없습니다. 단, 외부 시스템과의 연동 등을 위해 별도로 작성된 커스텀 쉘 스크립트를 보조로 실행하는 경우, 해당 스크립트 내에서 공통적으로 참조할 변수 값을 정의할 때 사용합니다. .. warning:: **설정 주의**: 잘못된 환경변수 선언은 연동 스크립트의 오작동이나 시스템 오류를 유발할 수 있습니다. 설정 전에 스크립트 내에서 해당 변수가 올바르게 처리되는지 반드시 확인하십시오. **활용 시나리오: 로그 레벨 제어** 외부 스크립트 실행 시 **로그 레벨(Log Level)** 이나 **재시도 횟수** 등 단순 동작 옵션을 제어할 수 있는 경우 사용합니다. .. code-block:: bash export LOG_LEVEL='ERROR' #. **사용자정의쿼리** : 정보 동기화가 완료된 직후 수행할 SQL 쿼리를 입력합니다. 동기화된 정보를 바탕으로 특정 조건에 따라 2차 가공이 필요한 경우 작성합니다. .. warning:: **데이터 손실 위험**: 이 기능은 데이터베이스에 직접 영향을 미칩니다. 특히 ``UPDATE`` 나 ``DELETE`` 구문 사용 시 **되돌릴 수 없는 데이터 손실** 이 발생할 수 있습니다. **활용 시나리오: 재직 상태에 따른 계정 잠금 처리** 정보 동기화 후, 인사 정보의 '재직 상태' 코드에 따라 퇴사자(또는 휴직자)의 NAC 계정 사용을 자동으로 중지하고 싶은 경우 사용합니다. **선행 작업** 1. **[설정] > [속성관리] > [추가필드] > [사용자 추가필드]** 에서 재직상태를 관리할 필드(예: ``USER_CUSTOM08``)를 생성합니다. 2. **[정보동기화]** 의 **[사용자정보]** - **[추가정보]** 에 1번에서 생성한 사용자 추가필드를 할당합니다. **작성 예시** ``USER_CUSTOM08`` 값이 '001'(퇴사/휴직 등)인 경우, ``USER_STATUS`` 를 '0'(사용 중지)으로 업데이트합니다. .. code-block:: sql UPDATE USER SET USER_STATUS = 0 WHERE USER_CUSTOM08 = '001'; **데이터베이스** 옵션 * DB타입은 REST API Server 를 선택하고, 사용하고 있는 서버주소를 입력합니다. * 예) slack의 경우 https://slack.com, ZTNA의 경우 https://(정책서버IP):8443 * 페이징은 지원하지 않으므로 페이징관련 설정은 입력하지 않습니다. #. **DB타입** : ``REST API Server`` #. **서버주소** : REST API Server의 주소를 입력합니다. #. **페이지 파라미터이름** : 서버측 페이징을 통해서 정보를 가져오는 경우 페이지번호를 의미하는 파라미터 이름을 입력합니다. #. **페이지 시작번호**: 서버측 페이징을 통해서 정보를 가져오는 경우 페이지 시작번호를 입력합니다. #. **페이지사이즈 파라미터이름** : 서버측 페이징을 통해서 정보를 가져오는 경우 페이지당 가져오는 데이터수를 의미하는 파라미터 이름을 입력합니다. #. **페이지사이즈** : 서버측 페이징을 통해서 정보를 가져오는 경우 페이지당 가져오는 데이터수를 입력합니다. #. **데이터소스 구분값** : 데이터소스 구분값은 동기화 한 사용자 정보의 출처 식별을 위한 값입니다. **사용자정보** 옵션 * 사용자정보출처를 입력할 때 상호인증을 API Key를 활용 한다면 /api/users.list?token= 를 입력하거나, API 서비스 계정을 활용 한다면 /api/users.list 만 입력합니다. 자세한 내용은 :ref:`API 활용을 위한 상호 인증 방법 ` 을 참고하시기 바랍니다. * 컬럼명은 JSON Object에서 값을 추출하기 위한 경로를 입력합니다. 경로는 . 으로 구분합니다. * 예) JSON Response [ { "id": "..", "name": ".." }, { "id": "..", "name": ".." } ] 인 경우에 ID컬럼명은 id, 이름컬럼명은 name 을 입력합니다. * 예) JSON Response { "users": { "members" : [ { "id": "..", "name": ".." }, { "id": "..", "name": ".." } ] } } 인 경우에 ID컬럼명은 users.members.id, 이름컬럼명은 users.members.name 을 입력합니다. #. **사용자정보출처** : 사용자정보동기화를 위한 URI 정보를 입력합니다. 입력된 URI설정은 서버주소 뒤에 경로명으로 추가됩니다.(예. /api/users.list 를 입력한 경우에 https://slack.com/api/users.list 를 호출합니다.) #. **사용자조건문** : 사용안함. #. **사용자ID컬럼명** : JSON Object에서 사용자 ID 값의 경로를 입력합니다.(예. users.id) #. **사용자이름컬럼명** : JSON Object에서 이름 값의 경로를 입력합니다.(예. users.name) #. **부서ID컬럼명** : JSON Object에서 부서 ID 값의 경로를 입력합니다.(예. users.department_id) #. 기타 추가 정보는 JSON Object에서 값의 경로를 입력합니다. .. attention:: 그외 부서, 직급, 노드, 장비수명 정보 옵션 설정은 사용자정보 옵션과 동일한 방식으로 설정 사용할 수 있습니다.