Postman을 통해 Umbrella Reporting API 사용

소개

이 문서에서는 Postman에서 Cisco Umbrella Reporting API를 사용하는 방법에 대해 설명합니다.

사전 요구 사항

요구 사항

이 문서에 대한 특정 요건이 없습니다.

사용되는 구성 요소

이 문서의 정보는 Cisco Umbrella를 기반으로 합니다.

이 문서의 정보는 특정 랩 환경의 디바이스를 토대로 작성되었습니다. 이 문서에 사용된 모든 디바이스는 초기화된(기본) 컨피그레이션으로 시작되었습니다. 현재 네트워크가 작동 중인 경우 모든 명령의 잠재적인 영향을 미리 숙지하시기 바랍니다.

개요

Umbrella API는 사용자가 Umbrella에 구축, 확장, 통합할 수 있는 사용자 친화적이고 안전한 플랫폼을 제공하는 것으로 2022년 9월에 출시되었습니다.

Umbrella API 엔드포인트는 api.umbrella.com에서 호스팅되며 활용 사례별로 그룹화된 경로가 있습니다. API 키는 Umbrella 대시보드에서, Admin(관리) > API keys(API 키)에서, 그리고 KeyAdmin API를 사용하여 프로그래밍 방식으로 관리할 수 있습니다. 각 키는 다음과 같은 5가지 기본 활용 사례에 따라 그룹화된 여러 범위로 세분화할 수 있습니다.

• 관리 API 엔드포인트를 사용하면 Umbrella API 키와 사용자를 프로비저닝 및 관리하고, 역할을 보고, 공급자 및 관리되는 공급자에 대한 고객을 관리할 수 있습니다.
• 인증 API 엔드포인트를 사용하면 Umbrella 플랫폼과의 다른 서비스 통합에 권한을 부여할 수 있습니다.
• 구축 API 엔드포인트를 사용하면 네트워크 및 기타 다양한 엔터티를 프로비저닝, 모니터링 및 관리하고 기존 Umbrella 정책에서 구성하여 보호할 수 있습니다.
• 정책 API 엔드포인트를 사용하면 대상 목록 및 목록별 대상을 프로비저닝하고 관리할 수 있습니다.
• 보고서 API 엔드포인트를 사용하면 구축에 대한 실시간 보안 정보를 읽고 감사할 수 있습니다. Umbrella App Discovery API는 클라우드 기반 애플리케이션에 대한 통찰력을 제공합니다.

이 문서에서는 API를 통해 활동 검색 보고서를 수집하는 방법을 설명합니다.

우산 절차

1. Umbrella 대시보드에서 Admin(관리) > API Keys(API 키)로 이동합니다.

2. API 키 > 추가를 선택합니다.

3. Key Scope(키 범위) 아래에서 Reports(보고서), Create Key(키 생성)를 선택합니다.

21495050167956

관리자는 각 API 키의 사용 용도에 따라 읽기/쓰기와 읽기 전용 사이의 범위별 액세스 레벨을 조정할 수 있으며, API 키는 미리 정의된 날짜에 만료되도록 구성할 수 있습니다. API 키/암호는 현재 표시되어 있으며 나중에 나타날 수 없으므로 이 단계에서 API 키/암호를 수집해야 합니다. 

API 자격 증명은 60분 동안 유효한 API 액세스 토큰을 생성합니다. 이 절차에서는 OAuth 2.0 클라이언트 자격 증명 흐름을 지원합니다. Umbrella 다중 조직 또는 서비스 공급자 환경에서는 상위 조직 API 자격 증명을 사용하여 권한 부여 프로세스 중에 지정된 하위 조직에 대해 동일한 범위의 액세스 토큰을 생성할 수 있습니다.

Postman 절차

먼저 OAuth 2.0 액세스 토큰을 생성해야 합니다. Umbrella API 인증 경로는 https://api.umbrella.com/auth/v2로 시작합니다. POST 쿼리 및 사용자 API 키를 사용자 이름으로 제출하고 API 비밀번호를 비밀번호로 제출하면 액세스 토큰이 생성됩니다.

21606708808468

21607051456276

이 단계에서는 액세스 토큰을 수집해야 합니다. 이제 액세스 토큰으로 정보를 검색할 수 있습니다.

GET 메서드를 선택하고 API 경로(필요한 매개 변수 포함)와 액세스 토큰을 모두 입력해야 합니다. 이 예에서는 지난 7일 동안 DNS 트래픽에 대해서만 활동 검색에서 100개의 보고서를 검색할 수 있습니다.

21607952074772

또 다른 예에서는 지난 7일 동안 DNS 트래픽, 특히 "gsa.apple.com" 도메인에 대해 활동 검색에서 1,000개의 보고서를 추출할 수 있습니다.

21607927544468

API 쿼리에서 사용할 수 있는 추가 매개변수를 검색하려면 쿼리 매개변수 요청을 참조할 수 있습니다.

참고: HTTP 클라이언트 요청이 Umbrella 데이터 웨어하우스의 위치와 동일한 대륙에서 시작되지 않으면 Umbrella 서버는 302 Found로 응답합니다. HTTP 요청을 자동으로 리디렉션하고 HTTP Authorization 헤더를 보존하려면 추가 플래그를 설정하거나 리디렉션 설정을 활성화할 수 있습니다.

컬: Curl HTTP 요청을 리디렉션하고 Authorization 헤더를 유지하려면 -L 또는 —location 및 —location-trusted 플래그를 전달해야 합니다.

21608126036628

Postman: Postman 환경 내에서 API로 이동하여 GET 메서드를 선택합니다. Settings(설정) > Enable Follow Authorization(다음 권한 부여 헤더 활성화)으로 이동하여 리디렉션 요청에 대한 권한 부여 헤더를 보존합니다.

21608126042388

응답

URL에 GET 작업을 전송한 후 다양한 상태 코드를 받을 수 있습니다.

• 상태:200: 요청한 정보를 요청에서 가져왔습니다.
• 상태: 400: 잘못된 요청입니다. 쿼리하기 위해 보낸 URL과 관련될 수 있습니다. 하나 이상의 매개 변수가 올바르지 않습니다.
• 상태: 401: 권한 없음. 권한 부여 헤더가 없거나 토큰이 인증되지 않았습니다.
• 상태:403: 금지됨. 토큰이 잘못되었습니다.