APS アクセス：2-legged と 3-legged

Autodesk Platform Services（APS）でエンドポイントを呼び出す際には、言うまでもなくアクセストークン（Access Token）が必要となります。アクセストークンは Client ID と Client Seret を元に Authentication API（OAuth API）を使って取得します。そして、アクセストークンの取得フローには、大きく 2-legged 認証と 3-legged 認証の 2 つのフローがあります。

2-legged 認証

"app-context（アプリケーションコンテキスト）" とも呼ばれる認証で、 APS API を利用するアプリが、直接、オートデスクのサーバーからアクセストークンを取得して、OSS（Object Storage Service）のAPI 共有領域に作成した Bucket にアクセスする際に使用します。旧 View and Data API で利用していた認証は、この方法によるものです。

2-legged と呼ばれるのは、サービスプロバイダー（オートデスク）とユーザー（APS API を利用する開発者）の 2 者が登場するためです。

3-legged 認証

"user-context（ユーザーコンテキスト）" とも呼ばれる認証で、第三者がアクセス権限を持つデータやサービスに、明示的な Web インタフェースを介してアクセスする権限を付与してもらう仕組みを実装することが出来ます。

例えば、Autodesk Construction Cloud（ACC） では、通常、エンドユーザーは、そのユーザーだけがアクセスを許可されたストレージ領域を持つことが出来ます。他のユーザーはそのストレージ領域にはアクセス出来ません。もし、アプリが ACC のユーザーストレージ領域（Autodesk Docs）にあるデータにアクセスする場合には、ACC のサインイン画面を表示させて同ユーザーにユーザー名（Autodesk ID）とパスワードを入力してもらい、アプリのアクセスを許可（認可）してもらう必要があります。

このように、3-legged 認証では、サービスプロバイダー（オートデスク）とアプリ（APS AP を利用するアプリ）の他に、データの所有権（ストレージのアクセス権）を持つエンドユーザーが登場します。これが、3-legged と呼ばれる所以です。

なぜ、2 つの認証フローが存在するのか？

APS に初めて、特に RESTful API に初めて触れる場合、この違いに戸惑われる方も多いようです。ここで 1 つの指標になるのが、APS へのアクセス目的です。具体的には、開発するアプリがオートデスクのクラウド製品のストレージ領域にアクセスする、また、オートデスクのクラウド製品の機能を利用する場合には 3-legged、そうでない場合には 2-legged といった区分けです。

Data Management API の Developer's Guide の API Basics ページには、次のような記述があります。

ご注目いただきたいのは、赤い下線を引いた記述です。Forge 時代から継承しているドキュメントなので、少し製品名が古くなっていますが、現時点で新規に購入可能なものに置き換えて意訳すると、次のようになります。

Fusion Team にアクセスする場合、エンドユーザーがデータにアクセスするには、APS アプリに 3-legged 認証フローで得たアクセストークンを提供する必要があります。
Autodesk Docs（Autodesk Construction Cloud）にアクセスする場合、Account Admin が Autodesk Construction Cloud（ACC）で「カスタム統合」を使ってアプリを追加する必要があります。APS アプリは、2-legged 認証フローまたは 3-legged 認証フローのいずれかで得たアクセストークンを使用してデータにアクセスできます。

ここで最初にご紹介した認証の意味合いを思い出してください。APS を利用するアプリが、Fusion Team、Autodesk Construction Cloud（ドキュメント層が Autodesk Docs）に保存したデータにアクセスする際には、データ所有者にアクセス許可（認可）を得る必要があります。つまり、原則、3-legged 認証フローでアクセストークンを取得する必要があります。

ただ、1 つ問題が出て来ます。3-legged 認証フローで特定のユーザーにアクセス許可を得た場合、そのアクセストークンを使用するアプリは、同ユーザーがアクセス権を持つデータ（プロジェクト、フォルダー、ファイル）にしかアクセスすることが出来ません。

開発する APS アプリの機能にも依りますが、複数のプロジェクトへのアクセスが必要なアプリの場合、それぞれのプロジェクトにアクセス権も持つユーザーにサインインしてもらい、都度、アクセス許可を得るのはナンセンスです。強力なユーザーロールやアクセス権の設定が可能な ACC へのアクセスでは、特に問題になります。

ユーザー権限を越えたアクセス

そこで考え出されたのが、2-legged 認証フローを使ったアクセスです。ACC へのアクセスに 2-legged 認証フローで得たアクセストークンを使うと、Account Admin と同じく、アプリはスーパーユーザー権限ですべてのプロジェクトにアクセス出来るようになります。これによって、プロジェクトを横断的にアクセスして、さまざまなデータから包括的なインサイト（洞察）を視覚化出来る等の利点が生まれます。

予期しないアクセスへの懸念

すべてにアクセス出来る 2-legged 認証フローを使ったアプリには、懸念が提起されることもあります。そういった懸念を完全に払拭することは出来ないかもしれませんが、安全弁のような機能があります。それが前述で触れた「カスタム統合」の仕組みです。

APS アプリには、APS API を利用するアプリの登録とキーの取得の手順で取得した Client ID と Client Secret が必要です。ACC にアクセス、あるいは、ACC API を利用するアプリは、事前に Client ID を「カスタム統合」で ACC アカウント（ハブ）に登録しなければなりません。

「カスタム統合」の具体的な手順は、次の記事でご案内しています。

逆に言えば、「カスタム統合」していない APS アプリは、2-legged 認証フォロー、3-legged 認証フローに関係なく、ACC にアクセスすることは出来ません。また、「カスタム統合」の処理は、Account Admin 権限のユーザーが ACC にサインインして実施することが必須です。

また、いつでも「カスタム統合」で登録した Client ID の登録を解除することも出来ます。もちろん、解除された Client ID を持つ APS アプリは、ACC へのアクセスを拒否されます。

2-legged 認証でのユーザーコンテキスト

スーパーユーザーとしてACC のデータアクセスが可能な 2-legged 認証フローですが、特定のユーザーに代わって処理をする必要がある場合も出てくる場面があります。ACC にファイルをアップロードしてバージョン登録するような場面です。

例えば、アプリケーションコンテキストとなるアプリでは、特定のユーザーと関連づけられていないため、ユーザーインターフェース上、アップロードしたユーザーは「ACC システム」になってしまいます。Upload a Files の手順で利用する POST projects/:project_id/items エンドポイントでは、リクエストヘッダーの説明が次のように記されています。

先と同じように、赤い矩形内の x-user-id ヘッダーパラメーターの記述を意訳すると、次のようになります。

2-legged 認証フローを使ったアプリコンテキストでは、アプリは SaaS 統合ユーザーインタフェースで管理者が指定したすべてのユーザーにアクセスできます。ただし、x-user-id ヘッダーパラメーターを指定することで、エンドポイント呼び出しは、指定されたユーザーの代理として動作するように制限されます。
3-legged 認証フロー、またはユーザー代理（x-user-id ）の 2-legged 認証フローでは、ユーザーは指定されたフォルダー（data.attributes.relations.parent.data.id ）にファイルをアップロードする権限を持っている必要があることに注意してください。

x-user-id で指定する値は、GET OIDC User Info エンドポイントで返されるレスポンスの sub フィールドから取得することが出来ます。 GET OIDC User Info エンドポイントの呼び出しには、3-legged 認証フローで取得したアクセストークンが必要です。

ACC ユーザーの x-user-id をリストするには、2-legged 認証フローで取得したアクセストークンを用いて、GET users エンドポイントレスポンスの uid フィールドから取得することが出来ます。

認証フローの違いによるオートデスク製品へのデータアクセス

認証フローによる ACC と Fusion Team へのデータアクセスの違いをまとめると、次のようになります。