Configurar la autenticación mTLS para un cliente

Describe cómo configurar la autenticación mTLS para un cliente.

Aprende a configurar la autenticación mTLS de un cliente con la Management API y el Auth0 Dashboard.

Auth0 Dashboard

Puede usar Auth0 Dashboard para configurar mTLS para un cliente y habilitar la autenticación de cliente mediante mTLS en el Servidor de autorización.

1. Vaya a Auth0 Dashboard > Applications > Applications.

2. Seleccione la aplicación que desea usar con mTLS o cree una aplicación nueva.

3. Seleccione la pestaña Credentials.

4. Elija el Authentication Method requerido, que puede ser uno de los siguientes:

   • mTLS con un certificado autofirmado
   • mTLS con un certificado firmado por una autoridad de certificación

5. Una vez que seleccione el tipo de certificado que prefiera, puede hacer lo siguiente:

   • Asignar una credencial (certificado) existente a la aplicación cliente
   • Agregar una credencial nueva cargando un certificado

Management API

Usa la Auth0 Management API para configurar mTLS para un cliente.

Los siguientes ejemplos especifican $management_access_token, o un token de acceso de la Management API. Debes reemplazarlo por un token de acceso que contenga al menos los siguientes alcances:

• create:custom_domains
• read:custom_domains
• create:clients
• update:clients
• update:client_credentials
• update:client_keys
• update:tenant_settings

Para obtener más información sobre cómo obtener un token de acceso con los alcances requeridos, consulta Obtener tokens de acceso.

​

Certificados autofirmados

Utilice certificados autofirmados para verificar la identidad del cliente durante la autenticación mTLS. Sin embargo, los certificados autofirmados tienen las siguientes limitaciones

• Algunos proveedores de servicios en la nube, como Amazon, no aceptan certificados autofirmados.
• Para garantizar la estabilidad de nuestra plataforma, Auth0 limita a dos el número de certificados que pueden registrar los clientes.

Generar un certificado

Para autenticarse mediante mTLS autofirmado, debe crear un nuevo certificado de cliente autofirmado.

El siguiente ejemplo de código genera un nuevo certificado autofirmado:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"

Si usas curl o Wget, el certificado PEM debe estar escapado en JSON antes de pasarlo a Auth0. Por ejemplo, reemplaza los saltos de línea con \r\n:

-----BEGIN PRIVATE KEY-----\r\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDDXAVKQo2SUMHH\r\no9ecWYNiL5\/yva5NSj8uQjKoeRAsOIOAyOBTLxgwmno13xZ8VDkcT1cHTlC+2CkE\r\noBII4OUbHPVof+dtknkL+jUBdIPX1QvlGSUbzduZE4hEEQ8zH6w4EAA2VN72Bymn\r\nT8i\/+Tz9Dx6M1nkuXPCwM7sYEuq5OrqT5yVB6KByKKElp\/tauJkHp0st04iGDgl2\r\nFJUt3QJFCFewTDDdGq62otVJxHfouXPmHBQjzf+f1CZy+N0q2z+JGRt44YZq+F9y\r\ne3RWawvv2x3TXgRBLpvIKqf99LoPVdwozHl8QODu52dyelvLQ866XLhAALuMwic\/\r\nbQbolnMpAgMBAAECggEAf6LliekFmezNTmQLgIkzP7kh5XRsJu81bEGv20aNfHbH\r\n5CJZ\/b8tLMQgyIWiqURVs9taXtmaA7YyxmTWo5pb1WUMKWQ3je0+zMaCTxsS8Lau\r\n+NV+2zWaHd8XDnGe3qX43QAHQ3gb294+JqQH4vUyFZwFN7sAnXv3fQevW0Ewvics\r\nOua\/xNa7y5hbJUPZiQjRhO+n+gTEqpfsnPWNlm9hk\/wVnnjKvMfstN4zUbznRAoN\r\nW8TK82tiVWAXW4CjgIBtVRZjTA9x3UOtbhcvNzaTRxc+scCpIpAVuurS+ZIKZdpm\r\nNnhiOk3akpLU3KZrm8C5JQRn8cupY9WkfCiLXbMFAQKBgQD9JfVMv6zDeNvExneR\r\n7fZDIT2UAEhYExwRJwQPyxkVPwev9HBYuuaaknIbomWTkt\/B6Q3k3p6VI4lxhnVl\r\nbkpOYl5UquP3VoVROEJts224hKgVcLw6s+i+lZDOAleNgbN7rj82l4BIu+SEj\/7c\r\nz94hAa\/wRRvsW+QnxF1sZnpY+QKBgQDFj2h8I4noFJk3sbbk3qQdi5+49ibWSuhc\r\nXVpU+0dQ1lRlhXYT9cDMc22HRt8hjXUNRhdpXvOqVaFiBjv9wBsmFyaJO3tOK3uE\r\ndBgD4lF03bnbGI7\/I3DivW\/tyEMS5JXI\/qrpdWor+wR30c5M\/45y2AGpjwnoGf+D\r\nX8SAMzknsQKBgQCrSljuIrBK3+eNAWH821CL4d0h3QMWnW+bZ5QG\/70sNCcGd1bh\r\noy3Qn5EYg81JitNfCUw+dihF7\/LbX0jmZjdfTI5Zqfxw6xlweKnyQrvWY+S8BTlI\r\nW138P4Xo74rAlGeXI7NgRCkojgK1dB3W2cyK9vJOmOSpDRCXm\/Y\/GCRnOQKBgCE\/\r\n75\/lA1LSFK9w8401g32NgEZK92JdnRnehFOFLw2F5RJpEeRuGhLO4oJABVHKUwb2\r\n4v3TA0OJwe2Tiwk8CdWxU8UJA8m2O8WhHGGa94apwpwDWB3MwzUGGQ52BAPsAOGh\r\nKva70jCwwKHB5+zBniHqBO2aq1oq9fwQZCwHcvkhAoGBAIa8QMHNrX7AuCSAeR4\/\r\n\/7XrGU1a4oExz417AYgZOuGaYQAI5BMIjRZZ3JTzO\/QsmkzeS1tFuBlih8li\/t4l\r\nE2TdnKhy376A6QWfbTDkJN6gzFeaMKwe98mOHKeq0KZITGYVTSa2AYH5zaro0Yku\r\nonOH1NdyEKFFgxGLg7wveYUW\r\n-----END PRIVATE KEY-----

Crear un nuevo cliente

Para crear un nuevo cliente, realiza una llamada POST al endpoint /clients con el siguiente payload:

• $client_name: el nombre del cliente nuevo
• $credential_name: el nombre de la clave pública
• $credential_certificate: el contenido de $certificate_pem generado en el paso anterior

curl --location --request POST 'https://$tenant/api/v2/clients' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$client_name",
  "app_type": "non_interactive",
  "client_authentication_methods": {
    "self_signed_tls_client_auth": {
      "credentials": [{ 
        "name": "$credential_name", 
        "credential_type": "x509_cert", 
        "pem": "$credential_certificate"
      }]
    }
  },
  "jwt_configuration": {
    "alg": "RS256"
  }
}'

Para más información, consulte la documentación de la API Crear un cliente.

Aplicar patch a un cliente existente

Puede actualizar un cliente existente para que acepte autenticación de cliente mTLS eliminando cualquier valor del campo token_endpoint_auth_method y agregando valores en el campo client_authentication_methods.

Una vez que haya configurado su cliente para mTLS, no podrá autenticarse con el Secreto del cliente a menos que configure token_endpoint_auth_method para que deje de usar mTLS. Para obtener más información, consulte Revertir un cliente para que use un Secreto del cliente.

Crear el recurso de credencial

Una vez que hayas generado un certificado, crea el recurso de credencial:

curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$credential_name", 
  "credential_type": "x509_cert", 
  "pem": "$credential_certificate"
}'

Auth0 devuelve un ID de credencial en la respuesta que deberá usar para asociar la credencial con el cliente.

Para obtener más información, consulte la documentación de la API Crear una credencial de cliente.

Asocia la credencial con el cliente y deshabilita token_endpoint_auth_method

Las credenciales cargadas no se habilitan automáticamente para la autenticación de cliente. Debe actualizar la autenticación de cliente para utilizar el nuevo certificado de cliente autofirmado.

La siguiente solicitud PATCH establece token_endpoint_auth_method en null, lo que deshabilita la autenticación mediante Secreto del cliente. También actualiza client_authentication_methods con el ID de credencial:

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token_endpoint_auth_method": null, 
  "client_authentication_methods": {
    "self_signed_tls_client_auth": {
      "credentials": [{ "id": $credential.id }]
    }
  }
}'

Una vez completada esta solicitud, el Secreto del cliente dejará de aceptarse y los clientes deberán autenticarse mediante mTLS.

Para obtener más información, consulte la documentación de la API Update a client.

​

Certificados firmados por una autoridad de certificación

A diferencia de los certificados autofirmados, que son generados por el cliente y no tienen cadena de confianza, los certificados firmados por una autoridad de certificación (CA) se consideran más fiables, ya que son emitidos por un tercero de confianza. Los certificados firmados por CA son el único tipo de certificado aceptado por algunos proveedores de nube, como Amazon.

Los certificados firmados por una CA incorporan en su información de identidad el concepto de Nombre Distinguido (DN). Si bien cada certificado individual creado por una CA determinada es único, pueden compartir un DN común. Al usar certificados firmados por una CA, Auth0 almacena el DN y compara los certificados de cliente reenviados con los DN registrados.

Generar un certificado

El método para generar un certificado de cliente firmado por una CA depende en gran medida de la Infraestructura de Clave Pública y queda fuera del alcance de este documento. Recomendamos generar al menos un par de claves RSA de 2048 bits.

Crear un nuevo cliente

Para crear un cliente, realiza una llamada POST al endpoint /clients con el siguiente payload:

• $client_name: el nombre del nuevo cliente
• $credential_name: el nombre de la clave pública
• $credential_certificate: el contenido de $certificate_pem que generó la CA

curl --location --request POST 'https://$tenant/api/v2/clients' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$client_name",
  "app_type": "non_interactive",
  "client_authentication_methods": {
    "tls_client_auth": {
      "credentials": [{ 
        "name": "$credential_name", 
        "credential_type": "cert_subject_dn", 
        "pem": "$credential_certificate"
      }]
    }
  },
  "jwt_configuration": {
    "alg": "RS256"
  }
}'

En lugar de pasar el archivo PEM completo, también puede pasar el DN del sujeto. El DN del sujeto debe coincidir con el Distinguished Name (DN) extraído de los certificados de cliente enviados durante el handshake mTLS.

La extracción del DN del sujeto puede variar entre distintos ecosistemas. La forma más fiable de garantizar que el servidor de autorización pueda hacer coincidir el DN del sujeto es cargar el archivo PEM completo.

La siguiente solicitud POST crea un nuevo cliente con el DN de asunto:

curl --location --request POST 'https://$tenant/api/v2/clients' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$client_name",
  "app_type": "non_interactive",
  "client_authentication_methods": {
    "tls_client_auth": {
      "credentials": [{ 
        "name": "$credential_name", 
        "credential_type": "cert_subject_dn", 
        "subject_dn": "C=XX\nST=StateName\nL=CityName\nO=CompanyName\nOU=CompanySectionName\nCN=CommonNameOrHostname"
      }]
    }
  },
  "jwt_configuration": {
    "alg": "RS256"
  }
}'

Para más información, consulte la documentación de la API Crear un cliente.

Aplicar patch a un cliente existente

Si no deseas crear un nuevo cliente para usar mTLS, puedes actualizar uno existente para que acepte la autenticación de cliente mTLS. Para ello, debes eliminar cualquier valor del campo token_endpoint_auth_method y definir valores en el campo client_authentication_methods.

Una vez que hayas configurado tu cliente para mTLS, no podrás autenticarte con el Secreto del cliente a menos que configures token_endpoint_auth_method para que deje de usar mTLS. Para obtener más información, consulta Revertir un cliente para que use un Secreto del cliente.

Crear el recurso de credencial

Una vez que hayas generado un par de claves exclusivamente para mTLS, crea el recurso de credencial. Realiza la siguiente solicitud POST al endpoint /clients:

curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$credential_name", 
  "credential_type": "cert_subject_dn", 
  "pem": "$credential_certificate"
}'

En lugar de pasar el archivo PEM completo, puede pasar el DN del sujeto. El DN del sujeto debe coincidir con el Distinguished Name (DN) extraído de los certificados de cliente enviados durante el handshake mTLS.

El siguiente ejemplo de código crea el recurso de credencial mediante el DN del sujeto:

curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$credential_name", 
  "credential_type": "cert_subject_dn", 
  "subject_dn": "C=XX\nST=StateName\nL=CityName\nO=CompanyName\nOU=CompanySectionName\nCN=CommonNameOrHostname"
}'

Al usar cualquiera de los dos métodos, tenga en cuenta que el ID de credencial que se devuelve en la respuesta es necesario para asociar la credencial con el cliente.

Para más información, consulte la documentación de la API Crear una credencial de cliente.

Asocia la credencial con el cliente y deshabilita token_endpoint_auth_method

Aunque hemos creado la credencial, aún no la hemos asociado con el cliente.

Para ello, actualiza client_authentication_methods realizando la siguiente solicitud PATCH al endpoint /clients. En la misma solicitud, establece token_endpoint_auth_method en null:

​​

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token_endpoint_auth_method": null, 
  "client_authentication_methods": {
    "tls_client_auth": {
      "credentials": [{ "id": $credential.id }]
    }
  }
}'

Una vez completada esta solicitud, el cliente solo podrá autenticarse mediante mTLS.

Para más información, consulte la documentación de la API Update a client.

​

Revertir un cliente para que use un Secreto del cliente

Para restaurar la configuración del cliente y autenticarse mediante un Secreto del cliente, deshabilite client_authentication_methods y vuelva a habilitar token_endpoint_auth_method con el método de autenticación deseado.

En la siguiente solicitud PATCH, establece token_endpoint_auth_method en client_secret_post para volver a habilitar la autenticación con Secreto del cliente:

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token_endpoint_auth_method": "client_secret_post", 
  "client_authentication_methods": null
}'

Para obtener más información, consulte la documentación de la API Update a client.

​

Más información

• Autenticarse con mTLS
• Configurar Customer Edge
• Configurar la autenticación mTLS para un Tenant