カスタムクレームへの移行

従来の名前空間付きクレームからカスタムクレームへ移行する方法を説明します。

2022年7月28日以降、Auth0 では、非公開かつ名前空間なしのカスタムクレームをアクセストークンと ID トークン に追加できるようになりました。これらのクレームは、/userinfo エンドポイント のレスポンスにも追加されます。JWT クレームの種類について詳しくは、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 がサポートするすべての OpenID Connect (OIDC) フローは、この移行の影響を受けます。フローの一覧については、認証および認可フローをご覧ください。

次の機能も影響を受けます：

• ネイティブソーシャルログイン
• リフレッシュトークン

次の機能は、ルールおよび属性マッピングと併用する場合にのみ影響を受けます：

• Web Services Federation Protocol (WS-Fed)
• SAML2 Web app add-on

​

制限事項

​

最大トークンサイズ

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 標準で使用されるクレームや、内部利用向けのクレームのカスタマイズは制限されています。これらのクレームを変更しようとしても、その変更は無視されます。transaction は失敗しませんが、そのクレームは token に追加されません。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');

};

​

制限対象のトークン audience

audience が Auth0 API であるアクセストークンでは、非公開かつ名前空間なしのカスタムクレームの作成が Auth0 によって制限されます。audience が Auth0 API のアクセストークンに非公開かつ名前空間なしのカスタムクレームを設定しようとしても、その試みは無視されます。トランザクションは失敗しませんが、そのクレームはトークンに追加されません。Auth0 は、Auth0 の API で使用されるトークンにはカスタムクレームを設定しないことを推奨しています。

• ID トークンはこの制限の対象ではありません。
• 公開の名前空間付きカスタムクレームはこの制限の対象ではありません。

次の audience では、非公開かつ名前空間なしのカスタムクレームの作成が制限されます。

• 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 audience です。次の audience では、非公開かつ名前空間なしのカスタムクレームが許可されます。

• https://YOUR_TENANT.auth0.com/userinfo
• https://YOUR_TENANT.auth0app.com/userinfo

​

例

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

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

  // これらはaudienceの制限対象外のため、成功します
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');
  api.idToken.setCustomClaim('https://myDomain.com/myIdTclaim', 'this is a claim');

};

以下の例は、audience が Auth0 API でない場合に返される、カスタムクレームを含むレスポンスを示しています。

-- リソース所有者パスワードフロー 
POST https://{yourTenant}.auth0.com/oauth/token

grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourApi}.com -- audienceに注意。これはカスタムAPIです
scope:openid profile

以下の例は、Auth0 API の audience を追加しない場合に、カスタムクレームが追加されないレスポンスを示しています。

-- リソース所有者パスワードフロー 
POST https://{yourTenant}.auth0.com/oauth/token

grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourTenant}.auth0.com/api/v2/ -- これはAuth0のaudienceです 
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 では、名前空間の identifier として Auth0 ドメインを使った、名前空間付きカスタムクレームは作成できません。Auth0 ドメインは次のとおりです。

• auth0.com
• webtask.io
• webtask.run

上記いずれかのドメインを identifier として使って token に名前空間付きカスタムクレームを設定しようとしても、その試みは無視されます。transaction 自体は失敗しませんが、クレームは token に追加されません。

この移行以前は、Auth0 ドメインを identifier にした名前空間付きカスタムクレームを設定すると、そのクレームは /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', '[e-mail]');

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

};

​

Auth0 ルールを使用した SAML2 add-on および Web Service Federation Protocol (WS-Fed) の属性マッピング

Auth0 ルールを使用してユーザーオブジェクトに変更を加える場合と同様に、app_metadata または user_metadata の移行前クレームでも、クレームが context.idToken オブジェクトに設定されていて名前が競合する場合は、内容がマージされます。オブジェクトのプロパティについて詳しくは、Rules 内のユーザーオブジェクトのプロパティ を参照してください。

ただし、カスタムクレームを使用する場合、Auth0 は context.idToken オブジェクトに設定されたクレームを優先します。

この変更は、context.id_token を介して app_metadata と user_metadata を設定し (それらにオブジェクトを代入し) 、同時に SAML add-on または Web Service Federation Protocol (WS-Fed) の属性マッピングでこれらのフィールドを使用する Auth0 ルールに影響します。

例 1: context.idToken.app_metadata が空のオブジェクトに設定されている場合、Auth0 は属性マッピングを無視します。

// Auth0 ルール
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 ルール
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) 用のルールを修正する

SAML2 アドオンまたは Web Service Federation Protocol (Ws-Fed) で属性マッピングとあわせて ルールを使用し、context.idToken オブジェクトに app_metadata または user_metadata のクレームを設定している場合は、これらのオブジェクト間でクレーム名が競合した際の Auth0 の評価方法に合わせて、設定を更新する必要があります。対処方法としては、次のようなものがあります。

• ルールのコードで、context.id_token に設定したオブジェクトの内容が常に優先されるようにしてください。

  // 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 Service Federation Protocol (Ws-Fed) の属性マッピングを使用している場合は、context.idToken オブジェクトに app_metadata または user_metadata のクレームを設定しないでください。可能であれば、これらのクレームは名前空間付きクレームに置き換えてください。

  context.idToken['https://mydomain.com/app_metadata'] = {
    my_claim: 'my claim'
  };
  

• 現在のプロトコルまたは現在の client に条件を設け、プロトコルが samlp または wsfed の場合は、app_metadata または user_metadata を設定する記述を除外してください。

  if (!['samlp', 'wsfed'].includes(context.protocol)) {
      context.idToken.app_metadata = {
        claim_set_via_id_token: "これは context.idToken を介して設定された claim です"
      };
  }
  

​

従来の動作を無効にする

従来の動作を無効にする前に、変更点の一覧を確認し、アプリケーションと連携に互換性があることを確認することをおすすめします。

テナントにこのトグルオプションが表示されない場合、そのテナントは影響を受けていないため、ほかに必要な対応はありません。

1. Auth0 Dashboard > Tenant Settings > Advanced に移動し、Migrations を検索します。
2. トグルを使用して Custom claims must be namespaced を無効にします。