Describe el caso especial de configuración para firmar y cifrar solicitudes SAML
Para mejorar la seguridad de tus transacciones, puedes firmar o cifrar tanto tus solicitudes como tus respuestas en el protocolo . En este artículo, encontrarás configuraciones para escenarios específicos, divididas en dos casos de uso:
Auth0 como proveedor de servicios SAML (por ejemplo, una conexión SAML)
Auth0 como SAML (por ejemplo, una aplicación configurada con el add-on SAML Web App)
Estos escenarios se aplican cuando Auth0 es el proveedor de servicios SAML, lo que significa que Auth0 se conecta a un proveedor de identidad SAML al crear una conexión SAML.
De forma predeterminada, las solicitudes de autenticación SAML se envían mediante HTTP-Redirect y usan la codificación deflate, lo que coloca la firma en un parámetro de consulta.Para desactivar la codificación deflate, puede hacer una solicitud PATCH al endpoint Update a Connection de la Management API y establecer la opción deflate en false.Al actualizar el objeto options de una conexión, se sobrescribe por completo dicho objeto. Para conservar las opciones anteriores de la conexión, obtenga el objeto options existente y agréguele nuevos pares clave-valor.Endpoint: https://{yourDomain}/api/v2/connections/{yourConnectionId}Carga útil:
{ { "options" : { [...], // todas las demás opciones de conexión "deflate": false } }}
Usar una clave personalizada para firmar solicitudes
De forma predeterminada, Auth0 usa la clave privada del inquilino para firmar solicitudes SAML (cuando la opción Sign Request está habilitada). También puedes proporcionar tu propio par de claves privada/pública para firmar solicitudes de una conexión específica.Puedes generar tu propio certificado y clave privada con este comando:
No es posible cambiar en la interfaz de usuario del Dashboard la clave usada para firmar solicitudes en la conexión, por lo que tendrás que usar el endpoint Update a Connection de la v2 y agregar una propiedad signing_key al objeto options, como se muestra en el ejemplo de payload a continuación.Al actualizar el objeto options de una conexión, se sobrescribe por completo el objeto options. Para conservar las opciones anteriores de la conexión, obtén el objeto options existente y agrégale los nuevos pares clave-valor.Endpoint: https://{yourDomain}/api/v2/connections/{yourConnectionId}Payload:
{ { "options" : { [...], // todas las demás opciones de conexión "signing_key": { "key":"-----BEGIN PRIVATE KEY-----\n...{your private key here}...\n-----END PRIVATE KEY-----", "cert":"-----BEGIN CERTIFICATE-----\n...{your public key cert here}...\n-----END CERTIFICATE-----" } } }}
Si Auth0 es el proveedor de servicios SAML, todas las respuestas SAML de su proveedor de identidad deben estar firmadas para indicar que no han sido manipuladas por un tercero no autorizado.Deberá configurar Auth0 para validar las firmas de las respuestas. Para ello, obtenga un certificado de firma del proveedor de identidad y cárguelo en la conexión de Auth0:
Si Auth0 es el proveedor de servicios SAML, puede que necesite recibir aserciones cifradas de un Proveedor de identidad. Para ello, debe proporcionar al IdP el certificado de clave pública del inquilino. El IdP cifra la aserción SAML con la clave pública y la envía a Auth0, que la descifra con la clave privada del inquilino.Use los siguientes enlaces para obtener la clave pública en diferentes formatos:
Descargue el certificado en el formato solicitado por el IdP.
De forma predeterminada, Auth0 admite automáticamente los algoritmos incluidos en el perfil de algoritmos más reciente para descifrar aserciones SAML.
Si la aserción está cifrada con un algoritmo que no figura en la lista, Auth0 la rechazará.
Para especificar un perfil distinto o usar un algoritmo que no figure en la lista, debes actualizar la conexión mediante el endpoint Update a Connection y cambiar la propiedad assertion_decryption_settings, como se muestra en el ejemplo de payload a continuación.Cuando actualizas el objeto de opciones de una conexión, la nueva configuración reemplaza todo el objeto options. Para conservar las opciones anteriores de la conexión, obtén el objeto de opciones existente y agrégale nuevos pares clave-valor.Endpoint: https://{yourDomain}/api/v2/connections/{yourConnectionId}
Payload:
{ "options": { [...], // todas las demás opciones de conexión "assertion_decryption_settings": { "algorithm_profile": "v2026-1", "algorithm_exceptions": [] } }}
Utilice su par de claves para descifrar respuestas cifradas
Como se indicó anteriormente, Auth0 usará de forma predeterminada el par de claves privada/pública de su inquilino para gestionar el cifrado. También puede proporcionar su propio par de claves pública/privada si un escenario avanzado así lo requiere.No es posible cambiar en la interfaz de usuario del Dashboard el par de claves que se usa para cifrar y descifrar solicitudes en la conexión, por lo que deberá usar el endpoint Update a Connection de la Management API v2 y agregar una propiedad decryptionKey al objeto options, como se muestra en el ejemplo de payload a continuación.Actualizar el objeto options de una conexión sobrescribe por completo dicho objeto. Para conservar las opciones anteriores de la conexión, obtenga el objeto options existente y agréguele los nuevos pares clave/valor.Endpoint: https://{yourDomain}/api/v2/connections/{yourConnectionId}Payload:
{ { "options" : { [...], // todas las demás opciones de conexión "decryptionKey": { "key":"-----BEGIN PRIVATE KEY-----\n...{your private key here}...\n-----END PRIVATE KEY-----", "cert":"-----BEGIN CERTIFICATE-----\n...{your public key cert here}...\n-----END CERTIFICATE-----" } }}
Los metadatos de SAML disponibles para la conexión se actualizarán con el certificado proporcionado para que el proveedor de identidad pueda usarlo para firmar la respuesta SAML.
Este escenario se aplica cuando Auth0 es el Proveedor de identidad SAML para una aplicación. Esto se representa en el Dashboard mediante una Application con el complemento SAML Web App Addon habilitado.
Si Auth0 es el proveedor de identidad SAML, firmará las aserciones SAML con la clave privada del inquilino y proporcionará al proveedor de servicios la clave pública o el certificado necesarios para validar la firma.Para firmar las aserciones SAML:
Seleccione SAML2 Web App para ver su configuración y ubique el bloque de código Settings.
Ubique la clave "signResponse". Quite el comentario (o agréguela, si es necesario) y establezca su valor en true (el valor predeterminado es false). La configuración debería verse así:
{ [...], // otra configuración "signResponse": true}
De forma predeterminada, Auth0 usará el par de claves privada/pública asignado a su inquilino para firmar las respuestas o aserciones SAML. En casos muy específicos, quizá desee proporcionar su propio par de claves. Puede hacerlo con una Rule como esta:
/*** Controlador que se invocará durante la ejecución de un flujo PostLogin.** @param {Event} event - Detalles sobre el usuario y el contexto en el que está iniciando sesión.* @param {PostLoginAPI} api - Interfaz cuyos métodos pueden usarse para modificar el comportamiento del inicio de sesión.*/exports.onExecutePostLogin = async (event, api) => { // reemplazar con el ID de la aplicación que tiene habilitado el complemento SAML Web App // para la que se desea cambiar el par de claves de firma. const samlIdpClientId = 'YOUR_SAML_APP_CLIENT_ID'; // hacer esto solo para el client_id específico. Si tiene varios IdPs que requieren // certificados personalizados, agregue una sentencia "if" para cada uno. if (event.client.client_id === samlIdpClientId) { // proporcione aquí su propia clave privada y certificado // consulte https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings // para instrucciones de formato: básicamente, comience con un certificado en formato PEM y // reemplace los saltos de línea con "\n" const signingCert = "-----BEGIN CERTIFICATE-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END CERTIFICATE-----\n"; const signingKey = "-----BEGIN PRIVATE KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END PRIVATE KEY-----\n"; api.samlResponse.setCert(signingCert) api.samlResponse.setKey(signingKey); } };
Recibir solicitudes de autenticación SAML firmadas
Si Auth0 es el proveedor de identidad SAML, puede recibir solicitudes firmadas con la clave privada del proveedor de servicios. Auth0 utiliza la clave pública o el certificado para validar la firma.Para configurar la validación de la firma:
Descargue el certificado del proveedor de servicios con la clave pública.
Seleccione SAML2 Web App para ver su configuración y localice el bloque de código Settings.
Localice la clave "signingCert". Quite el comentario (o agréguela, si es necesario) y, luego, establezca su valor en el certificado que descargó del proveedor de servicios. La configuración debería verse así:
{ [...], // otras configuraciones "signingCert": "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n"}
Si Auth0 es el Proveedor de identidad SAML, puede usar Actions para cifrar las aserciones SAML que envía. También puede seleccionar el algoritmo que se usa para cifrar las aserciones. Auth0 recomienda usar aes256-gcm para una configuración de seguridad más sólida.Debe obtener el certificado y la clave pública del proveedor de servicios. Si solo obtuvo el certificado, puede extraer la clave pública con openssl. Suponiendo que el archivo del certificado se llame certificate.pem, puede ejecutar:openssl x509 -in certificate.pem -pubkey -noout > public_key.pemUna vez que tenga los archivos del certificado y de la clave pública, debe convertirlos en cadenas para usarlos en una Action. La Action tendrá este aspecto:
exports.onExecutePostLogin = async (event, api) => {// este Action establece una clave pública específica para cifrar la aserción SAML generada por Auth0 if ( event.client.client_id === "THE_CLIENT_ID_OF_THE_APP_WITH_THE_SAML_APP_ADDON" ) { const encryptionCert = "-----BEGIN CERTIFICATE-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END CERTIFICATE-----\n"; const encryptionPublicKey = "-----BEGIN PUBLIC KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END PUBLIC KEY-----\n"; api.samlResponse.setEncryptionCert(encryptionCert); api.samlResponse.setEncryptionPublicKey(encryptionPublicKey); api.samlResponse.setEncryptionAlgorithm("aes256-gcm"); }};
Auth0 admite los siguientes algoritmos para el cifrado de aserciones:
aes256-gcm(recomendado): Cifrado autenticado que proporciona confidencialidad e integridad. Es resistente a ataques de oráculo de validez de formato.
aes256-cbc (predeterminado): No ofrece garantías de integridad. Cuando una Action no usa el objeto api.samlResponse.setEncryptionAlgorithm para establecer el algoritmo de cifrado, Auth0 usa de forma predeterminada el algoritmo aes256-cbc y registra una advertencia de desuso en los registros de tu inquilino.
Para el transporte de claves, Auth0 usa rsa-oaep, incluidas las funciones MGF1 y SHA1.
Auth0 tiene previsto actualizar el algoritmo de cifrado predeterminado a aes256-gcm.Para mantener un comportamiento coherente después de que cambie el algoritmo predeterminado, recomendamos cambiar a aes256-gcm:
Verifica que tu proveedor de servicios SAML admita aes256-gcm; si no es así, ponte en contacto con él para solicitar soporte.
Establece el algoritmo de cifrado en el código de tu Action con api.samlResponse.setEncryptionAlgorithm("aes256-gcm");.
Autenticar
Administrar usuarios
Personalizar
Auth0 AI
Plataforma