Access Token について

先日のブログ記事 Web ブラウザのデベロッパーツールについて で少し触れたこともあるので、今回は Forge を利用する上で重要になる Access Token について、まとめておきたいと思います。

Access Token は、Forge に限らず、Web 開発の世界では一般的なもので、アプリがサーバー（クラウド）上にあるリソースにアクセスする権限があるかチェックする仕組みを提供します。Forge の場合、2-legged、3-legged の違いを考えずに単純に考えると、下図のアニメーションのようになります。

Forge を利用しようとする開発者は、まず、Autodesk ID を使って Forge ポータル（https://forge.autodesk.com）にサインインし、アプリを登録する作業をおこないます。
アプリを登録すると、一意な Client ID と Client Secret が発行され、Web ページ上に文字列として表示されます。ここまでの 1.～ 2. の手順については、Forge API を利用するアプリの登録とキーの取得 で詳しく説明しています。
開発者は 2. で取得した Client ID と Client Secret をアプリ内のコードに書き込み、OAuth シナリオ に合わせた Forge Authentication API の endpoint 呼び出しをおこないます。
Forge サーバーから Access Token を含む JSON レスポンスが返されます。

先に触れたブログ記事 Web ブラウザのデベロッパーツールについて のとおり、セキュリティ上の理由から、クライアント（Web ブラウザ）の JavaScript コードから Authentication API の endpoint を呼び出すと、CORS エラーが発生して Access Token を取得することは出来ません（Access-Control-Allow-Origin: * などを返さない）。このため、Authentication API はサーバー実装でおこなうことになります。

Authentication API によって返されるのは、Access Token を含む JSON です。

{
    "access_token": "eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0.eyJjbGllbnRfaWQiOiJ1MzZUa2lhQVpmUnRJa2p0S2ZzR0FtdXo2NEJNenZmdyIsImV4cCI6MTU0MTEzNDg0MSwic2NvcGUiOlsiYnVja2V0OmNyZWF0ZSIsImJ1Y2tldDpyZWFkIiwiZGF0YTpyZWFkIiwiZGF0YTp3cml0ZSIsImRhdGE6Y3JlYXRlIl0sImF1ZCI6Imh0dHBzOi8vYXV0b2Rlc2suY29tL2F1ZC9qd3RleHA2MCIsImp0aSI6InBvSkhpVlBMeFp6NG1wQkxSbG5raUpiQWpHN1BEeXpBa1M4ZElBZVV1TDZSdkcyUUprUTZTQ0JJOW9rSVJNMk8ifQ.Fr4lUU21AfbDcIRBvMWlOXtxd0zjd9E7Tj2V6w6pp8U",
    "token_type": "Bearer",
    "expires_in": 3599
}

実際の Access Token となる文字列は JSON 内に含まれる "access_token" キーの値として格納されています。また、"token_type" は、Forge で扱う Token のタイプである Bearer（ベアラ）を示しています。なお、Forge で利用する Access Token には、有効期限が設定されています。有効期限を示すのが "expires_in" キーの値として格納されている秒数を表す数字です。

先の JSON 例では、Accesss Token が eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0.eyJjbGllbnRfaWQiOiJ1MzZUa2lhQVpmUnRJa2p0S2ZzR0FtdXo2NEJNenZmdyIsImV4cCI6MTU0MTEzNDg0MSwic2NvcGUiOlsiYnVja2V0OmNyZWF0ZSIsImJ1Y2tldDpyZWFkIiwiZGF0YTpyZWFkIiwiZGF0YTp3cml0ZSIsImRhdGE6Y3JlYXRlIl0sImF1ZCI6Imh0dHBzOi8vYXV0b2Rlc2suY29tL2F1ZC9qd3RleHA2MCIsImp0aSI6InBvSkhpVlBMeFp6NG1wQkxSbG5raUpiQWpHN1BEeXpBa1M4ZElBZVV1TDZSdkcyUUprUTZTQ0JJOW9rSVJNMk8ifQ.Fr4lUU21AfbDcIRBvMWlOXtxd0zjd9E7Tj2V6w6pp8U、有効期限が 3599 秒（約 60 分）ということになります。

取得した Access Token は、Forge の RESTful API を呼び出す際に、Header（ヘッダー）に指定して endpoint を呼び出すことで、リソースへのアクセス権を行使することが出来ます。もし、この Access Token の有効期限を過ぎてしまった際には、endpoint の呼び出しに失敗することになります。その場合には、再度 Access Token を取得しなおす必要があります（3-legged の場合は RefreshToken リクエストで Access Token を更新します）。

次のアニメーションは、2-legged OAuth を使って Bucket を作成、デザインファイルを当該 Bucket にアップロード後に変換し、Viewer に表示する過程を Access Token を明記したイメージです。

余談となりますが、オートデスクは Access Token のタイプを過去に 1 度変更しています。詳細は Access Token タイプの変更について の記事に譲りますが、Access Token の長さが最大 500 桁に及ぶ場合がある点に注意してください。Forge 登場後、しばらくの間、View and Data API から引き継いだ Reference Token タイプを採用していましたが、この頃、Access Token は比較的短い文字列として扱うことが出来ました。現在の JSON Web Token (JWT) タイプでは Access Token が可変長となるため、変数等に格納してプログラムで利用する際には、文字列領域の確保に配慮する必要があります。

Accesss Token については、もう 1 つ、Forge 登場後に変更を受けた点にがあります。Scope 指定なしで Access Token を利用している方へ でもご案内していますが、Access Token 発行時にアクセスレベルを指定する Scope です。Scope は、Forge を利用するアプリに対し、Forge サーバー（クラウド）側のリソースアクセスに必要な権限を与えるか否かを指定するもので、Authentication API 呼び出し時に次の文字列を使って指定します。十分な Scope を指定せずに Access Token を取得した場合、その Access Token を指定した endpoint 呼び出しに失敗する可能性があります。

例えば、上図の例で Bucket を新規に作成してデザインファイルをアップロードするシナリオをご案内しました。この場面で、Bucket を作成するための POST buckets endpointの呼び出す時に、bucket:create を Scope 指定せずに取得した Access Token を与えてしまうと、401 UNAUTHORIZED のエラーコードとともに呼び出しに失敗することになります。

各 endpoint の API リファレンスには、当該 endpoint 呼び出しに必要な Scope が記載されているので、あらかじめ必要となる Scope 値を把握することが出来るはずです。

なお、取得した Access Token で異なる endpoint を呼び出す必要がある場合には、Scope 文字列を半角スペースで区切って、複数の Scope 文字列を指定することも可能です（例："bucket:create bucket:read data:read data:write data:create"）。

Scope には Bucket を削除する bucket:delete が定義されていますが、実際の Bucket を削除する endpoint は非公開になっていて利用することは出来ません。

逆に、不要な Scope を指定してしまうと、取得した Access Token を悪用される危険性がある点にご注意ください。クライアント（Web ブラウザ）上で Forge Viewer を使って 3D モデルや 2D 図面を表示するだけなら、viewables:read の Scope で十分なはずです。この場面で不要な data:write を指定してしまと、Access Token が悪意のあるマルウェアなどに読み取られた場合、クラウド上のストレージにアクセスされてデータを書き換えられたり、削除されたりしてしまう可能性があります。

By Toshiaki Isezaki