Configure Private Key JWT Authentication
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
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.
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 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
.
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.
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. |
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. |
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.
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.