libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

KEYCLOAK-6771 Holder of Key mechanism

Browse source 
OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access
Tokens
This commit is contained in:
Takashi Norimatsu 2018-05-15 13:47:50 +09:00 committed by Marek Posolda
parent c143e2746b
commit b28335f7a0
3 changed files with 30 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
server_admin/topics/authentication/x509.adoc
View file

@ -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.

31
server_admin/topics/clients/client-oidc.adoc
View file

@ -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.

2
server_admin/topics/threat/compromised-tokens.adoc
View file

@ -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>>.