> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# API へのアプリケーションアクセス: クライアントグラント
> ユーザー委譲アクセスフローとマシンツーマシンフローの両方でクライアントグラントを使用して、API にアクセスできるアプリケーションとその権限を管理します。
Auth0 では、[アプリケーションの API アクセスポリシー](/docs/ja-jp/get-started/apis/api-access-policies-for-applications) とクライアントグラントを使用して、アプリケーションが API にアクセスする方法を制御できます。
クライアントグラントを使用すると、アプリケーションの API へのアクセスをきめ細かく制御できます。これにより、次の項目が関連付けられます。
* `audience` または一意の識別子で識別される API
* `client_id` で識別されるアプリケーション
* 指定された audience に対してアプリケーションがリクエストできる、スコープや `authorization_details_types` などの権限の一覧
クライアントグラントで定義できる属性の一覧について詳しくは、[クライアントグラントの属性](#client-grant-attributes) を参照してください。クライアントグラントの定義と管理の方法については、[クライアントグラントを作成する](#create-client-grant) を参照してください。
## アプリケーションのAPIアクセスポリシーとクライアントグラント
APIの[アプリケーションアクセスポリシー](/docs/ja-jp/get-started/apis/api-access-policies-for-applications)を`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 に要求できる最大権限を定義します。ユーザーに代わってアプリケーションに発行されるアクセストークン内の最終的な権限は、次の権限の積集合になります。
- アプリケーションが要求した権限
- クライアントグラントで許可された権限
- ユーザーに対して [ロールベースのアクセス制御ポリシー](/docs/ja-jp/manage-users/access-control/rbac) で許可された権限
- 該当する場合は、[エンドユーザーが同意した](/docs/ja-jp/get-started/applications/third-party-applications/user-consent-and-third-party-applications) 権限
ユーザー委譲アクセスフローの詳細については、[認証および認可フロー](/docs/ja-jp/get-started/authentication-and-authorization-flow) を参照してください。ユーザー委譲アクセスフローには、クライアント認証情報フローは含まれません。 |
[Actions](/docs/ja-jp/customize/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](/docs/ja-jp/manage-users/organizations/organizations-for-m2m-applications/configure-your-application-for-m2m-access#define-organization-behavior) を参照してください。 |
| `allow_any_organization` | クライアント認証情報フローの使用時に、アプリケーションが任意の 組織 にアクセスできるかどうかを決定します。
Organization の設定について詳しくは、[Organizations for M2M Applications: Define Organization Behavior](/docs/ja-jp/manage-users/organizations/organizations-for-m2m-applications/configure-your-application-for-m2m-access#define-organization-behavior) を参照してください。 |
## クライアントグラントを作成する
次のものを作成できます。
* [アプリケーションごとの権限](#per-application-permissions): テナント内の各アプリケーションにきめ細かな権限を適用します。
* [サードパーティアプリケーションのデフォルト権限](#default-permissions-for-third-party-applications): テナント内のすべてのサードパーティアプリケーションにデフォルト権限を適用します。
同じ API に対して両方が存在する場合は、アプリケーションごとの権限がサードパーティアプリケーションのデフォルト権限よりも優先されます。
### アプリケーションごとの権限
Auth0 Dashboard を使用してアプリケーションごとの権限を設定するには、次の手順に従います。
1. [Auth0 Dashboard > アプリケーション > APIs](https://manage.auth0.com/#/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** を選択します。
次のリクエストボディを指定して、`/client-grants` エンドポイントに [`POST`](https://auth0.com/docs/api/management/v2/client-grants/post-client-grants) リクエストを送信します。
```bash lines theme={null}
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"
}'
```
### サードパーティアプリケーションのデフォルト権限
[サードパーティアプリケーション](/docs/ja-jp/get-started/applications/third-party-applications)が API にアクセスするには、API の[アクセスポリシー](/docs/ja-jp/get-started/apis/api-access-policies-for-applications)が **Allow All** に設定されている場合でも、常に明示的なクライアントグラントが必要です。サードパーティアプリケーションが多数ある場合や、[Dynamic Client Registration](/docs/ja-jp/get-started/applications/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](/docs/ja-jp/get-started/applications/third-party-applications/configure-third-party-applications#configure-api-access-policies)を参照してください。
Auth0 Dashboard を使用してサードパーティアプリケーションのデフォルト権限を設定するには、次の手順に従います。
1. [Auth0 Dashboard > アプリケーション > APIs](https://manage.auth0.com/#/apis) に移動し、アプリケーションアクセスを設定する API を選択します。
2. **設定** タブに移動し、**サードパーティアプリケーションのデフォルト権限** までスクロールします。
* **User-Delegated Access** および/または **Client Access** を **Unauthorized**、**Authorized**、または **All** に設定します。
* **Unauthorized**: 権限は許可されません。
* **Authorized**: 権限を個別に選択します。
* **All**: 現在ある権限と今後追加される権限がすべて含まれます。
3. **Save** を選択します。
次の request body を指定して、`/api/v2/client-grants` endpoint に `POST` request を送信します。
```bash cURL wrap lines theme={null} theme={null}
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`](https://auth0.com/docs/api/management/v2/client-grants/patch-client-grants-by-id) リクエストを送信します。
```bash lines theme={null}
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`](https://auth0.com/docs/api/management/v2/client-grants/delete-client-grants-by-id) リクエストを送信します。
```bash lines theme={null}
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` コレクションを検索したり、ページ単位で取得したりすることもできます。
```bash lines theme={null}
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 アクセスポリシー](/docs/ja-jp/get-started/apis/api-access-policies-for-applications)
* [アプリケーションのグラントタイプ](/docs/ja-jp/get-started/applications/application-grant-types)
* [サードパーティアプリケーション](/docs/ja-jp/get-started/applications/third-party-applications)
* [サードパーティアプリケーションの設定](/docs/ja-jp/get-started/applications/third-party-applications/configure-third-party-applications)