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

​
OAuth 2.0

認可フレームワークを使用すると、ExampleCo の Regular Web アプリケーションと外部委託業者向けのサードパーティー アプリケーションは、Timesheets API に限定的にアクセスできるようになります。Auth0 を使えば、ExampleCo は OAuth 2.0/ Connect (OIDC) の仕様や、API 認可に関する数多くの技術的な側面を意識することなく、さまざまな グラントタイプ や認証フローに簡単に対応できます。

OAuth の役割

OAuth 2.0 のフローでは、次の役割を識別できます。
  • Resource Owner: 保護されたリソースへのアクセスを許可できる主体です。通常はエンドユーザーが該当します。
  • Resource Server: 保護されたリソースをホストするサーバーです。つまり、アクセスしたい API のことです。
  • Client: Resource Owner に代わって、保護されたリソースへのアクセスを要求するアプリケーションです。
  • Authorization Server: Resource Owner を認証し、適切な認可を得た後に アクセストークン を発行するサーバーです。この場合は Auth0 の Authentication API です。
グラントタイプ (or flows) は、これらの関係者がどのようにやり取りして、構築中の API への限定的なアクセスをアプリケーションに付与するかを定めるものです。その結果、アプリはユーザーに代わって API を呼び出すために使える アクセストークン を取得します。

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

OAuth 2 には、さまざまなユースケースに対応する複数のグラントタイプがあります。今回のように cron ジョブが API 経由でタイムシートをアップロードするケースでは、cron ジョブに API へアクセスするための権限を付与する対話的なユーザー (または ) は存在しません。 また、cron ジョブは特定のユーザーに代わって API 呼び出しを行うわけでもありません。代わりに、アプリケーション (cron ジョブ) はマシン間認可を使用して、 (API) に対して自らの behalf で呼び出しを行います。 このようにユーザーの操作が関与しない状況では、Client Credentials Grant が最適です。Client Credentials Grant (RFC 6749, section 4.4 で定義) では、アプリケーションは自身のクライアント認証情報 ( と ) を使って、 から直接 をリクエストできます。このトークンは Resource Owner を識別する代わりに、アプリケーション自体を表します。
undefined
  1. アプリケーションは、Client ID と Client Secret を使用して Authorization Server に認証します。
  2. Authorization Server はこの情報を検証し、アクセストークンを返します。
  3. アプリケーションは、そのアクセストークンを使用して、自身の behalf で Resource Server を呼び出すことができます。

​
APIの認証と認可

APIは、アプリケーションの機能をほかのアプリケーションに公開するための仕組みです。ほかのアプリケーションはAPIエンドポイントにリクエストを送信し、レスポンスを受け取ることができます。同様に、ExampleCoの委託先担当者が利用する外部アプリケーションも、Timesheet APIや、ExampleCoが社内従業員向けに構築したRegular Web Applicationと通信できます。 Timesheets APIは機密情報 (PIIや財務情報など) を扱うため、ExampleCoは、認可されたユーザーとアプリケーションのみがそのエンドポイントを呼び出せるようにする必要があります。

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

API には、保護されているものと保護されていないものがあります。アプリケーションが API の保護されたエンドポイントにアクセスする場合、必要な権限を持っていることを示す証明として、アクセストークン (access_token とも呼ばれます) を提示する必要があります。 アクセストークンは、アプリケーションに発行された認可を表す不透明な文字列で、Authorization Server でユーザーを認証することで取得されます。その後、ユーザーは自分に代わって API にアクセスすることをアプリケーションに許可できます。詳しくは、Access Tokens を参照してください。 Timesheets API のような API では、API が公開しているさまざまなエンドポイントに対して、誰がアクセスできるかを細かく制御できます。これらの権限はスコープとして表されます。 ExampleCo の Regular Web Application またはサードパーティのアプリケーションが、アクセストークンを取得するために Auth0 で認証するとき、認証リクエストには、そのアプリケーションが必要とする要求対象のスコープ一覧が含まれます。それらのスコープが許可されると、アクセストークンにはアプリケーションに付与された承認済みスコープの一覧が含まれます。 Regular Web App またはサードパーティのアプリケーションは、Timesheets API へのリクエスト時に Authorization Server から受け取ったアクセストークンを含めます。Timesheets API はスコープクレームを確認し、その特定のエンドポイントを呼び出すために必要な権限が付与されていることを検証します。 たとえば、Timesheets API では 4 種類の認可レベルを受け付ける場合があります。timesheet の読み取り (スコープ read:timesheets) 、timesheet の作成 (スコープ create:timesheets) 、timesheet の削除 (スコープ delete:timesheets) 、timesheet の承認 (スコープ approve:timesheets) です。 スコープの詳細については、Scopes を参照してください。 Regular Web App が新しい timesheet エントリを作成するために Timesheets API にリクエストを送信する場合、アクセストークンには create:timesheets スコープが含まれている必要があります。含まれていない場合、リクエストは拒否されます。同様に、既存の timesheet を削除するには、アクセストークンに delete:timesheets スコープが含まれている必要があります。 詳しくは、Scopes を参照してください。