> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.generaltranslation.app/llms.txt
> Use this file to discover all available pages before exploring further.
# カスタムクレームの移行
> レガシーの名前空間のあるクレームからカスタムクレームへの移行について説明します。
export const AuthCodeBlock = ({filename, icon, language, highlight, children}) => {
const [processedChildren, setProcessedChildren] = useState(children);
useEffect(() => {
let unsubscribe = null;
function init() {
unsubscribe = window.autorun(() => {
let processedChildren = children;
for (const [key, value] of window.rootStore.variableStore.values.entries()) {
processedChildren = processedChildren.replace(new RegExp(key, "g"), value);
}
setProcessedChildren(processedChildren);
});
}
if (window.rootStore) {
init();
} else {
window.addEventListener("adu:storeReady", init);
}
return () => {
window.removeEventListener("adu:storeReady", init);
unsubscribe?.();
};
}, [children]);
return
{processedChildren}
;
};
Auth0では、2022年7月28日より、名前空間のないプライベートのカスタムクレームをアクセストークンとIDトークンに追加できるようになりました。これらのクレームは、[`/userinfo`エンドポイント](https://auth0.com/docs/api/authentication#get-user-info)の応答にも追加されます。JWTクレームのタイプについては、「[JSON Web Tokenクレーム](/docs/ja-JP/ja-jp/secure/tokens/json-web-tokens/json-web-token-claims)」をお読みください。
プライベートで名前空間のないカスタムクレームを使用することはできますが、Auth0では可能な限り、パブリックで名前空間のあるカステムクレームの使用を強くお勧めします。後でクレームを標準に追加した際の衝突を避けるには、パブリックで名前空間のあるカステムクレームを使うことが最善の方法になります。
#### 例
これまでAuth0では、名前空間のあるクレームしかアクセストークンとIDトークンに許可されていませんでした。カスタムクレームへの本移行により、今後は名前空間のないクレームをAuth0のAuthentication APIのアクセストークン、IDトークン、および`/userinfo`エンドポイントで使用できます。
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// public namespaced custom claims
api.accessToken.setCustomClaim('https://myDomain.com/myClaim', 'this is a public, namespaced claim');
api.idToken.setCustomClaim('https://myDomain.com/myClaim', 'this is a public, namespaced claim');
// non-namespaced custom claims
api.accessToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
api.idToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
};
```
## 影響を受けるフロー
Auth0がサポートするすべてのOpenID Connect（OIDC）フローがこの移行の影響を受けます。フローの一覧は、「[認証および認可のフロー](/docs/ja-JP/ja-jp/get-started/authentication-and-authorization-flow)」でお読みください。
次の機能も影響を受けます。
* [ネイティブソーシャルログイン](/docs/ja-JP/ja-jp/get-started/authentication-and-authorization-flow)
* [リフレッシュトークン](/docs/ja-JP/ja-jp/secure/tokens/refresh-tokens)
次の機能は、[Auth0 Rules](/docs/ja-JP/ja-jp/customize/rules)および属性マッピングと併用する場合にのみ影響を受けます。
* [Web Services Federation（WS-Fed）プロトコル](/docs/ja-JP/ja-jp/authenticate/protocols/ws-fed-protocol)
* [SAML2 Webアプリアドオン](/docs/ja-JP/ja-jp/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon)
## 制限
### トークンサイズの上限
カスタムクレームのペイロードを最大100KBに制限します。認証トランザクションがエラーで失敗しないよう、ペイロードがこの上限を超えないようにすることが大切です。拡張コード（[Rules](/docs/ja-JP/ja-jp/customize/rules)、[Hooks](/docs/ja-JP/ja-jp/customize/hooks)または[Actions](/docs/ja-JP/ja-jp/customize/actions)）の使用を確認することを推奨します。特に、外部APIからの大きなペイロードを確認してください。
エラーを防ぐため、Auth0ではアプリケーションの操作に必要な最小限のトークンペイロードを使用することを推奨しています。カスタムクレーム値を設定する前に、重要でないプロパティをすべて削除しなければならない場合があります。
この制限は、全カスタムクレームのペイロードサイズの合計に適用されます。それには、名前空間があるパブリックのカスタムクレームか名前空間のないプライベートのカスタムクレームかにかかわらず、カスタムクレーム名とその関連値が含まれます。
100KBの制限は、アクセストークンとIDトークンにそれぞれ個別に適用されます。たとえば、同じトランザクションで100KBのアクセストークンと100KBのIDトークンを返すことが可能です。
#### 例
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// fetching a payload that is superior to 100KB
const aHeavyPayload = getHeavyPayload();
// this will fail the authentication
api.idToken.setCustomClaim('myclaim', aHeavyPayload);
};
```
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// fetching a payload that is 50KB
const a50KBPayload = getHeavyPayload();
// fetching another payload that is 50KB
const another50KBPayload = getHeavyPayload();
// this will fail the authentication
api.idToken.setCustomClaim('myclaim', a50KBPayload);
api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);
};
```
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// fetching a payload that is 50KB
const a50KBPayload = getHeavyPayload();
// fetching another payload that is 50KB
const another50KBPayload = getHeavyPayload();
// this will succeed
api.accessToken.setCustomClaim('myclaim', a50KBPayload);
api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);
};
```
### 予約済みのクレーム
Auth0は、OIDC標準やOAuth2標準で使用されるクレーム、または内部で使用するクレームのカスタマイズを制限します。そのため、これらのクレームを変更する試みはすべて無視されます。トランザクションは失敗しませんが、当該クレームがトークンに追加されることはありません。Auth0では、パブリックの、名前空間のあるクレームの使用を推奨しています。
* `acr`
* `act`
* `active`
* `amr`
* `at_hash`
* `ath`
* `attest`
* `aud`
* `auth_time`
* `authorization_details`
* `azp`
* `c_hash`
* `client_id`
* `cnf`
* `cty`
* `dest`
* `entitlements`
* `events`
* `exp`
* `groups`
* `gty`
* `htm`
* `htu`
* `iat`
* `internalService`
* `iss`
* `jcard`
* `jku`
* `jti`
* `jwe`
* `jwk`
* `kid`
* `may_act`
* `mky`
* `nbf`
* `nonce`
* `object_id`
* `org_id`
* `org_name`
* `orig`
* `origid`
* `permissions`
* `roles`
* `rph`
* `s_hash`
* `sid`
* `sip_callid`
* `sip_cseq_num`
* `sip_date`
* `sip_from_tag`
* `sip_via_branch`
* `sub`
* `sub_jwk`
* `toe`
* `txn`
* `typ`
* `uuid`
* `vot`
* `vtm`
* `x5t#S256`
#### 例
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// this will be ignored
api.accessToken.setCustomClaim('roles', 'this is a role, but Auth0 will ignore it');
// this will succeed, and appear in the token
api.idToken.setCustomClaim('https://myDomain.com/roles', 'this is a role');
};
```
### トークンオーディエンスの制限
Auth0では、オーディエンスがAuth0 APIであるアクセストークンでの、プライベートで名前空間のないカスタムクレームの作成を制限します。オーディエンスがAuth0 APIであるアクセストークンでプライベートの名前空間のないカスタムクレームを設定する試みは、すべて無視されます。トランザクションは失敗しませんが、当該クレームがトークンに追加されることはありません。Auth0では、Auth0のAPIによって使用されるトークンにカスタムクレームを設定しないことを推奨しています。
* IDトークンはこの制約に影響されません。
* パブリック名前空間のカスタムクレームは、この制限に影響されません。
次のオーディエンスは、プライベートで名前空間のないカスタムクレームの作成を制限します。
* `https://YOUR_TENANT.auth0.com/api`または`https://YOUR_TENANT.auth0app.com/api`
* `https://YOUR_TENANT.auth0.com/api/v2`または`https://YOUR_TENANT.auth0app.com/api/v2`
* `https://YOUR_TENANT.auth0.com/mfa`または`https://YOUR_TENANT.auth0app.com/mfa`
この制限の例外は、Auth0の`/userinfo`オーディエンスです。プライベートで名前空間のないカスタムクレームは、次のオーディエンスで許可されています。
* `https://YOUR_TENANT.auth0.com/userinfo`
* `https://YOUR_TENANT.auth0app.com/userinfo`
#### 例
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// these will be ignored if the audience is an Auth0 audience
api.accessToken.setCustomClaim('myATclaim', 'this is a claim');
api.accessToken.setCustomClaim('https://myDomain.com/myATclaim', 'this is a claim');
// these will succeed, they are not concerned by the audience restriction
api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');
api.idToken.setCustomClaim('https://myDomain.com/myIdTclaim', 'this is a claim');
};
```
以下の例は、オーディエンスがAuth0 APIでない場合に返されるカスタムクレーム付きの応答を示しています。以下の例は、オーディエンスがAuth0 APIでない場合に返されるカスタムクレーム付きの応答を示しています。
```lines theme={null}
-- A resource owner password flow
POST https://{yourTenant}.auth0.com/oauth/token
grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourTenant}.auth0.com/api/v2/ -- This is an Auth0 audience
scope:openid profile
```
export const codeExample = `// The Access token returned by Auth0
{
"iss": "https://{yourTenant}.auth0.com/",
"sub": ***,
"aud": [
"https://{yourApi}.com",
"https://{yourTenant}.auth0.com/userinfo"
],
"iat": 1655283444,
"exp": 1655369844,
"azp":***,
"scope": "openid profile",
"gty": "password",
// The custom claims were added, because the Audience is not an Auth0 audience
"myATclaim": "this is a claim",
"https://{yourDomain}.com/{myATclaim}": "this is a claim"
}`;
以下の例は、Auth0 APIオーディエンスで返される、カスタムクレームが追加されていない応答を示しています。
```lines theme={null}
-- A resource owner password flow
POST https://{yourTenant}.auth0.com/oauth/token
grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourTenant}.auth0.com/api/v2/ -- This is an Auth0 audience
scope:openid profile
```
```json lines theme={null}
// The Access token returned by Auth0
{
"iss": "https://{yourTenant}.auth0.com/",
"sub": ***,
"aud": [
"https://{yourTenant}.auth0.com/api/v2/",
"https://{yourTenant}.auth0.com/userinfo"
],
"iat": 1655283444,
"exp": 1655369844,
"azp":***,
"scope": "openid profile",
"gty": "password",
// The public namespaced custom claims was added, because it is not concerned by this restriction
// However, the private non-namespaced custom claim {myATclaim} was ignored
"https://mydomain.com/{myATclaim}": "this is a claim"
}
```
## Auth0とWebtaskの名前空間の制約
Auth0では、Auth0ドメインを名前空間識別子として使用した、名前空間ありのカスタムクレームの作成を制限します。Auth0ドメインは以下の通りです。
* auth0.com
* webtask.io
* webtask.run
上記のいずれかの識別子を使用してトークンに名前空間のあるカスタムクレームを設定しようとする試みは、すべて無視されます。トランザクションは失敗しませんが、当該クレームがトークンに追加されることはありません。
この移行の前に、Auth0ドメイン識別子を使って名前空間のあるカスタムクレームを設定すると、クレームが`/userinfo`応答に含まれてしまいます。この動作は、移行後には解消され、該当するカスタムクレームが完全に無視されます。
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// none of these will be added to tokens nor to /userinfo response
api.idToken.setCustomClaim('https://example.auth0.com', 'this is a claim');
api.idToken.setCustomClaim('https://example.webtask.io', 'this is a claim');
api.idToken.setCustomClaim('https://example.webtask.run', 'this is a claim');
};
```
### OIDCユーザープロファイルクレーム
Auth0では、OIDCユーザープロファイルクレームをアクセストークンに追加できるようになりました。
この移行前は、OIDCユーザープロファイルクレームをアクセストークンに追加する試みは、サイレントに無視されていました。しかし、更新後の動作では、アクセストークンにこれらのOIDCユーザープロファイルクレームを含むことができます。
アクセストークンにOIDCユーザープロファイルクレームを追加した場合、IDトークンと同様のスコープの制限が適用されます。たとえば、アクセストークンに`email`クレームを追加するには、`email`を含む`scope`を使ってフローをトリガーしなければなりません。
次のOIDCユーザープロファイルクレームをアクセストークンに追加できます。
* `address`
* `birthdate`
* `email`
* `email_verified`
* `family_name`
* `gender`
* `given_name`
* `locale`
* `middle_name`
* `name`
* `nickname`
* `phone_number`
* `phone_number_verified`
* `picture`
* `preferred_username`
* `profile`
* `updated_at`
* `website`
* `zoneinfo`
#### 例
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// this was ignored so far. From this migration on, the claim will be added to access tokens
// if the scope contains 'email'
api.accessToken.setCustomClaim('email', 'myemail@domin.com');
// this was ignored so far. From this migration on, the claim will be added to access tokens
// if the scope contains 'profile'
api.accessToken.setCustomClaim('family_name', 'A family name');
};
```
### Auth0 Rulesを使用したSAML2アドオンおよびWebサービスフェデレーション（WS-Fed）プロトコルの属性マッピング
Auth0 Rulesを使用してユーザーオブジェクトに変更を加える場合と同様に、`app_metadata`または`user_metadata`の移行前のクレームもまた、クレームが`context.idToken`オブジェクトに設定され、名前が衝突するときに、コンテンツを結合します。オブジェクトプロパティの詳細については、「[Rulesのユーザーオブジェクトプロパティ](https://auth0.com/docs/customize/rules/user-object-in-rules)」をお読みください。
ただし、カスタムクレームを使用する場合、Auth0は`context.idToken`オブジェクトに設定されたクレームを優先します。
この変更は、`context.id_token`経由で`app_metadata`および`user_metadata`を設定する（それらにオブジェクトを割り当てる）と同時に、SAMLアドオンまたはWebサービスフェデレーション（WS-Fed）プロトコルの属性マッピングでこれらのフィールドを使用するAuth0 Rulesに影響を与えます。
例1：Auth0は、`context.idToken.app_metadata`が空のオブジェクトで設定されている場合に属性マッピングを無視します。
```javascript lines theme={null}
// an Auth0 Rule
function (user, context, callback) {
user.app_metadata.a_claim = 'This is a claim';
user.app_metadata.another_claim = 'This is a another claim';
context.samlConfiguration = context.samlConfiguration || {};
context.samlConfiguration.mappings = {
"a_claim": "app_metadata.a_claim",
"another_claim": "app_metadata.another_claim"
};
context.idToken.app_metadata = {};
return callback(null, user, context);
}
```
この移行前のSAML応答：
```lines theme={null}
(...)
(...)
This is a claim
This is a another claim
```
アップグレード後の動作のSAML応答：
```lines theme={null}
(...)
(...)
```
例2：`context.id_token`内の`app_metadata`のバージョンが優先されます。
```javascript lines theme={null}
// an Auth0 Rule
function (user, context, callback) {
user.app_metadata.a_claim = 'This is a claim';
user.app_metadata.another_claim = 'This is a another claim';
context.samlConfiguration = context.samlConfiguration || {};
context.samlConfiguration.mappings = {
"a_claim": "app_metadata.a_claim",
"another_claim": "app_metadata.another_claim",
"claim_set_via_id_token": "app_metadata.claim_set_via_id_token"
};
context.idToken.app_metadata = {
claim_set_via_id_token: "This is a claim which was set via context.idToken"
};
return callback(null, user, context);
}
```
この移行前のSAML応答：
```lines theme={null}
(...)
(...)
This is a claim
This is a another claim
This is a claim which was set via context.idToken
```
アップグレード後の動作のSAML応答：
```lines theme={null}
(...)
(...)
This is a claim which was set via context.idToken
```
### プライベートで名前空間のないクレームをトークンに追加する
カスタムクレームは、カスタムクレームのベータプログラム加入者に対しても同じように動作します。この機能はすでに有効化されています。
プライベートで名前空間のないカスタムクレームをアクセストークンおよびIDトークンのペイロードに追加できるようになりました。
#### 例
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// previously ignored
// From this migration on, the claim will be added to access tokens
api.accessToken.setCustomClaim('myATclaim', 'this is a claim');
// previously ignored
// From this migration on, the claim will be added to ID tokens
api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');
};
```
### /userinfoへのプライベートで名前空間のないクレーム
Auth0では、IDトークンに設定されている場合、/userinfo応答でプライベートの名前空間のないカスタムクレームを返すようになりました。
#### 例
```javascript lines theme={null}
// an Auth0 action
exports.onExecutePostLogin = async (event, api) => {
// this was ignored so far.
// From this migration on, this claim will be returned in /userinfo
api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');
};
```
```lines theme={null}
-- a call to /userinfo
GET https://{yourTenant}.auth0.com/userinfo
Authorization: Bearer {yourAccessToken}
```
```json lines theme={null}
// the response from /userinfo
{
"sub": ***,
(...)
"myIdTclaim": "this is a claim"
}
```
## アクション
### テナントログを確認する
まず、テナントログで廃止の通知を確認して、テナントが移行の影響を受けるかどうかを判断します。
1. [［Auth0 Dashboard］>［Monitoring（モニタリング）］>［Logs（ログ）］](https://manage.auth0.com/#/logs)に移動します。
2. `type: depnote AND description:*Custom*claims*`のログを検索します。
### 例
以下は、拡張コードがトリガーされるたびに生成される廃止ログの例です。
```json lines theme={null}
{
"date": "2022-06-28T08:12:52.084Z",
"type": "depnote",
"description": "Custom claims must be namespaced: This feature is being deprecated. Please see details.feature of this log for more information.",
"connection_id": "",
"client_id": ****,
"client_name": ****,
"details": {
"feature": {
"grant": "password",
"access_token_claims_to_be_allowed": [
"myclaim"
],
"access_token_claims_to_be_disallowed": [
"gty"
],
"id_token_claims_to_be_allowed": [
"myclaim"
],
"id_token_claims_to_be_disallowed": [
"gty"
],
"id": "legacy_custom_claims",
"name": "Custom claims must be namespaced when they are added through rules / actions / hooks."
}
},
"log_id": ****,
"_id": ****,
"isMobile": false,
"user_agent": "Other 0.0.0 / Other 0.0.0",
"id": ****
}
```
### SAML2アドオンとWebサービスフェデレーション（WS-Fed）プロトコルのAuth0ルールを修正する
Auth0 Rulesと属性マッピングを使用したSAML2アドオンおよびWebサービスフェデレーション（WS-Fed）プロトコルを使って、`context.idToken`オブジェクトに`app_metadata`または`user_metadata`クレームを設定する場合、構成を更新して、Auth0がこれらのオブジェクト間の衝突するクレーム名を評価する方法を調整する必要があります。修正方法にはいくつかあります。
* Auth0ルールのコードが常に`context.id_token`に設定されたオブジェクトのコンテンツを優先するようにします。
```javascript lines theme={null}
// my_claim will be ignored, this line of code is not relevant anymore,
// prefer setting my_claim on `context.idToken`
user.app_metadata.my_claim = 'a value';
// this version of app_metadata will take precedence over any other change
context.idToken.app_metadata = {
another_claim: 'another value'
};
// Only `another_claim` will appear in SAML/WsFed responses
```
* SAML2アドオンまたはWebサービスフェデレーション（WS-Fed）プロトコルの属性マッピングを使用する場合は、`app_metadata`または`user_metadata`クレームを`context.idToken`オブジェクトに設定しないようにします。可能な場合は、これらのクレームを名前空間のあるクレームに置き換えます。
```lines theme={null}
context.idToken['https://mydomain.com/app_metadata'] = {
my_claim: 'my claim'
};
```
* プロトコルが`samlp`または`wsfed`の場合、現在のプロトコルまたは現在のクライアントで条件を使用して、`app_metadata`または`user_metadata`を設定するステートメントを除外します。
```lines theme={null}
if (!['samlp', 'wsfed'].includes(context.protocol)) {
context.idToken.app_metadata = {
claim_set_via_id_token: "This is a claim which was set via context.idToken"
};
}
```
### レガシーの動作を無効にする
レガシーの動作を無効化する前に、変更のリストを参照して、アプリケーションと統合に互換性があることを確認してください。
テナントにトグルオプションがない場合には、影響を受けないため、対処する必要はありません。
1. [［Auth0 Dashboard］>［Tenant Settings（テナント設定）］>［Advanced（詳細設定）］](https://manage.auth0.com/dashboard/#/tenant/advanced)に移動して、**［Migrations（移行）］** を探します。
2. トグルで **［Custom claims must be namespaced（カスタムクレームは名前空間ありでなければならない）］** を無効にします。