목차/05. API로 관리

05API로 관리API로 관리

SmartConsole에서 마우스로 손수 하는 일은 거의 모두 API로 자동화 할 수 있습니다. 이 장은 관리 서버에서 도는 API Server 가 무엇인지, 그것을 다루는 도구에는 어떤 것이 있는지, API Server를 어떻게 켜고 접속 범위를 정하는지, 그리고 사용자명·암호 대신 쓰는 API 키 인증 을 어떻게 만들어 활용하는지를 원문 그대로 빠짐없이 풀어 정리합니다.

API Server란 무엇인가

관리 서버에는 API Server 가 돌고 있습니다. 여러분이 API Server로 API 요청(API Request) 을 보내면, 그 요청에 따라 관리 서버를 구성하고 제어 할 수 있습니다. SmartConsole 화면에서 누르던 작업을 명령이나 스크립트로 대신 시키는 셈입니다.

API Server가 진짜 힘을 발휘하는 곳은 자동화와 연동입니다. API Server는 일상 작업을 자동화하는 스크립트 를 실행하고, Check Point 솔루션을 서드파티 시스템과 연동 합니다. 대표적인 연동 대상은 다음과 같습니다.

가상화 서버(virtualization servers)
티켓팅 시스템(ticketing systems)
변경 관리 시스템(change management systems)

관리 API를 더 깊이 배우고 싶거나, 코드 샘플을 보거나, 사용자 포럼을 활용하려면 다음을 참고하세요.

API 문서(API Documentation)
- 온라인 — Check Point Management API Reference
- 로컬 — https://<Server IP Address>/api_docs
CheckMates 커뮤니티의 Developers Network 섹션

로컬 API 문서는 기본적으로 접속이 비활성화 되어 있습니다. 켜는 방법은 sk174606을 따르세요.

API를 다루는 세 가지 도구

API Server를 다루는 도구는 세 가지가 있습니다. 어디서 실행하느냐, 무엇으로 통신하느냐가 다릅니다.

도구	어디에 포함	설명
`mgmt_cli`	Gaia 운영체제	관리 서버 자체에서 쓰는 독립 실행형(standalone) 관리 도구입니다.
`mgmt_cli.exe`	SmartConsole	Windows용 독립 실행형 도구입니다. SmartConsole 설치 폴더에서 다른 Windows PC로 복사 해 쓸 수 있습니다.
Web Services API	(HTTP/HTTPS)	클라이언트와 관리 서버가 HTTP 프로토콜 로 통신·데이터 교환하게 해 줍니다. 다른 Check Point 프로세스도 이 경로로 HTTPS 를 통해 관리 서버와 통신합니다.

Web Services API는 다음 형태의 주소로 호출합니다.

https://<IP Address of Management Server>/web_api/<command>

API Server 구성하기

API Server를 쓰려면 먼저 SmartConsole에서 켜고, 어떤 클라이언트가 접속할 수 있는지 정한 뒤, 관리자 권한을 확인하고 서버를 재시작합니다. 순서대로 따라가 보겠습니다.

SmartConsole로 접속 — Security Management Server 또는 해당 Domain Management Server에 SmartConsole로 붙습니다(SmartConsole 이해).
왼쪽 탐색 패널에서 Manage & Settings 를 누릅니다.
왼쪽 위 영역에서 Blades 를 누릅니다.
Management API 섹션에서 Advanced Settings 를 누릅니다. 그러면 Management API Settings 창이 열립니다.
Startup Settings(시작 설정)와 Access Settings(접속 설정)를 구성합니다.

각 설정을 자세히 보겠습니다.

Startup Settings — 자동 시작 설정

Automatic start 를 고르면, 관리 서버를 켜거나 재부팅할 때 API Server가 자동으로 시작 됩니다. 이 옵션의 기본값은 설치된 RAM 용량에 따라 갈립니다.

관리 서버에 RAM이 4GB를 초과 해 설치되어 있으면, 설치 과정에서 Automatic start 가 기본으로 활성화 됩니다.
관리 서버에 RAM이 4GB 미만 이면 Automatic start 는 비활성화 됩니다.

Access Settings — 누가 접속할 수 있나

어떤 클라이언트가 API Server에 접속할 수 있는지를 세 가지 중에서 고릅니다.

옵션	누가 접속하나
Management server only	관리 서버 자신만 접속합니다. 이때는 관리 서버 명령줄에서 `mgmt_cli` 유틸리티로만 API 요청을 보낼 수 있고, SmartConsole이나 Web services로는 보낼 수 없 습니다.
All IP addresses that can be used for GUI clients	SmartConsole의 Permissions & Administrators > Trusted Clients 에 정의된 모든 IP 주소 에서 보낼 수 있습니다. 여기에는 SmartConsole·Web services·`mgmt_cli` 요청이 모두 포함됩니다.
All IP addresses	모든 IP 주소 에서 보낼 수 있습니다. 마찬가지로 SmartConsole·Web services·`mgmt_cli` 요청이 모두 포함됩니다.

설정을 마쳤으면 OK 를 누릅니다.

관리자에게 Management API 권한이 있는지 확인

왼쪽 위 영역에서 Permissions & Administrators 를 누릅니다.
해당하는 각 관리자(Administrator) 객체 에서, 그 관리자에게 할당된 Permission Profile 이 Management API 접근을 허용 하는지 확인합니다.

확인하는 자세한 방법은 다음과 같습니다.

관리자(Administrator) 객체를 편집합니다.
왼쪽 패널에서 General 을 누릅니다.
Permissions 섹션에서, 선택된 Permission Profile 오른쪽의 눈(eye) 아이콘 을 누릅니다. 그러면 Permission Profile 객체가 읽기 전용 보기 로 열립니다.
왼쪽 패널에서 Management 를 누릅니다.
Management API Login 권한이 선택되어 있어야 합니다. 선택되어 있지 않다면, 이 창을 닫고 해당 Permission Profile 객체를 직접 편집해 켭니다.
Close 를 누릅니다.

세션 게시와 API Server 재시작

SmartConsole 세션을 Publish(게시) 합니다.
관리 서버에서 다음 명령으로 API Server를 재시작 합니다.

   api restart

여기서 주의할 점이 두 가지 있습니다.

Multi-Domain Server 에서는 이 명령을 해당 Domain Management Server의 컨텍스트 에서 실행해야 합니다. 먼저 컨텍스트를 지정합니다.

     mdsenv <IP Address or Name of Domain Management Server>

이 명령의 출력에는 반드시 다음이 보여야 합니다.

     API started successfully

관리 서버에서 다음 명령으로 API Server의 상태를 확인 합니다.

    api status

api status 의 출력이 정상이면 다음과 같이 전체 상태가 "Started" 로, 준비 테스트가 성공으로 나옵니다.

Overall API Status: Started
--------------------------------------------
API readiness test SUCCESSFUL. The server is up and ready
to receive connections

API 키로 인증하는 관리자 만들기

API key 는 클라이언트가 API를 호출할 때 제시하는 토큰 입니다. API 키 인증을 쓰면, 관리자는 평소의 사용자명/암호 대신 토큰 하나로 API 인터페이스에 인증 할 수 있습니다. 이 키는 SmartConsole에서 만들어 관리자에게 부여합니다.

SmartConsole에서 API 키 설정하기

SmartConsole에서 Manage & Settings > Permissions & Administrators > Administrators 로 갑니다. 상단 메뉴의 New 아이콘을 누르면 New Administrator 창이 열립니다.
관리자에게 이름 을 줍니다.
Authentication Method 필드에서 API Key 를 고릅니다.
Generate API key 를 누릅니다.
새 API key 창이 열립니다.
- Copy key to Clipboard 를 눌러 키를 복사합니다.
- 이 키를 나중에 쓰도록 잘 저장 해 둡니다(해당 관리자에게 전달).
OK 를 누릅니다.
SmartConsole 세션을 Publish(게시) 합니다.

예제 — API 키로 로그인해 simple-gateway 만들기

방금 만든 API 키로 로그인한 뒤, API로 simple-gateway 를 하나 생성 하는 전체 과정입니다.

Expert mode 로 로그인합니다.
앞서 생성한 키로 로그인하고, 표준 출력을 파일로 저장 합니다(> 기호로 파일에 리디렉션). 이 파일에는 이후 명령에서 쓸 세션 토큰 이 담깁니다.

구문:

   mgmt_cli login api-key <api-key> > /<path_to>/<filename>

예:

   mgmt_cli login api-key mvYSiHVmlJM+J0tu2FqGag12 > /var/tmp/token.txt

mgmt_cli 명령을 -s 플래그 와 함께 실행합니다. -s 뒤에는 방금 만든 토큰 파일 을 지정합니다.

구문:

   mgmt_cli -s /<path_to>/<filename> add simple-gateway name <gateway name> ip-address <ip address> one-time-password <password> blade <true>

예:

   mgmt_cli -s /var/tmp/token.txt add simple-gateway name "gw1" ip-address 192.168.3.181 one-time-password "aaaa" firewall true vpn true

더 자세한 내용은 Check Point Management API Reference 를 참고하세요.

API 키에 더해 인증서로도 인증하기

API 인증을 구성한 뒤에는, 여기에 더해 인증서 파일(certificate file) 로도 인증하도록 추가 구성할 수 있습니다. 그러면 관리자는 API 키 또는 인증서 파일 중 하나 로 Security Management Server에 인증할 수 있습니다.

인증서 파일은 SmartConsole에서 만듭니다. 관리자는 이 인증서로 SmartConsole에 두 가지 방식 으로 로그인할 수 있습니다.

Certificate File 옵션으로 로그인 — 이 방식에서는 관리자가 인증서 파일을 쓰기 위한 암호를 입력 해야 합니다.
CAPI Certificate 옵션으로 로그인 — 인증서 파일을 Microsoft Windows SmartConsole 컴퓨터의 Windows Certificate Store(인증서 저장소)에 가져오기(import) 해 두면, 관리자는 저장된 이 인증서로 로그인할 수 있습니다. 이때는 암호를 입력하지 않아도 됩니다.

또한 이 인증서는 다른 관리자에게 건네줄 수도 있어서, 자기 관리자 계정이 없는 사람도 그 인증서로 SmartConsole에 로그인할 수 있습니다.