[id="con-confidential-client-credentials_{context}"]

[[_client-credentials]]
= Confidential client credentials
[role="_abstract"]
If the <<_access-type, Client authentication>> of the client is set to *ON*, the credentials of the client must be configured under the *Credentials* tab.

.Credentials tab
image:images/client-credentials.png[Credentials Tab]

The *Client Authenticator* drop-down list specifies the type of credential to use for your client.

*Client ID and Secret*

This choice is the default setting. A random secret is generated automatically, but you can override it with a specific value if needed. The client secret can also reference a value stored in an <<_vault-administration,external vault>>. Click *Regenerate* to recreate random secret if necessary.


As specified in the OAuth2 and OpenID Connect specifications, it is possible to authenticate client either with the client secret in the `Authorization: Basic`
header (together with `client_id`) or by sending `client_id` and `client_secret` as parameters in the HTTP POST method body. You can configure the *Allowed authentication
method* to restrict only to one specified method of those if you want to authenticate client for example just with the `Authorization: Basic` method, but never with the request
parameters sent in the HTTP POST method body.

*Signed JWT issued by the client*
image:images/client-credentials-jwt.png[Signed JWT]

*Signed JWT* allows a client to authenticate with self-signed client assertions. This enables the client to authenticate without a shared secret.

In this authenticator you can enforce the *Signature algorithm* used by the client (any algorithm is valid by default) and the *Max expiration* allowed for the JWT token (tokens received after this period will not be accepted because they are too old, note that tokens should be issued right before the authentication, 60 seconds by default).

When choosing this credential type you will have to also generate a private key and certificate for the client in the tab `Keys`. The private key will be used to sign the JWT, while the certificate is used by the server to verify the signature.

.Keys tab
image:images/client-oidc-keys.png[Keys tab]

Click on the `Generate new keys` button to start this process.

.Generate keys
image:images/generate-client-keys.png[]

. Select the archive format you want to use.
. Enter a *key password*.
. Enter a *store password*.
. Click *Generate*.

When you generate the keys, {project_name} will store the certificate and you download the private key and certificate for your client.

You can also generate keys using an external tool and then import the client's certificate by clicking *Import Certificate*.

.Import certificate
image:images/import-client-cert.png[Import Certificate]

. Select the archive format of the certificate.
. Enter the store password.
. Select the certificate file by clicking *Import File*.
. Click *Import*.

Importing a certificate is unnecessary if you click *Use JWKS URL*. In this case, you can provide the URL where the public key is published in https://datatracker.ietf.org/doc/html/rfc7517[JWK] format. With this option, if the key is ever changed, {project_name} reimports the key.

If you are using a client secured by {project_name} adapter, you can configure the JWKS URL in this format, assuming that https://myhost.com/myapp is the root URL of your client application:

[source,bash,subs=+attributes]
----
https://myhost.com/myapp/k_jwks
----

See link:{developerguide_link}[{developerguide_name}] for more details.

*Signed JWT issued by an Identity Provider*

*Signed JWT* allows a client to authenticate with client assertions issued by an identity provider. Example use-cases
include:

* Client assertion issued by an OpenID Connect provider
* SPIFFE JWT SVIDs
* Kubernetes service accounts

Before using this authentication mechanism, an identity provider capable of verifying client assertions should be configured.

The identity providers which support client assertions are:

* <<_identity_broker_oidc,OpenID Connect>> (support for client assertions must be enabled)
* <<_identity_broker_spiffe,SPIFFE>>

image:images/client-federated-jwt.png[]

* Identity provider - the alias of the identity provider to use
* Federated subject - the external client id for the client (value of the `sub` claim of the client assertion)


*Signed JWT with Client Secret*

If you select this option, you can use a JWT signed by client secret instead of the private key.
The client secret can also reference a value stored in an <<_vault-administration,external vault>>.

The client secret will be used to sign the JWT by the client.

Like in the *Signed JWT* authenticator you can configure the *Signature algorithm* and the *Max expiration* for the JWT token.

*X509 Certificate*

{project_name} will validate if the client uses proper X509 certificate during the TLS Handshake.

.X509 certificate
image:images/x509-client-auth.png[]

The validator also checks the Subject DN field of the certificate with a configured regexp validation expression. For some
use cases, it is sufficient to accept all certificates. In that case, you can use `(.*?)(?:$)` expression.

Two ways exist for {project_name} to obtain the Client ID from the request:

* The `client_id` parameter in the query (described in Section 2.2 of the https://datatracker.ietf.org/doc/html/rfc6749[OAuth 2.0 Specification]).
* Supply `client_id` as a form parameter.
