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

Server + API アーキテクチャシナリオ向けソリューション概要

ExampleCo は、認可されたユーザーとアプリケーションだけに Timesheets API へのアクセスを許可するために、OAuth 2.0 認可フレームワーク を採用することにしました。このフレームワークには、Timesheets API と通信する必要があるさまざまな種類のアプリケーションを、異なるグラントを通じて容易に認可できるという柔軟性があります。

​

OAuth 2.0

OAuth 2.0 認可フレームワークを使用すると、ExampleCo の Regular Web アプリケーションと外部契約者向けのサードパーティアプリケーションは、Timesheets API への限定的なアクセス権を持てます。Auth0 を使用すれば、ExampleCo は OAuth 2.0/OpenID Connect (OIDC) の仕様や、API 認可に関する数多くの技術的な詳細を意識することなく、さまざまなグラントタイプや認証フローを簡単にサポートできます。

OAuth のロール

OAuth 2.0 のフローでは、次のロールを識別できます。

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

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

​

クライアントクレデンシャルグラント

OAuth 2 には、さまざまなユースケースに対応する複数のグラントタイプがあります。タイムシートを cron ジョブが API 経由でアップロードするこのユースケースでは、cron ジョブに API へのアクセス権限を付与するインタラクティブなユーザー (または リソースオーナー) は存在しません。

また、cron ジョブは特定のユーザーに代わって API 呼び出しを行うわけでもありません。代わりに、アプリケーション (cron ジョブ) はマシン間の認可を使用して、自身のために リソースサーバー (API) に対して呼び出しを行います。

このようにユーザー操作が関与しない状況では、クライアントクレデンシャルグラント が最適です。クライアントクレデンシャルグラント (RFC 6749, section 4.4 で定義) では、アプリケーションは自身のクライアントクレデンシャル (クライアントID と クライアントシークレット) を使用して、アクセストークン を 認可サーバー に直接リクエストできます。リソースオーナーを識別する代わりに、このトークンはアプリケーション自体を表します。

1. アプリケーションは、クライアントID と クライアントシークレットを使用して認可サーバーに認証します。
2. 認可サーバーはこの情報を検証し、アクセストークンを返します。
3. アプリケーションは、アクセストークンを使用して、自身のためにリソースサーバーを呼び出すことができます。

​

API認証と認可

API は、アプリケーションの機能を他のアプリケーションに公開するための仕組みです。他のアプリケーションは API エンドポイントにリクエストを送信し、レスポンスを受け取ることができます。同様に、ExampleCo の委託先担当者が使用する外部アプリケーションは、タイムシート API だけでなく、ExampleCo が社内従業員向けに構築した Regular Web Application とも通信できます。

タイムシート API は機密性の高い情報 (PII や財務情報など) を扱うため、ExampleCo は、認可されたユーザーとアプリケーションだけがそのエンドポイントを呼び出せるようにする必要があります。

​

アクセストークンとスコープ

API は保護することも、保護しないこともできます。アプリケーションが API の保護されたエンドポイントにアクセスするには、必要な権限を持っていることの証明として、アクセストークン (access_token とも呼ばれます) を提示する必要があります。

アクセストークンは、アプリケーションに対して発行された認可を表す不透明な文字列で、認可サーバーでユーザーを認証することで取得されます。その後、ユーザーは自分に代わって API へアクセスすることをアプリケーションに認可できます。詳細については、Access Tokens を参照してください。

Timesheets API のような API では、公開されているさまざまなエンドポイントに誰がアクセスできるかを細かく制御できます。これらの権限はスコープとして表現されます。

ExampleCo の Regular Web Application またはサードパーティアプリケーションが、アクセストークンを取得するために Auth0 で認証を行う際、認証リクエストにはアプリケーションが必要とする要求済みスコープの一覧が含まれます。それらのスコープが許可されると、アクセストークンにはアプリケーションに付与された認可済みスコープの一覧が含まれます。

Regular Web App またはサードパーティアプリケーションは、Timesheets API にリクエストを送信する際に、認可サーバーから取得したアクセストークンを含めます。Timesheets API は scope claim を確認し、その特定のエンドポイントを呼び出すために必要な権限が付与されていることを検証します。

たとえば、timesheet API では 4 つの異なる認可レベルを受け付ける場合があります。タイムシートの読み取り (スコープ read:timesheets) 、タイムシートの作成 (スコープ create:timesheets) 、タイムシートの削除 (スコープ delete:timesheets) 、タイムシートの承認 (スコープ approve:timesheets) です。

スコープの詳細については、Scopes を参照してください。

Regular Web App が新しいタイムシートエントリを作成するために Timesheets API にリクエストを送信する場合、アクセストークンには create:timesheets スコープが含まれている必要があります。含まれていない場合、リクエストは拒否されます。同様に、既存のタイムシートを削除するには、アクセストークンに delete:timesheets スコープが含まれている必要があります。

詳細については、Scopes を参照してください。