Postman による 3 legged 認証

以前の ブログ記事 で Postman のコレクション機能を使って、最もシンプルな 2-legged 認証 を利用した Bucket へのデザインファイルのアップロードと変換、 Viewer に表示までを、使用する endpoint とともにご紹介しました。（本記事は2022年5月更新）

今回は、同じ Postman コレクションを使って、3-legged 認証 と Viewer での表示までの手順を 2 回に渡ってご紹介していきたいと思います。

3-Legged 認証は、OSS に作成した Bucket 内のデザインファイルではなく、A360 や Fusion 360、BIM 360 などのオートデスクのクラウドサービスがアクセスするストレージ上のデザインファイルへのアクセスが目的となります。

繰り返しになりますが、2-Legged 認証との違いは、本来、Forge アプリがアクセス出来ないユーザストレージ領域へのアクセスを、ユーザからの明示的な権限付与によって可能にする点です。つまり、目的にデザインファイルが格納されているクラウドサービスへユーザにサインインしてもらってから、ユーザのストレージにアクセスする許可を得るプロセスが必要です。もちろん、使用する endpoint も 2-legged 認証のものとは異なります。

3-legged 認証では、Forge を利用するアプリは、次の手順に沿って Access Token（アクセストークン）を取得します。下図の 1. でユーザに A360 クラウドサービスにサインインするためのサインインページを表示させることになります。ここで使用する endpoint は https://developer.api.autodesk.com/authentication/v1/authorize、メソッドは GET です。同じく、下図の 4. で使用する endpoint は https://developer.api.autodesk.com/authentication/v1/gettoken、メソッドは POST です。詳細は、過去のブログ記事 Forge での OAuth 認証シナリオ の「3-legged 認証のワークフロー詳細」を確認ください。

この認証プロセスでは、上図 3. の Callback URL でリダイレクトする実装が必要になります。今回は、この処理を Postman で実現するための設定と、Access Token を取得する部分をご紹介しておきます。

Postman 上で 3 Legged 認証で使用する Callback URL は、https://www.getpostman.com/oauth2/callback に設定する必要があります。まず、Forge ポータル（https://forge.autodesk.com）に新規にアプリを作成するか登録済のアプリを編集して、Callback URL を、この値に変更してください。
続いて、Postman 側で OAuth2 の 3 legged 認証の設定をしていきます。 Postman を起動して、新しいタブ上で「Authorization」を選択します。
「Authorization」タブ名の下にある Type には、ドロップダウンリストから「OAuth 2.0」を選択します。
画面右下の [Configuration Options] タブをスクロールして値を入力していきます。
[Configuration Options] タブの各項目に、次の値を入力していきます。
- Token Name = Postman 上の保存名です。他の Postman コレクション名と同じく任意で結構です。
- Grant Type = Authorization Code （固定）
- Callback URL = https://www.getpostman.com/oauth2/callback（1. で指定）
- Auth URL = https://developer.api.autodesk.com/authentication/v1/authorize
- Access Token URL = https://developer.api.autodesk.com/authentication/v1/gettoken
- Client ID = Forge ポータルで作成したアプリ設定の Client ID
- Client Secret = Forge ポータルで作成したアプリ設定の Client Secret
- Scope = Forge アプリで必要となる Scope の値（例：data:read data:write data:create）
- State = 未指定
- Client Authentication = ”Send client credentials in body”
ここまでの設定で、3 legged 認証の準備が整いました。 [Get New Access Token] ボタンをクリックしてみてください。Autodesk ID（ユーザ名）の入力を促す画面が表示されるはずです。
Autodesk ID を入力して [ 次へ ] をクリックすると、パスワードの入力画面に遷移します。パスワードの入力後、 [ サインイン ] をクリックしてサインインを完了してください。
入力した Autodesk ID とパスワードで認証が完了すると、この Autodesk ID を持つユーザのストレージに Forge アプリがアクセスする許可を求められます。画面中央に表示されているアクセス権限は、5. で指定した Scope の内容に沿ったものとなります。
[ 許可 ] をクリックすると、Forge アプリがユーザストレージにアクセスすることを許可（認可）したことになります。
取得出来た Access Token を含むダイアログが表示されます。 [Use Token] をクリックします。
ここまでの処理で、「Access Token」欄に取得した Access Token の値が追加されているはずです。この値を利用して、RESTful 呼び出しで他の endpoint のテストをおこなうことが出来ます。

一度、使用した認証プロセスは、Token Name 名で再利用することが出来ます（ここでは Forge Access Token）。A360 などのストレージアクセスを Postman でテストする場合は、ここまでの手順で Callback URL をした 3-legged 認証 をシミュレーションすることが出来ます。次回、実際の endpoint を用いて、ストレージにアクセスしていきます。

By Toshiaki Isezaki