カスタムクレームの移行

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

例

これまで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');
};

Was this helpful?

/

影響を受けるフロー

Auth0がサポートするすべてのOpenID Connect（OIDC）フローがこの移行の影響を受けます。フローの一覧は、「認証および認可のフロー」でお読みください。

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

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

制限

トークンサイズの上限

カスタムクレームのペイロードを最大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);

};

Was this helpful?

/

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

};

Was this helpful?

/

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

};

Was this helpful?

/

予約済みのクレーム

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

};

Was this helpful?

/

トークンオーディエンスの制限

Auth0では、オーディエンスがAuth0 APIであるアクセストークンでの、プライベートで名前空間のないカスタムクレームの作成を制限します。オーディエンスがAuth0 APIであるアクセストークンでプライベートの名前空間のないカスタムクレームを設定する試みは、すべて無視されます。トランザクションは失敗しませんが、当該クレームがトークンに追加されることはありません。Auth0では、Auth0のAPIによって使用されるトークンにカスタムクレームを設定しないことを推奨しています。

次のオーディエンスは、プライベートで名前空間のないカスタムクレームの作成を制限します。

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

};

Was this helpful?

/

以下の例は、オーディエンスが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://{yourApi}.com -- Note the audience, that is a custom API
scope:openid profile

Was this helpful?

/

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

Was this helpful?

/

以下の例は、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

Was this helpful?

/

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

Was this helpful?

/

Auth0とWebtaskの名前空間の制約

Auth0では、Auth0ドメインを名前空間識別子として使用した、名前空間ありのカスタムクレームの作成を制限します。Auth0ドメインは以下の通りです。

  • auth0.com

  • webtask.io

  • webtask.run

上記のいずれかの識別子を使用してトークンに名前空間のあるカスタムクレームを設定しようとする試みは、すべて無視されます。トランザクションは失敗しませんが、当該クレームがトークンに追加されることはありません。

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

};

Was this helpful?

/

OIDCユーザープロファイルクレーム

Auth0では、OIDCユーザープロファイルクレームをアクセストークンに追加できるようになりました。

この移行前は、OIDCユーザープロファイルクレームをアクセストークンに追加する試みは、サイレントに無視されていました。しかし、更新後の動作では、アクセストークンにこれらのOIDCユーザープロファイルクレームを含むことができます。

次の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', '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');

};

Was this helpful?

/

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

Was this helpful?

/

この移行前の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>

Was this helpful?

/

アップグレード後の動作の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>

Was this helpful?

/

例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);
}

Was this helpful?

/

この移行前の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>

Was this helpful?

/

アップグレード後の動作の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>

Was this helpful?

/

プライベートで名前空間のないクレームをトークンに追加する

プライベートで名前空間のないカスタムクレームをアクセストークンおよび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');

};

Was this helpful?

/

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

};

Was this helpful?

/

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

Was this helpful?

/

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

Was this helpful?

/

アクション

テナントログを確認する

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

  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": ****
}

Was this helpful?

/

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

    Was this helpful?

    /

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

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

    Was this helpful?

    /

  • プロトコルが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"
    };
}

    Was this helpful?

    /

レガシーの動作を無効にする

  1. ［Auth0 Dashboard］>［Tenant Settings（テナント設定）］>［Advanced（詳細設定）］に移動して、［Migrations（移行）］を探します。

  2. トグルで［Custom claims must be namespaced（カスタムクレームは名前空間ありでなければならない）］を無効にします。