メインコンテンツへスキップ
2022年7月28日以降、Auth0 では、プライベートで名前空間のないカスタムクレームをアクセストークンおよびに追加できるようになります。これらのクレームは、/userinfo endpoint のレスポンスにも追加されます。クレームの種類の詳細については、JSON Web Token Claims を参照してください。
プライベートで名前空間のないカスタムクレームの使用は許可されますが、Auth0 では可能な限り、パブリックで名前空間付きのカスタムクレームを使用することを強く推奨しています。パブリックで名前空間付きのカスタムクレームは、今後標準に追加されるクレームとの衝突を回避する最善の方法です。

​
例

以前は、Auth0 ではアクセストークンとIDトークンでは名前空間付きのクレームのみが許可されていました。カスタムクレームへの移行により、、IDトークン、および Auth0 の Authentication API の /userinfo エンドポイントで、名前空間のないクレームも使用できるようになりました。 
// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // 公開名前空間付きカスタムクレーム 
  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');

  // 名前空間なしのカスタムクレーム
  api.accessToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
  api.idToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
};

​
影響を受けるフロー

Auth0 がサポートするすべての Connect (OIDC) フローは、この移行の影響を受けます。フローの一覧については、Authentication and Authorization Flows を参照してください。 次の機能も影響を受けます。 次の機能は、Auth0 Rules および属性マッピングと組み合わせて使用する場合にのみ影響を受けます。

​
制限事項

​
トークンの最大サイズ

Auth0 では、カスタムクレームのペイロードは最大 100KB に制限されます。ペイロードがこの上限を超えないようにすることが重要です。超えた場合、認証トランザクションはエラーとなって失敗します。Rules、Hooks、または Actions などの拡張機能コードの使用状況を確認することをお勧めします。特に、外部 API から返される大きなペイロードを見直してください。 エラーを回避するため、Auth0 では、アプリケーションの動作に必要な最小限のトークンペイロードを使用することを推奨しています。カスタムクレームの値を設定する前に、不要なプロパティを削除する必要がある場合があります。
この制限は、すべてのカスタムクレームの合計ペイロードサイズに適用されます。これには、カスタムクレームの名前と、それに対応する値の両方が含まれます。公開 名前空間付き か非公開 名前空間なし かは問いません。
100KB の上限は、アクセストークンと IDトークン にそれぞれ個別に適用されます。たとえば、100KB のアクセストークンと 100KB の IDトークンを同じトランザクションで返すことができます。

​
例

// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // 100KBを超えるペイロードを取得する
  const aHeavyPayload = getHeavyPayload();

  // これにより認証が失敗する
  api.idToken.setCustomClaim('myclaim', aHeavyPayload);

};

// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // 50KBのペイロードを取得する
  const a50KBPayload = getHeavyPayload();

  // 別の50KBのペイロードを取得する
  const another50KBPayload = getHeavyPayload();

  // これは認証に失敗する
  api.idToken.setCustomClaim('myclaim', a50KBPayload);
  api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);

};

// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // 50KBのペイロードを取得する
  const a50KBPayload = getHeavyPayload();

  // 別の50KBのペイロードを取得する
  const another50KBPayload = getHeavyPayload();

  // これは成功する
  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

​
例

// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // これは無視される
  api.accessToken.setCustomClaim('roles', 'this is a role, but Auth0 will ignore it');

  // これは成功し、トークンに表示される
  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

​
例

// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // オーディエンスがAuth0のオーディエンスの場合、これらは無視されます
  api.accessToken.setCustomClaim('myATclaim', 'this is a claim');
  api.accessToken.setCustomClaim('https://myDomain.com/myATclaim', 'this is a claim');

  // これらは成功します。オーディエンスの制限を受けないためです
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');
  api.idToken.setCustomClaim('https://myDomain.com/myIdTclaim', 'this is a claim');

};
以下の例は、オーディエンスが Auth0 API ではない場合に返される、カスタムクレームを含むレスポンスを示しています。 
-- Resource Owner Password Flow 
POST https://{yourTenant}.auth0.com/oauth/token

grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourApi}.com -- オーディエンスに注意。これはカスタムAPIです
scope:openid profile
以下の例は、Auth0 API のオーディエンスを追加していない場合に返される、カスタムクレームを含むレスポンスを示しています。 
-- 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/ -- これはAuth0のオーディエンスです 
scope:openid profile

// 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",

  // 公開名前空間付きカスタムクレームは、この制限の対象外であるため追加されました。
  // ただし、プライベートな名前空間なしのカスタムクレーム {myATclaim} は無視されました。
  "https://mydomain.com/{myATclaim}": "this is a claim"
}

​
Auth0 および Webtask の名前空間に関する制限

Auth0 では、Auth0 のドメインを名前空間の識別子として使用する名前空間付きカスタムクレームを作成できません。Auth0 のドメインは次のとおりです。
  • auth0.com
  • webtask.io
  • webtask.run
上記いずれかのドメインを識別子として使用してトークンに名前空間付きカスタムクレームを設定しようとしても、その指定は無視されます。トランザクション自体は失敗しませんが、クレームはトークンに追加されません。
この移行以前は、Auth0 のドメインを識別子として名前空間付きカスタムクレームを設定すると、そのクレームは /userinfo レスポンスに含まれていました。移行後はこの動作はなくなり、そのようなカスタムクレームは完全に無視されます。
// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // これらはいずれもトークンにも /userinfo レスポンスにも追加されない
  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

​
例

// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // これまでは無視されていました。このマイグレーション以降、スコープに 'email' が含まれる場合、クレームはアクセストークンに追加されます
  api.accessToken.setCustomClaim('email', 'myemail@domin.com');

  // これまでは無視されていました。このマイグレーション以降、スコープに 'profile' が含まれる場合、クレームはアクセストークンに追加されます
  api.accessToken.setCustomClaim('family_name', 'A family name');

};

​
Auth0 Rules を使用した SAML2 アドオンおよび Web Service Federation Protocol (WS-Fed) の属性マッピング

Auth0 Rules を使用してユーザーオブジェクトを変更する場合と同様に、app_metadata または user_metadata の移行前クレームも、クレームが context.idToken オブジェクトに設定され、名前が競合している場合は内容がマージされます。オブジェクトのプロパティの詳細については、Rules におけるユーザーオブジェクトのプロパティを参照してください。 ただし、カスタムクレームを使用する場合、Auth0 は context.idToken オブジェクトに設定されたクレームを優先します。 この変更は、context.id_token を介して app_metadata と user_metadata を設定し (それらにオブジェクトを割り当て) 、同時にこれらのフィールドを アドオンまたは Protocol (WS-Fed) の属性マッピングで使用する Auth0 Rules に影響します。 例 1: context.idToken.app_metadata が空のオブジェクトに設定されている場合、Auth0 は属性マッピングを無視します。 
// 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 レスポンス: 
<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <saml:Attribute Name="a_claim" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">
                    This is a claim
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="another_claim" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">
                    This is a another claim
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>
アップグレード後の動作でのSAMLレスポンス: 
<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </saml:Assertion>
</samlp:Response>
例 2: context.id_token 内の app_metadata のバージョンが優先されます。 
// 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 レスポンス: 
<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <saml:Attribute Name="a_claim">
                <saml:AttributeValue xsi:type="xs:anyType">
                    This is a claim
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="another_claim">
                <saml:AttributeValue xsi:type="xs:anyType">
                    This is a another claim
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="claim_set_via_id_token">
                <saml:AttributeValue xsi:type="xs:anyType">
                    This is a claim which was set via context.idToken
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>
アップグレード後の動作でのSAMLレスポンス: 
<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <saml:Attribute Name="claim_set_via_id_token" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">
                    This is a claim which was set via context.idToken
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

​
トークンに非公開の名前空間なしクレームを追加する

カスタムクレーム ベータプログラムの参加者については、カスタムクレームの動作に変更はありません。この機能はすでに有効になっています。
アクセス トークンとIDトークンのペイロードに、非公開の名前空間なしカスタムクレームを追加できるようになりました。

​
例

// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // 以前は無視されていた
  // このマイグレーション以降、クレームはアクセストークンに追加される
  api.accessToken.setCustomClaim('myATclaim', 'this is a claim');

  // 以前は無視されていた
  // このマイグレーション以降、クレームはIDトークンに追加される
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');

};

​
/userinfo に返されるプライベートな名前空間なしクレーム

Auth0 は、IDトークンに設定されているプライベートな名前空間なしのカスタムクレームを、/userinfo のレスポンスでも返すようになりました。

​
例

// Auth0 Action 
exports.onExecutePostLogin = async (event, api) => {

  // これまでは無視されていました。 
  // このマイグレーション以降、このクレームは /userinfo で返されます
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');

};

-- /userinfo への呼び出し 
GET https://{yourTenant}.auth0.com/userinfo
Authorization: Bearer {yourAccessToken}

// /userinfo からのレスポンス
{
    "sub": ***,
    (...)
    "myIdTclaim": "this is a claim"
}

​
Actions

​
テナントログを確認する

まず、この移行の影響をテナントが受けるかどうかを判断するため、テナントログで非推奨の通知を確認します。
  1. Auth0 の Dashboard > Monitoring > Logs に移動します。
  2. ログで type: depnote AND description: *Custom*claims* を検索します。

​
例

以下は、拡張機能コードがトリガーされるたびに生成される非推奨ログの例です。 
{
  "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 Service Federation Protocol (Ws-Fed) の Auth0 Rules を修正する

属性マッピングと併用して Auth0 Rules を使用し、SAML2 アドオンまたは Web Service Federation Protocol (Ws-Fed) で context.idToken オブジェクトに app_metadata または user_metadata のクレームを設定している場合は、これらのオブジェクト間で競合するクレーム名を Auth0 がどのように評価するかに合わせて、設定を更新する必要があります。修正方法としては、次のようなものがあります。
  • Auth0 Rule のコードで、context.id_token に設定されたオブジェクトの内容が常に優先されるようにしてください。 
    // my_claim は無視されます。このコード行はすでに意味を持ちません。
// `context.idToken` に my_claim を設定することを優先してください
user.app_metadata.my_claim = 'a value'; 

// この app_metadata は、ほかのどの変更よりも優先されます
context.idToken.app_metadata = {
  another_claim: 'another value'
};

// SAML/WsFed レスポンスに含まれるのは `another_claim` のみです
  • SAML2 アドオンまたは Web Service Federation Protocol (Ws-Fed) の属性マッピングを使用している場合は、context.idToken オブジェクトに app_metadata または user_metadata のクレームを設定しないでください。可能であれば、これらのクレームは名前空間付きクレームに置き換えてください。 
    context.idToken['https://mydomain.com/app_metadata'] = {
  my_claim: 'my claim'
};
  • 現在のプロトコルまたは現在のクライアントに対する条件を使用して、プロトコルが samlp または wsfed の場合は app_metadata または user_metadata を設定するステートメントを除外します。 
    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 > テナント設定 > 詳細設定 に移動し、Migrations を検索します。
  2. トグルを使用して Custom claims must be namespaced を無効にします。