From ec41c65ebc0cb46ccf35abd87ae3209774bc6320 Mon Sep 17 00:00:00 2001 From: amanda-vanscoy Date: Mon, 20 Apr 2026 15:51:26 -0400 Subject: [PATCH 1/2] Update for EA Additional Signing Algo for Private Key JWT Okta and OIDC --- .../private-key-jwt-client-auth.mdx | 34 ++++++++----------- .../private-key-jwt-client-auth.mdx | 8 +---- ...igure-applications-with-oidc-discovery.mdx | 8 +++++ .../configure-private-key-jwt.mdx | 22 ++---------- .../applications/signing-algorithms.mdx | 4 +++ .../authenticate-with-private-key-jwt.mdx | 5 +++ .../private-key-jwt-client-auth.mdx | 7 +--- 7 files changed, 36 insertions(+), 52 deletions(-) diff --git a/main/docs/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx b/main/docs/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx index 127703d609..ae19b1170e 100644 --- a/main/docs/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx +++ b/main/docs/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx @@ -2,12 +2,6 @@ description: Learn how to implement Private Key JWT Client Authentication for your enterprise connections. title: Private Key JWT Client Authentication for Okta and OIDC Connections --- - - -Private Key JWT Client Authentication for OpenID Connect (OIDC) and Okta Workforce connections is currently available in [Early Access](/docs/troubleshoot/product-lifecycle/product-release-stages). By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). - - - Private Key JWT Client Authentication is an alternative method of client authentication for OpenID Connect (OIDC) and Okta Workforce enterprise connections. While client authentication is most commonly handled by passing a shared client secret, Private Key JWT Client Authentication instead passes a signed JWT for improved application security. By using this feature, you can avoid some common security shortcomings often seen with standard client secret authentication, such as: @@ -75,7 +69,8 @@ You can configure OIDC and Okta Workforce enterprise connections to use Private * Private and public signing key pairs are automatically generated by Auth0 per connection. -* You can currently only use the RS256 algorithm for signing client assertion JWTs. +* You can use the following algorithms to sign client assertion JWTs: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, and `ES384` for Okta and OIDC Enterprise connections. Defaults to `RS256` if not specified. +* Switching between RSA/PS (`RS*`, `PS*`) and EC (`ES*`) algorithm families requires generating a new signing key pair for the connection. * Signed JWTs expire automatically after 60 seconds. @@ -84,12 +79,6 @@ You can configure OIDC and Okta Workforce enterprise connections to use Private You can use the Auth0 Dashboard to configure Private Key JWT Client Authentication for both new and existing OIDC and Okta Workforce connections. - - -If your custom OIDC connection uses an IdP that does not advertise support for back-channel communication or `private_key_jwt` as a client authentication method in its metadata, you will not be able to set up Private Key JWT Client Authentication through the Auth0 Dashboard. - - - 1. On your Auth0 Dashboard, navigate to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise). @@ -111,7 +100,6 @@ If your custom OIDC connection uses an IdP that does not advertise support for b * Set **Communication Channel** to **Back Channel**. * Set **Authentication Method** to **Private Key JWT**. 5. Select **Save** at the bottom of the screen. -6. On the confirmation popup, select **Change** to implement your modifications. @@ -126,8 +114,10 @@ To create a new OIDC connection that uses Private Key JWT Client Authentication, | Property | Description | | --- | --- | | `type` | Set this property to `back_channel`. | -| `token_endpoint_auth_method` | Set this property to `private_key_jwt`.

**Notes:** | -| `token_endpoint_auth_signing_alg` | Set this property to `RS256`.

**Notes:** | +| `token_endpoint_auth_method` | Authentication method used at the identity provider's token endpoint. Set to `private_key_jwt` to use a signed JWT assertion for enhanced security, or `client_secret_post` to send credentials in the request body. Defaults to `client_secret_post`. Applicable to `oidc` and `okta` strategies only. | +| `token_endpoint_auth_signing_alg` | Optional. Algorithm used to sign client assertions. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. Defaults to `RS256` if not set. Switching between RSA/PS (`RS*`, `PS*`) and EC (`ES*`) algorithm families requires generating a new signing key pair. Applicable to `oidc` and `okta` strategies only. | +| `id_token_signed_response_algs` | Optional. List of algorithms allowed to verify ID tokens issued by the identity provider. When set, Auth0 rejects ID tokens signed with any algorithm not in this list. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. If not set, Auth0 accepts ID tokens signed with any supported algorithm. Applicable to `oidc` and `okta` strategies only. | +| `token_endpoint_jwtca_aud_format` | Optional. Specifies the format of the `aud` (audience) claim in the JWT used for client authentication at the token endpoint. Set to `issuer` to use the OIDC issuer URL, or `token_endpoint` to use the token endpoint URL. | **Example POST call** @@ -139,7 +129,8 @@ POST /api2/connections options: { type: "back_channel", token_endpoint_auth_method: "private_key_jwt", - token_endpoint_auth_signing_alg: "RS256" + token_endpoint_auth_signing_alg: "RS256", + id_token_signed_response_algs: ["RS256", "RS384"] }, … } @@ -157,7 +148,10 @@ To modify an existing OIDC connection to use Private Key JWT Client Authenticati | Property | Description | | --- | --- | | `type` | Set this property to `back_channel`. | -| `token_endpoint_auth_method` | Set this property to `private_key_jwt`.

**Notes:** | +| `token_endpoint_auth_method` | Authentication method used at the identity provider's token endpoint. Set to `private_key_jwt` to use a signed JWT assertion for enhanced security, or `client_secret_post` to send credentials in the request body. Defaults to `client_secret_post`. Applicable to `oidc` and `okta` strategies only. | +| `token_endpoint_auth_signing_alg` | Optional. Algorithm used to sign client assertions. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. Defaults to `RS256` if not set. Switching between RSA/PS (`RS*`, `PS*`) and EC (`ES*`) algorithm families requires generating a new signing key pair. Applicable to `oidc` and `okta` strategies only. | +| `id_token_signed_response_algs` | Optional. List of algorithms allowed to verify ID tokens issued by the identity provider. When set, Auth0 rejects ID tokens signed with any algorithm not in this list. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. If not set, Auth0 accepts ID tokens signed with any supported algorithm. Applicable to `oidc` and `okta` strategies only. | +| `token_endpoint_jwtca_aud_format` | Optional. Specifies the format of the `aud` (audience) claim in the JWT used for client authentication at the token endpoint. Set to `issuer` to use the OIDC issuer URL, or `token_endpoint` to use the token endpoint URL. | **Example PATCH call** @@ -168,7 +162,9 @@ PATCH /api2/connections/{id} strategy: 'oidc', options: { type: "back_channel", - token_endpoint_auth_method: "private_key_jwt" + token_endpoint_auth_method: "private_key_jwt", + token_endpoint_auth_signing_alg: "RS256", + id_token_signed_response_algs: ["RS256", "RS384"] }, … } diff --git a/main/docs/fr-ca/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx b/main/docs/fr-ca/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx index 37641f18a3..c777d8d380 100644 --- a/main/docs/fr-ca/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx +++ b/main/docs/fr-ca/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx @@ -3,12 +3,6 @@ title: "Private Key JWT Client Authentication for Okta and OIDC Connections" 'description': "Learn how to implement Private Key JWT Client Authentication for your enterprise connections. " --- - - -Private Key JWT Client Authentication for OpenID Connect (OIDC) and Okta Workforce connections is currently available in [Early Access](/docs/fr-ca/troubleshoot/product-lifecycle/product-release-stages). By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). - - - Private Key JWT Client Authentication is an alternative method of client authentication for OpenID Connect (OIDC) and Okta Workforce enterprise connections. While client authentication is most commonly handled by passing a shared +If you have an OIDC Enterprise Connection, you can choose from [additional signing algorithms](/docs/authenticate/enterprise-connections/private-key-jwt-client-auth#configure-private-key-jwt-client-authentication) for Private Key JWT. + + With this setting, Auth0 will issue JWTs signed with your private signing key. Your app will verify them with your public signing key. + ## Configure applications with OAuth 2.0 Authorization Server Metadata If your application or SDK references the [OAuth RFC-8414](https://www.rfc-editor.org/rfc/rfc8414) Authorization Server Metadata specification, you can use the OAuth alias to fetch metadata about the IdP: `/.well-known/oauth-authorization-server`. For example, the [Auth0 Model Context Protocol Server](/docs/get-started/auth0-mcp-server) recommends all OAuth applications reference the OAuth Authorization Server Metadata specification. diff --git a/main/docs/get-started/applications/configure-private-key-jwt.mdx b/main/docs/get-started/applications/configure-private-key-jwt.mdx index 51f1bb38c3..e64ecb0863 100644 --- a/main/docs/get-started/applications/configure-private-key-jwt.mdx +++ b/main/docs/get-started/applications/configure-private-key-jwt.mdx @@ -97,7 +97,7 @@ curl --location --request POST 'https://{domain}/api/v2/clients' \ { "name": "{credentialName}", "credential_type": "public_key", - "pem": "{credentialublicKey}", + "pem": "{credentialPublicKey}", "alg": "{algorithm}", "expires_at": "{expiresAt}" } @@ -111,10 +111,6 @@ curl --location --request POST 'https://{domain}/api/v2/clients' \ ``` - - - - | Parameter | Description | | --- | --- | | `algorithm` | Algorithm used to sign assertions. Supported values are RS256, RS384 and PS256. If not specified, the algorithm will default to RS256. | @@ -180,11 +176,6 @@ curl --location --request POST 'https://{domain}/api/v2/clients/{clientId}/crede }' ``` - - - - - | Parameter | Description | | --- | --- | | `algorithm` | Algorithm used to sign assertions. Supported values are RS256, RS384 and PS256. If not specified, the algorithm default is RS256. | @@ -200,7 +191,7 @@ curl --location --request POST 'https://{domain}/api/v2/clients/{clientId}/crede The PEM public key should be JSON-escaped before being passed to Auth0. In this example, the content we need to pass is: ```pem lines -----BEGIN PUBLIC KEY----- +-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82 mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb @@ -280,11 +271,6 @@ curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \ }​​'​​ ``` - - - - - | Parameter | Description | | --- | --- | | `clientId` | ID of the updated application. | @@ -305,10 +291,6 @@ curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId}/cred ``` - - - - | Parameter | Description | | --- | --- | | `managementApiAccessToken` | Access tokens for the Management API with the scopes ` update:credentials`. | diff --git a/main/docs/get-started/applications/signing-algorithms.mdx b/main/docs/get-started/applications/signing-algorithms.mdx index 93e0daa341..b07cefb9ec 100644 --- a/main/docs/get-started/applications/signing-algorithms.mdx +++ b/main/docs/get-started/applications/signing-algorithms.mdx @@ -15,6 +15,10 @@ The most secure practice, and our recommendation, is to use RS256 because: * With RS256, you are sure that only the holder of the private key (Auth0) can sign tokens, while anyone can check if the token is valid using the public key. * With RS256, if the private key is compromised, you can implement key rotation without having to re-deploy your application or API with the new secret (which you would have to do if using HS256). + +If you are configuring Private Key JWT Authentication with an Okta or OpenID Connection (OIDC) enterprise connection, you may have to choose an [additional signing algorithms](/docs/authenticate/enterprise-connections/private-key-jwt-client-auth#configure-private-key-jwt-client-authentication). + + For troubleshooting help, review [Troubleshooting Invalid Token Errors](/docs/troubleshoot/basic-issues/invalid-token-errors). ## Learn more diff --git a/main/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt.mdx b/main/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt.mdx index 64256d5ebb..7ab2d9de5a 100644 --- a/main/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt.mdx +++ b/main/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt.mdx @@ -164,3 +164,8 @@ Claims within the assertion have the following limits: * `sub`: 64 characters * `jti`: 64 characters * `alg`: 16 characters + +## Learn more + +* [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt) +* [Private Key JWT Client Authentication for Okta and OIDC Connections](/docs/authenticate/enterprise-connections/private-key-jwt-client-auth) \ No newline at end of file diff --git a/main/docs/ja-jp/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx b/main/docs/ja-jp/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx index dd666667ae..ffafc2bec9 100644 --- a/main/docs/ja-jp/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx +++ b/main/docs/ja-jp/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx @@ -3,11 +3,6 @@ title: "Private Key JWT Client Authentication for Okta and OIDC Connections" 'description': "Learn how to implement Private Key JWT Client Authentication for your enterprise connections. " --- - - -Private Key JWT Client Authentication for OpenID Connect (OIDC) and Okta Workforce connections is currently available in [Early Access](/docs/ja-jp/troubleshoot/product-lifecycle/product-release-stages). By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). - - Private Key JWT Client Authentication is an alternative method of client authentication for OpenID Connect (OIDC) and Okta Workforce enterprise connections. While client authentication is most commonly handled by passing a shared client secret, Private Key JWT Client Authentication instead passes a signed JWT for improved application security. @@ -128,7 +123,7 @@ To create a new OIDC connection that uses Private Key JWT Client Authentication, | --- | --- | | `type` | Set this property to `back_channel`. | | `token_endpoint_auth_method` | Set this property to `private_key_jwt`.

**Notes:** | -| `token_endpoint_auth_signing_alg` | Set this property to `RS256`.

**Notes:** | +| `token_endpoint_auth_signing_alg` | Set this property to `RS256`, `RS512`, `PS256`, `PS384`, `ES256`, or `ES384`.

Omitting this property will default its value to `RS256`.| **Example POST call** From b851e6803f685bb558e5308563231daa377e8486 Mon Sep 17 00:00:00 2001 From: amanda-vanscoy Date: Fri, 24 Apr 2026 16:18:13 -0400 Subject: [PATCH 2/2] Addressed comment --- .../private-key-jwt-client-auth.mdx | 24 ++++++------------- .../applications/signing-algorithms.mdx | 2 +- 2 files changed, 8 insertions(+), 18 deletions(-) diff --git a/main/docs/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx b/main/docs/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx index ae19b1170e..ceecfde533 100644 --- a/main/docs/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx +++ b/main/docs/authenticate/enterprise-connections/private-key-jwt-client-auth.mdx @@ -70,7 +70,6 @@ You can configure OIDC and Okta Workforce enterprise connections to use Private * Private and public signing key pairs are automatically generated by Auth0 per connection. * You can use the following algorithms to sign client assertion JWTs: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, and `ES384` for Okta and OIDC Enterprise connections. Defaults to `RS256` if not specified. -* Switching between RSA/PS (`RS*`, `PS*`) and EC (`ES*`) algorithm families requires generating a new signing key pair for the connection. * Signed JWTs expire automatically after 60 seconds. @@ -99,7 +98,8 @@ You can use the Auth0 Dashboard to configure Private Key JWT Client Authenticati * Set **Communication Channel** to **Back Channel**. * Set **Authentication Method** to **Private Key JWT**. -5. Select **Save** at the bottom of the screen. +5. Select **Save**. +6. On the confirmation popup, select **Change** to implement your modifications. @@ -114,8 +114,8 @@ To create a new OIDC connection that uses Private Key JWT Client Authentication, | Property | Description | | --- | --- | | `type` | Set this property to `back_channel`. | -| `token_endpoint_auth_method` | Authentication method used at the identity provider's token endpoint. Set to `private_key_jwt` to use a signed JWT assertion for enhanced security, or `client_secret_post` to send credentials in the request body. Defaults to `client_secret_post`. Applicable to `oidc` and `okta` strategies only. | -| `token_endpoint_auth_signing_alg` | Optional. Algorithm used to sign client assertions. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. Defaults to `RS256` if not set. Switching between RSA/PS (`RS*`, `PS*`) and EC (`ES*`) algorithm families requires generating a new signing key pair. Applicable to `oidc` and `okta` strategies only. | +| `token_endpoint_auth_method` | Authentication method used at the identity provider's token endpoint. Set to `private_key_jwt` to use a signed JWT assertion for enhanced security, or `client_secret_post` to send credentials in the request body. Defaults to `token-endpoint`. Applicable to `oidc` and `okta` strategies only. | +| `token_endpoint_auth_signing_alg` | Optional. Algorithm used to sign client assertions. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. Defaults to `RS256` if not set. Applicable to `oidc` and `okta` strategies only. | | `id_token_signed_response_algs` | Optional. List of algorithms allowed to verify ID tokens issued by the identity provider. When set, Auth0 rejects ID tokens signed with any algorithm not in this list. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. If not set, Auth0 accepts ID tokens signed with any supported algorithm. Applicable to `oidc` and `okta` strategies only. | | `token_endpoint_jwtca_aud_format` | Optional. Specifies the format of the `aud` (audience) claim in the JWT used for client authentication at the token endpoint. Set to `issuer` to use the OIDC issuer URL, or `token_endpoint` to use the token endpoint URL. | @@ -136,11 +136,6 @@ POST /api2/connections } ``` - - - - - To modify an existing OIDC connection to use Private Key JWT Client Authentication, call the [Update a Connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint with the following `connection.options` properties set appropriately: @@ -148,8 +143,8 @@ To modify an existing OIDC connection to use Private Key JWT Client Authenticati | Property | Description | | --- | --- | | `type` | Set this property to `back_channel`. | -| `token_endpoint_auth_method` | Authentication method used at the identity provider's token endpoint. Set to `private_key_jwt` to use a signed JWT assertion for enhanced security, or `client_secret_post` to send credentials in the request body. Defaults to `client_secret_post`. Applicable to `oidc` and `okta` strategies only. | -| `token_endpoint_auth_signing_alg` | Optional. Algorithm used to sign client assertions. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. Defaults to `RS256` if not set. Switching between RSA/PS (`RS*`, `PS*`) and EC (`ES*`) algorithm families requires generating a new signing key pair. Applicable to `oidc` and `okta` strategies only. | +| `token_endpoint_auth_method` | Authentication method used at the identity provider's token endpoint. Set to `private_key_jwt` to use a signed JWT assertion for enhanced security, or `client_secret_post` to send credentials in the request body. Defaults to `token_endpoint`. Applicable to `oidc` and `okta` strategies only. | +| `token_endpoint_auth_signing_alg` | Optional. Algorithm used to sign client assertions. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. Defaults to `RS256` if not set. Applicable to `oidc` and `okta` strategies only. | | `id_token_signed_response_algs` | Optional. List of algorithms allowed to verify ID tokens issued by the identity provider. When set, Auth0 rejects ID tokens signed with any algorithm not in this list. Accepted values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `ES256`, `ES384`. If not set, Auth0 accepts ID tokens signed with any supported algorithm. Applicable to `oidc` and `okta` strategies only. | | `token_endpoint_jwtca_aud_format` | Optional. Specifies the format of the `aud` (audience) claim in the JWT used for client authentication at the token endpoint. Set to `issuer` to use the OIDC issuer URL, or `token_endpoint` to use the token endpoint URL. | @@ -170,11 +165,6 @@ PATCH /api2/connections/{id} } ``` - - - - - ## Retrieve Signing Keys @@ -196,7 +186,7 @@ To retrieve signing keys through the Auth0 Dashboard: -To view public keys through the Management API, call the Retrieve Connection Signing Keys endpoint using the ID of your connection. +To view public keys through the Management API, call the [Get connection keys](https://auth0.com/docs/api/management/v2/connections/get-keys) endpoint using the ID of your connection. diff --git a/main/docs/get-started/applications/signing-algorithms.mdx b/main/docs/get-started/applications/signing-algorithms.mdx index b07cefb9ec..6564b8bc9c 100644 --- a/main/docs/get-started/applications/signing-algorithms.mdx +++ b/main/docs/get-started/applications/signing-algorithms.mdx @@ -16,7 +16,7 @@ The most secure practice, and our recommendation, is to use RS256 because: * With RS256, if the private key is compromised, you can implement key rotation without having to re-deploy your application or API with the new secret (which you would have to do if using HS256). -If you are configuring Private Key JWT Authentication with an Okta or OpenID Connection (OIDC) enterprise connection, you may have to choose an [additional signing algorithms](/docs/authenticate/enterprise-connections/private-key-jwt-client-auth#configure-private-key-jwt-client-authentication). +If you are configuring Private Key JWT Authentication with an Okta or OpenID Connection (OIDC) enterprise connection, you may have to choose [additional signing algorithms](/docs/authenticate/enterprise-connections/private-key-jwt-client-auth#configure-private-key-jwt-client-authentication). For troubleshooting help, review [Troubleshooting Invalid Token Errors](/docs/troubleshoot/basic-issues/invalid-token-errors).