Forge での OAuth 認証シナリオ

インターネットの世界では、特定のメンバーしかアクセス出来ないようなや Web サイトやサービスを提供する際に、しばしば、ユーザ名とパスワードによって、 Web サイトにアクセスしようとする人が本人か否かをチェックする 認証（Authentication） をおこないます。一方、認証が完了してサイトに入った後には、その人がどのデータにアクセス出来るか、適切に 認可（Authorization） されてデータにアクセスすることになります。

API を使用して特定のデータにアクセスする場合には、その API を使用したアプリ（またはサービス）の認証をしたり、そのサービスやアプリがアクセスできるデータを許可する必要があります。場合によっては、第三者のみにアクセスが許可されたデータにアクセスしなければならない場合もあります。Forge Platform API では、これらを円滑に処理するため、オープンスタンダードとなっている OAuth 2.0 をサポートすることで、認証と認可を得る仕組みを提供しています。

OAuth を使用する Forge Platform の OAuth API では、API を利用するアプリに対して、2-ledgged 認証と 3-legged 認証の両者をサポートしています。いずれの場合でも、事前にデベロッパポータル（https://developer.autodesk.com/）でアプリを登録して、Consumer Key と Consumer Secret を取得しておく必要があります。

Forge ポータルでのアプリ登録の手順は、ブログ記事 Forge API を利用するアプリの登録とキーの取得 でご紹介しています。なお、Consumer Key と Consumer Secret は、それぞれ、Client ID と Client Secret と表記される場合があります。

2-legged 認証と 3-legged 認証の違いと目的は、次のとおりです。

2-legged 認証

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

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

3-legged 認証

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

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

このように、3-legged 認証では、サービスプロバイダー（オートデスク）とユーザー（Forge API を利用する開発者）の他に、エンドユーザーが登場します。これが、3-legged と呼ばれる所以です。

2-legged 認証のワークフロー詳細

前述のとおり、 2-legged 認証では、アプリがオートデスクが用意する OSS（Object Storage Service） API を使って、一意な名前の Bucket を作成し、データ変換や Viewer への表示をおこないます。

開発者が最初におこなわなければならないのは、Forge ポータルでアプリ登録して Consumer Key と Consumer Secret を取得することです。

※ Consumer Key と Consumer Secretは、ユーザー名とパスワードに相当するものになるので、他人に知られたりしないように注意しなければなりません。第三者に流出してしまった場合には、最悪、アプリが使用する Bucket にアクセスされる可能性があります。

Forge API を利用するアプリが OSS に Bucket を作成するには、Consumer Key と Consumer Secret を用いて Access Token（アクセストークン）を生成します。Access Token は通行手形のようなもので、API 呼び出し時に正当な Access Token を示せないと、呼び出しに失敗します。実際には、各種 RESTful API を呼び出す際に、HTTP ヘッダーに Access Token を指定することになります。

Access Token には、有効期限があり、authenticate リクエスト（https://developer.autodesk.com/en/docs/oauth/v2/reference/http/authenticate-POST/）で返される JSON レスポンスの expires_in 値（秒単位）で示されます。Access Token を取得して、expires_in にある秒数が経過すると、Access Token が無効になります。この状態で Access Token の指定が必要な RESTful API を呼び出すと 401 Unauthorized エラーとなってアクセスに失敗します。

2-legged 認証をおこなうアプリで Access Token が失効した場合には、単純に、再度、 2-legged 認証をおこなって Access Token を生成し直します。その後の RESTful API を呼び出しには、新しい Access Token を指定します。

2-legged 認証時に意識しなければならない点に Scope の指定があります。Scope はアクセス可能な範囲を指定するもので、1 行で指定する必要があります。例えば、Bucket 作成には bucket:create、作成した Bucket へのアクセスに bucket:read、Bucket へのファイルのップロードと変換に data:write、変換されたドキュメントの呼び出しに data:read を指定するには、

'bucket:create bucket:read data:read data:write'

のように半角スペースで区切って指定してください。

※ 旧 View and Data API 利用時には OSS API v1 （バージョン 1）を使用しており、Scope の指定は不要でした。2016 年6月に View and Data API が OAuth API、Model Derivative API 等に分離された時点で、OSS API v2 に変更され、同時に Scope 指定が導入されています。

3-legged 認証のワークフロー詳細

3-legged 認証でも、Consumer Key と Consumer Secret から生成される Access Token が必要です。また、Access Token に有効期限がある点と、Scope でアクセス範囲を指定しなければならない点も同様です。2-legged 認証との違いは、アクセスするデータが OSS のAPI 共有領域ではなく、第三者であるエンドユーザーだけがアクセス出来る外部のストレージ領域に格納されている点です。

3-legged 認証時には、エンドユーザーに代わってデータが保存されているクラウドストレージへのアクセスするため、その同意を得る必要があります。まず、クラウドストレージにアクセスする認証画面を表示させてサインインを促します。

サインインが完了すると、指定した Scope に沿ったアクセス権限をアプリに付与するか、同意を求める画面が表示されます。

エンドユーザーの同意が得られると、デベロッパポータルでアプリ登録した際に指定した Callback URL にリダイレクトされて、Access Token の生成処理に入ります。

前述のとおり、3-legged 認証で生成した Access Token にも有効期限があります。2-legged 認証とは異なり、新規に Access Token を生成する際には、エンドユーザーのサインインが再度必要になってしまいます。その手順も含めて、有効期限が切れた場合に選択可能な処理には、次の 2 つが考えられます。

有効期限が切れた旨を表示し、エンドユーザーに再度クラウドサービスへのサインインを促す。
初回に gettoken リクエスト（https://developer.autodesk.com/en/docs/oauth/v2/reference/http/gettoken-POST/）で Access Token を取得した際、同時に JSON レスポンスから得られる refresh_token をサーバー側に保持しておく。有効期限が切れた際には、保持していた refresh_token 値を利用して、Access Token をリフレッシュ（更新）する。Access Token のリフレッシュには、refreshtoken リクエスト（https://developer.autodesk.com/en/docs/oauth/v2/reference/http/refreshtoken-POST/）を使用します。この場合、エンドユーザーへのサインイン処理を抑止することが出来ます。なお、refresh_token をサーバー側に保持する理由は、純粋にセキュリティ保護のためです。

どちらを選択するかは、アプリを開発する開発者の判断に依存することになります。