API へのアプリケーションアクセス: クライアントグラント

ユーザー委譲アクセスフローとマシンツーマシンフローの両方でクライアントグラントを使用して、API にアクセスできるアプリケーションとその権限を管理します。

Auth0 では、アプリケーションの API アクセスポリシー とクライアントグラントを使用して、アプリケーションが API にアクセスする方法を制御できます。

クライアントグラントを使用すると、アプリケーションの API へのアクセスをきめ細かく制御できます。これにより、次の項目が関連付けられます。

• audience または一意の識別子で識別される API
• client_id で識別されるアプリケーション
• 指定された audience に対してアプリケーションがリクエストできる、スコープや authorization_details_types などの権限の一覧

クライアントグラントで定義できる属性の一覧について詳しくは、クライアントグラントの属性 を参照してください。クライアントグラントの定義と管理の方法については、クライアントグラントを作成する を参照してください。

​

アプリケーションのAPIアクセスポリシーとクライアントグラント

APIのアプリケーションアクセスポリシーをrequire_client_grantに設定すると、クライアントグラントが定義されているアプリケーションのみが、そのAPIのアクセストークンを取得できます。クライアントグラントは、最小権限の原則に基づき、アプリケーションがそのAPIに対して要求できる最大の権限を定めます。そのため、Auth0では、APIのアプリケーションアクセスポリシーを設定する際にrequire_client_grantを使用することを推奨しています。

​

例: Social Media API

クライアントグラントが最小権限の原則にどのように従うかを示す例として、read:posts、write:posts、read:friends、delete:posts という権限を持つ Social Media API があるとします。そこで、アプリケーションを作成し、read:posts と write:posts の権限を持つクライアントグラントを定義します。

このクライアントグラントは、厳格な上限として機能します。Social Media API にほかの権限があっても、アプリケーションが read:friends や delete:posts をリクエストしたり、それらの権限を付与されたりすることはありません。

​

ユーザー委譲アクセスとクライアントアクセスの違い

ユーザー委譲アクセスとクライアントアクセスでは、クライアントグラントが、アプリケーションの API へのアクセスを制御する最終的な権限セットを定義します。クライアントグラントの subject_type 属性によって、API に対して許可されるアプリケーションアクセスの種類が決まります。

1 つの API に対して、1 つのアプリケーションに最大 2 つのクライアントグラントを設定できます。

• subject_type を client に設定すると、マシンツーマシンの権限を定義します。
• subject_type を user に設定すると、ユーザーに代わって動作するための権限を定義します。

次の表は、アクセスフローの種類に応じて、クライアントグラントが API へのアプリケーションアクセスをどのように制御するかを説明しています。

アクセス種別	subject_type 属性	説明
クライアント資格情報アクセス (マシンツーマシンアクセス)	subject_type を client に設定します。	クライアントグラントは、エンドユーザーに代わってではなく、アプリケーション自身による API へのアクセスを直接認可します。クライアントグラントで定義した権限が、アプリケーションにアクセストークンで付与できる権限になります。
ユーザー委譲アクセス	subject_type を user に設定します。	クライアントグラントは、アプリケーションが API に要求できる最大権限を定義します。ユーザーに代わってアプリケーションに発行されるアクセストークン内の最終的な権限は、次の権限の積集合になります。 アプリケーションが要求した権限 クライアントグラントで許可された権限 ユーザーに対して ロールベースのアクセス制御ポリシー で許可された権限 該当する場合は、エンドユーザーが同意した 権限 ユーザー委譲アクセスフローの詳細については、認証および認可フロー を参照してください。ユーザー委譲アクセスフローには、クライアント認証情報フローは含まれません。

Actions を使用すると、認可サーバーがアプリケーションまたはユーザーに付与する最終的なスコープを変更できます。

​

クライアントグラントの属性

クライアントグラントには、Auth0 Management API を使用してアプリケーションの API へのアクセスを設定するために定義できる属性がいくつかあります。

Attribute	Description
id	クライアントグラントの一意の識別子。
audience	このクライアントグラントの対象となる API の一意の識別子。
client_id	アクセス権が付与されるアプリケーションの一意の ID。
scopes	アプリケーションがリクエストできる権限を表す文字列の配列。
authorization_details_types	アプリケーションがリクエストできるリッチ認可データ型を表す文字列の配列。この属性を指定できるのは、ユーザー委譲アクセスのフローのみです。
subject_type	クライアントグラントで許可されるアプリケーションアクセスの種類: user: ユーザー委譲アクセスに使用されます。これは、エンドユーザーに関連付けられた token を生成するすべてのフローに対応します。 client: マシンアクセスに使用されます。これは、クライアント認証情報フローに対応します。
allow_all_scopes	Boolean。API で定義されているすべてのスコープを、そのアプリケーションに許可するかどうかを示します。この API では、今後定義されるスコープも自動的に許可されます。
organization_usage	クライアント認証情報フローを通じて API にアクセスする際に、アプリケーションが Organizations をどのように使用できるかを決定します。指定できる値は deny、allow、require です。 Organization の設定について詳しくは、Organizations for M2M Applications: Define Organization Behavior を参照してください。
allow_any_organization	クライアント認証情報フローの使用時に、アプリケーションが任意の 組織 にアクセスできるかどうかを決定します。 Organization の設定について詳しくは、Organizations for M2M Applications: Define Organization Behavior を参照してください。

​

クライアントグラントを作成する

次のものを作成できます。

• アプリケーションごとの権限: テナント内の各アプリケーションにきめ細かな権限を適用します。
• サードパーティアプリケーションのデフォルト権限: テナント内のすべてのサードパーティアプリケーションにデフォルト権限を適用します。

同じ API に対して両方が存在する場合は、アプリケーションごとの権限がサードパーティアプリケーションのデフォルト権限よりも優先されます。

​

アプリケーションごとの権限

Auth0 Dashboard

Auth0 Dashboard を使用してアプリケーションごとの権限を設定するには、次の手順に従います。

1. Auth0 Dashboard > アプリケーション > APIs に移動し、アプリケーションアクセスを設定する API を選択します。
2. 設定 タブを開き、Application Access Policy までスクロールします。
   • User-Delegated Access を No apps allowed、Per-app authorization、または All apps allowed に設定します。
     • No apps allowed: どのアプリケーションも API のアクセストークンを取得できません。
     • Per-app authorization: クライアントグラントが定義されているアプリケーションのみ、その API のアクセストークンを取得できます。
     • All apps allowed: テナント内の任意のアプリケーションが、その API のアクセストークンを取得できます。
   • Client Access を Per-app authorization または All apps allowed に設定します。
     • Per-app authorization: クライアントグラントが定義されているアプリケーションのみ、その API のアクセストークンを取得できます。
     • All apps allowed: テナント内の任意のアプリケーションが、その API のアクセストークンを取得できます。
3. Application Access Policy の設定を保存するには、Save を選択します。

アプリケーションごとの権限では、各アプリケーションに対して API アクセスを個別に許可する必要があります。

1. アプリケーション > APIs に移動し、API を選択します。
2. Application Access タブを開きます。
3. 対象のアプリケーションまでスクロールし、Edit を選択してから、User-Delegated Access および/または Client Access の Grant Access を選択します。次に、必要な権限を選択します。
4. Save を選択します。

Management API

次のリクエストボディを指定して、/client-grants エンドポイントに POST リクエストを送信します。

curl --location 'https://{yourDomain}/api/v2/client-grants' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
--data '{
    "client_id": "{CLIENT_ID}",
    "audience": "https://api.my-service.com",
    "scope": [
        "read:item"
    ],
    "authorization_details_types":["payment"],
    "subject_type": "user"
}'

​

サードパーティアプリケーションのデフォルト権限

サードパーティアプリケーションが API にアクセスするには、API のアクセスポリシーが Allow All に設定されている場合でも、常に明示的なクライアントグラントが必要です。サードパーティアプリケーションが多数ある場合や、Dynamic Client Registrationを使用している場合の管理を簡単にするために、すべてのサードパーティアプリケーションに自動的に適用されるデフォルトのグラントまたは権限を設定できます。

デフォルトのサードパーティクライアントグラントでは、client_id の代わりに default_for 属性を使用します。特定の client_id を指定したクライアントグラントを作成して、アプリケーションごとの権限を定義することもできます。同じ API に対して両方が存在する場合は、アプリケーションごとの権限が優先されます。

システム API (Management API、My Account API など) は、デフォルトのサードパーティクライアントグラントをサポートしていません。サードパーティアプリケーションにシステム API へのアクセスを付与することはできません。

default_for 属性と client_id 属性は相互排他的です。各クライアントグラントでは、このいずれか一方のみを指定する必要があります。

サードパーティアプリケーション向けの API アクセスポリシーの設定方法については、Configure Third-Party Applicationsを参照してください。

Auth0 Dashboard

Auth0 Dashboard を使用してサードパーティアプリケーションのデフォルト権限を設定するには、次の手順に従います。

1. Auth0 Dashboard > アプリケーション > APIs に移動し、アプリケーションアクセスを設定する API を選択します。
2. 設定 タブに移動し、サードパーティアプリケーションのデフォルト権限 までスクロールします。
   • User-Delegated Access および/または Client Access を Unauthorized、Authorized、または All に設定します。
     • Unauthorized: 権限は許可されません。
     • Authorized: 権限を個別に選択します。
     • All: 現在ある権限と今後追加される権限がすべて含まれます。
3. Save を選択します。

Management API

次の request body を指定して、/api/v2/client-grants endpoint に POST request を送信します。

cURL

curl --request POST \
    --url 'https://YOUR_DOMAIN/api/v2/client-grants' \
    --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
        "default_for": "third_party_clients",
        "audience": "https://api.example.com",
        "scope": ["read:items", "write:items"],
        "subject_type": "user"
}'

パラメータ	型	説明
default_for	String	このグラントを特定のアプリ種別に自動適用するかどうかを指定します。すべてのサードパーティアプリがデフォルトでこの API にアクセスできるようにするには、third_party_clients に設定します。
audience	String	このグラントの作成対象となる API の一意の identifier (URI) です。
scope	Array	このグラントの一部として許可される permissions (scopes) の一覧です。
subject_type	String	API に対して許可するアプリケーションアクセスの種類を定義します。 user: エンドユーザーに関連付けられた token を生成するフローに対応する、user-delegated access に使用されます。 client: クライアント認証情報フローなどの machine-to-machine access に使用されます。

​

クライアントグラントを更新する

既存のクライアントグラントを更新するには、/client-grants/{id} に PATCH リクエストを送信します。

curl --location --request PATCH 'https://{yourDomain}/api/v2/client-grants/{CLIENT_GRANT_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
--data '{
    "scope": [
        "read:item",
        "update:item"
    ],
    "authorization_details_types":["payment", "credits_transfer"]
}'

​

クライアントグラントを削除する

クライアントグラントを削除するには、/client-grants/{id} に DELETE リクエストを送信します。

curl --location --request DELETE 'https://{yourDomain}/api/v2/client-grants/{CLIENT_GRANT_ID}' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}'

​

クライアントグラントを取得する

client_id、audience、subject_type などのパラメータを使用して、client-grants コレクションを検索したり、ページ単位で取得したりすることもできます。

curl --request GET \
--url 'https://{yourDomain}/api/v2/client-grants?subject_type=user&audience=https%3A%2F%2Fapi.my-service.com' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
--header 'Accept: application/json'

​

詳細はこちら

• アプリケーション向け API アクセスポリシー
• アプリケーションのグラントタイプ
• サードパーティアプリケーション
• サードパーティアプリケーションの設定