Client authentication methods

Some endpoints require client authentication. To make requests to these endpoints, you must include a header or parameter in the request depending on the authentication method that the application is configured with.

When registering an OAuth 2.0 client application, specify an authentication method by including the token_endpoint_auth_method parameter.

Note: If you don't specify a method when registering your client, the default method is client_secret_basic.

To create a client application and specify the authentication method, see Create a Client application. To change the client authentication method of an existing app, see Replace a Client Application.

Okta supports the following authentication methods, detailed in the sections below:

• client_secret_basic, client_secret_post, client_secret_jwt: Use one of these methods when the client has a client secret. Public clients (such as single-page and mobile apps) that can't protect a client secret must use none below.

• private_key_jwt: Use this when you want maximum security. This method is more complex and requires a server, so it can't be used with public clients.

• self_signed_tls_client_auth: Use this when you want to bind access tokens to a client TLS certificate. This method requires a server and isn't supported for public clients.

• none - Use this with clients that don't have a client secret (such as applications that use the authorization code flow with PKCE or the implicit flow).

If your client's token_endpoint_auth_method is either client_secret_basic or client_secret_post, include the client secret in outgoing requests.

• client_secret_basic: Provide the client_id and client_secret values in the Authorization header as a Basic auth base64-encoded string with the POST request:

    Authorization: Basic {Base64(<client_id>:<client_secret>)}

• client_secret_post: Provide the client_id and client_secret as additional parameters in the POST request body.

If you configured your client to use the client_secret_jwt client authentication method:

Provide the client_id in a JWT that you sign with the client_secret using an HMAC SHA algorithm (HS256, HS384, or HS512). The JWT must also contain other values, such as issuer and subject. See Token claims for client authentication with client secret or private key JWT.

Note: JWTs with a shared key require a secret that is at least 32 characters in length to satisfy HS256 cryptographic minimums. Clients that attempt to set token_endpoint_auth_method to client_secret_jwt with an imported secret less than 32 characters will receive a validation error. Clients that send Okta a JWT for verification signed with HS256, HS384, or HS512 with a secret less than 32 characters will receive an error: The client secret is too short to verify a JWT HMAC..

After you create the JWT, in the request you need to specify the client_assertion_type as urn:ietf:params:oauth:client-assertion-type:jwt-bearer and specify the JWT as the value for the client_assertion parameter.

For example:

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
  code=i1WsRn1uB1&
  client_id=0oajncakofQmjxlSw0h3
  client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
  client_assertion=PHNhbWxwOl ... ZT

This method is similar to JWT with shared key, but uses a public/private key pair for more security. The main benefit of this method is you can generate the private key on your own servers and never have it leave there for any reason, since you only need to provide the public key to Okta. This is better than client_secret_jwt since Okta must know what the client_secret string is beforehand, so there are more places that it could in theory be compromised.

If you configured your client to use the private_key_jwt client authentication method:

Provide the client_id in a JWT that you sign with your private key using an RSA or ECDSA algorithm (RS256, RS384, RS512, ES256, ES384, ES512). See Build a JWT for client authentication. The JWT must also contain other values, such as issuer and subject. See Token claims for client authentication with client secret or private key JWT.

Note: The private key that you use to sign the JWT must have the corresponding public key registered in the client's JWKSet.

After you create the JWT, in the request you need to specify the client_assertion_type as urn:ietf:params:oauth:client-assertion-type:jwt-bearer and specify the JWT as the value for the client_assertion parameter.

For example:

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
  code=i1WsRn1uB1&
  client_id=0oajncakofQmjxlSw0h3
  client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
  client_assertion=PHNhbWxwOl ... ZT

Note: mTLS client authentication is a self-service Early Access (EA) feature. See Manage Early Access and Beta features to enable the feature.

A client secret or JWT assertion proves who's asking for a token, but after Okta issues the token, it's a plain bearer token. This means that anyone who obtains it (such as through an intercepted request or a leaked log) can use it without further proof. mTLS client authentication closes that gap by binding the access token to the TLS certificate that the client presents when the token is requested. When the resource server enforces the binding, a party that obtains the token still needs the certificate's private key to use it. An interceptor can't use the token alone.

If you configure your client to use the self_signed_tls_client_auth client authentication method, present your client's X.509 certificate during the TLS handshake instead of sending a client secret or JWT assertion. You must include client_id in the form-encoded token request body so that Okta can identify the client. Okta validates the certificate with the client's registered JWKSet. An mTLS client can't use the implicit or password grant types, and you can't enable Demonstrating Proof-of-Possession (DPoP) for the client.

Because the TLS handshake is involved, you can't present the certificate to the standard token, introspection, or revocation endpoint URLs. Instead, make these requests to the mTLS-capable alias URLs that Okta publishes in the mtls_endpoint_aliases object of the OAuth 2.0 or OpenID Connect discovery metadata response. The tls_client_certificate_bound_access_tokens property in the same response indicates whether the authorization server supports certificate-bound access tokens.

When certificate validation succeeds, Okta issues an access token that's cryptographically bound to the certificate. The token's cnf claim contains an x5t#S256 member with the certificate's base64url-encoded SHA-256 thumbprint. Okta also binds refresh tokens to the certificate, so you must use refresh tokens over mTLS with the same certificate. To enforce the binding, the client must present the same certificate over mTLS when using the token, and the resource server must compare its thumbprint against the token's cnf.x5t#S256 value and reject requests with a missing or mismatched certificate. Without this check, anyone who obtains the token can use it without the certificate. Validating the token's signature or active status alone isn't sufficient. The introspection response for the token includes the same cnf.x5t#S256 value.

Specify none when the client is a public client and doesn't have a client secret. Only the client_id is sent in the request body.

If you use a JWT for client authentication (client_secret_jwt or private_key_jwt), use the following token claims:

Parameter details

• If jti is specified, the token can only be used once. So, for example, subsequent token requests won't succeed.
• The exp claim fails the request if the expiration time is more than one hour in the future or has already expired.
• If iat is specified, then it must be a time before the request is received.