Private Key JWT Client Authentication for Okta and OIDC Connections

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:

• An increased risk of interception and re-use, as client secrets must be transmitted between parties for every request.

• Limited mechanisms available to enforce expiration and prevent re-use by malicious actors. 

• An increased risk of leaks or exposure due to both parties holding the client secret.

You can set up Private Key JWT Client Authentication for your OIDC and Okta Workforce enterprise connections through either the Auth0 Dashboard or the Management API. 

The OIDC Connection flow uses authenticated endpoints such as /oauth/token or /oauth/par to verify a client’s identity against the authorization server or OpenID provider. With Private Key JWT Client Authentication, a signed client assertion JWT is passed to the OpenID provider instead of a client secret.

The client assertion JWT contains the following claims:

• An aud (audience) identifying the OpenID provider’s token endpoint.

• A jti (JWT ID) to enable one-time use or replay protection.

• An exp (expiration time) that limits the token’s validity window. 

• A sub and iss identifying the client ID. 

Private Key JWT Client Authentication offers a more secure method of authentication by eliminating the use of shared client secrets. Instead, the JWT is signed using the client’s private key, and the OpenID provider only has access to the public key. 

After a user completes authentication with an upstream identity provider (IdP), the user is redirected to Auth0 with an authorization code that is exchanged for tokens at the OpenID provider’s token endpoint. When Private Key JWT is enabled for a connection, the call to the OpenID provider’s token endpoint uses a client assertion instead of a client secret for a more secure authentication. 

The following steps demonstrate a typical Private Key JWT Client Authentication flow.

1. After configuring your connection, Auth0 automatically generates and stores two public and private key pairs.

   • One key pair is the active current set, while the other set is labeled as next to support key rotation.

2. Depending on your IDP, you next either:

   • Download the current public key and upload the file to the Authorization Server, or:

   • Copy and paste the jwks_uri to the Authorization Server.

3. A user performs an action that requires authentication, such as logging in to your application.

4. Auth0 sends a request to the Authorization Server to initiate authentication.

5. The Authorization Server displays authentication and consent screens to the user.

6. The user authenticates and provides consent to the Authorization Server.

7. The Authorization Server sends an authorization code to Auth0.

8. Auth0 generates a client assertion JWT and signs it using the current private key.

9. Auth0 passes the client assertion JWT to the Authorization Server.

10. The Authorization Server looks up the client based on the provided client_id.

11. The Authorization Server fetches public keys from Auth0 if a jwks_uri was provided; otherwise, the server identifies the public key registered in step 2.

12. If the jwks_uri was requested, Auth0 returns the public keys as JWKS.

13. The Authorization Server validates the JWT by verifying the signature with the current public key, identified by kid in the header of the client_assertion JWT.

14. The Authorization Server generates an access token.

15. The Authorization Server passes the access token to Auth0.

16. Using the access token, Auth0 requests a resource from the Resource Server.

17. The Resource Server provides the resource to complete the flow.

You can configure OIDC and Okta Workforce enterprise connections to use Private Key JWT Client Authentication through either the Auth0 Dashboard or Management API. Steps for each method are provided below.

You can use the Auth0 Dashboard to configure Private Key JWT Client Authentication for both new and existing OIDC and Okta Workforce connections.

You can use the Management API to configure Private Key JWT Client Authentication for both new and existing OIDC connections.

POST /api2/connections

{
  strategy: 'oidc',
  options: {
    type: "back_channel",
    token_endpoint_auth_method: "private_key_jwt",
    token_endpoint_auth_signing_alg: "RS256"
  },
  …
}

PATCH /api2/connections/{id}

{
  strategy: 'oidc',
  options: {
    type: "back_channel",
    token_endpoint_auth_method: "private_key_jwt"
  },
  …
}

After your connection has been configured to use Private Key JWT Client Authentication, you can retrieve its public keys through either the Auth0 Dashboard, the Management API, or a public JWKS URI.

GET /api2/connections/{id}/keys

{
    cert: "-----BEGIN CERTIFICATE-----
MIIDDTCCAfWgAwIBAgIJP...Ek=
-----END CERTIFICATE-----",
    pkcs7: "-----BEGIN PKCS7-----
MIIDPAYJKoZIhvcNAQcCo...AA==
-----END PKCS7-----
",
    kid: "E4CXqUP6r92yo0f_sdkdC",
    next: true,
    fingerprint: "7F:33:86:D9:4A:98:B2:DC:B0:41:74:54:DA:31:E7:74:42:32:96:8C",
    thumbprint: "7F3386D94A98B2DCB0417454DA31E7744232968C"
  }, 
  {
    cert: "-----BEGIN CERTIFICATE-----
MIIDDTCCAfWgAwIBAgI...Ss=
-----END CERTIFICATE-----",
    pkcs7: "-----BEGIN PKCS7-----
MIIDPAYJKoZIhvcNAQ...AA==
-----END PKCS7-----
",
    kid: "_4WuXpXlwwmSE65saKWDM",
    current: true,
    current_since: "2025-01-24T08:50:06.662Z",
    fingerprint: "33:7D:6F:35:46:31:AD:6E:69:43:01:A2:77:DF:8E:73:64:F6:E8:5B",
    thumbprint: "337D6F354631AD6E694301A277DF8E7364F6E85B"
  }, 
  {
    cert: "-----BEGIN CERTIFICATE-----
MIIDDTCCAfWgAwIBA...6Q=
-----END CERTIFICATE-----",
    pkcs7: "-----BEGIN PKCS7-----
MIIDPAYJKoZIhvcN...AA==
-----END PKCS7-----
",
    kid: "roUD9STeDy9qBTx5XjaTz",
    previous: true,
    current_since: "2025-01-24T08:48:51.523Z",
    current_until: "2025-01-24T08:50:06.663Z",
    fingerprint: "44:D3:DD:3B:63:99:59:9A:39:D9:F4:F0:4F:1B:AC:BB:18:72:40:5C",
    thumbprint: "44D3DD3B6399599A39D9F4F04F1BACBB1872405C"
  }

https://{auth0 domain}/oauth/connection/{connection name}/.well-known/jwks.json

Private Key JWT Client Authentication supports signing key rotation for increased security compared to the static, long-lived nature of shared client secrets. Rotating signing keys enhances security by limiting the exposure time of any single key, reducing the window of opportunity for an attacker to compromise it. It also allows for rapid response in the wake of a security incident. 

To avoid disruption, Auth0 recommends rotating signing keys after one year. You can use either the Auth0 Dashboard or the Management API to rotate signing keys:

POST /v2/connections/{id}/keys/rotate

• Connect Your Auth0 Application with Okta Workforce Enterprise Connection
• Connect to OpenID Connect Identity Provider