Configure 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.
Prerequisite
Generate a key pair
To configure an application that authenticates using Private Key JWT, generate an RSA key pair.
When you register the public key with Auth0, you must provide the public key encoded in PEM format. You may provide this as an X.509 certificate encoded in PEM format. Auth0 enforces a minimum RSA key size of 2048 bits and a maximum key size of 4096 bits. We recommend using openssl to generate a 2048 bit RSA key pair.
Generate a private key and a public key in PEM. You should safeguard the private key and never share it, not even with Auth0.
openssl genrsa -out test_key.pem 2048Extract the public key in PEM format using the following command. This command extracts the public key details so it can be safely shared without revealing the details of the private key.
openssl rsa -intest_key.pem -outform PEM -pubout -out test_key.pem.pubThe example below shows the contents of thetest_key.pem.pubPEM file:----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82 mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx +wIDAQAB -----END PUBLIC KEY-----Was this helpful?
/Save the key contents. You will need the PEM contents in other configuration steps.
Configure Private Key JWT
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
Navigate to Auth0 Dashboard > Applications > Application.
Select Create Application.
Choose your application type.
Under the application settings, select the Credentials tab.
Under Authentication Methods, select Private Key JWT.
Configure credential details:
Enter a name for the credential.
Upload your PEM format or X.509 certificate.
Select the algorithm to sign the assertions.
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.
Select Add Credential.
Configure an existing application
Navigate to Auth0 Dashboard > Applications.
Select the application you want to update.
Select the Credentials tab.
Choose Private Key JWT.
Configure credential details:
Enter a name for the credential.
Upload your PEM format or X.509 certificate.
Select the algorithm to sign the assertions.
Optional: Enable custom expiration. Select Set an explicit expiry date for this Credential and set a future date.
Select Add Credential.
Configure an application to use Client Secret authentication
Navigate to Auth0 Dashboard > Applications > Applications and select the application you want to update.
Select the Credentials tab.
Choose Client Secret (Post) or Client Secret (Basic).
Select Save.
Update credential expiration
You can update an existing credential with an expiration date with Auth0 Dashboard.
Navigate to Auth0 Dashboard > Applications > Applications and select the application you want to update.
Select the Credentials tab.
Choose the credential you want to update and select Edit Credential.
Select Set an explicit expiry date for this Credential and set a future date.
Select Update Credential.
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"
}
}
}'Was this helpful?
| 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}",
}'Was this helpful?
| 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-----Was this helpful?
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} }]
}
}
}'Was this helpful?
| 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
}'Was this helpful?
| 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}
}'Was this helpful?
| 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.