ソリューション概要（SPAs + API）

ExampleCo は、Timesheets API へのアクセスを許可されたユーザーおよびアプリケーションのみに制限するため、OAuth 2.0 認可フレームワークを採用することにしました。このフレームワークは、さまざまなグラントによって Timesheets API と通信する必要がある各種アプリケーションを容易に認可できるため、同社が求める柔軟性を提供します。

API の認証と認可

API は、アプリケーションの機能をほかのアプリケーションに公開するための仕組みです。アプリケーションは、API のエンドポイントにメッセージを送信してリクエストを行い、そのレスポンスとして情報を受け取ります。 API エンドポイントは、保護されている場合とそうでない場合があります。このケースでは、タイムシートはレビューや支払いに影響する機微な情報であるため、認可されたユーザーとアプリケーションだけが API のエンドポイントを呼び出せるようにすることが重要です。クライアントアプリケーションが API の保護されたエンドポイントにアクセスするには、そのエンドポイントを呼び出すために必要な権限を持っていることを示す証明として、を提示する必要があります。アクセストークンは、でユーザーを認証することで取得され、その後ユーザーは自分に代わって API にアクセスすることをアプリケーションに許可できます。

アクセストークンとは何ですか?

アクセストークン (access_token とも呼ばれます) は、アプリケーションに発行された認可を表す不透明な文字列です。これは、認可情報を取得するための識別子を示す場合もあれば、認可情報 (たとえば、ユーザーのアイデンティティや権限など) そのものを検証可能な形で含む場合もあります。アクセストークンが JSON Web Tokens として実装されることは、ごく一般的です。Auth0 のアクセストークンの詳細については、アクセストークンを参照してください。

API では、公開しているさまざまなエンドポイントに対して、誰がアクセスできるかをきめ細かく制御できます。これらの権限はスコープとして表現されます。ユーザーがクライアントアプリケーションを認可するとき、アプリケーションは必要な権限を指定することもできます。ユーザーはその権限を確認し、付与できます。これらの権限は、その後アクセストークンの scope クレームに含まれます。その後、クライアントが API へのリクエスト時にアクセストークンを渡すと、API は scope クレームを確認して、その特定の API エンドポイントを呼び出すために必要な権限が付与されていることを検証できます。

スコープとは何ですか?

各アクセストークンには、クライアントに付与された権限の一覧を含めることができます。クライアントが Auth0 で認証する際は、要求するスコープ (または権限) の一覧を指定します。それらのスコープが認可されると、アクセストークンには認可済みスコープの一覧が含まれます。たとえば、タイムシート API は 4 種類の認可レベルを受け付ける場合があります。タイムシートの読み取り (スコープ read:timesheets) 、タイムシートの作成 (スコープ create:timesheets) 、タイムシートの削除 (スコープ delete:timesheets) 、タイムシートの承認 (スコープ approve:timesheets) です。クライアントが API に新しいタイムシートエントリの作成を要求する場合、アクセストークンには create:timesheets スコープが含まれている必要があります。同様に、既存のタイムシートを削除するには、アクセストークンに delete:timesheets スコープが含まれている必要があります。スコープの詳細については、スコープを参照してください。

認可フレームワークを使用すると、自社のアプリケーションやサードパーティアプリケーションに対して、アプリケーション自身に代わって API への限定的なアクセス権を付与できます。Auth0 を使用すれば、OAuth 2.0/ Connect (OIDC) 仕様や、API 認可に関する数多くの技術的な側面を気にすることなく、自身の API でさまざまなフローを簡単にサポートできます。

OAuth の役割

OAuth 2.0 のフローには、次の役割があります。

リソースオーナー: 保護されたリソースへのアクセスを許可できる主体です。通常はエンドユーザーです。
リソースサーバー: 保護されたリソースをホストするサーバーです。つまり、アクセス先の API です。
クライアント: リソースオーナーに代わって、保護されたリソースへのアクセスを要求するアプリケーションです。
認可サーバー: リソースオーナーを認証し、適切な認可を得た後にアクセストークンを発行するサーバーです。この場合は Auth0 の Authentication API です。

グラントタイプ (またはフロー) は、これらの参加者がどのようにやり取りし、アプリケーションに構築中の API への限定的なアクセスを付与するかを決定します。その結果、アプリはアクセストークンを取得し、それを使用してユーザーに代わって API を呼び出せます。

Implicit Grant

OAuth 2.0 では、さまざまなユースケースに対応する複数のグラントタイプが提供されています。このユースケースでは、クライアントサイドアプリから API にアクセスします。そのため、SPA は Implicit Flow (Implicit Grant) を使用します。 Implicit Grant (RFC 6749, section 4.1 で定義) は、Authorization Code Flow で使用されるグラントと似ていますが、主な違いは、アプリケーションが authorization_code を必要とせず、アクセストークンを直接受け取る点です。これは、通常はブラウザー内で実行される JavaScript アプリであるこのアプリケーションが、サーバー上で実行される Web アプリよりも信頼性が低く、client_secret (Authorization Code Grant で必要) を安全に扱えるとは見なされないためです。ユーザーが認証されると、アプリケーションは URI のハッシュフラグメントでとアクセストークンを受け取ります。アプリケーションは、IDトークンを使用してユーザーに関する情報を取得し、アクセストークンを使用してユーザーに代わって API を呼び出せるようになります。

アプリはフローを開始し、ユーザーが認証できるように、ブラウザーを Auth0 (具体的には認可エンドポイント /authorize) にリダイレクトします。
Auth0 がユーザーを認証します。ユーザーが初めてこのフローを実行し、かつアプリケーションがサードパーティアプリケーションである場合は、クライアントに付与される権限 (たとえば、メッセージの投稿、連絡先の一覧表示など) を示す同意ページが表示されます。
Auth0 は、URI のハッシュフラグメントにアクセストークン (必要に応じて IDトークンも) を付加して、ユーザーをアプリにリダイレクトします。これでアプリは、ハッシュフラグメントからトークンを取り出せます。
アプリは、アクセストークンを使用して、ユーザーに代わって API を呼び出せます。

Authorization Extension

Auth0 Authorization Extension を使用すると、Roles、Groups、Permissions を設定し、それらをユーザーに割り当てることができます。

Permissions は、ユーザーが実行できる操作です。ExampleCo の業務要件では、4 つの Permissions (read、create、delete、approve timesheets) を設定します。
Roles は Permissions の集合です。ExampleCo の timesheets アプリは 2 種類のユーザー (employees と managers) が使用し、それぞれに異なる権限が必要なため、2 つの Roles (employee と manager) を設定します。

この要件はこれで満たされるため、Groups は作成しません。 Authorization Extension は、ユーザーに割り当てられた Roles、Groups、Permissions を読み取り、この情報を認証フロー中にユーザープロファイルに追加する Rule を作成します。この情報を使用することで、ユーザーに発行されるアクセストークンに許可されたスコープのみが含まれるようにできます。その後、ユーザーに必要な権限がない場合は Approve Timesheets 機能を無効にする、といった形でアプリをカスタマイズできます。

​API の認証と認可