カスタムクレームの移行

レガシーの名前空間のあるクレームからカスタムクレームへの移行について説明します。

Auth0では、2022年7月28日より、名前空間のないプライベートのカスタムクレームをアクセストークンとIDトークンに追加できるようになりました。これらのクレームは、/userinfoエンドポイントの応答にも追加されます。JWTクレームのタイプについては、「JSON Web Tokenクレーム」をお読みください。

プライベートで名前空間のないカスタムクレームを使用することはできますが、Auth0では可能な限り、パブリックで名前空間のあるカステムクレームの使用を強くお勧めします。後でクレームを標準に追加した際の衝突を避けるには、パブリックで名前空間のあるカステムクレームを使うことが最善の方法になります。

​

例

これまでAuth0では、名前空間のあるクレームしかアクセストークンとIDトークンに許可されていませんでした。カスタムクレームへの本移行により、今後は名前空間のないクレームをAuth0のAuthentication APIのアクセストークン、IDトークン、および/userinfoエンドポイントで使用できます。

// 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）フローがこの移行の影響を受けます。フローの一覧は、「認証および認可のフロー」でお読みください。

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

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

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

• Web Services Federation（WS-Fed）プロトコル
• SAML2 Webアプリアドオン

​

制限

​

トークンサイズの上限

カスタムクレームのペイロードを最大100KBに制限します。認証トランザクションがエラーで失敗しないよう、ペイロードがこの上限を超えないようにすることが大切です。拡張コード（Rules、HooksまたはActions）の使用を確認することを推奨します。特に、外部APIからの大きなペイロードを確認してください。

エラーを防ぐため、Auth0ではアプリケーションの操作に必要な最小限のトークンペイロードを使用することを推奨しています。カスタムクレーム値を設定する前に、重要でないプロパティをすべて削除しなければならない場合があります。

この制限は、全カスタムクレームのペイロードサイズの合計に適用されます。それには、名前空間があるパブリックのカスタムクレームか名前空間のないプライベートのカスタムクレームかにかかわらず、カスタムクレーム名とその関連値が含まれます。

100KBの制限は、アクセストークンとIDトークンにそれぞれ個別に適用されます。たとえば、同じトランザクションで100KBのアクセストークンと100KBのIDトークンを返すことが可能です。

​

例

// 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);

};

// 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);

};

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

​

例

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

​

例

// 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でない場合に返されるカスタムクレーム付きの応答を示しています。

-- 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

以下の例は、Auth0 APIオーディエンスで返される、カスタムクレームが追加されていない応答を示しています。

-- 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

// 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応答に含まれてしまいます。この動作は、移行後には解消され、該当するカスタムクレームが完全に無視されます。

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

​

例

// 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', '[e-mail]');

  // 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のユーザーオブジェクトプロパティ」をお読みください。

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

この変更は、context.id_token経由でapp_metadataおよびuser_metadataを設定する（それらにオブジェクトを割り当てる）と同時に、SAMLアドオンまたはWebサービスフェデレーション（WS-Fed）プロトコルの属性マッピングでこれらのフィールドを使用するAuth0 Rulesに影響を与えます。

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

// 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応答：

<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のバージョンが優先されます。

// 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応答：

<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トークンのペイロードに追加できるようになりました。

​

例

// 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応答でプライベートの名前空間のないカスタムクレームを返すようになりました。

​

例

// 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');

};

-- a call to /userinfo 
GET https://{yourTenant}.auth0.com/userinfo
Authorization: Bearer {yourAccessToken}

// the response from /userinfo
{
    "sub": ***,
    (...)
    "myIdTclaim": "this is a claim"
}

​

アクション

​

テナントログを確認する

まず、テナントログで廃止の通知を確認して、テナントが移行の影響を受けるかどうかを判断します。

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サービスフェデレーション（WS-Fed）プロトコルのAuth0ルールを修正する

Auth0 Rulesと属性マッピングを使用したSAML2アドオンおよびWebサービスフェデレーション（WS-Fed）プロトコルを使って、context.idTokenオブジェクトにapp_metadataまたはuser_metadataクレームを設定する場合、構成を更新して、Auth0がこれらのオブジェクト間の衝突するクレーム名を評価する方法を調整する必要があります。修正方法にはいくつかあります。

• 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サービスフェデレーション（WS-Fed）プロトコルの属性マッピングを使用する場合は、app_metadataまたはuser_metadataクレームをcontext.idTokenオブジェクトに設定しないようにします。可能な場合は、これらのクレームを名前空間のあるクレームに置き換えます。

  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］>［Tenant Settings（テナント設定）］>［Advanced（詳細設定）］に移動して、［Migrations（移行）］ を探します。
2. トグルで ［Custom claims must be namespaced（カスタムクレームは名前空間ありでなければならない）］ を無効にします。