こんにちは、SumoLogic担当の新藤です。
最近OneLogin APIとSumoLogicの連携についての作業を行っていました。そこでOneLogin APIの情報を手軽に見るためにPostmanを導入しようとしたのですが、OneLogin APIをPostmanで初めて扱うときの設定で意外と手こずってしまったので記事にしました。
今回はPostmanとOneLogin API連携するまでの手順と、実際にPostmanを用いてOneLogin APIの情報を扱う方法を説明します。
Postmanとは
PostmanはAPI開発用のテストツールです。Postman CollectionというPostmanで特定のサービスのAPIを使用するためのテンプレートのようなものがあります。そのCollectionをダウンロード、そしてPostmanにインポートし環境変数などを設定するとボタン1つ押すだけでAPIが扱えるようになります。わざわざスクリプトを書いたりコマンドを作成して叩かなくても簡単にAPIを扱うことができるのでとても便利です。
必要なもの
- OneLoginの管理者アカウント
- Postmanのインストール www.postman.com
セットアップ
さて、ここからは実際の手順を記載していきます。
OneLoginの設定
OneLogin APIのトークンを入手
OneLoginの管理者画面を開き、右上の「管理」を押します。
| 権限名 | 権限 |
|---|---|
| Authentication Only | ユーザー認証のみが可能です。 |
| Read Users | User, Role, Group APIのGETコールが可能です。 |
| Manage Users | User, Role, Group APIのGET, POST, PUT, DELETEコールが可能です。 |
| Read All | すべてのOneLogin APIのGETコールが可能です。 |
| Manage All | すべてのOneLOgin APIのGET, POST, PUT, DELETEコールが可能です。 |
ここでは「Read All」を選択しました。
以降の手順をするめるには少なくとも「Read Users」以上の権限を選択してください。
Postmanの設定
OneLogin API Collectionのインポート
Postmanをインストールし、ポップアップの表示に従いアカウントの初期設定などをします。
初期設定が完了し、Postmanを起動すると以下の画面が開かれます。左上の「Import」を押します。
ページ最下部までスクロールし、「Download」ボタンを押します。
環境変数の設定
インポート完了後、左にある「Collection」タブを展開します。
| VALUABLE | INITIAL VALUE | CURRENT VALUE |
|---|---|---|
| us_or_eu | us | |
| api-domain | api.us.onelogin.com | |
| client_id | OneLoginのClient ID | |
| client_secret | OneLoginのClient Secret |
（ちなみに、ペンティオが提供しているAPIドメインはすべてusとなります。）
右上の「No Environment」を押し、先ほど作成した環境（本記事の例では「support -readall」）を選択します。
PostmanでOneLogin APIを操作する
GETメソッドを使用する
ここではGETメソッドを使用する例としてOneLogin Users APIを用いて、OneLoginのUser情報を取得します。
まずOneLogin User APIに関するリファレンスページを開き、ページ最下部までスクロールします。 developers.onelogin.com
先ほどのトークン入手の際と同様に、Postman Collectionをダウンロードし、Postmanに「Import」からダウンロードデータをアップロードします。
インポートされたUser v1フォルダを展開し、「Get User」を押します。そして右上の「Send」を押します。
環境変数が適切に代入されていると以下のようにUsersの情報がJSON形式で取得することができます。
POSTメソッドを使用する
ここではPOSTメソッドを使用する例としてOneLogin Users APIを用いて、OneLoginのUserを作成します。この操作を行うためにはPOSTコールが可能であるManage Users / Manage All権限を持ったAPI Credentialで行う必要があります。新しくAPI Credentialを作成した場合は、その都度Postmanにて環境を新規に作成し、環境変数の値を代入する必要があります。
User v1フォルダを展開し、「Create a User」を押します。そして、「Body」タブを展開します。
{ "firstname":"api", "lastname":"test", "email":"api@test.com", "username":"api_test" }
入力後、「Send」ボタンを押します。
POSTが成功した場合は以下のようにmessageがSuccess、そしてその下に登録したUserの情報が表示されます。
401 unauthorized errorが表示される場合
OneLoginのトークンの有効期限は10時間であり、401 unauthorized errorが表示される場合はOneLoginのトークンの有効期限が過ぎている可能性があります。その際は先ほどのOAuth 2.0 Tokensフォルダの「Generate Tokens」を展開し「Send」ボタンを押します。この手順によって新規のトークンがPostmanの環境変数のaccess_tokenに代入されます。トークンを入手してから再度401 unauthorized errorが表示されていたフォルダを展開し「Send」を押すことにより、期待される結果が出力されます。
アクセストークンが自動で環境変数に代入される仕組み
なぜGenerate Tokenを実行すると、Postmanの環境変数に自動的に代入されるのかって疑問に思いませんでしたか？答えは、Generate TokensのTestsタブで環境変数への代入を行っているからです。
var jsonData = JSON.parse(responseBody); postman.setEnvironmentVariable("access_token", jsonData.access_token); postman.setEnvironmentVariable("refresh_token", jsonData.refresh_token);
というjavascriptが記述されていることがわかります。上のプログラムの通り、postmanクラスのsetEnvironmentVariableを用いると環境変数に代入ができます。responseBodyでGenerate Tokensの実行結果を受け取り、第1引数に環境変数名、第2引数に環境変数の値を代入することで環境変数にGenerate Tokensの実行結果を代入することができます。この機能があるだけでアクセストークンの有効期限が切れるたびに新たに環境変数を代入する必要がないのでとても便利ですね！
まとめ
PostmanでOneLogin APIを扱うことができるようになりました！OneLogin APIでは例で用いたOneLogin Users APIだけでなく、リファレンスに記載されているOneLogin APIはすべてPostman Collectionを作成しています。ぜひPostmanでOneLogin APIをたくさん使用してみてください！