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 JWT, 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');
};Was this helpful?
Flux affectés
Tous les flux OpenID 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);
};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?
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.
acractactiveamrat_hashathattestaudauth_timeauthorization_detailsazpc_hashclient_idcnfctydestentitlementseventsexpgroupsgtyhtmhtuiatinternalServiceissjcardjkujtijwejwkkidmay_actmkynbfnombre aléatoireobject_idorg_idorg_nameorigorigidpermissionsrolesrphs_hashsidsip_callidsip_cseq_numsip_datesip_from_tagsip_via_branchsubsub_jwktoetxntypuuidvotvtmx5t#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');
};Was this helpful?
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'audience 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/apiouhttps://YOUR_TENANT.auth0app.com/apihttps://YOUR_TENANT.auth0.com/api/v2ouhttps://YOUR_TENANT.auth0app.com/api/v2https://YOUR_TENANT.auth0.com/mfaouhttps://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/userinfohttps://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');
};Was this helpful?
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 profileWas 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?
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 profileWas 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?
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');
};Was this helpful?
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 :
addressbirthdateemailemail_verifiedfamily_namegendergiven_namelocalemiddle_namenamenicknamephone_numberphone_number_verifiedpicturepreferred_usernameprofileupdated_atwebsitezoneinfo
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');
};Was this helpful?
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 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 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);
}Was this helpful?
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>Was this helpful?
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>Was this helpful?
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);
}Was this helpful?
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>Was this helpful?
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>Was this helpful?
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');
};Was this helpful?
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');
};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?
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": ****
}Was this helpful?
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 responsesWas this helpful?
/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_metadataouuser_metadatasur l’objetcontext.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' };Was this helpful?
/Utilisez une condition sur le protocole actuel ou sur le client actuel pour exclure les déclarations définissant
app_metadataouuser_metadatalorsque le protocole estsamlpouwsfed.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?
/
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.