82 lines
5.3 KiB
Text
82 lines
5.3 KiB
Text
[[_client_authentication_adapter]]
|
|
==== Client authentication
|
|
|
|
When a confidential OIDC client needs to send a backchannel request (for example, to exchange code for the token, or to refresh the token) it needs to authenticate against the {project_name} server. By default, there are three ways to authenticate the client: client ID and client secret, client authentication with signed JWT, or client authentication with signed JWT using client secret.
|
|
|
|
===== Client ID and Client Secret
|
|
|
|
This is the traditional method described in the OAuth2 specification. The client has a secret, which needs to be known to both the adapter (application) and the {project_name} server.
|
|
You can generate the secret for a particular client in the {project_name} Admin Console, and then paste this secret into the `keycloak.json` file on the application side:
|
|
|
|
|
|
[source,json]
|
|
----
|
|
"credentials": {
|
|
"secret": "19666a4f-32dd-4049-b082-684c74115f28"
|
|
}
|
|
----
|
|
|
|
===== Client authentication with Signed JWT
|
|
|
|
This is based on the https://datatracker.ietf.org/doc/html/rfc7523[RFC7523] specification. It works this way:
|
|
|
|
* The client must have the private key and certificate. For {project_name} this is available through the traditional `keystore` file, which is either available on the client application's classpath or somewhere on the file system.
|
|
|
|
* Once the client application is started, it allows to download its public key in https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWKS] format using a URL such as \http://myhost.com/myapp/k_jwks, assuming that \http://myhost.com/myapp is the base URL of your client application. This URL can be used by {project_name} (see below).
|
|
|
|
* During authentication, the client generates a JWT token and signs it with its private key and sends it to {project_name} in
|
|
the particular backchannel request (for example, code-to-token request) in the `client_assertion` parameter.
|
|
|
|
* {project_name} must have the public key or certificate of the client so that it can verify the signature on JWT. In {project_name} you need to configure client credentials for your client. First you need to choose `Signed JWT` as the method of authenticating your client in the tab `Credentials` in the Admin Console.
|
|
Then you can choose to either in the tab `Keys`:
|
|
** Configure the JWKS URL where {project_name} can download the client's public keys. This can be a URL such as \http://myhost.com/myapp/k_jwks (see details above). This option is the most flexible, since the client can rotate its keys anytime and {project_name} then always downloads new keys when needed without needing to change the configuration. More accurately, {project_name} downloads new keys when it sees the token signed by an unknown `kid` (Key ID).
|
|
** Upload the client's public key or certificate, either in PEM format, in JWK format, or from the keystore. With this option, the public key is hardcoded and must be changed when the client generates a new key pair.
|
|
You can even generate your own keystore from the {project_name} Admin Console if you don't have your own available.
|
|
For more details on how to set up the {project_name} Admin Console, see the {adminguide_link}[{adminguide_name}].
|
|
|
|
For set up on the adapter side you need to have something like this in your `keycloak.json` file:
|
|
|
|
[source,json]
|
|
----
|
|
"credentials": {
|
|
"jwt": {
|
|
"client-keystore-file": "classpath:keystore-client.jks",
|
|
"client-keystore-type": "JKS",
|
|
"client-keystore-password": "storepass",
|
|
"client-key-password": "keypass",
|
|
"client-key-alias": "clientkey",
|
|
"token-expiration": 10
|
|
}
|
|
}
|
|
----
|
|
|
|
With this configuration, the keystore file `keystore-client.jks` must be available on classpath in your WAR. If you do not use the prefix `classpath:`
|
|
you can point to any file on the file system where the client application is running.
|
|
|
|
ifeval::[{project_community}==true]
|
|
For inspiration, you can take a look at the examples distribution into the main demo example into the `product-portal` application.
|
|
|
|
===== Client authentication with Signed JWT using client secret
|
|
|
|
This is the same as Client Authentication with Signed JWT except for using the client secret instead of the private key and certificate.
|
|
|
|
The client has a secret, which needs to be known to both the adapter (application) and the {project_name} server. You need to choose `Signed JWT with Client Secret` as the method of authenticating your client in the tab `Credentials` in the Admin Console, and then paste this secret into the `keycloak.json` file on the application side:
|
|
|
|
[source,json]
|
|
----
|
|
"credentials": {
|
|
"secret-jwt": {
|
|
"secret": "19666a4f-32dd-4049-b082-684c74115f28",
|
|
"algorithm": "HS512"
|
|
}
|
|
}
|
|
----
|
|
|
|
The "algorithm" field specifies the algorithm for Signed JWT using Client Secret. It needs to be one of the following values : HS256, HS384, and HS512. For details, please refer to https://datatracker.ietf.org/doc/html/rfc7518#section-3.2[JSON Web Algorithms (JWA)].
|
|
|
|
This "algorithm" field is optional so that HS256 is applied automatically if the "algorithm" field does not exist on the `keycloak.json` file.
|
|
|
|
===== Add your own client authentication method
|
|
|
|
You can add your own client authentication method as well. You will need to implement both client-side and server-side providers. For more details see the `Authentication SPI` section in link:{developerguide_link}[{developerguide_name}].
|
|
endif::[]
|