Skip to main content
API 開発者は、次のことを行う必要があります。
  1. アプリケーションがユーザーに代わってアクセスできるようにする情報を決定します。
  2. これらのアクセスレベルをカスタムスコープとして定義します。 (スコープについては、スコープを参照してください。)
  3. 呼び出し元アプリケーションが利用できるように、これらのスコープを識別します。

​
API スコープの使い方

API スコープは、さまざまな形で利用できます。
  • 呼び出し元アプリケーションがサードパーティ、つまり外部アプリケーションである API の場合。この場合、呼び出し元アプリケーションは、要求されたスコープへのアクセスについてユーザーに認可を求め、ユーザーはその要求を承認または拒否します。
  • 呼び出し元アプリケーションがファーストパーティアプリケーション、つまりその API と同じ Auth0 ドメインの下に登録されているアプリケーションである API の場合。この場合、デフォルトではユーザーの同意は求められませんが、同意を必須にするよう設定することもできます。
  • 呼び出し元アプリケーションが、サードパーティかファーストパーティかを問わずバックエンドサービスであり、ユーザーが存在しない API の場合。この場合、ユーザーの同意が求められることはありません。
これらの例はいずれも、トークンを使ってアクセスを制限するためにスコープを利用しています。必要に応じて、API ではトークンに加えて追加のロジックを用い、さらに詳細なアクセス制御を実施することもできます。 アプリケーションのカスタム API アクセスを要求する方法を示す例については、スコープとクレームのユースケース例 を参照してください。

​
例: サードパーティアプリケーションから呼び出される API

たとえば、オンライン決済アプリケーションに銀行口座情報を提供する API を構築しているとします。アプリは状況に応じて、口座残高を確認したり、資金を送金したりする必要があります。そのため、この API に 2 つのスコープを作成します。1 つは口座残高の読み取りアクセスを許可するもの (read:balance) 、もう 1 つは資金の送金を許可するもの (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 に登録されており、API ではファーストパーティアプリケーション向けの Allow Skipping User Consent オプションが有効になっています。Authorization Extension をインストールし、organizer ロールを設定して、create:events と update:events のスコープを作成し、それを User A に割り当てています。また、participant ロールも設定し、view:events と register:events のスコープを作成して、それを User B に割り当てています。 User A はこの呼び出し元アプリケーションで認証され、必要なスコープを要求しますが、ファーストパーティアプリケーションであるため、ユーザーの同意は求められません。アプリは create:events、update:events、view:events、register:events の任意の組み合わせのスコープを要求できますが、User A は organizer ロールを持つユーザーとして認識されるため、付与されるのは create:events と update:events のスコープだけです。 その後、アプリが API を呼び出す際には、認証されたユーザーのロールに関連付けられたスコープについてのみ認可されていることを示すトークンが含まれます。

​
例: バックエンド サービスから呼び出される API

たとえば、あなたが病院で働いていて、患者が MRI 検査を受けるたびに大量の画像データを生成する API を持っているとします。画像データは 6 か月間ローカルに保存しますが、病院では規制遵守のために、画像を長期保存する必要があります。そのため病院には、毎晩画像データをオフサイトのコールド ストレージ ソリューションにコピーし、ローカルの医療データを保存後 6 か月で削除するサービスがあります。 これを実現するために、API に 2 つのスコープを作成します。1 つは画像データへの読み取りアクセスを許可するもの (read:images)、もう 1 つは画像データの削除アクセスを許可するもの (delete:images) です。API と自動化サービスは Auth0 に登録されており、自動化サービスが API 用のトークンをリクエストできるよう許可されています。 呼び出し元の自動化サービスは必要なスコープをリクエストしますが、ユーザーが存在しないため、同意は求められません。サービスは、リクエストに read:images スコープを含めることで画像データへの読み取りアクセスを、delete:images スコープを含めることで削除アクセスを、または read:images と delete:images の両方のスコープを含めることで、読み取りと削除の両方のアクセスをリクエストできます。 これで、自動化サービスが API を呼び出す際には、要求したスコープに対する認可を持っていることを示すトークンが含まれるようになります。

​
API スコープを制限する

アプリケーションは、API へのリクエストに、その API で定義されている任意のスコープを含めることができます。ただし、利用可能なすべてのスコープをリクエストできるようにするのではなく、アプリケーション向け API アクセスポリシー を使用して、アプリケーションの API へのアクセス方法を制御できます。

​
詳しく見る