こんにちは、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の管理者画面を開き、右上の「管理」を押します。 画面が遷移したあと、「Developer」タブの「API Credentials」を押します。 画面が遷移したあと、「New Credentials」を押します。 ポップアップが表示されるのでトークン名を入力します。OneLogin API Credentialsには5種類の権限があります。下に行くほど権限が上がります。
権限名 | 権限 |
---|---|
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」以上の権限を選択してください。 権限を選択したあと、「Save」を押します。その後画面が遷移し、「Client ID」「Client Secret」が表示されます。以上でOneLoginでの設定は終了です。後ほど「Client ID」「Client Secret」の値が必要となるため、ブラウザのタブを閉じないことをおすすめします。
Postmanの設定
OneLogin API Collectionのインポート
Postmanをインストールし、ポップアップの表示に従いアカウントの初期設定などをします。 初期設定が完了し、Postmanを起動すると以下の画面が開かれます。左上の「Import」を押します。 OneLogin APIのToken API Postman Collectionをダウンロードします。一旦Postmanの画面を離れ、OneLogin APIのリファレンスのトークンに関するページを開きます。
ページ最下部までスクロールし、「Download」ボタンを押します。 ダウンロードしたファイルをPostmanにインポートします。そして、右上の「Import」を押します。「NAME」が「OAuth 2.0 Tokens」となっていることを確認します。
環境変数の設定
インポート完了後、左にある「Collection」タブを展開します。 先ほどインポートしたOneLogin APIトークンに関するPostman Collectionが表示されます。「OAuth 2.0 Tokens」フォルダを展開し、「Generate Tokens」を押します。 この画面で赤色で{{xxx}}となっている文字はPostmanにおける環境変数です。事前に環境変数を設定することで簡単にOneLogin APIのリクエストを実行することができます。 具体的にはClient IDやClient Secretなどの認証情報を登録することにより、OneLogin APIを利用するときに「Generate Tokens」のリクエストを「Send」ボタンを押して実行するだけで最新のAccess Tokenを取得できるなど、メリットが多数あります。 画面が遷移したあと、右上の「歯車マーク」を押します。 右下の「Add」を押します。 その後、環境変数名を入力します。OneLoginの先ほどのAPI Credentialsの画面から以下の値を入力します。以下の4種類の環境変数は入力が必須です。入力後、右下の「Add」を押します。そして右上の「✕」を押します。
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」)を選択します。 その後、設定したすべての環境変数{{xxx}}の上にカーソルを合わせ、以下のように緑が表示されることを確認してください。緑となっていれば環境変数は適切に値が代入されております。赤となっている場合は環境変数に適切に値が代入されておりません。その際は環境変数の名前が適切であるか、そして環境は先ほど作成した環境となっているかを確認してください。 環境変数に適切に値が代入されていることを確認したあと、右上の「Send」を押してください。数秒後、「Body」タブにアクセストークンやステータスなどが表示されます。表示された「access_token」の値はaccess_tokenという名前の環境変数に自動的に代入されるようになっています。これにより、OneLogin APIのトークンを入手することができました。
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」タブを展開します。 以下の画像のように登録するUserの情報を入力します。
{ "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タブで環境変数への代入を行っているからです。 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をたくさん使用してみてください!