【Safeguard for Privileged Passwords(SPP)】APIで操作する(Swagger UI 利用編 ①)

SPP のすべての機能は API を通して利用することができます。今回は、SPP に組み込まれている Swagger UI の使用方法を紹介します。

※参照:OneIdentity/safeguard-api-tutorialhttps://github.com/OneIdentity/safeguard-api-tutorial

SPP API について

SPP は RESTベースの API(RESTful API)を提供します。SPP API のエンドポイントは、HTTP オペレーターや JSON(または XML)のリクエストとレスポンスを使って呼び出されます。

SPP API は、Swagger でドキュメント化されています。ユーザーは、Swagger UI から API を直接呼び出したり、URL やパラメーター、ペイロードに関するドキュメントを確認したりすることができます。

SPP API は、One Identity のオープンソースプロジェクトでサポートされます。SPP API を学習するために役立つ API チュートリアルやハンズオンラボ、PowerShell や bash で使用できるスクリプトリソースも用意されています。

SPP API を構成するサービス

SPP API は、core、appliance、notification、event、a2a サービスから構成されています。

サービス説明
coreクラスタ全体の操作、アクセスリクエストワークフロー、資産管理、ポリシー管理など、ほとんどの製品機能
applianceIP アドレスの設定、メンテナンス、バックアップ、サポートバンドル、アプライアンス管理など、アプライアンス固有の操作
notification匿名、未認証の操作
eventリアルタイムイベントのために SignalR に接続するための専用エンドポイント
a2aアプリケーション統合に特化した操作。パスワードの取得、ユーザーに代わってのアクセスリクエストなど

これら SPP API サービスごとに OpenAPI ファイルがあります。

Swagger OpenAPI ファイルへのアクセス

Swagger OpenAPI ファイルへアクセスするには、ブラウザで以下にアクセスします。

https://<SPPのネットワークアドレス>/service/<サービス名>/swagger/v4/swagger.json

ここでは、Firefoxを使用しています。SPP OpenAPI ファイルへは、Firefox またはその他 JSON パーサーでアクセスすることをお勧めします。

paths ノードを展開すると、SPP API でこのサービスに対して公開されているすべてのエンドポイントが表示されます。

展開すると、利用可能な HTTP メソッドが表示されます(例:getpostputdelete)。

これらの HTTP メソッドは、標準的なデータ操作の動詞 (CRUD) に対応しています。

  • post = create
  • get = read
  • put = update
  • delete = delete

components/schemas ノードを展開すると、SPP API で、このサービスに対して公開されているすべてのデータ転送オブジェクト(data transfer objects = DTOs) が表示されます。DTOは、REST API から渡されるデータ表現です。

SPP Swagger UI へのアクセス

Swagger UI にアクセスするには、ブラウザで以下にアクセスします。

https://<SPPネットワークアドレス>/service/<使用するSPPサービス>/swagger

notification サービスの呼び出し

最初に、notification サービスを見てみます。 ブラウザを起動し、以下にアクセスします。

https://<SPPのネットワークアドレス>/service/notification/swagger

自動的に以下のアドレスにリダイレクトされます。

https://<SPPのネットワークアドレス>/service/notification/swagger/index.html

ページがロードされると、サービスによってホストされているトップレベルのエンドポイントリストが表示されます。

Status をクリックすると、利用可能なエンドポイントが表示されます。

例として、GET /v4/Status/Availability をクリックしてみます。
エンドポイントと対話できる HTML フォームが表示されます。

出力形式を選択することができます。

Schema リンクをクリックすると、オブジェクトプロパティの詳細情報が表示されます。

Try it out ボタンをクリックします。

Execute ボタンをクリックします。

GET /v4/Status/Availability エンドポイントが呼び出されます。
Swagger UI がサーバーに HTTP GETリクエストを発行し、HTTP レスポンスの結果が表示されます。

Code には、呼び出しが成功したかどうかが示されます。200番台は成功で、400番台や500番台は失敗です。
Response body フィールドには、結果が表示されます。失敗した場合は Response body フィールドに情報が表示されます。
Response body の情報を見ると、SPPアプライアンスが ”Online”(オンライン)状態であることがわかります。

この notification エンドポイントは SPP がメンテナンス中であっても利用可能で、認証も必要ありません
cURL コマンドをロードバランサーから使用して、SPP アプライアンスが ”Online”であるかどうかをチェックすることができます。また、このアプライアンスが ”IsPrimary”(プライマリかどうか)を判断することもできます。

core サービスの呼び出し

次に、実際に SPP の設定変更を行う core サービスを見てみます。
ブラウザの URL を次のように変更します。

https://<SPPのネットワークアドレス>/service/core/swagger/index.html

今回は、OpenAPI ファイルが大きいため、ページの読み込みに時間がかかります。

ページがロードされたら、例として AssetPartitions のエンドポイントをクリックし、
GET /v4/AssetPartitions をクリックします。

先ほどと同じように Try it out をクリックした後、Execute をクリックします。

今回の HTTP レスポンスコードは、401(エラー)でした。これは、ユーザーが認証されていないためです。

前の notification サービスの呼び出しは認証なしで実行できましたが、今回は、ユーザーの認証が必要です。

認証のため、Swagger UI ページの上部にある Authorize ボタンをクリックします。

Authorize をクリックします。

SPP のログイン画面が表示されます。
ここでは、「資産」アクセス許可権限を持つユーザーでログインしてください。

Close ボタンをクリックして、画面を閉じます。

もう一度、GET /v4/AssetPartitionsExecute をクリックしてみてください。

Codeが 200番ですので、今回は成功です。

レスポンスコードが 403 の場合、ユーザーは認証されたが、エンドポイントを使用するためのアクセス許可権限を持っていないことを意味します。適切なアクセス許可権限を持つユーザーで認証をやり直してください。

appliance サービスの呼び出し

最後に、appliance サービスも見てみましょう。
ブラウザの URL を次のように変更します。

https://<SPPのネットワークアドレス>/service/appliance/swagger/index.html

例として、ApplianceStatus をクリックし、POST /v4/ApplianceStatus/Reboot エンドポイントをクリックします。

Try it out ボタンをクリックします。

[Reason for performing operation]フィールドに test と入力して、Execute ボタンをクリックします。

401 エラーが戻ります(認証されていないため、実行に失敗しました)。

これは、Swagger UI ページを切り替えるたびに再認証が必要であるためです。前と同じ手順で認証(今回は、「アプライアンス」または「操作」アクセス許可権限を持つユーザーで認証)すれば、この API を実行することができます。

Swagger UI を頻繁に使用する予定がある場合は、ブラウザを複数のタブで開いたままにしておくことをお勧めします。

このセクションには、アプライアンスの状態を変更するのに便利なエンドポイントがあります。
IPアドレスの変更、再起動、シャットダウン、バックアップの取得、その他多くの操作をこのインターフェイスから行うことができますが、たいていの場合、認証された「アプライアンス」アクセス許可権限を必要とします。

さいごに

SPP は、他のアプリケーションやシステムとの連携を可能にする RESTful API を提供します。SPP API を学習するために役立つ API チュートリアルやハンズオンラボ、Powershell や bash で使用できるスクリプトリソースも用意されています。評価版でお試しください。

SPP 製品紹介ページ

SPPには、この記事で紹介した以外にも機能があります。
その他の特長や機能については、それぞれの製品紹介ページをご参照ください。

SPP 評価版

SPP の評価版は、仮想アプライアンス(OVAまたはVHDXファイル)で提供いたします。
SPPの評価版では、すべての機能を 90日間無料でご利用いただけます。
評価版の利用をご希望いただく場合は、下記お問い合わせフォームから評価ライセンスをお申し込みください。

お問い合わせ

購入前の SPP に関するお問い合わせは、下記お問い合わせフォームからお問い合わせください。

こんな記事も読まれています

最新記事

おすすめ記事

  1. 【Syslog監視】Syslogサーバーとネットワーク監視を連携。PRTGで重要なSyslogだけを監視する。

  2. システム管理者の特権アカウントを保護するための7つの方法

  3. 「Wiresharkでsyslogプロトコルパケットを覗く」syslog-ng Store Box活用連載企画vol.4

製品カテゴリー

JTC IT用語集
TOP