> ## 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="/ja/docs/glossary?term=access+tokens">アクセストークン</Tooltip>を<Tooltip tip="認可サーバー: ユーザーのアクセス範囲の境界を定義する集中管理サーバーです。たとえば、認可サーバーは、ユーザーが利用できるデータ、タスク、機能を制御できます。" cta="用語集を見る" href="/ja/docs/glossary?term=authorization+server">認可サーバー</Tooltip>から取得して保存することで、プランのトークン数の上限を最適化できます (該当する場合) 。新しいトークンを要求する代わりに、保存したトークンが期限切れになるまでは、以後の呼び出しでそのトークンを使用してください。トークンの保存方法は、アプリケーションの特性によって異なります。一般的な方法としては、データベース (セッションの有無にかかわらず API 呼び出しを実行する必要があるアプリ向け) や HTTP セッション (アクティビティの時間枠がインタラクティブなセッションに限定されるアプリ向け) があります。サーバー側での保存とトークン再利用の例については、[トークンの保存](/ja/docs/secure/security-guidance/data-security/token-storage)を参照してください。

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

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

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

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

デフォルトでは、トークンベースの認証でトークンが大きくなりすぎるのを避けるため、`scope=openid` を使用します。トークンに含めたい標準の <Tooltip tip="OpenID: アプリケーションがログイン情報を収集して保存しなくても、ユーザーのIDを検証できる認証のオープン標準です。" cta="用語集を表示" href="/ja/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) クレームは、それらをスコープ値として追加することで制御できます。たとえば、`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 Worker または JavaScript クロージャを使ってアクセストークンを設定する必要があります。詳しくは、[トークンの保存](/ja/docs/secure/security-guidance/data-security/token-storage) ページの Browser in-memory scenarios セクションを参照してください。

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

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

* [Authorization Code Flow](/ja/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow)
* [Proof Key for Code Exchange (PKCE) を使用する Authorization Code Flow](/ja/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/add-login-using-the-authorization-code-flow-with-pkce)
* [Resource Owner Password Flow](/ja/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)
* [デバイス認可フロー](/ja/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)

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

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

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

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

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

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

Auth0 では、アプリケーションごとに、ユーザー 1 人あたり最大 200 個の有効なリフレッシュトークンまで保持できます。この上限は、有効なトークンにのみ適用されます。上限に達した状態で新しいリフレッシュトークンが作成されると、システムはそのユーザーとアプリケーションに対する最も古いトークンを失効させて削除します。失効済みのトークンおよび期限切れのトークンは、この上限にはカウントされません。

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

リフレッシュトークンは自動テストによって蓄積されることがあり、通常はテスト期間中のみ使用されます。リフレッシュトークンの制限に抵触するほどトークンがたまるのを防ぐには、Auth0 の <Tooltip tip="Management API: 顧客が管理タスクを実行できるようにする製品。" cta="用語集を見る" href="/ja/docs/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 を使用することは推奨しません。また、Management API のレート制限に達する可能性があるため、テストユーザーやアーティファクトを保持したり、device credential エンドポイントを使用してリフレッシュトークンをクリーンアップしたりすることも推奨しません。詳しくは、[Management API エンドポイントのレート制限](/ja/docs/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. ユーザーが 1,000 個を超えるトークンを持っている場合は、そのユーザーのトークンがなくなるまで、トークンの一覧表示と削除を繰り返します。

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

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

不要になったリフレッシュトークンが蓄積するのを防ぐため、リフレッシュトークン数の上限によって最も古いトークンから削除されるとはいえ、リフレッシュトークンの有効期限を設定することをお勧めします。ローテーションされるリフレッシュトークンとローテーションされない (再利用可能な) リフレッシュトークンは、どちらもアイドル有効期限または絶対有効期限のいずれかを使用して期限切れになるよう設定できます。どちらの有効期限も、アクティブに使用されていないトークンを削除し、ユーザーごとのトークンの蓄積を防ぐのに役立ちます。詳しくは、[リフレッシュトークンの有効期限を設定する](/ja/docs/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 Tokens](/ja/docs/secure/tokens/json-web-tokens) を参照してください。署名の詳細については、[JSON Web Token Structure](/ja/docs/secure/tokens/json-web-tokens/json-web-token-structure) を参照してください。

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

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

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

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

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

JWKS には複数の署名鍵が含まれる可能性があることを前提にするのがベストプラクティスです。Auth0 の JWKS エンドポイントには通常 1 つの署名鍵しか含まれないため、不要に思えるかもしれません。ただし、署名証明書をローテーションする際には、JWKS に複数の鍵が含まれることがあります。

アプリケーションのパフォーマンスを向上させ、レート制限に達するのを避けるため、署名鍵をキャッシュすることを推奨します。ただし、トークンのデコードに失敗した場合は、キャッシュを無効化して新しい署名鍵を取得してから、**1 回だけ** 再試行するようにしてください。

<div id="learn-more">
  ## 詳しく見る
</div>

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