Migrer les claims personnalisés

Décrit la migration des claims avec espace de noms Legacy vers des claims personnalisés.

À compter du 28 juillet 2022, Auth0 permettra d’ajouter des claims personnalisés privés sans espace de noms aux jetons d’accès et aux jetons d’identité. Ces mêmes claims seront également ajoutés à la réponse de l’endpoint /userinfo. Pour en savoir plus sur les types de claims dans les JWT, consultez Claims d’un JSON Web Token.

Bien qu’Auth0 permette l’utilisation de claims personnalisés privés sans espace de noms, il recommande fortement d’utiliser des claims personnalisés publics avec espace de noms chaque fois que possible. Les claims personnalisés publics avec espace de noms constituent la meilleure façon d’éviter toute collision avec de futurs claims ajoutés à la norme.

​

Exemple

Auparavant, Auth0 n’autorisait que les claims avec espace de noms dans les jetons d’accès et les jetons d’identité. Avec la migration vers les claims personnalisés, les claims sans espace de noms peuvent être utilisés dans les jetons d’accès, les jetons d’identité et le endpoint /userinfo de l’Authentication API d’Auth0.

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

  // claims personnalisés publics avec espace de noms 
  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');

  // claims personnalisés sans espace de noms
  api.accessToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
  api.idToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
};

​

Flux concernés

Tous les flux OpenID Connect (OIDC) pris en charge par Auth0 sont touchés par cette migration. Pour consulter la liste des flux, lisez Flux d’authentification et d’autorisation.

Les fonctionnalités suivantes sont aussi touchées :

• Native Social Login
• Jetons d’actualisation

Les fonctionnalités suivantes sont touchées uniquement lorsqu’elles sont utilisées avec Auth0 Rules et le mappage d’attributs :

• Web Services Federation Protocol (WS-Fed)
• module complémentaire SAML2 Web App

​

Restrictions

​

Taille maximale du jeton

Auth0 limite la charge utile des claims personnalisés à un maximum de 100 Ko. Il est important de vous assurer que la charge utile ne dépasse pas cette limite, sinon la transaction d’authentification échouera avec une erreur. Nous vous recommandons de revoir votre utilisation du code d’extensibilité (c.-à-d. Rules, Hooks ou Actions). Vérifiez en particulier les charges utiles volumineuses provenant d’API externes.

Pour éviter les erreurs, Auth0 recommande d’utiliser la plus petite charge utile de jeton nécessaire au fonctionnement de votre application. Vous devrez peut-être supprimer les propriétés non essentielles avant de définir la valeur du claim personnalisé.

Cette restriction s’applique à la taille totale de la charge utile de tous vos claims personnalisés. Cela comprend les noms des claims personnalisés ainsi que les valeurs associées, qu’elles soient publiques avec espace de noms ou privées sans espace de noms.

La limite de 100 Ko s’applique séparément aux jetons d’accès et aux jetons d’identité. Par exemple, un jeton d’accès de 100 Ko et un jeton d’identité de 100 Ko peuvent être renvoyés dans la même transaction.

​

Exemples

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

  // récupération d'un payload supérieur à 100 Ko
  const aHeavyPayload = getHeavyPayload();

  // ceci fera échouer l'authentification
  api.idToken.setCustomClaim('myclaim', aHeavyPayload);

};

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

  // récupération d'un payload de 50 Ko
  const a50KBPayload = getHeavyPayload();

  // récupération d'un autre payload de 50 Ko
  const another50KBPayload = getHeavyPayload();

  // ceci fera échouer l'authentification
  api.idToken.setCustomClaim('myclaim', a50KBPayload);
  api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);

};

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

  // récupération d'un payload de 50 Ko
  const a50KBPayload = getHeavyPayload();

  // récupération d'un autre payload de 50 Ko
  const another50KBPayload = getHeavyPayload();

  // ceci réussira
  api.accessToken.setCustomClaim('myclaim', a50KBPayload);
  api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);

};

​

Claims restreints

Auth0 restreint la personnalisation des claims utilisés par les normes OIDC ou OAuth2, ainsi que des claims réservés à un usage interne. Toute tentative de modifier l’un de ces claims sera ignorée. La transaction n’échouera pas, mais le claim ne sera pas inclus dans les jetons. Auth0 recommande d’utiliser un claim public avec espace de noms.

• 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

​

Exemple

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

  // ceci sera ignoré
  api.accessToken.setCustomClaim('roles', 'this is a role, but Auth0 will ignore it');

  // ceci réussira et apparaîtra dans le jeton
  api.idToken.setCustomClaim('https://myDomain.com/roles', 'this is a role');

};

​

Audience restreinte des jetons

Auth0 limitera la création de claims personnalisés privés, sans espace de noms, sur les jetons d’accès dont l’audience correspond à une Auth0 API. Toute tentative de définir un claim personnalisé privé, sans espace de noms, sur un jeton d’accès dont l’audience est une Auth0 API sera ignorée. La transaction n’échouera pas, mais le claim ne sera pas ajouté à votre jeton. Auth0 recommande de ne pas définir de claims personnalisés sur les jetons destinés aux API d’Auth0.

• Les jetons d’identité ne sont pas visés par cette restriction.
• Les claims personnalisés publics avec espace de noms ne sont pas visés par cette restriction.

Les audiences suivantes limiteront la création de claims personnalisés privés, sans espace de noms :

• https://YOUR_TENANT.auth0.com/api ou https://YOUR_TENANT.auth0app.com/api
• https://YOUR_TENANT.auth0.com/api/v2 ou https://YOUR_TENANT.auth0app.com/api/v2
• https://YOUR_TENANT.auth0.com/mfa ou https://YOUR_TENANT.auth0app.com/mfa

L’exception à cette restriction est l’audience Auth0 /userinfo. Les claims personnalisés privés, sans espace de noms, sont autorisés pour les audiences suivantes :

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

​

Exemples

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

  // ceux-ci seront ignorés si l'audience est une audience Auth0
  api.accessToken.setCustomClaim('myATclaim', 'this is a claim');
  api.accessToken.setCustomClaim('https://myDomain.com/myATclaim', 'this is a claim');

  // ceux-ci réussiront, ils ne sont pas touchés par la restriction d'audience
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');
  api.idToken.setCustomClaim('https://myDomain.com/myIdTclaim', 'this is a claim');

};

L’exemple ci-dessous montre la réponse retournée avec des claims personnalisés si l’audience n’est pas une Auth0 API :

-- Un flow Resource Owner Password 
POST https://{yourTenant}.auth0.com/oauth/token

grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourApi}.com -- Notez l'audience, il s'agit d'une API personnalisée
scope:openid profile

L’exemple ci-dessous montre la réponse renvoyée lorsque des claims personnalisés ne sont pas ajoutés avec une audience de l’Auth0 API :

-- Un flux Resource Owner Password 
POST https://{yourTenant}.auth0.com/oauth/token

grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourTenant}.auth0.com/api/v2/ -- Il s'agit d'une audience Auth0 
scope:openid profile

// Le jeton d'accès retourné par 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",

  // Les claims personnalisés avec espace de noms public ont été ajoutés, car elles ne sont pas visées par cette restriction
  // Cependant, le claim personnalisé privé sans espace de noms {myATclaim} a été ignoré
  "https://mydomain.com/{myATclaim}": "this is a claim"
}

​

Restriction sur les espaces de noms Auth0 et Webtask

Auth0 limitera la création de claims personnalisés avec espace de noms dont l’identifiant d’espace de noms est un domaine Auth0. Les domaines Auth0 sont :

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

Toute tentative de définir un claim personnalisé avec espace de noms sur un token en utilisant l’un des domaines ci-dessus comme identifiant sera ignorée. La transaction n’échouera pas, mais le claim ne sera pas ajouté à votre token.

Avant cette migration, le fait de définir un claim personnalisé avec espace de noms à l’aide d’un identifiant de domaine Auth0 faisait en sorte que le claim apparaissait dans la réponse /userinfo. Ce comportement disparaît après la migration, et ces claims personnalisés sont complètement ignorés.

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

  // aucun de ces éléments ne sera ajouté aux jetons ni à la réponse /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');

};

​

Claims du profil utilisateur OIDC

Auth0 permet maintenant d’ajouter des claims du profil utilisateur OIDC aux jetons d’accès.

Avant cette migration, les tentatives d’ajout de claims du profil utilisateur OIDC au jeton d’accès étaient ignorées sans avertissement. Avec ce comportement mis à jour, les jetons d’accès contiendront ces claims du profil utilisateur OIDC.

Si vous ajoutez des claims du profil utilisateur OIDC aux jetons d’accès, les mêmes restrictions de scope s’appliquent que pour les jetons d’identité. Par exemple, pour ajouter le claim email aux jetons d’accès, le flow doit être déclenché avec un scope contenant email.

Vous pouvez ajouter les claims du profil utilisateur OIDC suivants aux jetons d’accès :

• 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

​

Exemple

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

  // ceci était ignoré jusqu'à présent. À partir de cette migration, le claim sera ajouté aux jetons d'accès 
  // si le scope contient 'email'
  api.accessToken.setCustomClaim('email', '[e-mail]');

  // ceci était ignoré jusqu'à présent. À partir de cette migration, le claim sera ajouté aux jetons d'accès 
  // si le scope contient 'profile'
  api.accessToken.setCustomClaim('family_name', 'A family name');

};

​

Mappage d’attributs du module complémentaire SAML2 et du protocole Web Service Federation (WS-Fed) avec Auth0 Rules

Comme avec Auth0 Rules pour modifier l’objet user, les claims de prémigration app_metadata ou user_metadata fusionnent aussi leur contenu lorsque le claim est défini dans l’objet context.idToken et que les noms sont en conflit. Pour en savoir plus sur les propriétés de l’objet, consultez User Object Properties In Rules.

Toutefois, dans le cas des custom claims, Auth0 donne priorité au claim défini dans l’objet context.idToken.

Ce changement a une incidence sur les Auth0 Rules qui définissent app_metadata et user_metadata au moyen de context.id_token (en leur assignant des objets) et qui, en même temps, utilisent ces champs dans le mappage d’attributs pour le module complémentaire SAML ou le protocole Web Service Federation (WS-Fed).

Exemple 1 : Auth0 ignore le mappage d’attributs lorsque context.idToken.app_metadata est défini comme un objet vide.

// une règle 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);
}

Réponse SAML avant cette migration :

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

Réponse SAML avec le comportement mis à jour :

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

Exemple 2 : La version de app_metadata dans context.id_token prévaut.

// une règle 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 Response avant cette migration :

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

Réponse SAML avec le nouveau comportement :

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

​

Ajouter des claims personnalisés privés sans espace de noms aux jetons

Le comportement des claims personnalisés restera inchangé pour les membres du programme bêta des claims personnalisés. Cette fonctionnalité est déjà activée.

Vous pouvez maintenant ajouter des claims personnalisés privés sans espace de noms au payload des jetons d’accès et d’ID.

​

Exemple

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

  // précédemment ignoré
  // À partir de cette migration, la revendication sera ajoutée aux jetons d'accès
  api.accessToken.setCustomClaim('myATclaim', 'this is a claim');

  // précédemment ignoré
  // À partir de cette migration, la revendication sera ajoutée aux jetons d'identité
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');

};

​

Revendications privées sans espace de noms dans /userinfo

Auth0 renvoie désormais les revendications personnalisées privées sans espace de noms dans la réponse /userinfo lorsqu’elles sont définies dans les jetons d’identité.

​

Exemple

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

  // ceci était ignoré jusqu'à présent. 
  // À partir de cette migration, ce claim sera retourné dans /userinfo
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');

};

-- une requête vers /userinfo 
GET https://{yourTenant}.auth0.com/userinfo
Authorization: Bearer {yourAccessToken}

// la réponse de /userinfo
{
    "sub": ***,
    (...)
    "myIdTclaim": "this is a claim"
}

​

Actions

​

Vérifier les journaux du tenant

Commencez par vérifier les journaux du tenant pour repérer les avis de dépréciation et déterminer si votre tenant est touché par la migration.

1. Accédez à Auth0 Dashboard > Monitoring > Logs.
2. Recherchez dans les journaux type: depnote AND description: *Custom*claims*.

​

Exemple

Vous trouverez ci-dessous un exemple de journal de dépréciation généré chaque fois que du code d’extensibilité est exécuté.

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

​

Corriger les règles Auth0 pour le module complémentaire SAML2 et le protocole Web Service Federation (Ws-Fed)

Si vous définissez des claims app_metadata ou user_metadata sur l’objet context.idToken à l’aide du module complémentaire SAML2 ou du protocole Web Service Federation (Ws-Fed) avec Auth0 Rules, ainsi qu’un mappage d’attributs, vous devrez mettre à jour votre configuration pour tenir compte de la façon dont Auth0 évalue les noms de claims en conflit entre ces objets. Plusieurs correctifs sont possibles :

• Assurez-vous que le code de votre règle Auth0 donne toujours priorité au contenu des objets définis sur context.id_token :

  // my_claim sera ignoré, cette ligne de code n'est plus pertinente,
  // privilégiez plutôt la définition de my_claim sur `context.idToken`
  user.app_metadata.my_claim = 'a value'; 
  
  // cette version de app_metadata aura préséance sur toute autre modification 
  context.idToken.app_metadata = {
    another_claim: 'another value'
  };
  
  // Seul `another_claim` apparaîtra dans les réponses SAML/WsFed
  

• Si vous utilisez le mappage d’attributs du module complémentaire SAML2 ou du protocole Web Service Federation (Ws-Fed), évitez de définir des claims app_metadata ou user_metadata sur l’objet context.idToken. Remplacez ces claims par des claims avec espace de noms lorsque possible :

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

• Utilisez une condition sur le protocole actuel ou sur le client actuel pour exclure les instructions qui définissent app_metadata ou user_metadata lorsque le protocole est samlp ou wsfed.

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

​

Désactiver le comportement hérité

Avant de désactiver le comportement hérité, nous vous recommandons de consulter la liste des modifications et de vérifier que vos applications et intégrations sont compatibles.

Si votre tenant n’a pas d’option de bascule, il n’est pas concerné et aucune autre action n’est requise.

1. Accédez à Auth0 Dashboard > Paramètres du tenant > Avancé et recherchez Migrations.
2. Utilisez la bascule pour désactiver Les claims personnalisés doivent utiliser un espace de noms.