公開アプリケーションがカスタムトークン交換を使用できることに注意してください。利用する場合は必ず「[攻撃防御](#attack-protection)」をお読みください。 |
| `audience` | Auth0で定義されているAPI識別子です。 |
| `scope` | OAuth2スコープのパラメーターです。 |
その他の拡張パラメーターは、対応するアクションの`event.request.body`に含まれていますが、無視されます。
Organizationsはカスタムトークン交換の早期アクセスではまだ対応されていません。organizationパラメーターを使用すると、要求が拒否されます。Organizations対応は次のバージョンのカスタムトークン交換に追加する予定です。
### 要求例
```bash lines theme={null}
curl --location 'https://{{YOUR_TENANT}}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'audience=https://api.acme.com' \
--data-urlencode 'scope=openid offline_access acme-scope1 acme-scope2' \
--data-urlencode 'subject_token_type=urn:acme:external-idp-migration' \
--data-urlencode 'subject_token=t8e7S2D9trQm73e .... iqBR3GjxDtbDVjpfQU' \
--data-urlencode 'client_id={{CLIENT_ID}}' \
--data-urlencode 'client_secret={{CLIENT_SECRET}}'
```
## 攻撃防御
なりすましやリプレイ攻撃で悪意のある攻撃者がサブジェクトトークンを推測または再利用しようとするのを防ぐために、カスタムトークン交換は[不審なIPのスロットリング](/docs/ja-jp/secure/attack-protection/suspicious-ip-throttling)に対応しています。これにより、[サブジェクトトークンが無効](#api-access-rejectinvalidsubjecttoken-reason-)な場合に、アクション内のコードから信号を特異的に送信できるため、Auth0は外部IPからの試行の失敗をカウントできます。
1つのIPアドレスからの試行の失敗数が事前構成のしきい値に達すると、該当するIPアドレスからのカスタムトークン交換要求について、Auth0は以下のエラー応答でトラフィックをブロックします。
```json lines theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
"error": "too_many_attempts",
"error_description": "We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator."
}
```
構成済みの期間が過ぎると、IPアドレスは要求を再び行えるようになります。
すべての事例で推奨されることですが、**不審なIPのスロットリングを正しく構成してアクティブ化することは、カスタムトークン交換をネイティブアプリケーションやシングルページアプリケーションで使用する場合には特に重要です** 。ネイティブアプリケーションやSPAなどの非機密アプリケーションは、自身を認証するためにシークレットを安全に保管できません。攻撃者は簡単にサブジェクトトークンを推測したり、窃盗や漏洩したものを使用したりできます。
不審なIPのスロットリングを正しく使用するためには、受け取ったサブジェクトトークンが厳密に検証されない場合は必ず、アクションのコードに`api.access.rejectInvalidSubjectToken`を使用してください。
不審なIPのスロットリングはAuth0テナントにはデフォルトでアクティブ化されます。アクティブ化や構成の方法については、「[不審なIPのスロットリング](/docs/ja-jp/secure/attack-protection/suspicious-ip-throttling)」をお読みください。アクティブ化すると、カスタムトークン交換のデフォルト設定が適用されます。
* しきい値：10。1つのIPアドレスが失敗した試行の最大数です。
* スロットリングレート：1時間あたり6回。しきい値を超えない範囲で10分ごとに1回の試行が補充されます。
カスタムトークン交換には、Management APIを使用してカスタムのしきい値やスロットリングレートを構成できます。
まず、APIを使用するために[Management APIトークンを取得](/docs/ja-jp/secure/tokens/access-tokens/management-api-access-tokens#get-management-api-tokens)します。そして、以下のGET要求を[不審なIPのスロットリング設定取得エンドポイント](https://auth0.com/docs/api/management/v2/attack-protection/get-suspicious-ip-throttling)に対して行います。
```bash lines theme={null}
curl --location 'https://{{YOUR _TENANT}}/api/v2/attack-protection/suspicious-ip-throttling' \
--header 'Authorization: Bearer {{MANAGEMENT_API_TOKEN}}' \
```
以下のような応答を受け取ります。
```json lines theme={null}
{
"enabled": true,
"shields": [
"admin_notification",
"block"
],
"allowlist": [],
"stage": {
"pre-login": {
"max_attempts": 100,
"rate": 864000
},
"pre-user-registration": {
"max_attempts": 50,
"rate": 1200
},
"pre-custom-token-exchange": {
"max_attempts": 10,
"rate": 600000
}
}
}
```
以下の`PATCH`要求では`pre-custom-token-exchange`ステージを必要な値で更新できます。レートは新たに試行が許可されるまでをミリ秒単位の間隔で表していることに注意してください。
```bash lines theme={null}
curl --location --request PATCH 'https://{{YOUR _TENANT}}/api/v2//attack-protection/suspicious-ip-throttling' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{MANAGEMENT_API_TOKEN}}' \
--data '{"stage":{"pre-custom-token-exchange":{"max_attempts":10,"rate":600000}}}'
```
## ユースケースの例とサンプルコード
技術的な制約やユーザーエクスペリエンスの観点から、エンドユーザーのリダイレクトに基づく標準的なフェデレーションログインストラテジーが適用できない高度な統合シナリオには、カスタムトークン交換をソリューションとして使用できます。ユースケースに提供するコードは不完全なものであり、対処するコードを論理的に進められるように説明することのみを意図しています。より詳しいサンプルコードについては、「[サンプルコード](#code-samples)」を参照してください。
できる限り、そのままで使用できる通常のフェデレーションログインの使用をお勧めします。カスタムトークン交換はトランザクションにユーザーを設定可能にすることで、トランザクションの安全な検証と処理を強化し、柔軟性を向上します。
このセクションでは、ユースケースの例と該当するシナリオの実装に推奨されるサンプルコードを紹介します。ユースケースを説明するために、GearUpという架空のレンタカー会社を想定します。
### ユースケース：Auth0へシームレスに移行する
GearUpには何百万人もが使用するモバイルアプリがあり、アイデンティティソリューションの近代化が必要なため、Auth0を使用することに決めました。ただし、レガシーIDプロバイダー（IdP）からの移行に関してユーザーエクスペリエンスでの摩擦を懸念して、ユーザーに再認証を強制することは避けたいと考えています。
これを解消し、リスクを制限するために、GearUpは段階的に移行しています。それぞれのユーザーについて、レガシーIdPからのリフレッシュトークンをAuth0のアクセストークン、リフレッシュトークン、IDトークンのセットに交換することを希望しています。そうすることで、アプリが速やかにAuth0をIdPとして使い始め、Auth0発行のトークンを用いてGearUp APIを使用できるようになります。すべてのユーザーに交換が完了したら、エンドユーザーとGearUpのビジネスに影響することなく、アプリは完全に移行され、古いIdPが切断されます。
前提条件として、GearUpはAuth0テナントに[ユーザーの一括インポート](/docs/ja-jp/manage-users/user-migration/bulk-user-imports)を行い、モバイルアプリには移行するユーザーの有効なレガシーリフレッシュトークンがあります。
1. モバイルアプリがAuth0に対してレガシーのリフレッシュトークンの交換を要求します。その際にはレガシーのリフレッシュトークンをサブジェクトトークンとして設定します。
2. 該当するカスタムトークン交換プロファイルのアクションが実行されます。リフレッシュトークンをレガシーIdPで照会して、ユーザープロファイルから外部のユーザーIDを取得します。そして、必要な認可ポリシーを適用し、最終にユーザーを設定します。
3. Auth0がAuth0のアクセストークン、IDトークン、リフレッシュトークンを含めて応答します。
4. これで、ユーザーが再認証することなく、モバイルアプリがAuth0のトークンを使って顧客のAPIを使用できるようになりました。
以下のサンプルコードは、カスタムトークン交換アクションでこれを実装する方法を示しています。このユースケースではユーザープロファイルがすでにAuth0データベース接続にインポートされているため、以下が当てはまります。
* Auth0はユーザーを作成しません。
* Auth0はユーザープロファイルを更新しません。
Auth0は外部IdPのユーザーIDを使用して、該当する接続でユーザーを設定します。
```javascript lines theme={null}
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
// 1. VALIDATE the refresh_token received in the subject_token by using it to get
// the UserProfile from the external IdP
const { isValid, user } = await getUserProfile(
event.transaction.subject_token,
event.secrets.CLIENT_SECRET,
);
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
// 3. When we have the profile, we SET THE USER in the target connection
api.authentication.setUserByConnection(
connectionName,
{
// only the user_id in the connection is needed, as we are not
// creating nor updating the user
user_id: user.sub,
},
{
creationBehavior: "none",
updateBehavior: "none",
},
);
}
};
/**
* Exchange the refresh token and load the user profile from the legacy IdP
* @param {string} refreshToken
* @param {string} clientSecret
* @returns {Promise<{ isValid: boolean, user?: object }>} If the refresh token was exchanged successfully, returns the user profile
*/
async function getUserProfile(refreshToken, clientSecret) {
// Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
```
不透明なリフレッシュトークンをレガシーIdPで検証する方法の詳しい例については、「[サンプルコード](#code-samples)」をお読みください。
### ユースケース：外部の認証プロバイダーを再利用する
別のユースケースでは、GearUpがAir0という大手旅行会社と提携し、Air0のシングルページアプリケーション内でレンタカーサービスを直接提供します。GearUpは自社APIの使用をカプセル化したJavaScriptライブラリーを提供します。そうすることで、レンタカーサービスを提供するAir0のWebサイトがGearUpのAPIを手軽に使用できるようになります。
今回も、GearUpへの再認証を避けて、ソリューションがエンドユーザーから見えないようにする必要があります。これを実現するために、GearUpのJavaScriptライブラリーは外部のAir0 IDトークンを入力として使用し、トークン交換を処理できます。その結果、Auth0のアクセストークンが生成され、メールアドレスを基に所定のGearUpユーザーと関連付けられます。GearUpライブラリーがアクセストークンを取得したら、Air0のWebサイトで直接レンタカーサービスを提供するために、GearUpのAPIを使い始めることができます。
前提条件として、GearUpはAir0 IdPをフェデレーションのエンタープライズ接続またはソーシャル接続としてセットアップし、ユーザー認証をフェデレーションログインで行うか、以下のようにカスタムトークン交換で行えるようにします。
1. ユーザーを認証したら、シングルページアプリが外部IdPからIDトークンを取得します。
2. シングルページアプリがIDトークンをサブジェクトトークンとして設定し、トークンの交換を要求します。
3. 該当するカスタムトークン交換プロファイルのアクションが実行されます。IDトークンを検証し、トークンからユーザーIDと他のプロファイル属性を取得します。そして、必要な認可ポリシーを適用し、最終にユーザーを設定します。
4. Auth0がAuth0のアクセストークン、IDトークン、リフレッシュトークンを含めて応答します。
5. これで、ユーザーが再認証することなく、SPAで実行中のJavascriptコードがAuth0のトークンを使って顧客のAPIを使用できるようになりました。
以下のサンプルコードは、カスタムトークン交換アクションでこれを実装する方法を示しています。このユースケースでは以下が当てはまります。
* Auth0は外部IdPのユーザーIDを使用して、該当する接続でユーザーを設定します。
* ユーザーが存在しない場合にはAuth0が作成します。
* ユーザーがすでに存在する場合のために、より完全な属性のセットがフェデレーションログインで取得できるのであれば、Auth0はユーザープロファイルを置換しません。
* Auth0はユーザーの作成時にメールを検証しません。
```javascript lines theme={null}
const jwksUri = "https://example.com/.well-known/jwks.json";
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
// 1. VALIDATE the id_token received in the subject_token
const { isValid, payload } = await validateToken(
event.transaction.subject_token,
);
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
// 3. SET THE USER in the target connection.
// We don't want to verify emails when users are created
// This example assumes subject_token (id_token) contains standard OIDC claims. Other custom mappings
// are also possible.
api.authentication.setUserByConnection(
'Enterprise-OIDC',
{
user_id: formattedUserId,
email: subject_token.email,
email_verified: subject_token.email_verified,
phone_number: subject_token.phone_number,
phone_verified: subject_token.phone_number_verified,
username: subject_token.preferred_username,
name: subject_token.name,
given_name: subject_token.given_name,
family_name: subject_token.family_name,
nickname: subject_token.nickname,
verify_email: false
},
{
creationBehavior: 'create_if_not_exists',
updateBehavior: 'none'
}
);
}
/**
* Validate the subject token
* @param {string} subjectToken
* @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
*/
async function validateToken(subjectToken) {
// Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
};
```
JWTを安全に検証する方法の詳しい例については、「[サンプルコード](#code-samples)」をお読みください。
### ユースケース：別のオーディエンスのAuth0トークンを取得する
GearUpはAPI要求を処理するために、内部のマイクロサービス間で呼び出しの認可方法を改善したいと考えています。それぞれのサービスに使用可能なリソースを制御するために、ポリシーの一元管理を希望しています。これもトークン交換を使用して実現できます。
まず、API要求がサービスAに到達すると、受け取ったアクセストークンを、新しいオーディエンスとしてサービスBの使用を許可する新しいアクセストークンに交換します。トークン交換を管理する認可ポリシーが許す場合、サービスAが新しいトークンを取得して、サービスBが使用できるようになります。ユーザーIDは新しいトークンで変わらずに維持されるため、ユーザーの正しいコンテキストがプロセス全体で維持されます。
GearUpアプリケーションは当初、API Aをユーザーに代わって使用するために、アクセストークンを取得します。
1. アプリが要求に当初のアクセストークンを含めてAPI Aに送信します。
2. API Aのバックエンドサービスがアクセストークンを検証し、それをサブジェクトトークンとして設定して、API Bを使用するための新しいアクセストークンとの交換を要求します。
3. 該当するカスタムトークン交換プロファイルのアクションが実行されます。IDトークンを検証し、トークンからAuth0ユーザーIDを取得します。そして、必要な認可ポリシーを適用し、最終にユーザーを設定します。
4. Auth0がAPI Bオーディエンスを使用するためのAuth0のアクセストークンを含めて応答します。
5. API Aのバックエンドサービスが新しいアクセストークンを使用してAPI Bを呼び出します。このアクセストークンは引き続き同じユーザーに関連付けられています。
以下のサンプルコードは、カスタムトークン交換アクションでこれを実装する方法を示しています。このユースケースでは以下が当てはまります。
* Auth0がAuth0のユーザーIDを使用してユーザーを設定するため、接続のスコープにこれを設定する必要はありません。
* Auth0はユーザーの作成や更新を行いません。
このユースケースに関する詳しいサンプルコードについては、「[非対称鍵で署名されたJWTを検証する](#validate-jwts-signed-with-asymmetric-keys)」を参照してください。
```javascript lines theme={null}
const jwksUri = "https://example.com/.well-known/jwks.json";
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
// 1. VALIDATE the access_token received in the subject_token
const { isValid, payload } = await validateToken(
event.transaction.subject_token,
);
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
// 3. SET THE USER
api.authentication.setUserById(payload.sub);
}
/**
* Validate the subject token
* @param {string} subjectToken
* @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
*/
async function validateToken(subjectToken) {
// Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
};
```
JWTを安全に検証する方法の詳しい例については、「[サンプルコード](#code-samples)」をお読みください。
### サンプルコード
以下のサンプルコードは、受け取ったサブジェクトトークンを安全で効率よく検証するために、シナリオ共通のベストプラクティスを示しています。
Auth0とシークレットを共有する必要がない場合は、できる限り非対称のアルゴリズムと鍵を使用します。これは、適用できるk公開鍵を公表するためにJWKS URIエンドポイントを公開する場合などで、鍵のローテーションも簡素化します。
強力なアルゴリズムと十分な高エントロピーのキーやシークレットで確実にサブジェクトトークンを保護することは、お客様の責任であることに注意してください。
#### 非対称鍵で署名されたJWTを検証する
以下の推奨事項を検討してください。
* Actionsの[api.cache](#api-cache)メソッドを使用し、トランザクションごとに署名鍵を取得しないようにします。
* [RFC8725](https://www.rfc-editor.org/rfc/rfc8725.txt)のベストプラクティスに従います。
* RS\*、PS\*、ES\*、またはEd25519のアルゴリズムを使用します。
* noneアルゴリズムを使用したり、受け入れたりしてはいけません。
* 最小長2048ビットのRSAを使用します。
```javascript lines theme={null}
const { jwtVerify } = require("jose");
const jwksUri = "https://example.com/.well-known/jwks.json";
const fetchTimeout = 5000; // 5 seconds
const validIssuer = "urn:my-issuer"; // Replace with your issuer
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
const { isValid, payload } = await validateToken(
event.transaction.subject_token,
);
// Apply your authorization policy as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// Set the user in the current request as authenticated, using the user ID from the subject token.
api.authentication.setUserById(payload.sub);
}
/**
* Validate the subject token
* @param {string} subjectToken
* @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
*/
async function validateToken(subjectToken) {
try {
const { payload, protectedHeader } = await jwtVerify(
subjectToken,
async (header) => await getPublicKey(header.kid),
{
issuer: validIssuer,
},
);
// Perform additional validation on the token payload as required
return { isValid: true, payload };
} catch (/** @type {any} */ error) {
if (error.message === "Error fetching JWKS") {
throw new Error("Internal error - retry later");
} else {
console.log("Token validation failed:", error.message);
return { isValid: false };
}
}
}
/**
* Get the public key to use for key verification. Load from the actions cache if available, otherwise
* fetch the key from the JWKS endpoint and store in the cache.
* @param {string} kid - kid (Key ID) of the key to be used for verification
* @returns {Promise
4. **［Create（作成）］** を選択します。
5. アクションを **［Deploy（デプロイ）］** します。
アクションをデプロイすると、Auth0がアクションIDを割り当てます。アクションにはカスタムロジックを追加しなければなりませんが、その前にアクションIDを取得して、カスタムトークン交換プロファイルを作成します。
6. Auth0 DashboardでアクションIDを取得するには、ブラウザーウィンドウのURLを確認します。下の画像が示すように、アクションIDはURLの末尾の部分にあります。
アクションIDはManagement APIで取得することもできます。まず、APIを使用するために[Management APIトークンを取得](/docs/ja-jp/secure/tokens/access-tokens/management-api-access-tokens#get-management-api-tokens)します。そして、以下のGET要求を`/actions`エンドポイントに送信します。
```bash lines theme={null}
curl --location 'https://{{YOUR _TENANT}}/api/v2/actions/actions?actionName={{ACTION_NAME}}' \
--header 'Authorization: Bearer {{MANAGEMENT_API_TOKEN}}' \
```
応答本文の`actions[0].id`内にアクションIDが含まれているはずです。アクションIDはカスタムトークン交換プロファイルの作成に必要です。
#### カスタムトークン交換プロファイルを作成する
カスタムトークン交換プロファイルを作成するには、Management APIを使用して、POST要求に以下のパラメーターを含めて`/token-exchange-profiles`エンドポイントに送信します。
```bash lines theme={null}
curl --location 'https://{{YOUR _TENANT}}/api/v2/token-exchange-profiles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{MANAGEMENT_API_TOKEN}}' \
--data '{
"name": "{{PROFILE_NAME}}",
"subject_token_type": "{{UNIQUE_PROFILE_TOKEN_TYPE_URI}}",
"action_id": "{{ACTION_ID}}",
"type": "custom_authentication"
}'
```
| パラメーター | 説明 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `subject_token_type` | 特有なプロファイルのトークンタイプの`https://`または`urn`で始まるURIです。
## トークン交換を呼び出す
カスタムトークン交換を使用するには、以下のパラメーターを指定して`POST`要求を`/oauth/token`エンドポイントに対して行います。以下に留意してください。
* カスタムトークン交換に使用する`subject_tokens`は、アクションコードが解釈できるのであれば、どのような形式や種類のトークンでも構いません。
* `subject_token_type`はそれぞれ特定のカスタムトークン交換プロファイルにマッピングされ、そのトランザクションを制御する特定のアクションに関連付けられます。
| パラメーター | 説明 |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `grant_type` | カスタムトークン交換には `urn:ietf:params:oauth:grant-type:token-exchange` を使用します。 |
| `subject_token_type` | サブジェクトトークンの種類です。カスタムトークン交換では、独自に所有するURIでスコープが限定された任意の値です。たとえば、`http://acme.com/legacy-token`や`urn:acme:legacy-token`.
カスタムトークン交換には、Management APIを使用してカスタムのしきい値やスロットリングレートを構成できます。
まず、APIを使用するために[Management APIトークンを取得](/docs/ja-jp/secure/tokens/access-tokens/management-api-access-tokens#get-management-api-tokens)します。そして、以下のGET要求を[不審なIPのスロットリング設定取得エンドポイント](https://auth0.com/docs/api/management/v2/attack-protection/get-suspicious-ip-throttling)に対して行います。
```bash lines theme={null}
curl --location 'https://{{YOUR _TENANT}}/api/v2/attack-protection/suspicious-ip-throttling' \
--header 'Authorization: Bearer {{MANAGEMENT_API_TOKEN}}' \
```
以下のような応答を受け取ります。
```json lines theme={null}
{
"enabled": true,
"shields": [
"admin_notification",
"block"
],
"allowlist": [],
"stage": {
"pre-login": {
"max_attempts": 100,
"rate": 864000
},
"pre-user-registration": {
"max_attempts": 50,
"rate": 1200
},
"pre-custom-token-exchange": {
"max_attempts": 10,
"rate": 600000
}
}
}
```
以下の`PATCH`要求では`pre-custom-token-exchange`ステージを必要な値で更新できます。レートは新たに試行が許可されるまでをミリ秒単位の間隔で表していることに注意してください。
```bash lines theme={null}
curl --location --request PATCH 'https://{{YOUR _TENANT}}/api/v2//attack-protection/suspicious-ip-throttling' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{MANAGEMENT_API_TOKEN}}' \
--data '{"stage":{"pre-custom-token-exchange":{"max_attempts":10,"rate":600000}}}'
```
## ユースケースの例とサンプルコード
技術的な制約やユーザーエクスペリエンスの観点から、エンドユーザーのリダイレクトに基づく標準的なフェデレーションログインストラテジーが適用できない高度な統合シナリオには、カスタムトークン交換をソリューションとして使用できます。ユースケースに提供するコードは不完全なものであり、対処するコードを論理的に進められるように説明することのみを意図しています。より詳しいサンプルコードについては、「[サンプルコード](#code-samples)」を参照してください。
前提条件として、GearUpはAuth0テナントに[ユーザーの一括インポート](/docs/ja-jp/manage-users/user-migration/bulk-user-imports)を行い、モバイルアプリには移行するユーザーの有効なレガシーリフレッシュトークンがあります。
1. モバイルアプリがAuth0に対してレガシーのリフレッシュトークンの交換を要求します。その際にはレガシーのリフレッシュトークンをサブジェクトトークンとして設定します。
2. 該当するカスタムトークン交換プロファイルのアクションが実行されます。リフレッシュトークンをレガシーIdPで照会して、ユーザープロファイルから外部のユーザーIDを取得します。そして、必要な認可ポリシーを適用し、最終にユーザーを設定します。
3. Auth0がAuth0のアクセストークン、IDトークン、リフレッシュトークンを含めて応答します。
4. これで、ユーザーが再認証することなく、モバイルアプリがAuth0のトークンを使って顧客のAPIを使用できるようになりました。
以下のサンプルコードは、カスタムトークン交換アクションでこれを実装する方法を示しています。このユースケースではユーザープロファイルがすでにAuth0データベース接続にインポートされているため、以下が当てはまります。
* Auth0はユーザーを作成しません。
* Auth0はユーザープロファイルを更新しません。
Auth0は外部IdPのユーザーIDを使用して、該当する接続でユーザーを設定します。
```javascript lines theme={null}
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
// 1. VALIDATE the refresh_token received in the subject_token by using it to get
// the UserProfile from the external IdP
const { isValid, user } = await getUserProfile(
event.transaction.subject_token,
event.secrets.CLIENT_SECRET,
);
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
// 3. When we have the profile, we SET THE USER in the target connection
api.authentication.setUserByConnection(
connectionName,
{
// only the user_id in the connection is needed, as we are not
// creating nor updating the user
user_id: user.sub,
},
{
creationBehavior: "none",
updateBehavior: "none",
},
);
}
};
/**
* Exchange the refresh token and load the user profile from the legacy IdP
* @param {string} refreshToken
* @param {string} clientSecret
* @returns {Promise<{ isValid: boolean, user?: object }>} If the refresh token was exchanged successfully, returns the user profile
*/
async function getUserProfile(refreshToken, clientSecret) {
// Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
```
不透明なリフレッシュトークンをレガシーIdPで検証する方法の詳しい例については、「[サンプルコード](#code-samples)」をお読みください。
### ユースケース：外部の認証プロバイダーを再利用する
別のユースケースでは、GearUpがAir0という大手旅行会社と提携し、Air0のシングルページアプリケーション内でレンタカーサービスを直接提供します。GearUpは自社APIの使用をカプセル化したJavaScriptライブラリーを提供します。そうすることで、レンタカーサービスを提供するAir0のWebサイトがGearUpのAPIを手軽に使用できるようになります。
今回も、GearUpへの再認証を避けて、ソリューションがエンドユーザーから見えないようにする必要があります。これを実現するために、GearUpのJavaScriptライブラリーは外部のAir0 IDトークンを入力として使用し、トークン交換を処理できます。その結果、Auth0のアクセストークンが生成され、メールアドレスを基に所定のGearUpユーザーと関連付けられます。GearUpライブラリーがアクセストークンを取得したら、Air0のWebサイトで直接レンタカーサービスを提供するために、GearUpのAPIを使い始めることができます。
前提条件として、GearUpはAir0 IdPをフェデレーションのエンタープライズ接続またはソーシャル接続としてセットアップし、ユーザー認証をフェデレーションログインで行うか、以下のようにカスタムトークン交換で行えるようにします。
1. ユーザーを認証したら、シングルページアプリが外部IdPからIDトークンを取得します。
2. シングルページアプリがIDトークンをサブジェクトトークンとして設定し、トークンの交換を要求します。
3. 該当するカスタムトークン交換プロファイルのアクションが実行されます。IDトークンを検証し、トークンからユーザーIDと他のプロファイル属性を取得します。そして、必要な認可ポリシーを適用し、最終にユーザーを設定します。
4. Auth0がAuth0のアクセストークン、IDトークン、リフレッシュトークンを含めて応答します。
5. これで、ユーザーが再認証することなく、SPAで実行中のJavascriptコードがAuth0のトークンを使って顧客のAPIを使用できるようになりました。
以下のサンプルコードは、カスタムトークン交換アクションでこれを実装する方法を示しています。このユースケースでは以下が当てはまります。
* Auth0は外部IdPのユーザーIDを使用して、該当する接続でユーザーを設定します。
* ユーザーが存在しない場合にはAuth0が作成します。
* ユーザーがすでに存在する場合のために、より完全な属性のセットがフェデレーションログインで取得できるのであれば、Auth0はユーザープロファイルを置換しません。
* Auth0はユーザーの作成時にメールを検証しません。
```javascript lines theme={null}
const jwksUri = "https://example.com/.well-known/jwks.json";
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
// 1. VALIDATE the id_token received in the subject_token
const { isValid, payload } = await validateToken(
event.transaction.subject_token,
);
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
// 3. SET THE USER in the target connection.
// We don't want to verify emails when users are created
// This example assumes subject_token (id_token) contains standard OIDC claims. Other custom mappings
// are also possible.
api.authentication.setUserByConnection(
'Enterprise-OIDC',
{
user_id: formattedUserId,
email: subject_token.email,
email_verified: subject_token.email_verified,
phone_number: subject_token.phone_number,
phone_verified: subject_token.phone_number_verified,
username: subject_token.preferred_username,
name: subject_token.name,
given_name: subject_token.given_name,
family_name: subject_token.family_name,
nickname: subject_token.nickname,
verify_email: false
},
{
creationBehavior: 'create_if_not_exists',
updateBehavior: 'none'
}
);
}
/**
* Validate the subject token
* @param {string} subjectToken
* @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
*/
async function validateToken(subjectToken) {
// Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
};
```
GearUpアプリケーションは当初、API Aをユーザーに代わって使用するために、アクセストークンを取得します。
1. アプリが要求に当初のアクセストークンを含めてAPI Aに送信します。
2. API Aのバックエンドサービスがアクセストークンを検証し、それをサブジェクトトークンとして設定して、API Bを使用するための新しいアクセストークンとの交換を要求します。
3. 該当するカスタムトークン交換プロファイルのアクションが実行されます。IDトークンを検証し、トークンからAuth0ユーザーIDを取得します。そして、必要な認可ポリシーを適用し、最終にユーザーを設定します。
4. Auth0がAPI Bオーディエンスを使用するためのAuth0のアクセストークンを含めて応答します。
5. API Aのバックエンドサービスが新しいアクセストークンを使用してAPI Bを呼び出します。このアクセストークンは引き続き同じユーザーに関連付けられています。
以下のサンプルコードは、カスタムトークン交換アクションでこれを実装する方法を示しています。このユースケースでは以下が当てはまります。
* Auth0がAuth0のユーザーIDを使用してユーザーを設定するため、接続のスコープにこれを設定する必要はありません。
* Auth0はユーザーの作成や更新を行いません。
このユースケースに関する詳しいサンプルコードについては、「[非対称鍵で署名されたJWTを検証する](#validate-jwts-signed-with-asymmetric-keys)」を参照してください。
```javascript lines theme={null}
const jwksUri = "https://example.com/.well-known/jwks.json";
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
// 1. VALIDATE the access_token received in the subject_token
const { isValid, payload } = await validateToken(
event.transaction.subject_token,
);
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
// 3. SET THE USER
api.authentication.setUserById(payload.sub);
}
/**
* Validate the subject token
* @param {string} subjectToken
* @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
*/
async function validateToken(subjectToken) {
// Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
};
```
JWTを安全に検証する方法の詳しい例については、「[サンプルコード](#code-samples)」をお読みください。
### サンプルコード
以下のサンプルコードは、受け取ったサブジェクトトークンを安全で効率よく検証するために、シナリオ共通のベストプラクティスを示しています。
Auth0とシークレットを共有する必要がない場合は、できる限り非対称のアルゴリズムと鍵を使用します。これは、適用できるk公開鍵を公表するためにJWKS URIエンドポイントを公開する場合などで、鍵のローテーションも簡素化します。