APIスコープ

API開発者は、次のことを行います。

ユーザーに代わって、アプリケーションがどの情報にアクセスできるようにしたいかを決める。
アクセスレベルをカスタムスコープとして定義する。（スコープについては、「スコープ」をお読みください。）
スコープを識別し、呼び出しているアプリケーションが使用できるようにする。

APIスコープの使用方法

APIスコープは、さまざまな方法で使用できます。

呼び出す側のアプリケーションがサードパーティ（外部）アプリケーションであるAPI内で。この場合、呼び出す側のアプリケーションは、ユーザーに対し、要求されたスコープへのアクセスを認可するよう要求します。ユーザーは、要求を承認または拒否します。
呼び出す側のアプリケーションがファーストパーティアプリケーションであるか、同じAuth0ドメインの下で、呼び出しているAPIとして登録されたアプリケーションであるAPI内で。この場合、デフォルトではユーザーの同意は要求されませんが、同意の要求を構成することができます。
呼び出す側のアプリケーションが、ファーストパーティまたはサードパーティのバックエンドサービスであり、ユーザーが存在しないAPI内で。この場合、ユーザーの同意が要求されることはありません。

これらの例では、トークンを使用したアクセスを制限するために、スコープを使用します。その場合、APIにトークン以外のロジックも適用し、アクセス制御を強化することができます。

アプリケーションのためにカスタムAPIアクセスを要求する例は「サンプルユースケース：スコープとクレーム」を参照してください。

例：サードパーティアプリケーションによって呼び出されるAPI

オンライン決済アプリケーションに銀行口座情報を提供するAPIをビルドするとしましょう。アプリは、複数の時点で口座残高や資金振替を読み取る必要があります。それには、APIのために2つのスコープ、つまり、口座残高の読み取りを認可するスコープ（read:balance）と、資金振替を認可するスコープ（transfer:funds）を作成します。APIは、Auth0で登録されています。

呼び出す側のアプリケーションは、ユーザーに対し、要求されたスコープへのアクセスを認可するよう要求します。ユーザーは、要求を承認または拒否します。アプリは、read:balanceスコープを要求に含めることでユーザーの残高の読み取りアクセスを要求したり、transfer:fundsスコープを要求に含めることで資金振替へのアクセスを要求したり、read:balanceとtransfer:fundsの両方のスコープを要求に含めることでユーザーの残高の読み取りアクセスと資金振替へのアクセスの両方を要求できます。

さて、アプリがAPIを呼び出すとき、そこには、ユーザーが自身のコンテンツへのアクセスを認可したということを確認し、ユーザーがどのスコープを承認したかを示すトークンが含まれています。APIは、承認されたスコープに従い、ユーザーが認可した情報だけを呼び出す側のアプリケーションに提供します。

例：ファーストパーティアプリケーションによって呼び出されるAPI

たとえば、自分で書いたイベントアプリにデータを提供するAPIをビルドするとしましょう。ロールベースのアクセス制御（RBAC）を実装し、organizerロールとparticipantロールを作成します。organizerロールを持つユーザーがイベントを作成して更新する必要があるのに対し、participantロールを持つユーザーはイベントを表示してイベントに登録する必要があります。このためには、APIのために4つのスコープ、つまり、イベントの作成アクセスを認可するスコープ（create:events）、イベントの更新アクセスを認可するスコープ（update:events）、イベントの読み取り専用アクセスを認可するスコープ（view:events）、イベントの登録アクセスを認可するスコープ（register:events）を作成します。APIとイベントアプリケーションの両方がAuth0で登録されており、ファーストパーティアプリケーションの［Allow Skipping User Consent（ユーザー同意のスキップの許可）］オプションがAPIで有効になっています。認可拡張機能をインストールし、organizerロールを構成し、このロールにcreate:eventsスコープとupdate:eventsスコープを作成し、ユーザーAに割り当てました。また、participantロールを構成し、このロールにview:eventsスコープとregister:eventsスコープを作成し、ユーザーBに割り当てました。

ユーザーAは、呼び出す側のアプリケーションで認証を行います。それによって必要なスコープが要求されますが、ファーストパーティアプリケーションであるため、ユーザーの同意は求められません。アプリは、create:events、update:events、view:events、register:eventsのいずれかのスコープの組み合わせを要求する可能性がありますが、ユーザーAはorganizerロールを持っていると認識されるため、create:eventsスコープとupdate:eventsスコープのみが付与されます。

さて、アプリがAPIを呼び出すとき、そこにはトークンが含まれます。そのトークンは、認証されたユーザーのロールに関連するスコープのみに対して認可を受けていることを確認します。

例：バックエンドサービスによって呼び出されるAPI

たとえば、あなたは医療従事者で、MRI検査を実施する度に大量の画像データを作成するAPIを持っているとしましょう。画像データは、ローカルで6か月間保管されますが、病院が規制に準拠するためには、長期間にわたる保管が必要です。そのため、病院には、画像データを毎晩コピーしてオフサイトのコールドストレージに保管し、ローカルの医療データを6か月の保管期間の後にすべて削除するサービスがあります。

それには、APIのために2つのスコープ、つまり、画像データの読み取りアクセスを認可するスコープ（read:images）と、画像データの削除アクセスを認可するスコープ（delete:images）を作成します。APIと自動サービスは、Auth0に登録されており、自動サービスがAPIのトークンを要求することも認可されています。

呼び出す側の自動サービスは、必要なスコープを要求しますが、ユーザーがいないので同意は求められません。サービスは、read:imagesスコープを要求に含めることで画像データの読み取りアクセスを要求したり、delete:imagesスコープを要求に含めることで削除アクセスを要求したり、read:imagesとdelete:imagesの両方のスコープを要求に含めることで読み取りアクセスと削除アクセスの両方を要求したりする場合があります。

さて、自動サービスがAPIを呼ぶとき、そこには要求されたスコープに対する認可があることを検証するトークンが含まれます。