.. _rest-api-guide:

REST API 활용 가이드
==============================================================================

가이드 개요
------------------------------------------------------------------------------
 Genian ZTNA는 타 장비 또는 타 시스템 등과의 연동을 위해 단말 정보의 제공, 정책/객체의 생성, 설정변경 등이 가능하도록 REST API를 제공합니다.

 본 가이드는 V5.0 기준으로 작성되었으며, Genian ZTNA의 REST API를 활용하기 위한 요구사항, 인증 방법, 주요 API 등에 대한 안내를 목적으로 합니다. 

 유튜브를 통해 REST API 활용 가이드 동영상을 확인할 수 있습니다. |youtube01-1| 
 
.. _rest-api-guide-preparation:

사전 준비사항
------------------------------------------------------------------------------
 **Genian ZTNA 활용 사전 준비사항**

   외부 장비에서 Genian ZTNA로 REST API를 호출하기 위해서 인증이 필요하며, 인증을 위한 API 인증방식을 'API Key' 또는 'API 서비스 계정' 방식 중에서 선택하고, 그 값을 생성합니다. 

   **API Key**
     - API Key방식은 연동을 위한 계정의 API키를 생성하여 Genian ZTNA의 API를 호출할 때 마다 API-Key를 첨부하여 활용하는 방식입니다.
     - 각 계정 별로 별도로 생성하여 활용이 가능합니다. 호출의 권한은 해당 계정의 권한에 종속됩니다.
     - 자세한 내용은 :ref:`API Key를 이용한 상호 인증 방법 <rest-api-guide-api-key-auth>` 을 참고하시기 바랍니다.

   **API 서비스 계정**
     - API 서비스계정을 활용하는 방식은 연동을 위한 별도의 계정을 생성하여 활용하는 방식입니다.
     - 호출 건 마다 API-Key를 첨부하여 활용하는 API-Key 방식과 달리 하나의 단위로 구현되어 API 서비스 계정으로 Genian ZTNA로 Log-in 후 기능을 수행합니다. 
     - 이 후 Log-off 절차까지 구현하는 방식으로 단순한 정보 확인 등을 위한 단편적인 기능 보다는 하나의 기능으로 구현하고자 할 때 유리한 방식입니다. 
     - API 서비스계정은 Web콘솔 접속용 계정으로는 활용할 수 없습니다.
     - 자세한 내용은 :ref:`API 서비스계정을 이용한 상호 인증 방법 <rest-api-guide-api-service-account-auth>` 을 참고하시기 바랍니다.

 **Networking 사전 준비사항**

   Genian ZTNA에서 제공하는 REST API는 https 프로토콜(TCP/8443)로 접속합니다.

   TCP/8443 포트는 Web콘솔 접속용 포트와 동일합니다. 따라서, 방화벽 등에서 Genian ZTNA Web콘솔 접속을 위한 설정이 적용된 상태라면, 추가 작업은 하지 않으셔도 됩니다. 

.. _rest-api-guide-auth:

API 활용을 위한 상호 인증 방법
------------------------------------------------------------------------------
 Genian ZTNA와 연동 대상 장비 간의 보안성이 확보된 상태에서 REST API를 활용하기 위해, 상호인증 수행이 우선 진행되어야 합니다.

 Genian ZTNA는 2가지의 인증 방식(API Key, API 서비스계정)을 제공하며, REST API를 활용하기 위해서는 Request URL 문이나 curl 명령이 필요합니다.

 curl 생성 및 테스트 방법은 :ref:`참고 - API 활용도구 제공: Swagger <rest-api-guide-swagger>` 를 참고하시기 바랍니다.
 
 .. note::
   - curl 을 통한 API 호출은 Ubuntu Terminal, Windows Command 등 에서 가능합니다.
   - curl 을 활용하여 API 호출 시, SSL 오류(신뢰되지 않은 인증서의 경우)가 발생하면 k 옵션(URL에 대한 SSL 검증을 하지 않도록 설정)을 추가하여 적용 하시기 바랍니다. (옵션 변경 : -X -> -kX)
   
     - 예시 : curl -X POST https://{정책서버IP}/mc2/rest/{API Path} **-->** curl -kX POST https://{정책서버IP}/mc2/rest/{API Path}

.. _rest-api-guide-api-key-auth:

API Key를 이용한 상호 인증 방법
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 API Key를 이용한 방법은 사전에 상호간 합의된 Key값을 통해 API를 호출하여 사용할 수 있습니다.

 API Key는 각 관리자 계정 별로 생성되며, 계정과 동일한 권한으로 API를 호출합니다.

 .. warning:: 
   - **API Key 유출 시, 시스템의 정보가 노출될 수 있으니 주의하시기 바랍니다. 또한 보안을 위해 주기적으로 변경하는 것을 권장드립니다.**

 **1단계. API Key 생성**
   #. Genian ZTNA Web콘솔 접속 후 **관리 > 사용자** 메뉴 클릭
   #. API Key를 사용할 **관리자 계정** 클릭 
   #. **기본정보 > 로그인 설정 > API 키** 항목으로 이동
   #. **신규 키 생성** 버튼을 클릭하여 해당 계정의 API Key 생성

 **2단계. API Key를 활용한 인증**
   #. 사용하려는 curl에서 API Path가 끝나는 부분에 **?apiKey={003def2d-4326-4a40-8372-e7806ce5950f}** 와 같이 생성했던 API Key 입력
   #. curl을 활용하여 API 호출 테스트 진행
     
     - curl 예시
     
       .. code-block:: bash

         curl -kX POST "https://192.168.100.253:8443/mc2/rest/nodes?apiKey={003def2d-4326-4a40-8372-e7806ce5950f}" 
         -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8" 
         -d "[ { \"nl_ipstr\": \"100.100.100.101\", \"nl_mac\": \"00:00:00:00:00:00\", \"nl_sensornid\": \"\", \"nl_genidev\": 0, \"doNotDeleteNode\": true }]"

 .. note::
   - REST API는 Request URL과 Get Parameter부분을 구분하기 위해 **"?"** 구분자를 사용합니다. Request URL이 끝난 부분 이후 구분자를 2개 이상 사용하게 되면 정상적으로 인식 되지 않습니다.
   - REST API 사용 시 Get Parameter 에 다른 Parameter 값이 존재할 때, 값이 끝나는 부분에 **"&"** 를 이용하여 apiKey를 추가하면 정상적으로 동작됩니다.

     - 예시 : curl -kX GET "https://192.168.100.253:8443/mc2/rest/tags?page=1&pageSize=30&apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"

.. _rest-api-guide-api-service-account-auth:

API 서비스계정을 이용한 상호 인증 방법
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 API 서비스계정을 이용한 인증방법은 API를 활용하기 위한 전용 계정을 추가하여 사용하는 방법입니다.

 **1단계. 서비스역할 생성**
   #. 서비스역할 생성 방법은 시스템 보안과 관련하여 별도의 관리가 필요하므로, **API 서비스역할(권한)** 생성을 요청해 주시면, 기술지원 담당자가 별도로 안내해 드리도록 하겠습니다. 

 **2단계. API 서비스를 위한 계정에 서비스 역할 부여**
   #. Genian ZTNA Web콘솔 접속 후 **관리 > 사용자** 메뉴 클릭
   #. API 서비스계정으로 사용할 **계정** 클릭
   #. **기본정보 > 기본설정 > 관리역할** 항목으로 이동
   #. 생성 요청을 통해 만들어 두었던 **API 서비스역할** 권한 부여

 **3단계. IP 패턴 또는 URL 패턴 설정**
   #. **API 서비스역할** 권한을 부여한 **계정** 클릭
   #. **기본정보 > 관리역할별 설정 > 신뢰연결 설정** 항목으로 이동
   #. API 호출을 허용할 **IP** 또는 **URL** 에 대해 패턴 설정

   .. warning:: 
     - 보안상의 문제가 발생할 수 있으므로, IP 패턴 설정 시 **Subnet과 Range 설정은 불가합니다.**

 **4단계. API 서비스계정을 활용한 인증**
   #. curl을 활용하여 API 호출 테스트 진행 (API 서비스계정은 **API Key 없이 호출이 가능합니다.** )
   
     - curl 예시

       .. code-block:: bash

         curl -kX POST "https://192.168.100.253:8443/mc2/rest/nodes" 
         -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8" 
         -d "[ { \"nl_ipstr\": \"100.100.100.102\", \"nl_mac\": \"11:11:11:11:11:11\", \"nl_sensornid\": \"\", \"nl_genidev\": 0, \"doNotDeleteNode\": true }]"

.. _rest-api-guide-main-api-list:

주요 API
------------------------------------------------------------------------------
 Genian ZTNA와 연동을 위한 주요 API 항목은 NODES, TAGS, USERS, LOGS, NODEGROUPS, CVES 등이 있고, 각각의 내용은 다음과 같습니다.

 **NODES API**

   Genian ZTNA에서 노드(Node)란 IP 와 MAC 을 갖고 있는 장비 또는 엔드포인트를 말합니다. 

   노드는 ZTNA에서 관리하는 네트워크 대역대에 접속하거나 노드에 설치된 에이전트에 의해 자동으로 등록됩니다.

   노드와 관련한 주요 API는 다음과 같습니다.

   .. csv-table::
     :header: "Description", "Type", "API Path", "주요 목적"
     :class: longtable
     :widths: 20 5 15 60

     "전체 노드 목록 및 정보 조회", "GET", "/nodes", "특정 노드의 정보 조회 및 태그 할당, 제거를 수행하기 위해서 노드의 ip 및 nodeId를 얻기 위한 목적으로 전체 노드 목록 및 정보를 조회합니다."
     "특정 IP의 노드 정보 조회", "GET", "/nodes/{ip}/managementscope", "특정 노드에 태그 할당 및 제거를 위해 전달받은 특정 IP에 대해서 nodeId값을 얻기 위한 목적으로 사용됩니다."
     "특정 노드에 태그 할당", "POST", "/nodes/{nodeId}/tags", "위협노드로 판단되는 특정노드에 차단 태그를 할당하여 네트워크 격리를 수행하기 위한 목적으로 사용됩니다."
     "특정 노드에 태그 해제", "DELETE", "/nodes/{nodeId}/tags", "안전하다고 판단되는 특정노드에 차단 태그를 제거하여 네트워크 진입을 허용하기 위한 목적으로 사용됩니다."
     "특정 노드의 상세 정보 조회", "GET", "/nodes/{nodeId}/information/{catgry}", "포트 관리를 위해 특정 노드의 열린 포트 목록을 얻기 위한 목적으로 사용됩니다."

   - 전체 노드 목록 및 정보 조회 예시

     .. code:: bash

       curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodes?page=1&pageSize=30&view=node&nid=All
       &apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"

   - 특정 IP의 노드 정보 조회 예시

     .. code:: bash

       curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodes/192.168.100.200/managementscope
       ?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"

   - 특정 노드에 태그 할당 예시

     .. code:: bash

       curl -kX POST "https://192.168.100.100:8443/mc2/rest/nodes/974bc18c-2cf9-103a-8002-2cf05d0cf498-c0649e1c
       /tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8" 
       -H "Content-Type: application/json;charset=UTF-8" -d "[ { \"id\": \"\", \"name\": \"test_tag\", 
       \"description\": \"\", \"startDate\": \"\", \"expireDate\": \"\", \"periodType\": \"\", \"expiryPeriod\": \"\" }]

   - 특정 노드에 태그 해제 예시

     .. code:: bash

       curl -kX DELETE "https://192.168.100.100:8443/mc2/rest/nodes/974bc18c-2cf9-103a-8002-2cf05d0cf498-c0649e1c
       /tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8" 
       -H "Content-Type: application/json;charset=UTF-8" -d "[ \"5\"]"

   - 특정 노드의 상세 정보 조회 예시

     .. code:: bash

       curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodes/974bc18c-2cf9-103a-8002-2cf05d0cf498-c0649e1c
       /information/CAT_NETINFO?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"

 **TAGS API**

   Genian ZTNA는 노드/사용자를 분류할 때 태그(Tag)를 사용할 수 있습니다. (디폴트 Tag로는 TRUSTED, THREAT, GUEST가 있고, 수정 및 추가가 가능합니다.)

   외부장비에서 연동으로 ZTNA 제어정책 적용 시 노드그룹을 구분하기 위해 Tag가 사용됩니다.

   태그와 관련한 주요 API는 다음과 같습니다.

   .. csv-table::
     :header: "Description", "Type", "API Path", "주요 목적"
     :class: longtable
     :widths: 15 5 10 70

     "태그 목록 조회", "GET", "/tags", "노드, 사용자ID에 태그 할당 및 제거를 수행하기 위해 태그의 id값 혹은 name 정보를 얻기 위한 목적으로 태그의 정보를 조회합니다."
     "태그 생성", "POST", "/tags", "관리자가 노드 혹은 사용자ID에 부여하려는 태그 항목이 Genian ZTNA에 존재하지 않을 시 태그 생성을 위한 목적으로 사용됩니다."

   - 태그 목록 조회 예시

     .. code:: bash

       curl -kX GET "https://192.168.100.100:8443/mc2/rest/tags?page=1&pageSize=30&apiKey={912fae69-b454-4608-bf4b-fa142353b463}" 
       -H "accept: application/json;charset=UTF-8"

   - 태그 생성 예시

     .. code:: bash

       curl -kX POST "https://192.168.100.100:8443/mc2/rest/tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" 
       -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8" 
       -d "{ \"np_idx\": 0, \"np_name\": \"test_tag\", \"np_desc\": \"테스트 태그\", \"np_periodtype\": 0, 
       \"np_period\": \"\", \"np_periodexpire\": \"\", \"np_adminroles\": \"\", \"np_color\": \"\", \"np_static\": 0}"

 **USERS API**

   Genian ZTNA의 사용자(User)는 관리자가 생성하거나 DB 동기화 등을 통하여 생성된 사용자 및 부서정보를 의미합니다.

   사용자와 관련한 주요 API는 다음과 같습니다.

   .. csv-table::
     :header: "Description", "Type", "API Path", "주요 목적"
     :class: longtable
     :widths: 20 5 15 60

     "특정 사용자ID에 적용된 태그 목록 조회", "GET", "/users/{userId}/tags", "특정 사용자ID에 적용된 태그의 목록을 조회하여 태그 할당 및 제거하기 위한 목적으로 tagid값 혹은 name 정보를 조회합니다."
     "특정 사용자ID에 태그 할당", "POST", "/users/{userId}/tags", "인가되지 않은 특정 사용자ID에 차단 태그를 할당하여 네트워크 격리를 수행하기 위한 목적으로 사용됩니다."
     "특정 사용자ID에 태그 해제", "DELETE", "/users/{userId}/tags", "인가된 특정 사용자ID에 차단 태그를 제거하여 네트워크 진입을 허용하기 위한 목적으로 사용됩니다."

   - 특정 사용자ID에 적용된 태그 목록 조회 예시

     .. code:: bash

       curl -kX GET "https://192.168.100.100:8443/mc2/rest/users/test1/tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" 
       -H "accept: application/json;charset=UTF-8"

   - 특정 사용자ID에 태그 할당 예시

     .. code:: bash

       curl -kX POST "https://192.168.100.100:8443/mc2/rest/users/test1/tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" 
       -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8" 
       -d "[ { \"id\": \"\", \"name\": \"test_tag\", \"description\": \"\", \"startDate\": \"\", 
       \"expireDate\": \"\", \"periodType\": \"\", \"expiryPeriod\": \"\" }]"

   - 특정 사용자ID에 태그 해제 예시

     .. code:: bash

       curl -kX DELETE "https://192.168.100.100:8443/mc2/rest/users/test1/tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" 
       -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8" -d "[ \"5\"]

 **LOGS API**

   Genian ZTNA에서 감사로그란 시스템, 장비 등에서 발생하는 이벤트에 대한 모든 로그를 뜻하며, 자체적으로 로그서버에 저장합니다.

   로그와 관련한 주요 API는 다음과 같습니다.

   .. csv-table::
     :header: "Description", "Type", "API Path", "주요 목적"
     :class: longtable
     :widths: 15 5 10 70

     "감사로그 조회", "GET", "/logs", "대시보드 및 이벤트 현황 작성에 활용하기 위한 목적으로 Genian ZTNA의 감사로그를 조회합니다."

   - 감사로그 조회 예시

     .. code:: bash

       curl -kX GET "https://192.168.100.100:8443/mc2/rest/logs?page=1&pageSize=30&logschema=auditlog&periodType=custom
       &apiKey={912fae69-b454-4608-bf4bfa142353b463}"-H "accept: application/json;charset=UTF-8"

 **NODEGROUPS API**

   Genian ZTNA의 정책(Policy)은 노드정책과 제어정책으로 구분되며 정책적용을 위해서는 노드그룹이 필요합니다. 

   노드그룹과 관련한 주요 API는 다음과 같습니다.

   .. csv-table::
     :header: "Description", "Type", "API Path", "주요 목적"
     :class: longtable
     :widths: 15 5 10 70

     "노드그룹 목록 조회", "GET", "/nodegroups", "대시보드 및 보안 운영 보고서 작성에 활용하기 위한 목적으로 Genian ZTNA에 생성되어 있는 노드그룹 목록을 조회합니다."

   - 노드그룹 목록 조회 예시

     .. code:: bash

       curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodegroups?page=1&pageSize=30&
       apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"

 **CVES API**

   Genian ZTNA는 각 노드별로 공개적으로 알려진 정보 보안 취약성 및 노출에 대한 정보를 제공합니다.

   CVES와 관련한 주요 API는 다음과 같습니다. 

   .. csv-table::
     :header: "Description", "Type", "API Path", "주요 목적"
     :class: longtable
     :widths: 15 5 10 70
     
     "노드의 CVE 내역 조회", "GET", "/cves", "위험노드에 네트워크 격리를 수행하기 위한 목적으로 Genian ZTNA에서 노드의 CVE 내역을 조회합니다."

   - 노드의 CVE 내역 조회 예시

     .. code:: bash

       curl -kX GET "https://192.168.100.100:8443/mc2/rest/cves?page=1&pageSize=30
       &apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"

.. _rest-api-guide-responses-code:

RESPONSES CODE
------------------------------------------------------------------------------
 아래 표는 REST API에서 사용하는 HTTP Status Codes를 나타냅니다.

 .. csv-table::
   :header: "Code", "Descriptions", "Detailed Descriptions"
   :class: longtable
   :widths: 10 20 70

   "200", "Successful operation", "요청 정상 처리"
   "206", "Partial Content", "Range가 지정된 요청인 경우, 지정된 범위만큼의 요청을 받았다는 것을 알려줌."
   "400", "Bad Request", "클라이언트의 요청 구문이 잘못됨"
   "401", "Unauthorized", "요청 처리를 위해 HTTP 인증 정보가 필요함을 알려줌. 접근 허용을 차단함."
   "403", "Forbidden", "접근 금지 응답. Directory Listing 요청 및 Web콘솔 접근 등을 차단하는 경우의 응답"
   "404", "Not Found", "클라이언트가 요청한 리소스가 서버에 없음. 요청한 URL을 찾을 수 없음을 의미"
   "406", "Not Acceptable", "클라이언트 요청에 대해 적절한 컨텐츠가 없음을 의미"
   "412", "Precondition Failed", "클라이언트의 헤더에 있는 전제조건은 서버의 전제조건에 적절하지 않다고 알려줌"
   "416", "Range Not Satisfiable", "Range 헤더 필드에 요청한 지정 범위를 만족시킬 수 없습니다."
   "500", "Internal Server Error", "서버에서 클라이언트 요청을 처리 중에 에러가 발생함"

.. _rest-api-guide-swagger:

참고 - API 활용도구 제공: Swagger
------------------------------------------------------------------------------
 Genian ZTNA는 API를 활용하는데 도움을 드리고자, Swagger(http://swagger.io/)를 제공합니다.

 Swagger는 웹페이지를 통해서 REST API 정보와 테스트 도구를 제공합니다.

 **1단계. Swagger 접속**
   #. Genian ZTNA의 관리자 계정으로 Web콘솔 1차 접속
   #. 로그인이 된 상태에서 주소창에 **https://{정책서버IP}:8443/mc2/swagger/index.html** 을 입력하여 2차 접속
   #. Swagger 접속 확인

 **2단계. Swagger를 이용한 테스트**
   #. 활용하고자 하는 API를 선택한 후, 해당 API의 창 우측에 **Try It out** 버튼 클릭
   #. Parameters 항목에서 **Description** 값 및 Body 의 **Example Value** 값 입력
   #. 아래의 **Execute** 버튼 클릭
   #. Responses 항목에서 **curl** 및 **Request URL** 값 확인 (Server response 항목에서 Code값이 **200** 일때 정상동작 됩니다.)

 .. note::
   - Content Type은 JSON을 사용하며 'application/json;charset=UTF-8'을 표준으로 합니다. (포맷이 다른 경우, 폰트가 손상되어 보일 수 있습니다.)




.. |youtube01-1| image:: /images/youtube.png
  :target: https://www.youtube.com/watch?v=mRrNlaiUlqs&t=422s
  :width: 30px