この記事はオルターブース Advent Calendar 2022の21日目の記事です。
マウスポインターをよく見失うようになってきたので、大きさを一段階大きくしました。
老眼ルーキーの木本です。
毎年恒例のアドベントカレンダー。8日目を担当した加来が書いているように、このアドベントカレンダーは弊社社員にとって【鉄の掟】のひとつですので、1人の例外もなく全社員が参加します。
ブログのようにまとまった文章からは、普段の会話やテキストチャットからはわからない「その人の知らない一面」が見え隠れするので、毎年その年に新しく仲間になったメンバーが書いたものを読むというのが楽しみでもあります。
しかし、鉄の掟により僕も書かなければならないので、楽しんでばかりもいられません。
僕の場合はだいたい「その年の仕事の中で印象に残っているもの」をネタにしているので、今年も「なにしたっけな～？」と振りかえってみたのですが、「そういえば、あのツールをよく使ったなぁ」と思い当たったものがあるので、それについて書きます。
そのツールとは・・・じゃじゃん！！
Postman！！
誰ですか、「いまさらかよ・・・」って言ったのは。
API開発をしている人にはもうすっかりお馴染みで「いまさら感」のあるPostmanですが、これから使いはじめるという方もまだまだ多いと思いますので、今回はそういった「Postman初心者」のアナタに向けて書きますよ。
そう、そこのアナタです。
Postmanというのは、ザックリ一言で言うと「API開発ツール」です。
設計、テスト、ドキュメント、モック作成、APIの共有など、様々なツールが統合されていますが、最も使用されているのはAPIを簡単に動作検証できる「API Client」ではないでしょうか。
というか、僕はほぼ「API Client」でAPIの動作を確認するという使い方しかしていません。
弊社はマイクロソフトのクラウドソリューションプロバイダー（CSPパートナー）なのですが、そのパートナー業務をサポートするためのAPIがマイクロソフトからたくさん提供されています。本当にたくさんあります。マジでたくさんあります。
このパートナー向けAPIを利用するためにはいろいろと前準備が必要なのですが、実行するにあたってはAzure ADを使った認証（OAuth 2.0）が必要です。
具体的には「認証コードの取得→更新トークンの取得→アクセストークンの取得→APIの呼出」という手順が必要になりますが、以前はPowerShellでコマンドをぽちぽち打ってアクセストークンを取得→Postmanにコピペという作業を行っていました。
というのも、これまではたま～に「ちょっと動かしてみる」程度だったので、これでも許容範囲だったんですね。
でも連日、様々なAPIを検証しようとするとこれがもう面倒くさい。
そもそも「コマンドを打つ」という作業があまり得意じゃないので本当に面倒くさい。
あ～も～、ホントにメンドクサイ！！
めんどうくさいぞ～！！と叫びながらググってみたら、Postman様がアクセストークンを取得してくれることがわかりました。
前置きが長くなりましたが、今回はこのPostmanを使ったOAuth 2.0認証について書きます。
※マイクロソフトのパートナー向けAPIの利用を前提にはしていますが、要は「Azure ADを使ったOAuth 2.0認証 with Postman」な話です。
Azure ADへのWebアプリ登録
まず大前提として、Azure ADへのアプリケーション登録が必要となります。
アプリケーションの登録方法については、下記のドキュメントを参考にしてください。
で、ワタクシ、ここでいきなり躓きました・・・
アプリケーションを登録する時にリダイレクトURIを設定するんですが、Postmanで認証をする場合になにを設定したらいいのかわからない。
わからないぞ～！と叫びながらググってみたら、Postmanの公式ドキュメントに書いてありました。（最初に読むべし。）
https://learning.postman.com/docs/sending-requests/authorization/#requesting-an-oauth-20-tokenlearning.postman.com
ここには黙って"https://oauth.pstmn.io/v1/browser-callback"を設定しましょう。
Postmanで必要になる情報をメモする
アプリ登録が終わったら、この後のPostmanでの設定に必要な情報をコピペしてメモしておきましょう。
まずは「アプリケーション（クライアント）ID」（①）。
次はエンドポイント。
「エンドポイント」をクリックすると各種エンドポイントが表示されますので、「OAuth 2.0 承認エンドポイント (v1)」（②）と「OAuth 2.0 トークン エンドポイント (v1)」（③）を控えておきます。
最後にクライアントシークレット（④）。
「証明書とシークレット」を開いて「新しいクライアントシークレット」をクリックして作成。画面遷移してしまうと二度と見られなくなるので「値」を確実にコピーしておきましょう。
これでAzure AD側の準備は完了です。
Postmanで認証する
それではPostmanでOauth 2.0認証を行うための設定をしていきましょう。
※この記事では、Postman Version 10.5.8を使用しています。
認証するための設定を行う
Postmanを開き、[Collection]を作成・選択すると、Collection内のリクエストで利用される共通設定の画面が表示されます。
その画面の中で[Authorization]タブをクリックして開き、以下のように設定します。
- Type：Oauth 2.0
- Add auth data to：Request Headers
- Header Prefix：Bearer
[Access Token]が空になっていますが、ここに後ほど取得するアクセストークンが設定されるので今は空のままでOK。
その下に、以下のようなメッセージが表示されていると思います。
「Edit token configuration」をクリックして、認証に必要な情報を設定していきましょう。
[Configure New Token]にはふたつのタブがありますが、まず[Configuration Options]タブから以下の通りに設定していきましょう。
- Token Name：お好きな名前をどうぞ。
- Grant Type：Authorization Code
- Callback URL：https://oauth.pstmn.io/v1/browser-callback
- Auth URL：先ほど取得した「OAuth 2.0 承認エンドポイント (v1)」（②）
- Access Token URL：先ほど取得した「OAuth 2.0 トークン エンドポイント (v1)」（③）
- Client ID：先ほど取得した「アプリケーション（クライアント）ID」（①）
- Client Secret：先ほど取得した「クライアントシークレット」（④）
- Scope：openid
- Client Authentication：Send as Basic Auth header
※わかりやすくするために、ここではClient IDとClient Secretに値を直接入力していますが、実際にはEnvironments（環境変数）に設定して利用しましょう。Environmentsで設定した方がよりセキュアに管理できますし、本番環境やテスト環境など実行環境を変更してアクセストークンを取得しなおす場合もEnvironmentsを切り替えるだけで対応できます。
Environmentsについては、以下の公式ドキュメントをご覧ください。
https://learning.postman.com/docs/sending-requests/managing-environments/learning.postman.com
続いて、[Advanced Options]タブを開いて[Resource]を設定します。
これはトークンが使用される予定のリソースまたはターゲットサービスを示すURIです。
今回利用するマイクロソフトのパートナー向けAPIの場合は "https://api.partnercenter.microsoft.com" と入力します。
必要な設定はこれでおしまいです。
アクセストークンを取得する
では、いよいよアクセストークンを取得してみます。
「Get New Access Token」をクリックすると、認証画面が出てくるのでサインインしましょう。
サインインが完了し、アクセストークンが取得できたら以下のダイアログが表示されます。
「Proceed」をクリックする（もしくは5秒間放置する）と取得されたアクセストークンが表示されます。
右上にある「Use Token」ボタンをクリックすると、先ほどまで空っぽだった[Access Token]に、いま取得したばかりのアクセストークンがセットされ、Collectionの中に作成されているリクエストでこのアクセストークンを利用できるようになります。
※その横にある「Sync Token」ボタンは取得したアクセストークンをチーム内で共有するためのボタンなので、今回は押さなくて大丈夫です。
以後アクセストークンを取得したい場合は、この手順を行うだけでOK。
ボタンをポチっとするだけでアクセストークンを取得することができるようになりました。
取得したアクセストークンをリクエストで利用するには、リクエストの[Authorization]タブにある[Type]を「Inherit auth from parent」にしておくだけ。
Collectionの中にあるリクエストの[Headers]タブを確認すると、ヘッダー情報に「Authorization」が自動追加され、取得したアクセストークンがセットされていることがわかります。
以上が、PostmanでAPI実行する際にAzure ADでOAuth 2.0認証を行う方法です。
たったこれだけで「コマンドぽちぽちェ・・・」から「ボタンぽち～！！（ファンファーレ）」になって充実のAPIライフが送れるようになるんですから最高ですよね。
GUI万歳！！
最後までお読みいただきありがとうございました。
オルターブースの【鉄の掟】アドベントカレンダーは残り4日！ adventar.org
