Describe la migración de claims con espacio de nombres legado a claims personalizados.
A partir del 28 de julio de 2022, Auth0 permitirá agregar claims personalizados privados sin espacio de nombres a los tokens de acceso y a los . Estos mismos claims también se agregarán a la respuesta del endpoint /userinfo. Para obtener más información sobre los tipos de claims en , lee Claims de JSON Web Token.
Aunque se permite el uso de claims personalizados privados sin espacio de nombres, Auth0 recomienda encarecidamente usar claims personalizados públicos con espacio de nombres siempre que sea posible. Los claims personalizados públicos con espacio de nombres son la mejor manera de evitar cualquier colisión con futuros claims añadidos al estándar.
Anteriormente, Auth0 solo permitía claims con espacio de nombres en los token de acceso y los ID Tokens. Con la migración a claims personalizados, los claims sin espacio de nombres pueden usarse en los , los ID Tokens y el endpoint /userinfo de la Authentication API de Auth0.
// un Auth0 Action exports.onExecutePostLogin = async (event, api) => { // claims personalizados públicos con espacio de nombres 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 personalizados sin espacio de nombres api.accessToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim'); api.idToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');};
Todos los flujos de Connect (OIDC) compatibles con Auth0 se ven afectados por esta migración. Para revisar la lista de flujos, consulte Flujos de autenticación y autorización.Las siguientes características también se ven afectadas:
Auth0 limitará la carga útil de los claims personalizados a un máximo de 100KB. Es importante asegurarse de que la carga útil no supere este límite; de lo contrario, la transacción de autenticación fallará con un error. Le recomendamos revisar el uso que hace del código de extensibilidad (es decir, Rules, Hooks o Actions). En particular, revise las cargas útiles de gran tamaño provenientes de APIs externas.Para evitar errores, Auth0 recomienda usar la carga útil de token más pequeña posible para que su aplicación funcione. Es posible que deba eliminar las propiedades que no sean esenciales antes de definir el valor del claim personalizado.
Esta restricción se aplica al tamaño total de la carga útil de todos sus claims personalizados. Esto incluye tanto los nombres de los claims personalizados como sus valores asociados, ya sean públicos con espacio de nombres o privados sin espacio de nombres.
El límite de 100KB se aplica por separado a los tokens de acceso y a los ID Tokens. Por ejemplo, en la misma transacción se pueden devolver un token de acceso de 100KB y un ID Token de 100KB.
// un Auth0 action exports.onExecutePostLogin = async (event, api) => { // obteniendo una carga útil superior a 100KB const aHeavyPayload = getHeavyPayload(); // esto fallará la autenticación api.idToken.setCustomClaim('myclaim', aHeavyPayload);};
// un Auth0 Action exports.onExecutePostLogin = async (event, api) => { // obteniendo una carga útil de 50KB const a50KBPayload = getHeavyPayload(); // obteniendo otra carga útil de 50KB const another50KBPayload = getHeavyPayload(); // esto fallará en la autenticación api.idToken.setCustomClaim('myclaim', a50KBPayload); api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);};
// un Auth0 action exports.onExecutePostLogin = async (event, api) => { // obteniendo una carga útil de 50KB const a50KBPayload = getHeavyPayload(); // obteniendo otra carga útil de 50KB const another50KBPayload = getHeavyPayload(); // esto se ejecutará correctamente api.accessToken.setCustomClaim('myclaim', a50KBPayload); api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);};
Auth0 restringe la personalización de los claim usados en los estándares OIDC u OAuth2, así como de los claim de uso interno. Cualquier intento de modificar uno de estos claim se ignorará. La transacción no fallará, pero el claim no se agregará a los tokens. Auth0 recomienda usar un claim público con espacio de nombres.
// un Auth0 Action exports.onExecutePostLogin = async (event, api) => { // esto será ignorado api.accessToken.setCustomClaim('roles', 'this is a role, but Auth0 will ignore it'); // esto se ejecutará correctamente y aparecerá en el token api.idToken.setCustomClaim('https://myDomain.com/roles', 'this is a role');};
Auth0 restringirá la creación de claims personalizados privados sin espacio de nombres en tokens de acceso cuya sea una API de Auth0. Se ignorará cualquier intento de establecer un claim personalizado privado sin espacio de nombres en un token de acceso cuya audiencia sea una API de Auth0. La transacción no fallará, pero el claim no se agregará a tu token. Auth0 recomienda no establecer claims personalizados en tokens que vayan a consumir las API de Auth0.
Los ID Token no se ven afectados por esta restricción.
Los claims personalizados públicos con espacio de nombres no se ven afectados por esta restricción.
La siguiente audiencia restringirá la creación de claims personalizados privados sin espacio de nombres:
https://YOUR_TENANT.auth0.com/api o https://YOUR_TENANT.auth0app.com/api
https://YOUR_TENANT.auth0.com/api/v2 o https://YOUR_TENANT.auth0app.com/api/v2
https://YOUR_TENANT.auth0.com/mfa o https://YOUR_TENANT.auth0app.com/mfa
La excepción a esta restricción es la audiencia /userinfo de Auth0. Se permiten claims personalizados privados sin espacio de nombres en la siguiente audiencia:
// una Auth0 action exports.onExecutePostLogin = async (event, api) => { // estos serán ignorados si la audiencia es una audiencia de Auth0 api.accessToken.setCustomClaim('myATclaim', 'this is a claim'); api.accessToken.setCustomClaim('https://myDomain.com/myATclaim', 'this is a claim'); // estos se ejecutarán correctamente, no están afectados por la restricción de audiencia api.idToken.setCustomClaim('myIdTclaim', 'this is a claim'); api.idToken.setCustomClaim('https://myDomain.com/myIdTclaim', 'this is a claim');};
En el siguiente ejemplo se muestra la respuesta devuelta con claims personalizados si la audiencia no es una API de Auth0:
-- Un flujo de contraseña del propietario del recurso POST https://{yourTenant}.auth0.com/oauth/tokengrant_type:passwordusername:***password:***client_id:***client_secret:***audience:https://{yourApi}.com -- Nota la audiencia, se trata de una API personalizadascope:openid profile
El siguiente ejemplo muestra la respuesta que se devuelve con claims personalizados que no se añadieron mediante una audiencia de API de Auth0:
-- Un flujo de contraseña del propietario del recurso POST https://{yourTenant}.auth0.com/oauth/tokengrant_type:passwordusername:***password:***client_id:***client_secret:***audience:https://{yourTenant}.auth0.com/api/v2/ -- Esta es una audiencia de Auth0 scope:openid profile
// El token de acceso devuelto por 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", // Se agregó el claim personalizado público con espacio de nombres, porque no está sujeto a esta restricción // Sin embargo, el claim personalizado privado sin espacio de nombres {myATclaim} fue ignorado "https://mydomain.com/{myATclaim}": "this is a claim"}
Restricción sobre los espacios de nombres de Auth0 y Webtask
Auth0 restringirá la creación de claims personalizados con espacio de nombres que usen un dominio de Auth0 como identificador del espacio de nombres. Los dominios de Auth0 son:
auth0.com
webtask.io
webtask.run
Cualquier intento de establecer un claim personalizado con espacio de nombres en un token usando uno de los dominios anteriores como identificador se ignorará. La transacción no fallará, pero el claim no se agregará a tu token.
Antes de esta migración, al establecer un claim personalizado con espacio de nombres con un dominio de Auth0 como identificador, el claim aparecía en la respuesta de /userinfo. Este comportamiento desaparece después de la migración, y esos claims personalizados se ignoran por completo.
// un Auth0 Action exports.onExecutePostLogin = async (event, api) => { // ninguno de estos se añadirá a los tokens ni a la respuesta de /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');};
Auth0 ahora permite agregar claims del perfil de usuario de OIDC a los tokens de acceso.Antes de esta migración, los intentos de agregar claims del perfil de usuario de OIDC al token de acceso se ignoraban sin notificación. Con el comportamiento actualizado, los tokens de acceso contendrán estos claims del perfil de usuario de OIDC.
Si agrega claims del perfil de usuario de OIDC a los tokens de acceso, se aplican las mismas restricciones de scope que a los ID Token. Por ejemplo, para agregar el claim email a los tokens de acceso, el flujo debe activarse con un scope que incluya email.
Puede agregar los siguientes claims del perfil de usuario de OIDC a los tokens de acceso:
// un Auth0 action exports.onExecutePostLogin = async (event, api) => { // esto se ignoraba hasta ahora. A partir de esta migración, el claim se agregará a los tokens de acceso // si el scope contiene 'email' api.accessToken.setCustomClaim('email', 'myemail@domin.com'); // esto se ignoraba hasta ahora. A partir de esta migración, el claim se agregará a los tokens de acceso // si el scope contiene 'profile' api.accessToken.setCustomClaim('family_name', 'A family name');};
Asignación de atributos del complemento SAML2 y del protocolo Web Service Federation (WS-Fed) con Auth0 Rules
Al igual que al usar Auth0 Rules para realizar cambios en el objeto de usuario, los claims de pre-migración de app_metadata o user_metadata también combinan su contenido cuando el claim se establece en el objeto context.idToken y hay conflictos de nombres. Para obtener más información sobre las propiedades del objeto, consulte Propiedades del objeto de usuario en Rules.Sin embargo, al usar claims personalizados, Auth0 da prioridad al claim que se estableció en el objeto context.idToken.Este cambio afecta a las Rules de Auth0 que establecen app_metadata y user_metadata mediante context.id_token (asignándoles objetos) y, al mismo tiempo, usan estos campos en la asignación de atributos para el complemento o el protocolo (WS-Fed).Ejemplo 1: Auth0 ignora la asignación de atributos cuando context.idToken.app_metadata se establece con un objeto vacío.
// un Rule de Auth0function (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);}
Respuesta de SAML antes de esta migración:
<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>
Respuesta de SAML con el comportamiento actualizado:
Ejemplo 2: La versión de app_metadata en context.id_token prevalece.
// un Rule de Auth0function (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);}
Respuesta de SAML previa a esta migración:
<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>
Respuesta SAML con el nuevo comportamiento:
<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>
Agregue claims personalizados privados sin espacio de nombres a los tokens
El comportamiento de los claims personalizados no cambiará para los miembros del programa beta de claims personalizados. Esta función ya está habilitada.
Ahora puede agregar claims personalizados privados sin espacio de nombres a la carga útil de los tokens de acceso y los ID Tokens.
// un Auth0 Action exports.onExecutePostLogin = async (event, api) => { // ignorado anteriormente // A partir de esta migración, el claim se añadirá a los tokens de acceso api.accessToken.setCustomClaim('myATclaim', 'this is a claim'); // ignorado anteriormente // A partir de esta migración, el claim se añadirá a los ID tokens api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');};
// un Auth0 Action exports.onExecutePostLogin = async (event, api) => { // esto se ignoraba hasta ahora. // A partir de esta migración, este claim se devolverá en /userinfo api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');};
-- una llamada a /userinfo GET https://{yourTenant}.auth0.com/userinfoAuthorization: Bearer {yourAccessToken}
// la respuesta de /userinfo{ "sub": ***, (...) "myIdTclaim": "this is a claim"}
Corregir las Rules de Auth0 para complemento SAML2 y protocolo Web Service Federation (Ws-Fed)
Si configura claims de app_metadata o user_metadata en el objeto context.idToken mediante complemento SAML2 o protocolo Web Service Federation (Ws-Fed) con Rules de Auth0 junto con la asignación de atributos, deberá actualizar su configuración para adaptarla a la forma en que Auth0 evalúa los nombres de claims en conflicto entre estos objetos. Hay varias soluciones posibles:
Asegúrese de que el código de su Rule de Auth0 siempre dé prioridad al contenido de los objetos definidos en context.id_token:
// my_claim se ignorará; esta línea de código ya no es relevante,// es preferible definir my_claim en `context.idToken`user.app_metadata.my_claim = 'a value'; // esta versión de app_metadata tendrá prioridad sobre cualquier otro cambio context.idToken.app_metadata = { another_claim: 'another value'};// Solo `another_claim` aparecerá en las respuestas SAML/WsFed
Si usa la asignación de atributos de complemento SAML2 o protocolo Web Service Federation (Ws-Fed), evite definir claims de app_metadata o user_metadata en el objeto context.idToken. Sustituya estos claims por claims con espacio de nombres siempre que sea posible:
Use una condición en el protocolo actual o en el cliente actual para excluir las instrucciones que definen app_metadata o user_metadata cuando el protocolo sea samlp o 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" };}
Antes de deshabilitar el comportamiento legado, le recomendamos que revise la lista de cambios y verifique que sus aplicaciones e integraciones sean compatibles.
Si su inquilino no tiene esta opción, no se verá afectado y no es necesario realizar ninguna otra acción.
Autenticar
Administrar usuarios
Personalizar
Auth0 AI
Plataforma