Umbrella: Umbrella API の概要と使用例

[tkitahar]

※ 本記事の Umbrella API は 2023 年 9 月 1 日 (UTC) でサポート終了する予定です。それまでに新しい API へ移行することが推奨されています。

Introducing the new Cisco Umbrella Open API

https://support.umbrella.com/hc/en-us/articles/8989122216340-Introducing-the-new-Cisco-Umbrella-Open-API

• 1. はじめに
• 2. Umbrella API の概要
• 3. Umbrella API の使用例
• 4. (補足) Legacy Network Devices

※ 2018 年 6 月 5 日現在の情報をもとに作成しています

1. はじめに

Umbrella には Enforcement API、Investigate API、Umbrella API という 3 種類の API が用意されており、以前の記事で Enforcement API の使用例 (こちらとこちら) について紹介しました。今回はこの中でも最も新しい Umbrella API について取り上げたいと思います。

2. Umbrella API の概要

Umbrella API は、Identity の 1 つである Network Device を HTTPS 経由で管理するために用意された、ネットワーク製品開発者向けの API で、現在、以下のような操作が可能です。

• Network Device の登録
• Network Device の一覧表示または 1 つのデバイスの情報表示
• Network Device に適用されているポリシーの一覧表示
• 既存の Network Device の内容の変更
• Network Device の削除

Umbrella では、将来的に Network Device に限らず、他の Identity も管理する API を用意したり、それ以外の Umbrella Dashboard の機能についても API から操作できるようにする計画をしています。

なお、現時点において、上記の Network Device への操作以外で既に用意されているものには以下のようなものがあります。

• 自身の OrgID の取得
• Umbrella Dashboard に登録されているポリシーの一覧取得
• 特定の Identity へのポリシーのアサイン
• 特定の Identity からのポリシーの解除
• Multi-org、MSSP ユーザー向けのコンソール情報の取得

3. Umbrella API の使用例

Umbrella API の使用例として、本項では自身の OrgID を取得します。

なお、Umbrella API を使うには、Umbrella Dashboard の Admin -> API Keys にアクセスし、新しい Umbrella Network Devices を作成する必要があります。もし Dashboard 上に API keys の項目自体がない場合は、ご利用のサブスクリプションに制限があるため、Umbrella API を使用できません。

Umbrella Network Devices を作成すると、クラウド上の Umbrella サーバーと通信をするために必要となる API Key と API Secret が発行されます。これらはそれぞれ API に対するユーザー名とパスワードの役割を果たします。

なお、API Key は API Keys 画面からいつでも確認することができますが、API Secret は Umbrella Network Devices 作成時に一度だけ表示され、その後は二度と画面に表示されません。もし API Secret を忘れてしまった場合は、REFRESH ボタンを押して再発行する必要があります。

では、Umbrella API を通して実際に自身の OrgID を取得してみます。API への HTTPS リクエストには以前の記事と同様に curl コマンドを使用します。

curl 'https://management.api.umbrella.com/v1/organizations' -u 'XXXXXX:YYYYYY'
※ XXXXXX は API Key で、YYYYYY は API Secret

または

curl 'https://management.api.umbrella.com/v1/organizations' -H 'Authorization: Basic ZZZZZZ'
※ ZZZZZZ は XXXXXX:YYYYYY を Base64 でエンコードした値

以下はこのコマンドの実行結果で、organizationId の右隣に実際の OrgID が、name の右隣に実際の組織の名前が出力されます。

[{"organizationId":1111111,"name":" Cisco"}]

4. (補足) Legacy Network Devices

前項で扱った Umbrella Network Devices の API は比較的新しく用意されたもので、実はそれ以前にも Network Device を管理する API は用意されていました。現在、この古い API は Legacy Network Devices と呼ばれており、ISR 4K シリーズとの連携など、限られたシチュエーションで引き続き使われています。