[Secure Endpoint] Postmanを使ったSecure Endpoint API v3のテスト方法

[yutogawa]

• はじめに　
• 前提条件
• API Clientの発行
• PostmanによるSecure Endpoint API v3利用にあたっての下準備
• アクセストークンの生成
• SecureX API アクセストークンの生成
• Secure Endpoint API アクセストークンの生成
• Secure Endpoint API v3を使ったデータの取得例

はじめに　

この記事では、PostmanをつかったSecure Endpoint API v3の利用方法について手順を紹介いたします。PostmanをつかったSecure Endpoint API v0/v1のご利用方法については、こちらの記事をご参照ください。Secure Endpoint API v0/v1へのアクセスはAPI keyをつかったbasic認証方式でしたが、Secure Endpoint API v3ではアクセストークンを生成して認可を行う方式に変わっております。

前提条件

•    こちらは2023/5/29時点での確認結果となります。将来的に予告なしに画面や動作が変更される場合がございます。
•    ここでは、Windows版Postman ver9.31を利用しております。
• 　SecureXとSecure Enpointが統合されている必要があります。
• 　本記事の内容についてはあくまで当方の環境での実行結果のご紹介であり、お客様環境での動作を保証するものではございません。また、Postmanに関しては弊社製品ではございませんため、お問合せ等は対応できかねます。
• 　ここでは、APJC(Asia Pacific, Japan and China )にあるリソースにアクセスしています。
• 　Secure Endpoint API v3の詳細に関してはこちらのドキュメントをご参照ください。
• 　ここでお見せするPostmanの設定方法はあくまでも一例となります。

API Clientの発行

SecureXの管理コンソールにログインし、Administrationタブをクリックします。

　　　

ナビゲーションペインからAPI Clientsをクリックし、Generate API Clientをクリックします。

　　　

Client Nameを入力し、API Clientsを選択します。Scopes(ここではすべてを選択)を指定し、Add New Clientボタンをクリックします。ここでは、Client NameはTest APIとし、Scopesはすべてを選択しています。必要に応じてDescriptionも入力ください。

　　　

Client IdとClient Passwordが発行されますので、これらを控えてください。※Client Passwordはこの画面を閉じてしまいますとその後は確認ができませんため、ご注意ください。

　　　

PostmanによるSecure Endpoint API v3利用にあたっての下準備

Postmanを起動して、まずはナビゲーションペインからEnvironmentsをクリックし、＋ボタンをクリックします。Environment名は任意の名前で問題ありません。(ここでは名前はSecure Endpoint APIとしています。)

　　　

以下の通り環境変数の入力を行います。Client_idとClient_passwordにはINITIAL VALUEとして、上の手順で発行したClient IdとClient Passwordを入力します。Secure_Endpoint_API_URLの変数には、INITIAL VALUEに以下のURLを入力ください。

Secure_Endpoint_API_URL: https://api.apjc.amp.cisco.com/v3

VARIABLE名は任意の名前で問題ありません。 最後にSaveボタンをクリックして保存をします。

右上のドロップダウンメニューから上で作成したEnvironmentを選択します。

アクセストークンの生成

SecureX API アクセストークンの生成

左上のNewをクリックし、HTTP Requestをクリックして新規にHTTP Requestを作成します。

　　

MethodでPOSTを選択し、URLにSecureX API Access Token EndpointのURL(https://visibility.apjc.amp.cisco.com/iroh/oauth2/token) を入力します。

Authorizationタブをクリックし、TypeのドロップダウンメニューからBasic Authを選択し、UsernameおよびPasswordに上の手順で用意したClient_idおよびClient_passwordの変数を入力します。

Headersタブをクリックし、Key/Valueペアに以下の値を入力します。

KEY: Content-Type VALUE: application/x-www-form-urlencoded
KEY: Accept VALUE: application/json

Bodyタブをクリックし、Key/Valueペアに以下の値を入力します。

KEY: grant_type VALUE: client_credentials

Testsタブをクリックし、以下のスクリプトを入力します。リクエストによって上の手順で用意したSecureX_API_AccessToken変数にSecureX APIのアクセストークンが格納されるようになります。

var data = pm.response.json();
pm.environment.set("SecureX_API_AccessToken", data.access_token);

Sendボタンをクリックしリクエストを送ると、以下の通り、トークンが生成されSecureX_API_AccessToken変数に格納されます。HTTP Requestは保存することによって再利用が可能です。

Secure Endpoint API アクセストークンの生成

まずは新規にHTTP Requestを作成します。

Methodで POSTを選択し、URLにSecure Endpoint API のアクセストークンEndpointのURL({{Secure_Endpoint_API_URL}}/access_tokens) を入力します。{{Secure_Endpoint_API_URL}}は上の手順で用意した変数となります。

Authorizationタブをクリックし、TypeのドロップダウンメニューからBearer Tokenを選択し、Tokenに上の手順で用意したSecureX_API_AccessTokenの変数を入力します。

Testsタブをクリックし、以下のスクリプトを入力します。上の手順で用意したSecure_Endpoint_API_AccessToken変数にリクエストで生成したSecure Endpoint APIのアクセストークンが格納されるようになります。

var data = pm.response.json();
pm.environment.set("Secure_Endpoint_API_AccessToken", data.access_token);

Sendボタンをクリックしリクエストを送ると、以下の通り、アクセストークンが生成されSecureX_API_AccessToken変数に格納されます。

Secure Endpoint API v3を使ったデータの取得例

まずは、新規にHTTP Requestを作成します。

ここでは例として、上の手順で生成したSecure Endpoint APIのアクセストークンを使って、Organizationの情報を取得します。

MethodでGetを選択し、以下のURLを入力します。

{{Secure_Endpoint_API_URL}}/organizations?size=10　※Sizeは可変です。

次に、Authorizationタブをクリックし、ドロップダウンメニューからBearer Tokenを選択し、TokenにSecure_Endpoint_API_AccessTokenの変数を入力します。最後にSendをクリックしてリクエストを送ると以下のように自身が管理者となっているOrganizationの一覧が結果として返ってきます。

次の例は、Organizationに存在するPolicy一覧を取得する方法となります。以下のURLを指定してSendをクリックすると以下のようにポリシー一覧が結果として返ってきます。

{{Secure_Endpoint_API_URL}}/organizations/{organizationIdentifier}/policies?size=10　※Sizeは可変です

アクセストークンの有効期限が切れると以下のようなエラーが返ってきます。この場合、上の手順で再度アクセストークンを生成する必要があります。