Configurar la autenticación con Private Key JWT

Private Key JWT está disponible para clientes con el plan Enterprise. Para actualizar tu plan, ponte en contacto con Auth0 pricing.

La autenticación con Private Key admite la autenticación de cliente de OIDC Connect Core Client Authentication 1.0 mediante aserciones JWT firmadas con pares de claves asimétricas. Puedes crear una aplicación nueva para usar private_key_jwt o habilitar aplicaciones existentes para que usen pares de claves para la autenticación.

Requisitos previos

Antes de configurar una aplicación que se autentica mediante Private Key JWT, debe generar un par de claves RSA.

Configurar Private Key JWT

Auth0 Dashboard
Management API

Puede usar el Auth0 Dashboard para crear una aplicación nueva y configurar las credenciales, o actualizar una aplicación existente.Le recomendamos almacenar de forma segura el parámetro client_secret actual antes de cambiar el método de credenciales de su aplicación a Private Key JWT. El parámetro client_secret quedará oculto una vez que se complete la configuración de Private Key JWT.

Configurar una aplicación nueva para `private_key_jwt`

Vaya a Auth0 Dashboard > Applications > Application.
Seleccione Create Application.
Elija el tipo de aplicación.
En la configuración de la aplicación, seleccione la pestaña Credentials.
En Authentication Methods, seleccione Private Key JWT.
Configure los detalles de la credencial:
1. Introduzca un nombre para la credencial.
2. Cargue su certificado en formato PEM o X.509.
3. Seleccione el algoritmo para firmar las aserciones.
4. Opcional: habilite una fecha de vencimiento personalizada. Seleccione Set an explicit expiry date for this Credential y establezca una fecha futura.
  Puede recibir un error de certificado no válido si envía material de clave mal formado. Para evitar problemas, lo mejor es cargar directamente el archivo creado por OpenSSL.
Seleccione Add Credential.

Configurar una aplicación existente

Vaya a Auth0 Dashboard > Applications.
Seleccione la aplicación que desea actualizar.
Seleccione la pestaña Credentials.
Elija Private Key JWT.
Configure los detalles de la credencial:
1. Introduzca un nombre para la credencial.
2. Cargue su certificado en formato PEM o X.509.
3. Seleccione el algoritmo para firmar las aserciones.
4. Opcional: habilite una fecha de vencimiento personalizada. Seleccione Set an explicit expiry date for this Credential y establezca una fecha futura.
Seleccione Add Credential.

Configurar una aplicación para usar la autenticación con Secreto del cliente

Vaya a Auth0 Dashboard > Applications > Applications y seleccione la aplicación que desea actualizar.
Seleccione la pestaña Credentials.
Elija Client Secret (Post) o Client Secret (Basic).
Seleccione Save.

Actualizar el vencimiento de la credencial

Puede actualizar la fecha de vencimiento de una credencial existente desde Auth0 Dashboard.

Vaya a Auth0 Dashboard > Applications > Applications y seleccione la aplicación que desea actualizar.
Seleccione la pestaña Credentials.
Elija la credencial que desea actualizar y seleccione Edit Credential.
Seleccione Set an explicit expiry date for this Credential y establezca una fecha futura.
Seleccione Update Credential.

Configurar una nueva aplicación para `private_key_jwt`

Puedes crear una nueva aplicación con private_key_jwt como método de autenticación mediante la Management API. Realiza una llamada POST al endpoint Create a Client con la siguiente carga útil:

curl --location --request POST 'https://{domain}/api/v2/clients' \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
 "name": "{clientName}",
 "app_type": "non_interactive",
 "client_authentication_methods": {
   "private_key_jwt": {
     "credentials": [
       { 
          "name": "{credentialName}", 
          "credential_type": "public_key", 
          "pem": "{credentialPublicKey}",
          "alg": "{algorithm}",
          "expires_at": "{expiresAt}"
       }
     ]
   },
   "jwt_configuration": {
     "alg": "RS256"
   }
 }
}'

Parámetro	Descripción
`algorithm`	Algoritmo utilizado para firmar aserciones. Los valores admitidos son RS256, RS384 y PS256. Si no se especifica, se usará RS256 de forma predeterminada.
`clientName`	Nombre para el nuevo cliente.
`credentialName`	Nombre para la clave pública.
`expires_at`	Opcional. Fecha de vencimiento de la credencial en formato ISO 8601. Por ejemplo, `2020-08-20T19:10:06.299Z`. Una vez pasada la fecha de vencimiento, la credencial deja de ser válida.
`managementApiAccessToken`	Token de acceso para Management API con el scope `create:credentials`.
`pem`	Clave pública o certificado X.509 codificado en formato PEM.
`parse_expiry_from_cert`	Opcional. Un valor Boolean que indica que Auth0 debe analizar la fecha de expiración cuando se proporciona un certificado. Si no se proporciona un certificado, Auth0 devolverá un error. `parse_expiry_from_cert` y `expires_at` también se excluyen mutuamente. En este caso, Auth0 devolverá un error.

La clave pública en formato PEM debe escaparse como JSON antes de pasarla a Auth0. En nuestro ejemplo, este es el contenido que debemos pasar:

La respuesta contiene la propiedad client_id, que vinculará tu aplicación al servidor de recursos. La respuesta también contiene un kid generado para la credencial que creaste. Este se usará más adelante para generar el client_assertion.

Auth0 sigue el estándar JSON Web Key Thumbprint para generar el kid de sus credenciales.El kid consiste en un hash SHA-256 codificado en base64URL de la representación JWK de su clave pública.

Configurar una aplicación existente

También puedes configurar una aplicación existente para que use la autenticación con Private Key JWT mediante la Auth0 Management API. Para ello, deberás eliminar los valores del campo token_endpoint_auth_method y agregar valores en el campo client_authentication_methods.

Si actualiza una aplicación de producción existente para autenticarse con private_key_jwt, le recomendamos almacenar de forma segura el valor actual de client_secret para consultarlo más adelante.Después de configurar private_key_jwt, no podrá acceder al valor de client_secret a menos que restaure la configuración de su aplicación para que use un Secreto del cliente.

Crear el recurso de credencial

Una vez que haya generado un par de claves, cree el recurso de credencial. Realice la siguiente solicitud POST al endpoint /clients de la Management API.

curl --location --request POST 'https://{domain}/api/v2/clients/{clientId}/credentials' \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "name": "{credentialName}", 
          "credential_type": "public_key", 
          "pem": "{credentialPublicKey}",
          "alg": "{algorithm}",
          "expires_at ": "{expiresAt}",
}'

Parámetro	Descripción
`algorithm`	Algoritmo utilizado para firmar aserciones. Los valores admitidos son RS256, RS384 y PS256. Si no se especifica, el algoritmo predeterminado es RS256.
`clientId`	ID de la aplicación que se actualizará.
`credentialName`	Nombre de la clave pública.
`managementApiAccessToken`	Token de acceso para la Management API con el scope `create:credentials`.
`pem`	Clave pública o certificado X.509, codificado en formato PEM.
`expires_at`	Opcional. Fecha de vencimiento de la credencial en formato ISO 8601. Por ejemplo, `2020-08-20T19:10:06.299Z`. Una vez pasada la fecha de vencimiento, la credencial deja de ser válida.
`parse_expiry_from_cert`	Opcional. Un valor booleano que indica que Auth0 debe extraer la fecha de vencimiento cuando se proporciona un certificado. Si no se proporciona un certificado, Auth0 devolverá un error. `parse_expiry_from_cert` y `expires_at` son mutuamente excluyentes. En este caso, Auth0 devolverá un error.

La clave pública PEM debe escaparse en JSON antes de enviarla a Auth0. En este ejemplo, el contenido que debemos pasar es:

La respuesta devuelve un credential ID. Utilice el ID para el siguiente paso.

Asociar la credencial

Una vez que hayas creado la credencial, asóciala con tu aplicación. Tu aplicación usará estas credenciales durante la autenticación con private_key_jwt.Realiza una solicitud PATCH al endpoint Update a Client de la Management API:

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "token_endpoint_auth_method": null, 
          "client_authentication_methods": {
             "private_key_jwt": {
                "credentials": [{ "id": {credentialId} }]
             }
          }
   }​​'​​

Parámetro	Descripción
`clientId`	ID de la aplicación que se actualizará.
`managementApiAccessToken`	Token de acceso para la Management API con los scopes `update:client` y `update:credentials`.
`credentialId`	ID de la credencial que creó.
`pem`	La clave pública en formato PEM.

Auth0 no admite el uso de HS256 como algoritmo de firma de JWT de la aplicación. Debe tener el campo jwt_configuration.alg configurado con el algoritmo RS256. Para obtener información sobre cómo cambiar el algoritmo de firma, consulte Cambiar los algoritmos de firma de la aplicación.

Configurar una aplicación para usar autenticación con Secreto del cliente

Para restaurar la configuración de su aplicación y usar un Secreto del cliente, debe deshabilitar client_authentication_methods y volver a habilitar token_endpoint_auth_method con el método de autenticación.

Una vez que haya configurado su método de autenticación como client_secret, sus aplicaciones ya no podrán autenticarse mediante private_key_jwt hasta que las actualice para que se autentiquen con client_secret.

Ejemplo

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "token_endpoint_auth_method": "{tokenEndpointAuthMethod}", 
          "client_authentication_methods": null
   }​​'​​

Parámetro	Descripción
`clientId`	ID de la aplicación actualizada.
`managementApiAccessToken`	Token de acceso para la Management API con los scopes `update:client` y `update:credentials`.
`tokenEndpointAuthMethod`	Método final de autenticación. Por ejemplo: `client_secret_basic` o `client_secret_post`.

Actualizar credentials con un campo de expiración

Puede actualizar una credencial existente con una fecha de vencimiento mediante el endpoint Update a credential de la Management API.

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId}/credentials/{credentialId} ' \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "expires_at": {expiresAt}
   }'

Parámetro	Descripción
`managementApiAccessToken`	Tokens de acceso para la Management API con el alcance `update:credentials`.
`clientId`	El cliente que desea actualizar.
`expires_at`	La fecha de caducidad de la credencial en formato ISO 8601. Por ejemplo, `2020-08-20T19:10:06.299Z`.

El único campo que puede actualizar es el campo expires_at. El resto de los atributos son inmutables y, para modificarlos, es necesario rotar la credencial.

Límites de credenciales

Auth0 exige un tamaño mínimo de clave RSA de 2048 bits y un tamaño máximo de 4096 bits. Las aplicaciones pueden tener configuradas como máximo dos credenciales.

Rotar credenciales

Para evitar la exposición de claves, Auth0 recomienda rotar periódicamente el par de claves. Para saber cómo hacerlo, consulte Rotar credenciales.

​Requisitos previos

​Configurar Private Key JWT

​Configurar una aplicación nueva para private_key_jwt

​Configurar una aplicación existente

​Configurar una aplicación para usar la autenticación con Secreto del cliente

​Actualizar el vencimiento de la credencial

​Configurar una nueva aplicación para private_key_jwt

​Configurar una aplicación existente

Crear el recurso de credencial

Asociar la credencial

​Configurar una aplicación para usar autenticación con Secreto del cliente

​Actualizar credentials con un campo de expiración

​Límites de credenciales

​Rotar credenciales

​Más información

Requisitos previos

Configurar Private Key JWT

Configurar una aplicación nueva para `private_key_jwt`

Configurar una aplicación existente

Configurar una aplicación para usar la autenticación con Secreto del cliente

Actualizar el vencimiento de la credencial

Configurar una nueva aplicación para `private_key_jwt`

Configurar una aplicación existente

Configurar una aplicación para usar autenticación con Secreto del cliente

Actualizar credentials con un campo de expiración

Límites de credenciales

Rotar credenciales

Más información