F5 EAPのAPI操作を簡単にするPostmanのセットアップと使い方をまとめてみた

こんにちは、臼田です。

皆さん、WAFの管理してますか？(挨拶

今回はF5のSaaS型WAFであるF5 EAP(Essential App Protect)を操作するためのAPIについて解説します。APIを操作する上でF5からはPostmanを利用することが推奨されているため、Postman自体のセットアップなども合わせて説明します。

前置き

F5のクラウドサービス(EAPの他にDNSサービスなどがある)のAPIリファレンスではAPIファーストアプローチで開発されていることやそのメリットについて説明されています。(引用した下図はその開発順とメリットについての解説)

APIファーストであるところもあると思いますが、F5 EAPではGUIで設定できない内容をAPIで設定することができたりします。

現状(2020/07/25)では細かい例外の条件登録や機密情報のフィルター(描写したくない文字列を***で隠す設定)などはAPIでのみ設定が可能です。

F5からPostmanでインポートして利用できるAPIコレクションが用意されており、プログラミングせずに簡単にAPIを利用できるようになっています。

前提条件

F5 EAP自体のセットアップは事前にされている前提で説明します。(API自体はこのセットアップから実行できます。今回はセットアップ済みの環境をベースにはじめるため割愛)

EAP自体のセットアップについては下記をご参照ください。

Postmanセットアップ

まずはPostmanのセットアップからです。

Postmanは簡単に説明するとAPIをテストするツールです。昔は簡単にREST APIを送ったり確認する程度の機能でしたが、現在はAPI開発のコラボレーションプラットフォームとしてチームでの開発やドキュメンテーション機能、自動テスト機能など有用な機能が沢山追加されているようです。

まずはアプリケーションをダウンロードします。(ちなみにWeb上で利用できるクライアントもありますが、ブラウザのクロスオリジン要求ブロックでうまく行かなかったためインストールして利用するアプリケーションの利用が良いと思います)

Postmanのダウンロードページにアクセスしてダウンロード・インストールします。(下図はMacでアクセスしたページですがWindowsも同じようにできると思います)

アプリケーションを起動したらCreate Accountに切り替えてアカウントを作成します。(アカウントがない場合)

ログインすると下記のような画面になります。(ダークモードに切り替えています。ダークモードはCustomizeの項目で切り替えられます。)

EAPコレクションのインポート

コレクションはAPIスキーマから作成されるjsonドキュメントです。F5が各クラウドサービスのコレクションを公開しておりEAPもあります。これをインポートしてすぐにAPIを試すことができます。

まずF5 APIガイドからEssential App Protect Collectionを選んでjsonをダウンロードします。

Postmanアプリの左上にあるImportを押してjsonファイルをアップロードします。

EAPのコレクションが確認画面に出るのでImportします。

コレクションの設定とパラメータ取得

APIを利用するには下記の順番でAPIを実行して設定していきます。

• ログイン
• アカウント情報の取得
• サブスクリプションIDの取得

まずログインするための情報を設定します。インポートしたEAPのコレクションの右下の…からEditを選択します。

Variablesを選択してUSERNAMEとPASSWORDのCURRENT VALUEを自身のF5 EAPの情報に変更してUPDATEします。これはコレクション全体で有効なGlobal Variablesとして扱われます。

まずはログインを行います。EAPのコレクションを開き、「Create New Essential App Protect ...」のフォルダを開くとPOST LoginのAPIがあるのでこれを開きます。すると右画面にLoginのAPIのURLや必要なHeader/Bodyが設定された状態で開きます。

各所{{USERNAME}}のように変数が設定されていてGlobal VariablesやEnvironmentで設定されている値が自動で挿入されます。Sendしてみると下部にStatus: 200が返ってきてaccess_tokenなどが表示されます。

中段のAPIのタブをTests、下段のレスポンスのタブをTest Resultsに切り替えて見てみます。TestsにはレスポンスからACCESS_TOKENとREFRESH_TOKENがGlobal Variablesとしてセットされる処理が書かれています。実際に結果にはPASSと成功していることが伺えます。

右上の目のアイコンを押してみると設定されているVariablesが確認できます。実際にACCESS_TOKENなどが設定されていることが確認できました。このように必要な値を自動的に設定できるのがPostmanやF5提供のコレクションを利用するメリットです。手動でパラメータを毎回変更する必要はありません。

ログインできたので次はアカウントの情報を取得します。具体的にはUSER_IDとACCOUNT_IDが必要になる為これを取得します。

左側の「Create New ...」の中にあるGET Account DetailsのAPIを開き、Sendします。ちなみにHeadersを開くと先程取得したACCESS_TOKENをヘッダに利用していることが確認できます。

成功するとTestsにより必要な値が設定されています。レスポンスのidがUSER_IDとなり、primary_account_idがACCOUNT_IDとなっています。

最後にサブスクリプションIDを取得します。これはEAPの環境毎に作成されます。今回は事前に設定済みの前提であるので、これをAPIから取得します。APIからサブスクリプションする場合にはそのレスポンスでIDを設定できます。

正確にはsubscription_idとservice_instance_idを取得します。コレクションから「Essential App Protect Administration」の中にあるGet All WAF Subscriptionsを開いてSendします。ここでcatalogIdやservice_typeが設定されていますが、これは各F5のクラウドサービス毎に固定の値になっているのでそのままで問題ありません。

レスポンスからsubscription_idとservice_instance_idを控えておきます。残念ながらこのAPIはすべてのサブスクリプションを取得するため、Testsで自動設定されません。

控えた値をEnvironmentに設定していきます。先程ログイン情報などはGlobal Variablesを変更しましたが、サブスクリプションは複数ある場合もありますので都度変数を切り替えられるEnvironmentが有効です。

Environmentの設定は右上の目のアイコンを開いた後、すぐ側にあるAddを押します。

Environmentの名前を適当に入れ、設定したいSUBSCRIPTION_IDとSERVICE_INSTANCE_IDをVARIABLEに入れ、INITIAL VALUEあるいはCURRENT VALUEに取得した値を入れます。特性上この値はEnvironment毎1つしか使わないのでどちらでもいいと思います。Addで追加します。

これで一通り必要な設定が完了しました。

APIを利用してみた

それではAPIを使っていきましょう。今回はセキュリティイベントを取得するAPIを使ってみます。

右上のEnvironmentが先ほど作成したもの(私の環境ではTestWAF)になっていることを確認します。

左カラムから「Analytics Service」にあるGet Security Eventsを開きます。このAPIでは先程取得したservice_instance_idとsubscription_idをBodyに入れて送る必要があります。デフォルトでは謎の値が入っていますが、このまま送ってもうまくいきません。先程Environmentに設定した変数を入れるために"{{SERVICE_INSTANCE_ID}}"などに変更します。注意点として送る値はstring型のため"(ダブルクォーテーション)で変数を括ることを忘れないようにしましょう。ついでに期間も適当に変更してSendしてみましょう。レスポンスが200になりイベントが取れていれば成功です。

まとめ

Postmanを利用してF5 EAPのAPIを実行するセットアップ方法をまとめました。

Postman自体の機能とF5から提供されているコレクションがかなり使いやすくなっていて操作自体はいい感じです。(このAPIの内容の理解やセットアップ方法の確立までには結構時間がかかりましたが)

これからもっとEAPの設定などにAPIを活用していきたいと思います。