【第2回】Sandboxを試そう！～Umbrellaの紹介と接続～

[khada]

はじめに

Ciscoが提供するDevNet Sandboxについて紹介する、第2弾のテーマは「Cisco Umbrella」です。
前回はSandboxの概要と「Meraki Always-on」について、接続方法からAPIの試行までをご紹介しました。
今回は、前回紹介しきれなかったSandboxの別のラボの説明と接続方法、実際の操作画面など、画像を参照しながらご紹介していこうと思います。

前回記事のURLは下記に設置していますので、併せてご参照ください。

前回

【第1回】Sandboxを試そう!~Meraki Always-On立ち上げからMeraki Dash Board APIの試行まで~ - Cisco Community

準備するもの

• インターネット接続可能なパソコン
• サンドボックス:https://developer.cisco.com/site/Sandbox/

前回のおさらい

第1回の記事では、Sandboxには以下のようなラボがあることをご紹介しました。

1. 予約なしで使用できる『ALWAYS-ON SANDBOX』
2. 予約して使用できる『RESERVATION SANDBOX』

今回は2つ目の『RESERVATION SANDBOX』を取り上げようと思います。

予約して使用できる『RESERVATION SANDBOX』ですが、他の利用者がいない場合は、『Launch』ボタンを押すことですぐに使用することができます。
ただし、今回のUmbrella APIのように、予約ボタンを押し、必要なユーザー情報やパスワードがメールで送られてくるのを待つ必要もあります。

Cisco Umbrella

APIを実際に操作する前に、今回紹介するUmbrellaについて公式サイトでの紹介を引用します。

Umbrella は、最前線でインターネット上の脅威を防御する
「セキュア インターネットゲートウェイ」Secure Internet Gateway（SIG）です。
場所や VPN のオン/オフに関わらず、すべてのユーザとデバイスを保護する、
かんたん・スピード導入が可能なクラウド型セキュリティサービスです。

DNSの仕組みを利用したトラフィックのフィルタリングや、APIを利用して対象デバイスのクラウドアプリケーション内にマルウェア等の脅威がないか検知する機能など、セキュリティ関連の機能が多く搭載されています。
詳細については上記公式サイトに載っているので、よろしければ併せてご覧ください。

接続前に

Umbrella DashBoardの紹介と共に、軽くではありますがUmbrella APIを試していこうと思います。
試行環境は前回同様、Postmanを使用していきますので、ご準備ください。
また、APIについては2018年～2022年にCisco community内で紹介されたUmbrella関連の記事も併せてご参照ください。

Umbrella: API のリニューアルについて - Cisco Community

当記事で紹介するものは、2023年9月のリニューアル以降で動作することを前提としています。
もし以前までの環境でUmbrella APIを触ったことがある方は、上記のリニューアル記事に変更点等がまとまっていますので、今回の試行前にご覧いただくと始めやすいと思います。

１．接続方法の紹介

まずはSandboxにて予約を行います。
Catalog (cisco.com)を開いてください。
検索ボックスに「Umb」までご入力いただくと、「Cisco Umbrella Secure Internet Gateway」が表示されるので、「Launch」を押してください。
下記のような画面が表示されると思いますので、画面の左下部にある「Launch Environment」を押すと予約のメールが送られてくるかと思います。

Umbrella DashBoardにログインするためにはユーザー情報とパスワードが必要です。
返ってくるメール内に記載されているので、必ずメールをご確認ください。
タイトルは予約を受け付けたことを知らせる「We Are Preparing Your Cisco DevNet Sandbox Lab」と、ログイン情報などが記載されている「YourLabIsReady_with_Credentials_Email」の2通です。

２．ログイン画面

Cisco Umbrella > Sso Loginにアクセスします。
メール内に記載されているユーザーとパスワードを使用してログインしてください。
途中、Microsoftのアカウントに関するポップアップが出た場合は、ユーザーを追加するボタンを押し、ユーザーとパスワードを同じように登録することで解消されます。
注意点ですが、Sandboxを経由して操作する場合、Sandboxで停止処理を行うとユーザーもパスワードも無効となります。
またログインする場合はもう1度予約を行う必要がありますので、ご留意ください。

完了すると以下のようにDashBoardが表示されました。

３．API Keyを作成
UmbrellaのAPIを試行するため、API Keyを作成する必要があります。
API Keyの作成方法はこちら「Umbrella: Umbrella API の概要と使用例 - Cisco Community」の記事でも紹介されていますが、リニューアルに伴いUIも一部ブラッシュアップされたため、新規画面をもとに順にやっていきましょう。

リニューアル前の記事内には「サブスクリプションによっては機能制限がある」旨の記載もありますが、Sandobox経由の場合はAPI Keyを生成可能です。
ログイン後の画面左側のメニューバーから「Admin」をクリックすると、さらにメニューが展開されるので、その中から「API Key」をクリックしてください。
Sandobox経由の場合、複数のユーザーが同アカウントを使用しているため、複数のAPI Keyが確認できるかと思います。
自身で作成したAPI Key以外は操作しないようご注意ください。

API Keyの新規作成は容易に行えます。
まず、画面右上の追加ボタンを押します。
基本的に操作するのは「API Name」と「Key Scorp」の二か所のみです。
「API Name」は文字通りそのAPIの名前になります。自身が操作しているAPIだとわかるような名前にしてください。
「Key Scorp」は該当のKeyにどんな操作が可能か決定するためのものです。
今回は「Admin」にのみチェックをいれますが、必要に応じて設定してください。

API Keyの生成が完了したら、Keyとアクセスキーが表示されると思います。
アクセスキーは生成した直後にのみ表示され、以降は表示する方法がなくなってしまうのでご注意ください。

４．Postmanの設定

Umbrella側の準備が整ったので、生成・発行したAPI Keyを使用してさっそく試行してみます。
今回は
・API Key/secretを使用してアクセストークンを取得する
・取得したアクセストークンを使用してユーザー情報を取得する
この2点を行います。

リニューアル後のUmbrella APIでは、APIを呼び出すためのアクセストークン自体を、API Key/secretを用いて取得するようになりました。
まず、変数を使用してURLやAPI Key/Secretをマスクしていきます。
グローバル/ローカルの環境変数を設定する方法は以前の記事でもご紹介していますので、そちらもご参照ください。


①アクセストークンを取得するAPIをコールする

Postmanを開き、「new Collection」または「＋」ボタンをクリックして新しいタブを作成してください。
名前は任意のもので大丈夫です。
今回は仮に「Get Access token」とします。

実行する内容
１．環境変数を設定するタブを開き、認証に必要なユーザー名とパスワード、ベースとなるエンドポイント情報をマスクする
２．Auth/認可タブで「Basic Auth」を開き、ユーザー名とパスワードを１で作成した変数で設定する
３．エンドポイントに１で作成した変数を設定しコールする

それぞれ順に作業していきましょう。

１．環境変数を設定するタブを開き、認証に必要なユーザー名とパスワード、ベースとなるエンドポイント情報をマスクする

環境名：Umbrella API

名称	内容
baseUrl	エンドポイントでベースとなるURL
userName	API Key
userPass	API secret

※作成後、タブに環境変数を適用してください

２．Auth/認可タブで「Basic Auth」を開き、ユーザー名とパスワードを１で作成した変数で設定する

３．エンドポイントに１で作成した変数を設定しコールする

成功するとアクセストークンがレスポンスされます。

今回のAPIには有効時間あります。
毎回決まっているわけではありませんが、今回は「3600/秒」です。
有効時間が切れた場合は、もう一度Sandboxで予約を行ってください。

次はこのアクセストークンを利用してユーザー情報を取得するのですが、今回は認証同様、アクセストークンも環境変数として設定し、使用していこうと思います。

①環境変数を修正する
アクセストークンを取得する際に用いた環境変数のグループに、新たに「access_token」という変数を追加します。

②アクセストークンを環境変数に格納する
API コール後、レスポンスされたアクセストークンを環境変数「access_token」に格納する処理を実装します。
Postmanの画面中央部分にある「Script」タブをクリックしてください。
※PostmanのバージョンやUIによっては「Test」となっている場合もあります。

このScriptタブ上に以下の処理を書き込んでください。

// レスポンス内容を.JSONとして取得する
const jsonData = pm.response.json();

// jsonDataからアクセストークンのみを抜き出し、環境変数「access_token」に格納する
var accessToken = jsonData.access_token;
pm.environment.set("access_token", accessToken);

画面キャプチャ：

ここまで用意できたら一度保存し、APIを再度コールします。
すると、空だった環境変数「access_token」にレスポンスされたアクセストークンが登録されていることを確認しましょう。

次はここで取得したアクセストークンを使用し、ユーザー情報を取得するAPIをコールするための処理を実装します。
「Get Access token」タブを作成したように、「new Collection」または「＋」ボタンで新規タブを作成してください。
名前は任意のもので大丈夫です。
今回は仮に「Get User」とします。

実行する内容
１．タブに環境変数を適用する
２．Auth/認可タブで「Bearer token」を開き、アクセストークンを作成した変数「access_token」で設定する
３．APIをコールする

順に実行していきましょう。

１．タブに環境変数を適用する

「Get Access token」同様、環境「Umbrella API」を適用します。

２．Auth/認可タブで「Bearer token」を開き、アクセストークンを作成した変数「access_token」で設定する

３．APIをコールする

Body等は操作せずSendボタンをクリックしコールします。
UserIdなどがレスポンスされたら成功です。

Umbrella APIのアクセストークンは他のAPIでも用いる重要なものなので、今回のように環境変数を用いることで、アクセストークンをコピー＆ペーストして用いる手間がなくなり、また、レスポンスされるアクセストークンの内容が変わっても追加の動作なくテスト作業ができました。
他のUmbrella APIの動作などについては、また機会があればご紹介できたらと思います。