111 lines
No EOL
6.3 KiB
Text
111 lines
No EOL
6.3 KiB
Text
[id="con-advanced-settings_{context}"]
|
|
= Advanced settings
|
|
[role="_abstract"]
|
|
When you click _Advanced Settings_, additional fields are displayed.
|
|
|
|
[[_mtls-client-certificate-bound-tokens]]
|
|
*OAuth 2.0 Mutual TLS Certificate Bound Access Tokens Enabled*
|
|
|
|
ifeval::["{kc_dist}" == "wildfly"]
|
|
[NOTE]
|
|
====
|
|
To enable mutual TLS in {project_name}, see <<_enable-mtls-wildfly, Enable mutual SSL in WildFly>>.
|
|
====
|
|
endif::[]
|
|
|
|
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://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.
|
|
|
|
[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://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 tokens according to the https://datatracker.ietf.org/doc/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://datatracker.ietf.org/doc/html/rfc7517[Json Web Keys (JWK)] specification.
|
|
|
|
The procedure is:
|
|
|
|
. Open the client's *Keys* tab.
|
|
. Toggle *JWKS URL* to ON.
|
|
. Input the client's public key URL in the *JWKS URL* 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)
|
|
* 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.
|
|
|
|
[[_mapping-acr-to-loa-client]]
|
|
*ACR to Level of Authentication (LoA) Mapping*
|
|
|
|
In the advanced settings of a client, you can define which `Authentication Context Class Reference (ACR)` value is mapped to which `Level of Authentication (LoA)`.
|
|
This mapping can be specified also at the realm as mentioned in the <<_mapping-acr-to-loa-realm,ACR to LoA Mapping>>. A best practice is to configure this mapping at the
|
|
realm level, which allows to share the same settings across multiple clients.
|
|
|
|
The `Default ACR Values` can be used to specify the default values when the login request is sent from this client to {project_name} without `acr_values` parameter and without
|
|
a `claims` parameter that has an `acr` claim attached. See https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata[offical OIDC dynamic client registration specification].
|
|
|
|
WARNING: Note that default ACR values are used as the default level, however it cannot be reliably used to enforce login with the particular level.
|
|
For example, assume that you configure the `Default ACR Values` to level 2. Then by default, users will be required to authenticate with level 2.
|
|
However when the user explicitly attaches the parameter into login request such as `acr_values=1`, then the level 1 will be used. As a result, if the client
|
|
really requires level 2, the client is encouraged to check the presence of the `acr` claim inside ID Token and doublecheck that it contains the requested level 2.
|
|
|
|
image:{project_images}/client-oidc-map-acr-to-loa.png[alt="ACR to LoA mapping"]
|
|
|
|
For further details see <<_step-up-flow,Step-up Authentication>> and https://openid.net/specs/openid-connect-core-1_0.html#acrSemantics[the offical OIDC specification]. |