From b28335f7a0afdb6d01e6c7878c9e798835e539c0 Mon Sep 17 00:00:00 2001 From: Takashi Norimatsu Date: Tue, 15 May 2018 13:47:50 +0900 Subject: [PATCH] KEYCLOAK-6771 Holder of Key mechanism OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens --- server_admin/topics/authentication/x509.adoc | 1 + server_admin/topics/clients/client-oidc.adoc | 31 ++++++++++++++++--- .../topics/threat/compromised-tokens.adoc | 2 ++ 3 files changed, 30 insertions(+), 4 deletions(-) diff --git a/server_admin/topics/authentication/x509.adoc b/server_admin/topics/authentication/x509.adoc index 176e5250fb..96bbbe33cf 100644 --- a/server_admin/topics/authentication/x509.adoc +++ b/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. diff --git a/server_admin/topics/clients/client-oidc.adoc b/server_admin/topics/clients/client-oidc.adoc index 9b5194a0f9..786852e8b1 100644 --- a/server_admin/topics/clients/client-oidc.adoc +++ b/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. diff --git a/server_admin/topics/threat/compromised-tokens.adoc b/server_admin/topics/threat/compromised-tokens.adoc index e1074a063b..944bf4fb30 100644 --- a/server_admin/topics/threat/compromised-tokens.adoc +++ b/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 <>.