Configure Private Key JWT Authentication

Describes how to configure new and existing applications to use Private Key JWT Authentication.

Private Key JWT is available for customers on the Enterprise plan. To upgrade, contact Auth0 pricing.

Private Key JWT Authentication supports OIDC Connect Core Client Authentication 1.0 client authentication using JWT assertions signed with asymmetric key pairs. You can create a new application to use private_key_jwt or enable existing applications to use private key pairs for authentication.

Prerequisites

Before configuring an application that authenticates using Private Key JWT, you must generate an RSA key pair.

Configure Private Key JWT

Auth0 Dashboard

You can use the Auth0 Dashboard to create a new application and configure the credentials or update an existing application.

We recommend you securely store the current client_secret parameter before you set your application credential method to Private Key JWT. The client_secret parameter will be hidden once the Private Key JWT configuration is complete.

Configure a new application for private_key_jwt

1. Navigate to Auth0 Dashboard > Applications > Application.

2. Select Create Application.

3. Choose your application type.

4. Under the application settings, select the Credentials tab.

5. Under Authentication Methods, select Private Key JWT.

   

6. Configure credential details:

   1. Enter a name for the credential.

   2. Upload your PEM format or X.509 certificate.

   3. Select the algorithm to sign the assertions.

   4. Optional: Enable custom expiration. Select Set an explicit expiry date for this Credential and set a future date.

      You may receive an invalid certificate error if you are submitting an malformed key material, to avoid any issues it’s best to upload the file directly created by openssl.

7. Select Add Credential.

Configure an existing application

1. Navigate to Auth0 Dashboard > Applications.

2. Select the application you want to update.

3. Select the Credentials tab.

4. Choose Private Key JWT.

5. Configure credential details:

   1. Enter a name for the credential.
   2. Upload your PEM format or X.509 certificate.
   3. Select the algorithm to sign the assertions.
   4. Optional: Enable custom expiration. Select Set an explicit expiry date for this Credential and set a future date.

6. Select Add Credential.

Configure an application to use Client Secret authentication

1. Navigate to Auth0 Dashboard > Applications > Applications and select the application you want to update.
2. Select the Credentials tab.
3. Choose Client Secret (Post) or Client Secret (Basic).
4. Select Save.

Update credential expiration

You can update an existing credential with an expiration date with Auth0 Dashboard.

1. Navigate to Auth0 Dashboard > Applications > Applications and select the application you want to update.

2. Select the Credentials tab.

3. Choose the credential you want to update and select Edit Credential.

   

4. Select Set an explicit expiry date for this Credential and set a future date.

5. Select Update Credential.

Management API

Configure a new application for private_key_jwt

You can create a new application with private_key_jwt as the authentication method using the Management API. Make a POST call to the Create a Client endpoint with the following payload:

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": "{credentialublicKey}",
          "alg": "{algorithm}",
          "expires_at": "{expiresAt}"
       }
     ]
   },
   "jwt_configuration": {
     "alg": "RS256"
   }
 }
}'

Parameter	Description
algorithm	Algorithm used to sign assertions. Supported values are RS256, RS384 and PS256. If not specified, the algorithm will default to RS256.
clientName	Name for your new client.
credentialName	Name for the public key.
expires_at	Optional. Expiration date of the credential in ISO 8601 format. For example, 2020-08-20T19:10:06.299Z. Once the expiration date passes, the credential is no longer valid.
managementApiAccessToken	Access token for the Management API with the scope create:credentials.
pem	Public key, or x.509 certificate, encoded in PEM format.
parse_expiry_from_cert	Optional. A boolean that indicates that Auth0 should parse the expiry when provided a certificate. If a certificate is not provided, Auth0 will return an error. parse_expiry_from_cert and expires_at are also mutually exclusive. In this case, Auth0 will return an error.

The public key PEM should be JSON escaped before being passed to Auth0, in our example, this is the content we need to pass:

-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82 mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx +wIDAQAB -----END PUBLIC KEY-----

The response contains the client_id property which will link your application to the resource server. The response also contains a generated kid for the credential you created. This will be used later to generate the client_assertion.

Auth0 follows the JSON Web Key Thumbprint standard to generate the kid of your credentials.

The kid consists of a base64URL encoded SHA256 digest of of the JWK representation of your public key.

Configure an existing application

You can also configure an existing application to use Private Key JWT Authentication with the Auth0 Management API. You will need to remove any values in the token_endpoint_auth_method field and create values in the client_authentication_methods field.

If you update an existing production application to authenticate with private_key_jwt, we recommend you securely store your current client_secret value for future reference.

After you configure private_key_jwt, you won’t be able to access the client_secret value unless you restore your application’s configuration to use a Client Secret.

Create the credential resource

Once you have generated a key pair, create the credential resource. Make the following POST request to the Management API’s /clients endpoint.

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}",
}'

Parameter	Description
algorithm	Algorithm used to sign assertions. Supported values are RS256, RS384 and PS256. If not specified, the algorithm default is RS256.
clientId	ID of the application to be updated.
credentialName	Name of the public key.
managementApiAccessToken	Access token for the Management API with the scope create:credentials.
pem	Public key, or x.509 certificate, encoded in PEM format.
expires_at	Optional. Expiration date of the credential in ISO 8601 format. For example, 2020-08-20T19:10:06.299Z. Once the expiration date passes, the credential is no longer valid.
parse_expiry_from_cert	Optional. A boolean that indicates that Auth0 should parse the expiry when provided a certificate. If a certificate is not provided, Auth0 will return an error. parse_expiry_from_cert and expires_at are mutually exclusive. In this case, Auth0 will return an error.

The PEM public key should be JSON-escaped before being passed to Auth0. In this example, the content we need to pass is:

----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82
mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm
Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb
jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g
Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg
IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx
+wIDAQAB
-----END PUBLIC KEY-----

A credential ID returns in the response. Use the ID for the next step.

Associate the credential

After you create the credential, associate it with your application. Your application uses these credentials during authentication with private_key_jwt.

Make a PATCH request to the Management API Update a Client endpoint:

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} }]
             }
          }
   }​​'​​

Parameter	Description
clientId	ID of the application to be updated.
managementApiAccessToken	Access token for the Management API with the scope update:client and update:credentials.
credentialId	ID of the credential you created.
pem	The public key in PEM format.

Auth0 does not support use of HS256 as the applications’s JWT signing algorithm. You must have the jwt_configuration.alg field set to the RS256 algorithm. To learn how to change the signing algorithm, read Change Application Signing Algorithms.

Configure an application to use Client Secret authentication

To restore your application’s configuration to use a Client Secret, you must disable client_authentication_methods and re-enable token_endpoint_auth_method with the authentication method.

Once you have configured your authentication method as client_secret, your applications will no longer be able to authenticate using private_key_jwt until you have updated them to authenticate using client_secret.

Example

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
   }​​'​​

Parameter	Description
clientId	ID of the updated application.
managementApiAccessToken	Access token for the Management API with the scopes update:client and update:credentials.
tokenEndpointAuthMethod	Final authentication method. For example: client_secret_basic or client_secret_post.

Patch credentials with an expiration field

You can update an existing credential with an expiration date with the Management API Update a credential endpoint.

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}
   }'

Parameter	Description
managementApiAccessToken	Access tokens for the Management API with the scopes update:credentials.
clientId	The client you want to update.
expires_at	The expiration date of the credential in ISO 8601 format. For example, 2020-08-20T19:10:06.299Z.

The only field you can update is the expires_at field. The rest of the attributes are immutable and require you to rotate the credential to change.

Credential limits

Auth0 enforces a minimum RSA key size of 2048 bits and a maximum key size of 4096 bits. Applications can have a maximum of two credentials configured.

Rotate credentials

To prevent leaked keys, Auth0 recommends you periodically rotate the key pair. To learn how, read Rotate Credentials.

Learn more

• Application Credentials
• Credential Settings
• Authenticate with Private Key JWT