ソリューションの概要（サーバーアプリ + API）

ExampleCoでは、タイムシートAPIへのアクセスを承認されたユーザーとアプリケーションのみに限定するために、OAuth 2.0 Authorization Frameworkを使用することを決めました。このフレームワークは、異なる付与タイプを使用して、タイムシートAPIと通信する必要があるさまざまな種類のアプリケーションを簡単に認可できるため、同社が求めている柔軟性を提供しています。

OAuth 2.0

OAuth 2.0 Authorization Frameworkを使用することで、ExampleCoの通常のWebアプリケーションと社外の請負業者向けのサードパーティアプリケーションは、タイムシートAPにI制限付きでアクセスできるようになります。Auth0を使用することで、ExampleCoは、OAuth 2.0/OpenID Connect（OIDC）の仕様や、API認証に関する他の多くの技術的側面を心配することなく、異なる付与タイプや認証フローを簡単にサポートすることができます。

OAuthロール

OAuth 2.0フローでは、次のロールが識別されます：

  • リソース所有者（Resource Owner）：保護されたリソースへのアクセス権を付与できるエンティティ。通常は、エンドユーザーです。

  • リソースサーバー（Resource Server）：保護されたリソースをホストするサーバー。アクセスしたいAPIのことです。

  • クライアント（Client）：リソース所有者の代わりに保護されたリソースへのアクセス権を要求するアプリケーション。

  • 認可サーバー（Authorization Server）：リソース所有者を認証し、適切な認可を得た後にアクセストークンを発行するサーバー。この場合、Auth0の認証APIになります。

付与タイプ（またはフロー）は、これらの関係者がどのように作用し、ビルド中のAPIへの制限付きアクセスをアプリに付与するのかを決定します。そして、ユーザーの代わりにAPIを呼び出すためのアクセストークンをアプリが取得します。

クライアント資格情報付与

OAuth 2は、異なるユースケースのために複数の付与タイプを提供しています。この特定のユースケースでは、cronジョブがAPI経由でタイムシートをアップロードするため、APIへのアクセスについて、cronジョブに権限を付与する対話型ユーザー（またはリソース所有者）が存在しません。

また、cronジョブは、ユーザーの代わりにAPIを呼び出しません。アプリケーション（cronジョブ）は、マシンツーマシン認可を使ってリソースサーバー（API）に自らの代理で呼び出しを行います。

このようにユーザーとの対話が関与しない状況では、クライアント資格情報付与が最も適しています。クライアント資格情報付与（RFC 6749のセクション4.4で定義）を使用すると、アプリケーションは自身のクライアント資格情報（クライアントIDとクライアントシークレット）を使って、直接認可サーバーにアクセストークンを要求することができます。リソース所有者を特定する代わりに、このトークンはアプリケーション自体を表します。

undefined

  1. アプリケーションは、自身のクライアントIDとクライアントシークレットを使用して、認可サーバーで認証します。

  2. 認可サーバーはこの情報を検証し、アクセストークンを返します。

  3. アプリケーションはそのアクセストークンを使って、自身の代理としてリソースサーバーを呼び出します。

API認証と認可

APIは、アプリケーションの機能性を他のアプリケーションに公開する手段になります。他のアプリケーションは、APIエンドポイントに要求を送信し、応答を受信することができます。同様に、ExampleCoの請負業者が使用する外部アプリケーションは、タイムシートAPIと通信できる他にも、ExampleCoが社内従業員のために構築した通常のWebアプリケーションと通信することもできます。

タイムシートAPIは機密情報（PIIや財務情報など）を扱うため、ExampleCoは、認可されたユーザーとアプリケーションのみがそのエンドポイントを呼び出せるようにしなければなりません。

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

APIは、セキュリティ保護することも、しないこともできます。アプリケーションがAPIの保護されたエンドポイントにアクセスしたい場合は、必要な権限があることを証明するために、アクセストークン（access_tokenとも呼ばれる）を提供する必要があります。

アクセストークンは、アプリケーションに発行された認可を表す不透明な文字列で、ユーザーを認可サーバーで認証することによって取得されます。すると、ユーザーは、アプリケーションが自身の代理でAPIにアクセスすることを許可できます。詳細については、「アクセストークン」をお読みください。

タイムシートAPIのようなAPIは、APIが公開するさまざまなエンドポイントに誰がアクセスを許可されるかについて、きめ細かい制御を行うことができます。これらのアクセス許可はスコープと呼ばれます。

ExampleCoの通常のWebアプリケーションやサードパーティアプリケーションがAuth0で認証してアクセストークンを取得する場合、認証要求にはアプリケーションが必要とする要求されたスコープのリストが含まれています。これらのスコープが許可されると、そのアクセストークンには、アプリケーションに付与された認可済みスコープのリストが含まれます。

通常のWebアプリケーションやサードパーティアプリケーションは、タイムシートAPIへの要求に、認可サーバーからのアクセストークンを含めます。タイムシートAPIは、特定のエンドポイントの呼び出しに必要な許可が付与されていることを確認するために、スコープクレームを検証します。

たとえば、タイムシートAPIは、タイムシートの読み取り（スコープ：read:timesheets）、タイムシートの作成（スコープ：create:timesheets）、タイムシートの削除（スコープ：delete:timesheets）、タイムシートの承認（スコープ：approve:timesheets）という異なる4レベルの認可を受け入れることができます。

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

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

詳しくは、「スコープ」をお読みください。