PostmanとOneLogin APIを連携する

f:id:pentiotech:20201029174601p:plain
PostmanとOneLogin APIを連携する

こんにちは、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の管理者画面を開き、右上の「管理」を押します。

f:id:cmt_192cm:20200623162241p:plain
ポータル画面
画面が遷移したあと、「Developer」タブの「API Credentials」を押します。
f:id:cmt_192cm:20200623162440p:plain
管理者画面
画面が遷移したあと、「New Credentials」を押します。
f:id:cmt_192cm:20200623162500p:plain
API Credentialの新規作成
ポップアップが表示されるのでトークン名を入力します。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」以上の権限を選択してください。

f:id:cmt_192cm:20200623162952p:plain
API Credentialの権限の選択
権限を選択したあと、「Save」を押します。その後画面が遷移し、「Client ID」「Client Secret」が表示されます。以上でOneLoginでの設定は終了です。後ほど「Client ID」「Client Secret」の値が必要となるため、ブラウザのタブを閉じないことをおすすめします。
f:id:cmt_192cm:20200623163238p:plain
Client IDとClient Secret

Postmanの設定

OneLogin API Collectionのインポート

Postmanをインストールし、ポップアップの表示に従いアカウントの初期設定などをします。 初期設定が完了し、Postmanを起動すると以下の画面が開かれます。左上の「Import」を押します。

f:id:cmt_192cm:20200623164011p:plain
Importボタン
OneLogin APIのToken API Postman Collectionをダウンロードします。一旦Postmanの画面を離れ、OneLogin APIのリファレンスのトークンに関するページを開きます。

developers.onelogin.com

ページ最下部までスクロールし、「Download」ボタンを押します。

f:id:cmt_192cm:20200623164135p:plain
Postman Collectionダウンロード
ダウンロードしたファイルをPostmanにインポートします。そして、右上の「Import」を押します。「NAME」が「OAuth 2.0 Tokens」となっていることを確認します。
f:id:cmt_192cm:20200623164248p:plain
Postman Collectionインポート

環境変数の設定

インポート完了後、左にある「Collection」タブを展開します。

f:id:cmt_192cm:20200623164828p:plain
Collectionタブ
先ほどインポートしたOneLogin APIトークンに関するPostman Collectionが表示されます。「OAuth 2.0 Tokens」フォルダを展開し、「Generate Tokens」を押します。
f:id:cmt_192cm:20200623170738p:plain
Generate Tokensの展開
この画面で赤色で{{xxx}}となっている文字はPostmanにおける環境変数です。事前に環境変数を設定することで簡単にOneLogin APIのリクエストを実行することができます。 具体的にはClient IDやClient Secretなどの認証情報を登録することにより、OneLogin APIを利用するときに「Generate Tokens」のリクエストを「Send」ボタンを押して実行するだけで最新のAccess Tokenを取得できるなど、メリットが多数あります。
f:id:cmt_192cm:20200623170819p:plain
環境変数
画面が遷移したあと、右上の「歯車マーク」を押します。
f:id:cmt_192cm:20200623171204p:plain
環境変数の設定
右下の「Add」を押します。
f:id:cmt_192cm:20200623171341p:plain
環境の追加
その後、環境変数名を入力します。OneLoginの先ほどのAPI Credentialsの画面から以下の値を入力します。以下の4種類の環境変数は入力が必須です。入力後、右下の「Add」を押します。そして右上の「✕」を押します。
f:id:cmt_192cm:20200623171710p:plain
環境変数の追加

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」)を選択します。

f:id:cmt_192cm:20200623172120p:plain
環境の変更
その後、設定したすべての環境変数{{xxx}}の上にカーソルを合わせ、以下のように緑が表示されることを確認してください。緑となっていれば環境変数は適切に値が代入されております。赤となっている場合は環境変数に適切に値が代入されておりません。その際は環境変数の名前が適切であるか、そして環境は先ほど作成した環境となっているかを確認してください。
f:id:cmt_192cm:20200623172637p:plain
環境変数の確認
環境変数に適切に値が代入されていることを確認したあと、右上の「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形式で取得することができます。

f:id:cmt_192cm:20200623173843p:plain
OneLogin Users API

POSTメソッドを使用する

ここではPOSTメソッドを使用する例としてOneLogin Users APIを用いて、OneLoginのUserを作成します。この操作を行うためにはPOSTコールが可能であるManage Users / Manage All権限を持ったAPI Credentialで行う必要があります。新しくAPI Credentialを作成した場合は、その都度Postmanにて環境を新規に作成し、環境変数の値を代入する必要があります。

User v1フォルダを展開し、「Create a User」を押します。そして、「Body」タブを展開します。

f:id:cmt_192cm:20200623174244p:plain
Create a UserのBodyタブ展開
以下の画像のように登録するUserの情報を入力します。
f:id:cmt_192cm:20200623174612p:plain
登録するUser情報

{
  "firstname":"api",
  "lastname":"test",
  "email":"api@test.com",
  "username":"api_test"
}

入力後、「Send」ボタンを押します。

POSTが成功した場合は以下のようにmessageがSuccess、そしてその下に登録したUserの情報が表示されます。

f:id:cmt_192cm:20200623174704p:plain
POSTが成功したときの挙動

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タブで環境変数への代入を行っているからです。

f:id:cmt_192cm:20200624132551p:plain
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をたくさん使用してみてください!

developers.onelogin.com