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

Keycloak 15786 (#16)

Browse source 
* rebase corrections

* post feedback changes
This commit is contained in:
Brian Dooley 2020-10-12 21:04:31 +01:00 committed by Marek Posolda
parent a04a2a28fd
commit 06b791e17e
2 changed files with 92 additions and 129 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -6,132 +6,5 @@
and work best with HTML5/JavaScript applications.
include::proc-creating-oidc-client.adoc[]
*Backchannel Logout URL*
When {project_name} receives a logout request via `end_session_endpoint` it will post a backchannel logout request at this URL like described in the
https://openid.net/specs/openid-connect-backchannel-1_0.html[OpenID Connect specification].
This causes the client to log itself out.
*Backchannel Logout Session Required*
If enabled, the session id is included in the logout token when a backchannel logout request is sent.
This results in only logging out a specific session. If disabled, all sessions of the corresponding
user will be logged out.
*Backchannel Logout Revoke Offline Sessions*
If enabled, a `revoke_offline_access` event is added to the logout token. This should result in also logging out offline
sessions with a backchannel logout request. This event is not specified by the https://openid.net/specs/openid-connect-backchannel-1_0.html[OpenID Connect specification]
and may have to change in the future. Keycloak itself will respect the `revoke_offline_access` in a logout token when receiving
a backchannel logout request.
==== Advanced Settings
[[_mtls-client-certificate-bound-tokens]]
*OAuth 2.0 Mutual TLS Certificate Bound Access Tokens Enabled*
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. This 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://datatracker.ietf.org/doc/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.
[[_proof-key-for-code-exchange]]
*Proof Key for Code Exchange (PKCE)*
When an attacker steals an authorization code that was issued to a legitimate client, PKCE prevents the attacker from receiving the tokens that apply to that code.
The administrator can select the following three options:
*Proof Key for Code Exchange Code Challenge Method*
* (blank) : {project_name} does not apply PKCE unless the client sends PKCE's parameters appropriately to {project_name}'s authorization endpoint. It is the default setting.
* S256 : {project_name} applies to the client PKCE whose code challenge method is S256.
* plain : {project_name} applies to the client PKCE whose code challenge method is plain.
Please see https://datatracker.ietf.org/doc/html/rfc7636[RFC 7636 Proof Key for Code Exchange by OAuth Public Clients] for more details.
[[_jwe-id-token-encryption]]
*Signed and Encrypted ID Token Support*
{project_name} can encrypt ID token according to the https://datatracker.ietf.org/doc/html/rfc7516[Json Web Encryption (JWE)] specification. The administrator can determine whether encrypting ID token or not per client. This feature is disabled as default.
The key for encrypting ID token is called Content Encryption Key (CEK). {project_name} and a client need to negotiate which CEK is used and how to deliver it. The way to do so is called Key Management Mode.
JWE specification determines 5 types of Key Management Mode. {project_name} supports Key Encryption among them.
In Key Encryption, the client generates a key pair of asymmetric cryptography. The public key is used to encrypt CEK. {project_name} generates CEK per ID token, encrypts the ID token by this generated CEK and encrypts this CEK by this client's public key. The client decrypts this encrypted CEK by their private key, and decrypt the ID token by decrypted CEK. Therefore, any party other than the client is not able to decrypt ID token.
The client needs to pass their public key for encrypting CEK onto {project_name}. {project_name} supports downloading public keys from the URL the client provides. The client needs to provide their public keys according to https://datatracker.ietf.org/doc/html/rfc7517[Json Web Keys (JWK)] specification. The detailed procedure is as follows:
* open the client's `Keys` tab
* toggle `Use JWKS URL` to ON
* input the client's public key providing URL on `JWKS URL` textbox
{project_name} also supports inputting JWKS directly. The detailed procedure is as follows:
* open the client's `Keys` tab
* toggle `Use JWKS` to ON
* input the client's JWKS on `JWKS` textbox
Key Encryption's algorithms are defined in the https://datatracker.ietf.org/doc/html/rfc7518#section-4.1[Json Web Algorithm (JWA)] specification. {project_name} supports RSAES-PKCS1-v1_5(RSA1_5), RSAES OAEP using default parameters (RSA-OAEP), and RSAES OAEP 256 using SHA-256 and MFG1 (RSA-OAEP-256). The detailed procedure to select this algorithm is as follows:
* open the client's `Settings` tab
* open `Fine Grain OpenID Connect Configuration`
* select `RSA1_5`, `RSA-OAEP`, or `RSA-OAEP-256` from `ID Token Encryption Key Management Algorithm` pulldown menu
ID token encryption algorithms by CEK are also defined in the https://datatracker.ietf.org/doc/html/rfc7518#section-5.1[JWA] specification. {project_name} supports AES_CBC_HMAC_SHA2 algorithms and AES GCM algorithms. The detailed procedure to select this algorithm is as follows:
* open the client's `Settings` tab
* open `Fine Grain OpenID Connect Configuration`
* select the algorithm from `ID Token Encryption Content Encryption Algorithm` pulldown menu
<<<<<<< HEAD
[[_pushed_authorization_requests]]
*OAuth 2.0 Pushed Authorization Requests*
Basic features of https://datatracker.ietf.org/doc/html/draft-ietf-oauth-par[OAuth 2.0 Pushed Authorization Requests] has been supported.
For more details about PAR, see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-par[PAR Specification].
There are two configuration parameters. The former can be set up on Advanced Settings per client for activating and deactivating PAR.
|===
|Configuration|Description
|Pushed Authorization Request Enabled
|Boolean parameter indicating whether the authorization server accepts authorization request data only via the pushed authorization request method.
|===
The latter can be set up on Realm Setting's Token tab per realm for determining lifetime of PAR's Request URI.
|===
|Configuration|Description
|Lifetime of the Request URI for Pushed Authorization Request
|Number that represents the lifetime of the request URI in minutes or hours, the default value is 1 minute.
|===
=======
>>>>>>> a65ad84d... KEYCLOAK-15614 modularisation of 'Creating an Open ID Connect Client' (#14)
include::con-basic-settings.adoc
include::con-advanced-settings.adoc[]

90
server_admin/topics/clients/con-advanced-settings.adoc Normal file
View file

@ -0,0 +1,90 @@
[id="con-advanced-settings_{context}"]
==== Advanced Settings
When you click _Advanced Settings_, additional fields are displayed.
[[_mtls-client-certificate-bound-tokens]]
*OAuth 2.0 Mutual TLS Certificate Bound Access Tokens Enabled*
[NOTE]
====
To enable mutual TLS in {project_name}, see <<_enable-mtls-wildfly, Enable mutual SSL in WildFly>>.
====
Mutual TLS binds an access token and a refresh token together with a client certificate, which is exchanged during a TLS handshake. This binding prevents an attacker from using stolen tokens.
This type of token is a holder-of-key token. Unlike bearer tokens, the recipient of a holder-of-key token can verify if the sender of the token is legitimate.
If this setting is on, the workflow is:
. A token request is sent to the token endpoint in an authorization code flow or hybrid flow.
. {project_name} requests a client certificate.
. {project_name} receives the client certificate.
. {project_name} successfully verifies the client certificate.
If verification fails, {project_name} rejects the token.
In the following cases, {project_name} will verify the client sending the access token or the refresh 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.
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.
[NOTE]
====
Currently, {project_name} client adapters do not support holder-of-key token verification. {project_name} adapters treat access and refresh tokens as bearer tokens.
====
[[_proof-key-for-code-exchange]]
*Proof Key for Code Exchange Code Challenge Method*
If an attacker steals an authorization code of a legitimate client, Proof Key for Code Exchange (PKCE) prevents the attacker from receiving the tokens that apply to the code.
An administrator can select one of these options:
`(blank)`:: {project_name} does not apply PKCE unless the client sends appropriate PKCE parameters to {project_name}s authorization endpoint.
`S256`:: {project_name} applies to the client PKCE whose code challenge method is S256.
`plain`:: {project_name} applies to the client PKCE whose code challenge method is plain.
See https://tools.ietf.org/html/rfc7636[RFC 7636 Proof Key for Code Exchange by OAuth Public Clients] for more details.
[[_jwe-id-token-encryption]]
*Signed and Encrypted ID Token Support*
{project_name} can encrypt ID tokens according to the https://tools.ietf.org/html/rfc7516[Json Web Encryption (JWE)] specification. The administrator determines if ID tokens are encrypted for each client.
The key used for encrypting the ID token is the Content Encryption Key (CEK). {project_name} and a client must negotiate which CEK is used and how it is delivered. The method used to determine the CEK is the Key Management Mode. The Key Management Mode that {project_name} supports is Key Encryption.
In Key Encryption:
. The client generates an asymmetric cryptographic key pair.
. The public key is used to encrypt the CEK.
. {project_name} generates a CEK per ID token
. {project_name} encrypts the ID token using this generated CEK
. {project_name} encrypts the CEK using the client's public key.
. The client decrypts this encrypted CEK using their private key
. The client decrypts the ID token using the decrypted CEK.
No party, other than the client, can decrypt the ID token.
The client must pass its public key for encrypting CEK to {project_name}. {project_name} supports downloading public keys from a URL provided by the client. The client must provide public keys according to the https://tools.ietf.org/html/rfc7517[Json Web Keys (JWK)] specification.
The procedure is:
. Open the client's `Credentials` tab.
. Select `Signed Jwt` from the `Client Authenticator` menu.
. Set the `JWKS URL` switch to ON.
. Input the client's public key URL in the `JWKS URL` textbox.
Key Encryption's algorithms are defined in the https://tools.ietf.org/html/rfc7518#section-4.1[Json Web Algorithm (JWA)] specification. {project_name} supports:
* RSAES-PKCS1-v1_5(RSA1_5)
* RSAES OAEP using default parameters (RSA-OAEP)
* RSAES OAEP 256 using SHA-256 and MFG1 (RSA-OAEP-256)
The procedure to select the algorithm is:
. Open the client's `Settings` tab.
. Open `Fine Grain OpenID Connect Configuration`.
. Select the algorithm from `ID Token Encryption Content Encryption Algorithm` pulldown menu.