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

クライアントグラントについて説明します

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

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

• audience または一意の識別子で識別される API。
• client_id で識別されるアプリケーション。
• 指定したオーディエンスに対して、そのアプリケーションがリクエストを許可されている、スコープや 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 つのアプリケーションに対して、1 つの API には最大 2 つのクライアントグラントを設定できます。

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

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

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

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

​

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

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

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

​

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

作成できる項目は次のとおりです。

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

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

​

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

Auth0 Dashboard

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

1. Dashboard > Applications > APIs に移動し、アプリケーションアクセスを設定する API を選択します。
2. Settings タブに移動し、下にスクロールして 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. Applications > 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. Dashboard > Applications > APIs に移動し、アプリケーションアクセスを設定する API を選択します。
2. Settings タブに移動し、Default Permissions for Third-Party Applications までスクロールします。
   • User-Delegated Access および/または Client Access を Unauthorized、Authorized、または All に設定します。
     • Unauthorized: 権限は許可されません。
     • Authorized: 権限を個別に選択します。
     • All: 既存および今後の権限が含まれます。
3. Save を選択します。

Management API

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

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"
}'

Parameter	Type	Description
default_for	String	このグラントを特定のアプリ種別に自動的に適用するかどうかを指定します。すべてのサードパーティアプリがデフォルトでこの API にアクセスできるようにするには、third_party_clients に設定します。
audience	String	グラントの作成対象である API の一意の識別子 (URI) です。
scope	Array	このグラントの一部として許可される権限 (スコープ) のリストです。
subject_type	String	API に対して許可されるアプリケーションアクセスの種類を定義します。 user: ユーザー委任アクセスに使用されます。これは、エンドユーザーに関連付けられたトークンを生成するフローに対応します。 client: Client Credentials フローなどのマシンツーマシンアクセスに使用されます。

​

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

既存のクライアントグラントを更新するには、/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 Access ポリシー
• アプリケーションのグラントタイプ
• サードパーティアプリケーション
• サードパーティアプリケーションを設定する