KEYCLOAK-6771 Holder of Key mechanism

OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access
Tokens

server_admin/topics/authentication/x509.adoc

@@ -56,6 +56,7 @@ Other Features: Extended Certificate Validation::
 
 The following sections describe how to configure WildFly/Undertow and the {project_name} Server to enable X.509 client certificate authentication.
 
+[[_enable-mtls-wildfly]]
 Enable mutual SSL in WildFly::
 See link:https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-EnableSSL[Enable SSL] and link:https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-%7B%7B%3Cssl%2F%3E%7D%7D[SSL] for the instructions how to enable SSL in WildFly.
 

server_admin/topics/clients/client-oidc.adoc

@@ -123,10 +123,33 @@ See link:{adapterguide_link}[{adapterguide_name}] for more information.
 To fill in the `Web Origins` data, enter in a base URL and click the + sign to add.  Click the - sign next to URLs you want to remove.
 Remember that you still have to click the `Save` button!
 
-
+==== Advanced Settings
-
+
-
+[[_mtls-client-certificate-bound-tokens]]
-
+*OAuth 2.0 Mutual TLS Client Certificate Bound Access Token*
+
+Mutual TLS binds an access token and a refresh token with a client certificate exchanged during TLS handshake. This prevents an attacker who finds a way to steal these tokens from exercising the tokens. The type of token is called a holder-of-key token. Unlike bearer tokens, the recipient of a holder-of-key token can verify whether the sender of the token is legitimate.
+
+If the following conditions are satisfied on a token request, {project_name} will bind an access token and a refresh token with a client certificate and issue them as holder-of-key tokens. If all conditions are not met, {project_name} rejects the token request.
+
+* The feature is turned on
+* A token request is sent to the token endpoint in an authorization code flow or a hybrid flow
+* On TLS handshake, {project_name} requests a client certificate and a client send its client certificate
+* On TLS handshake, {project_name} successfully verifies the client certificate
+
+To enable mutual TLS in {project_name}, see <<_enable-mtls-wildfly, Enable mutual SSL in WildFly>>.
+
+In the following cases, {project_name} will verify the client sending the access token or the refresh token; if verification fails, {project_name} rejects the token.
+
+* A token refresh request is sent to the token endpoint with a holder-of-key refresh token
+* A UserInfo request is sent to UserInfo endpoint with a holder-of-key access token
+* A logout request is sent to Logout endpoint with a holder-of-key refresh token
+
+Please see https://tools.ietf.org/html/draft-ietf-oauth-mtls-08#section-3[Mutual TLS Client Certificate Bound Access Tokens] in the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens for more details.
+
+WARNING:
+None of the keycloak client adapters currently support holder-of-key token verification.
+Instead, keycloak adapters currently treat access and refresh tokens as bearer tokens.
 
 
 

server_admin/topics/threat/compromised-tokens.adoc

@@ -6,6 +6,8 @@ There are a few things you can do to mitigate access tokens and refresh tokens f
 Another thing you can do to mitigate leaked access tokens is to shorten their lifespans.  You can specify this within the <<_timeouts, timeouts page>>.
 Short lifespans (minutes) for access tokens for clients and applications to refresh their access tokens after a short amount of time. If an admin detects a leak, they can logout all user sessions to invalidate these refresh tokens or set up a revocation policy. Making sure refresh tokens always stay private to the client and are never transmitted ever is very important as well.
 
+You can also mitigate against leaked access tokens and refresh tokens by issuing these tokens as holder-of-key tokens. See <<_mtls-client-certificate-bound-tokens, OAuth 2.0 Mutual TLS Client Certificate Bound Access Token>> to learn how.
+
 If an access token or refresh token is compromised, the first thing you should do is go to the admin console and push a not-before revocation policy to all applications. This will enforce that any tokens issued prior to that date are now invalid. Pushing new not-before policy will also ensure that application will be forced to download new public keys from {project_name}, hence it is also useful for the case, when you think that realm signing key was compromised.
 More info in the  <<realm_keys, keys chapter>>.