Migration des demandes personnalisées

À partir du 28 juillet 2022, Auth0 permettra d’ajouter des demandes personnalisées privées, sans espace de nommage, aux jetons d’accès et d’ID. Ces mêmes demandes ont également été ajoutées à la réponse du point de terminaison /userinfo. Pour en savoir plus sur les types de demandes , consultez Demandes de jetons Web JSON.

Bien qu’autorisant l’utilisation de revendications personnalisées privées, sans espace de noms, Auth0 recommande vivement l’utilisation de revendications personnalisées publiques, avec espace de noms, chaque fois que possible. Les demandes personnalisées publiques, avec espace de noms, sont le meilleur moyen d’éviter toute collision avec les futures demandes ajoutées à la norme.

Exemple

Antérieurement, Auth0 autorisait uniquement les demandes avec espace de noms sur les jetons d’accès et d’ID. Grâce à la migration vers les demandes personnalisées, les demandes sans espace de noms peuvent être utilisées sur les jetons d’accès, les jetons d’ID et le point de terminaison /userinfo de l’Authentication API Auth0.

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

Flux affectés

Tous les flux Connect (OIDC) pris en charge par Auth0 sont concernés par cette migration. Pour consulter la liste des flux, lisez Flux d’authentification et d’autorisation. Les fonctionnalités suivantes sont également affectées :

Les fonctionnalités suivantes ne sont concernées que lorsqu’elles sont utilisées conjointement avec les Règles d’Auth0 et le mappage d’attributs :

Restrictions

Taille maximale du jeton

Auth0 a restreint la charge utile des demandes personnalisées (100 Ko max.). Il est important de s’assurer que la charge utile ne dépasse pas cette limite, sinon la transaction d’authentification échouera et une erreur se produira. Nous vous recommandons de revoir votre utilisation du code d’extensibilité (c’est-à-dire les Règles, les Hooks ou les Actions). Plus particulièrement, vérifiez les charges utiles importantes provenant d’API externes. Pour éviter que des erreurs se produisent, Auth0 recommande d’utiliser la plus petite charge utile de jeton nécessaire au fonctionnement de votre application. Vous devrez peut-être supprimer toutes les propriétés qui ne sont pas cruciales avant de définir la valeur de la demande personnalisée.

Cette restriction s’applique à l’intégralité de la taille de la charge de toutes vos demandes personnalisées. Cela inclut les noms des demandes personnalisées 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 aux jetons d’accès et aux jetons d’ID séparément. À titre d’exemple, un jeton d’accès de 100 Ko et un jeton d’ID de 100 Ko peuvent être renvoyés au cours de la même transaction.

Exemples

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

};

Demandes restreintes

Auth0 restreindra la personnalisation des demandes utilisées dans les normes OIDC ou OAuth2 ou des demandes à usage interne. Toute tentative de modification de l’une de ces demandes sera ignorée. La transaction n’échouera pas, mais la demande ne sera pas ajoutée aux jetons. Auth0 recommande l’utilisation d’une demande publique, 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
nombre aléatoire
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

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

};

Audience de jetons restreints

Auth0 restreindra la création de demandes personnalisées privées, sans espace de noms, sur les jetons d’accès dont l’ est une API Auth0. Toute tentative de définition d’une demande personnalisée privée, sans espace de nommage, sur un jeton d’accès dont l’audience est une API Auth0 sera ignorée. La transaction n’échouera pas, mais la demande ne sera pas ajoutée à votre jeton. Auth0 recommande de ne pas définir de demandes personnalisées sur les jetons qui doivent être consommés par les API d’Auth0.

Les jetons d’ID ne sont pas concernés par cette restriction.
Les demandes personnalisées publiques à espace de noms ne sont pas concernées par cette restriction.

L’audience suivante restreint la création de demandes personnalisées privées, sans espacement 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 demandes personnalisées privées, sans espace de nom, sont autorisées pour les audiences suivantes :

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

Exemples

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

};

L’exemple ci-dessous vous montre la réponse renvoyée avec des demandes personnalisées si l’audience n’est pas une API Auth0 :

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

L’exemple ci-dessous vous montre la réponse renvoyée avec des demandes personnalisées qui n’ont pas été ajoutées avec une audience de l’API Auth0 :

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

Restriction sur les espaces de noms Auth0 et Webtask

Auth0 restreindra la création de demandes personnalisées avec espace de nommage comportant un domaine Auth0 comme identifiant d’espace de nommage. Les domaines Auth0 sont :

auth0.com
webtask.io
webtask.run

Auth0 restreindra la création de demandes personnalisées avec espace de nommage comportant un domaine Auth0 comme identifiant d’espace de nommage. Les domaines Auth0 sont :

Avant cette migration, la définition d’une demande personnalisée à espace de noms avec un identifiant de domaine Auth0 entraînait l’affichage de la demande dans la réponse /userinfo. Ce comportement disparaît après la migration et ces demandes personnalisées sont complètement ignorées.

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

};

Demandes de profil utilisateur OIDC

Auth0 permet désormais d’ajouter aux jetons d’accès des demandes de profil utilisateur OIDC. Auth0 permet désormais d’ajouter aux jetons d’accès des demandes de profil utilisateur OIDC.

Si vous ajoutez des demandes de profil utilisateur OIDC à des jetons d’accès, les mêmes restrictions de permissions que celles applicables aux jetons d’ID s’appliquent. Par exemple, pour ajouter la demande de courriel aux jetons d’accès, le flux doit être déclenché avec une permission contenant le courriel.

Vous pouvez ajouter les demandes de profil d’utilisateur OIDC suivantes 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

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

};

Module complémentaire SAML2 et protocole Web Service Federation (WS-Fed) avec règles d’Auth0

De la même manière que les règles Auth0 permettent de modifier l’objet utilisateur, les demandes de pré-migrationapp_metadata ou user_metadata fusionnent également le contenu lorsque la demande est définie sur l’objet context.idToken et que les noms sont en conflit. Pour en savoir plus sur les propriétés de l’objet, consultez Propriétés de l’objet utilisateur dans les règles. Cependant, en utilisant des demandes personnalisées, Auth0 privilégie la demande qui a été définie sur l’objet context.idToken. Ce changement a un impact sur les règles d’Auth0 qui définissent app_metadata et user_metadata via 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 ou le protocole (WS-Fed). Exemple 1 : Auth0 ignore le mappage d’attributs lorsque context.idToken.app_metadata est défini avec un objet vide.

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

Réponse SAML avant la 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 avec app_metadata dans context.id_token est prioritaire.

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

Réponse SAML avant la 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 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: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 demandes privées, sans espace de noms, aux jetons

Le comportement des demandes personnalisées ne changera pas pour les membres du programme Bêta concerné. Cette fonctionnalité est déjà activée.

Vous pouvez désormais ajouter des demandes personnalisées privées, sans espace de noms, à la charge utile des jetons d’accès et d’ID.

Exemple

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

};

Demandes privées, sans espace de noms, vers /userinfo

Auth0 renvoie désormais des demandes personnalisées privées, sans espace de noms, dans la réponse /userinfo lorsqu’elles sont définies sur des jetons d’ID.

Exemple

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

Actions

Examiner les journaux de locataires

Vérifiez d’abord les avis de dépréciation dans les journaux de vos locataires afin de déterminer si votre locataire est concerné par la migration.

Naviguez vers Auth0 Dashboard > Surveillance > Journaux.
Recherchez dans les journaux type: depnote AND description: *Custom*claims*.

Exemple

Vérifiez d’abord les avis de dépréciation dans les journaux de vos locataires afin de déterminer si votre locataire est concerné par la migration.

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

Correction des règles d’Auth0 pour le module complémentaire SAML2 et le protocole Web Service Federation (Ws-Fed)

Si vous définissez des demandes app_metadata ou user_metadata sur l’objet context.idToken en utilisant le module complémentaire SAML2 ou le protocole Web Service Federation (Ws-Fed) avec les règles d’Auth0 ainsi que le mappage d’attributs, vous devrez mettre à jour votre configuration pour ajuster la façon dont Auth0 évalue les conflits de noms de demandes entre ces objets. Plusieurs solutions sont possibles :

Assurez-vous que le code de votre règle Auth0 privilégie toujours le contenu des objets définis sur 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

Si vous utilisez le module complémentaire SAML2 ou le mappage d’attributs du protocole Ws-Fed (Web Service Federation Protocol), évitez de définir des demandes app_metadata ou user_metadata sur l’objet context.idToken. Remplacez ces demandes par des demandes avec espace de nom lorsque c’est 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 déclarations définissant 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 l’ancien comportement, nous vous recommandons de consulter la liste des modifications et de vérifier que vos applications et intégrations sont compatibles.

Si votre locataire ne dispose pas de l’option de bascule, il n’est pas affecté et aucune autre action n’est nécessaire.

Naviguez vers Auth0 Dashboard > Paramètres du locataire > Avancé et recherchez Migrations.
Utilisez la case à cocher pour désactiver l’option les demandes personnalisées doivent avoir un espace de nommage.

Obtenir de l’aide

Dépannage

Cycle de vie des produits Auth0

Migration des demandes personnalisées

Exemple

Flux affectés

Restrictions

Taille maximale du jeton

Exemples

Demandes restreintes

Exemple

Audience de jetons restreints

Exemples

Restriction sur les espaces de noms Auth0 et Webtask

Demandes de profil utilisateur OIDC

Exemple

Module complémentaire SAML2 et protocole Web Service Federation (WS-Fed) avec règles d’Auth0

Ajouter des demandes privées, sans espace de noms, aux jetons

Exemple

Demandes privées, sans espace de noms, vers /userinfo

Exemple

Actions

Examiner les journaux de locataires

Exemple

Correction des règles d’Auth0 pour le module complémentaire SAML2 et le protocole Web Service Federation (Ws-Fed)

Désactiver le comportement hérité

​Exemple

​Flux affectés

​Restrictions

​Taille maximale du jeton

​Exemples

​Demandes restreintes

​Exemple

​Audience de jetons restreints

​Exemples

​Restriction sur les espaces de noms Auth0 et Webtask

​Demandes de profil utilisateur OIDC

​Exemple

​Module complémentaire SAML2 et protocole Web Service Federation (WS-Fed) avec règles d’Auth0

​Ajouter des demandes privées, sans espace de noms, aux jetons

​Exemple

​Demandes privées, sans espace de noms, vers /userinfo

​Exemple

​Actions

​Examiner les journaux de locataires

​Exemple

​Correction des règles d’Auth0 pour le module complémentaire SAML2 et le protocole Web Service Federation (Ws-Fed)

​Désactiver le comportement hérité

Exemple

Flux affectés

Restrictions

Taille maximale du jeton

Exemples

Demandes restreintes

Exemple

Audience de jetons restreints

Exemples

Restriction sur les espaces de noms Auth0 et Webtask

Demandes de profil utilisateur OIDC

Exemple

Module complémentaire SAML2 et protocole Web Service Federation (WS-Fed) avec règles d’Auth0

Ajouter des demandes privées, sans espace de noms, aux jetons

Exemple

Demandes privées, sans espace de noms, vers /userinfo

Exemple

Actions

Examiner les journaux de locataires

Exemple

Correction des règles d’Auth0 pour le module complémentaire SAML2 et le protocole Web Service Federation (Ws-Fed)

Désactiver le comportement hérité