> ## 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.

> 認証と認可でトークンを使用する際のベストプラクティスを一覧で示します。

# トークンのベストプラクティス

トークンを使用する際に、念頭に置いておくべき基本的なポイントを以下に示します。

* **秘密にして安全に保つ**: 署名鍵は他の認証情報と同様に扱い、必要とするサービスにのみ共有してください。
* **ペイロードに機密データを追加しない**: トークンは改ざんを防ぐために署名されていますが、デコードは容易です。パフォーマンスとセキュリティを最適化するため、ペイロードに追加するクレームは必要最小限にとどめてください。
* **トークンに有効期限を設定する**: 技術的には、トークンはひとたび署名されると、署名鍵が変更されるか、有効期限が明示的に設定されない限り、永久に有効です。これは潜在的な問題を招くおそれがあるため、トークンを失効または取り消すための方針を用意してください。
* **HTTPS を使用する**: 非 HTTPS 接続でトークンを送信しないでください。そのようなリクエストは傍受され、トークンが侵害される可能性があります。
* **認可に関するすべてのユースケースを検討する**: トークンが自分のサーバーで生成されたことを保証するための追加のトークン検証システムが、要件を満たすうえで必要になる場合があります。
* **保存して再利用する:** アプリケーションの攻撃対象領域を広げる不要な往復通信を減らし、<Tooltip tip="アクセストークン: API へのアクセスに使用される認可資格情報で、不透明な文字列または JWT の形式を取ります。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=access+tokens">アクセストークン</Tooltip>を<Tooltip tip="認可サーバー: ユーザーのアクセス範囲の境界を定義するのに寄与する集中型サーバー。たとえば、認可サーバーはユーザーが利用できるデータ、タスク、機能を制御できます。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=authorization+server">認可サーバー</Tooltip>から取得して保存することで、プランのトークン上限 (該当する場合) を最適化してください。新しいトークンを毎回要求するのではなく、有効期限が切れるまでは、以後の呼び出しで保存したトークンを使用してください。トークンの保存方法は、アプリケーションの特性によって異なります。一般的な方法としては、データベース (セッションの有無にかかわらず API 呼び出しを実行する必要があるアプリ向け) や HTTP セッション (対話型セッションの利用中のみ動作するアプリ向け) があります。サーバー側での保存とトークン再利用の例については、[トークンの保存](/docs/ja-jp/secure/security-guidance/data-security/token-storage)を参照してください。

<div id="tokens-vs-cookies">
  ## トークンとクッキー
</div>

通常、シングルページアプリ (React、Vue、AngularJS + Node など) 、Native のモバイルアプリ (iOS や Android など) 、および Web API (Node、Ruby、ASP.NET、またはそれらを組み合わせて記述されたもの) は、トークンベースの認証の恩恵を最も受けやすいです。一方、従来型のサーバーサイド Web アプリケーションでは、これまでクッキーベースの認証が一般的に使われてきました。

トークンベースの認証は、ユーザーの認証時にトークンを生成し、その後の API への各リクエストの `Authorization` ヘッダーにそのトークンを設定することで実装されます。そのトークンには、<Tooltip tip="JSON Web トークン (JWT): 2者間でクレームを安全に表現するために使われる標準的な ID トークン形式（多くの場合、アクセストークン形式でもあります）。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=JSON+web+tokens">JSON Web トークン</Tooltip> のような標準的なものを使うのが望ましいです。ほとんどのプラットフォームでライブラリが利用できますし、独自に暗号処理を実装する必要もないためです。

どちらの方法でも、ユーザーから取得できる情報量は同じです。これは、login リクエストで送信される `scope` パラメーターで制御されます (Lock、当社の JavaScript ライブラリ、または単純なリンクを使う場合も同様です) 。`scope` は `.signin({scope: 'openid name email'})` メソッドのパラメーターであり、最終的には login リクエストの query string の一部になります。

デフォルトでは、トークンが大きくなりすぎるのを避けるため、トークンベースの認証では `scope=openid` を使用します。必要な標準の <Tooltip tip="OpenID: アプリケーションが login 情報を収集・保存することなく、ユーザーの本人確認を行えるようにする authentication のためのオープン標準です。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) クレームは、scope の値として追加することで、トークンに含める内容を制御できます。たとえば、`scope=openid name email family_name address phone_number` のように指定します。詳しくは、[openid.net の Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) を参照してください。

トークンベースの認証とクッキーベースの認証は組み合わせて使うこともできます。Web アプリケーションと API が同じドメインから提供されている場合は、クッキーで問題なく動作するため、トークンベースの認証が不要なこともあります。必要であれば、Web アプリケーションのフローでも JWT を返します。実装方法は SDK ごとに異なります。既存のクッキーを使わずに JavaScript から API を呼び出したい場合は、トークンの送信と保存を扱うために、Web Workers または JavaScript クロージャを使ってアクセストークンを設定する必要があります。詳しくは、[トークンの保存](/docs/ja-jp/secure/security-guidance/data-security/token-storage) ページの Browser in-memory scenarios セクションを参照してください。

<div id="refresh-token-usage">
  ## リフレッシュトークンの使用
</div>

次のフローを実装している場合にのみ、<Tooltip tip="リフレッシュトークン: ユーザーに再度ログインさせることなく、新しいアクセストークンを取得するために使用されるトークンです。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=Refresh+token">リフレッシュトークン</Tooltip>を取得できます。

* [認可コードフロー](/docs/ja-jp/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow)
* [Proof Key for Code Exchange (PKCE) を使用する認可コードフロー](/docs/ja-jp/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/add-login-using-the-authorization-code-flow-with-pkce)
* [リソース所有者パスワードフロー](/docs/ja-jp/get-started/authentication-and-authorization-flow/resource-owner-password-flow)
* [デバイス認可フロー](/docs/ja-jp/get-started/authentication-and-authorization-flow/device-authorization-flow)

API へのオフラインアクセスを制限している場合は、[Auth0 Dashboard > Applications > APIs > Settings](https://manage.auth0.com/#/apis) の **オフラインアクセスの許可** スイッチで設定される保護機能により、リクエストに `offline_access` スコープを含めていても、Auth0 はその API に対してリフレッシュトークンを返しません。

リフレッシュトークン交換ではルールが実行されます。特別なロジックを実行するには、ルール内で `context.protocol` プロパティを確認します。値が `oauth2-refresh-token` であれば、そのルールは交換中に実行されています。

リフレッシュトークンを取得しようとする場合、<Tooltip tip="audience: 発行されたトークンの audience を表す一意の識別子です。トークン内では aud という名前で示され、その値には ID トークンの場合はアプリケーション (Client ID)、アクセストークンの場合は API (API Identifier) の ID が含まれます。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=audience">audience</Tooltip> パラメーターはルールのコンテキストオブジェクトでは使用できません。audience パラメーターを追加しようとしてエラーが発生した場合は、そのトークンに設定していないことを確認してください。

`context.redirect` でリダイレクトしようとすると、認証フローはエラーを返します。

ルールを使ってトークンにカスタムクレームを追加している場合、そのルールが有効である限り、リフレッシュトークンの使用時に発行される新しいトークンにもカスタムクレームが含まれます。新しいトークンがカスタムクレームを自動的に継承するわけではありませんが、リフレッシュトークンフロー中にもルールが実行されるため、同じコードが実行されます。これにより、以前に認可されたアプリケーションに新しいリフレッシュトークンの取得を求めることなく、新たに発行されるトークンのカスタムクレームを追加または変更できます。

<div id="refresh-token-limits">
  ### リフレッシュトークンの上限
</div>

Auth0 では、ユーザー 1 人・アプリケーション 1 つあたり、有効なリフレッシュトークンは 200 個までに制限されています。この上限は、有効なトークンにのみ適用されます。上限に達した状態で新しいリフレッシュトークンが作成されると、システムはそのユーザーとアプリケーションに関連付けられた最も古いトークンを取り消して削除します。取り消されたトークンと有効期限切れのトークンは、この上限にはカウントされません。

<div id="automated-tests">
  #### 自動テスト
</div>

リフレッシュトークンは自動テストによって蓄積されやすく、通常はテスト期間中のみ使用されます。リフレッシュトークンの上限に抵触するほどトークンがたまるのを避けるため、不要なリフレッシュトークンは Auth0 の<Tooltip tip="Management API: お客様が管理タスクを実行できるようにする製品。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=Management+API">Management API</Tooltip>を使って削除できます。

1. Management API で[ユーザーを作成](https://auth0.com/docs/api/management/v2#!/Users/post_users)します。このユーザーをテストに使用します。
2. レスポンスで `user_id` が返されるので、後で使えるようテスト中は保持しておく必要があります。
3. テストが完了したら、Management API を使って[ユーザーを削除](https://auth0.com/docs/api/management/v2#!/Users/delete_users_by_id)します。テストユーザーを削除すると、リフレッシュトークンを含む関連データも削除されます。

<Warning>
  このユースケースでは、固定のユーザー ID を使用することは推奨しません。また、テストユーザーや関連データを保持したり、device credential エンドポイントを使ってリフレッシュトークンを削除したりすることも推奨しません。Management API のレート制限に達する可能性があるためです。詳しくは、[Management API Endpoint Rate Limits.](/docs/ja-jp/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits) を参照してください。
</Warning>

今後のテストのためにテストユーザーを残しておきたい場合は、次のようにします。

1. [Management API の device credential エンドポイント](https://auth0.com/docs/api/management/v2#!/Device_Credentials/get_device_credentials)を使って、ユーザーのリフレッシュトークンを一覧表示します。このエンドポイントは、蓄積されたトークン数やページネーションの使用有無にかかわらず、順不同で最大 1000 件のトークンを返します。
2. [DELETE](https://auth0.com/docs/api/management/v2#!/Device_Credentials/delete_device_credentials_by_id) メソッドを使って、それらの資格情報を削除します。
3. ユーザーが 1k を超えるトークンを持っている場合は、そのユーザーのトークンがなくなるまで、一覧表示と削除を繰り返します。

<div id="configure-expiring-refresh-tokens">
  #### 有効期限付きリフレッシュトークンを設定する
</div>

ユーザーが Auth0 を使ってアプリケーションにログインし、認可リクエストで `offline_access` が要求されると、そのユーザーに新しいリフレッシュトークンが発行されます。ユーザーが同じデバイスでログアウトして再度ログインした場合も、新しいリフレッシュトークンが発行されます。アプリケーションでリフレッシュトークンをどのように保存・使用しているかによっては、最初のログイン時に発行された古いリフレッシュトークンは不要になることがあり、両方のトークンが同じ audience で発行されている場合、アプリケーションは新しいリフレッシュトークンを使用することになる可能性が高くなります。詳しくは、[トークンの保存](/docs/ja-jp/secure/security-guidance/data-security/token-storage)を参照してください。

不要になったリフレッシュトークンが蓄積するのを防ぐため、リフレッシュトークンの上限によって最も古いトークンから削除されるとはいえ、リフレッシュトークンの有効期限を設定することをお勧めします。ローテーションあり、ローテーションなし (再利用可能) のどちらのリフレッシュトークンでも、非アクティブ期限または絶対有効期限を設定できます。どちらの有効期限も、アクティブに使用されていないトークンの削除に役立ち、ユーザーのトークンが蓄積するのを防ぎます。詳しくは、[リフレッシュトークンの有効期限を設定する](/docs/ja-jp/secure/tokens/refresh-tokens/configure-refresh-token-expiration)を参照してください。

<div id="jwt-validation">
  ## JWT の検証
</div>

JWT の解析と検証には、ミドルウェアまたは既存のオープンソースのサードパーティライブラリを使用することを強く推奨します。[JWT.io](https://jwt.io/#libraries-io) では、.NET、Python、Java、Ruby、Objective-C、Swift、PHP など、さまざまなプラットフォームや言語向けのライブラリを見つけることができます。

<div id="signing-algorithms">
  ## 署名アルゴリズム
</div>

アプリケーションまたは API 向けに発行されるトークンの署名に使用されるアルゴリズムです。署名は JWT の一部であり、トークンの送信者が正当な送信元であることを確認し、途中でメッセージが改ざんされていないことを保証するために使用されます。JWT について詳しくは、[JSON Web トークン](/docs/ja-jp/secure/tokens/json-web-tokens)を参照してください。署名について詳しくは、[JSON Web Token Structure](/docs/ja-jp/secure/tokens/json-web-tokens/json-web-token-structure)を参照してください。

次の<Tooltip tip="署名アルゴリズム: トークンが改ざんされていないことを保証するために、トークンにデジタル署名する際に使用されるアルゴリズム。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=signing+algorithms">署名アルゴリズム</Tooltip>から選択できます。

* **RS256** (SHA-256 を使用する RSA 署名): 非対称アルゴリズムです。つまり、キーは 2 つあり、1 つは公開キー、もう 1 つは秘密として保持しなければならない秘密キーです。Auth0 は署名の生成に使用する秘密キーを保持し、JWT の利用者は Auth0 が提供するメタデータエンドポイントから公開キーを取得して、それを使って[JWT 署名を検証](/docs/ja-jp/secure/tokens/json-web-tokens/validate-json-web-tokens)します。
* **HS256** (SHA-256 を使用する HMAC): 対称アルゴリズムです。つまり、秘密として保持しなければならない秘密キーは 1 つだけで、それを 2 者間で共有します。同じキーが署名の生成と検証の両方に使われるため、キーが漏えいしないよう十分に注意する必要があります。この秘密キー (またはシークレット) は、アプリケーション (**<Tooltip tip="Client Secret: クライアント（アプリケーション）が認可サーバーに対して認証するために使用するSecretです。クライアントと認可サーバーだけが知っているべきであり、推測されないよう十分にランダムでなければなりません。" cta="用語集を見る" href="/docs/ja-jp/glossary?term=Client+Secret">Client Secret</Tooltip>**) または API (**Signing Secret**) を登録し、HS256 署名アルゴリズムを選択したときに作成されます。

最も安全で、Auth0 が推奨するのは **RS256** を使用することです。理由は次のとおりです。

* RS256 では、秘密キーの保有者 (Auth0) のみがトークンに署名でき、公開キーを使えば誰でもそのトークンが有効かどうかを確認できます。
* RS256 では、複数の audience に対して有効なトークンをリクエストできます。
* RS256 では、秘密キーが漏えいした場合でも、新しいシークレットを使ってアプリケーションまたは API を再デプロイすることなく、キー ローテーションを実施できます (HS256 を使用している場合は再デプロイが必要です) 。
* HS256 では、シークレットキーが漏えいした場合、新しいシークレットを使って API を再デプロイする必要があります。

<div id="signing-keys">
  ## 署名鍵
</div>

JWKS に複数の署名鍵が含まれている可能性を想定しておくことをおすすめします。Auth0 の JWKS エンドポイントには通常 1 つの署名鍵しか含まれないため、一見不要に思えるかもしれませんが、署名証明書をローテーションする際には、JWKS に複数のキーが含まれることがあります。

アプリケーションのパフォーマンスを向上させ、レート制限に抵触しないようにするため、署名鍵はキャッシュすることをおすすめします。安全にキャッシュしつつローテーションされたキーも取得する方法については、[JSON Web Key Set をキャッシュする](/docs/ja-jp/secure/tokens/json-web-tokens/json-web-key-sets#cache-the-json-web-key-set)をお読みください。

<div id="learn-more">
  ## さらに詳しく
</div>

* [トークン](/docs/ja-jp/secure/tokens)
* [トークンの保存](/docs/ja-jp/secure/security-guidance/data-security/token-storage)