keycloak-scim/server_admin/topics/clients/client-oidc.adoc

=== OIDC Clients

<<_oidc,OpenID Connect>> is the preferred protocol to secure applications.  It was designed from the ground up to be web friendly
and work best with HTML5/JavaScript applications.

To create an OIDC client go to the `Clients` left menu item.  On this page you'll see a `Create` button on the right.

.Clients
image:{project_images}/clients.png[]

This will bring you to the `Add Client` page.


.Add Client
image:{project_images}/add-client-oidc.png[]

Enter in the `Client ID` of the client.  This should be a simple
alpha-numeric string that will be used in requests and in the {project_name} database to identify the client.
Next select `openid-connect` in the `Client Protocol` drop down box.
Finally enter in the base URL of your
application in the `Root URL` field and click `Save`.  This will create the client and bring you to the client `Settings`
tab.

.Client Settings
image:{project_images}/client-settings-oidc.png[]

Let's walk through each configuration item on this page.

*Client ID*

This specifies an alpha-numeric string that will be used as the client identifier for OIDC requests.

*Name*

This is the display name for the client whenever it is displayed in a {project_name} UI screen.  You can localize
the value of this field by setting up a replacement string value i.e. $\{myapp}.  See the link:{developerguide_link}[{developerguide_name}]
for more information.

*Description*

This specifies the description of the client.  This can also be localized.

*Enabled*

If this is turned off, the client will not be allowed to request authentication.

*Consent Required*

If this is on, then users will get a consent page which asks the user if they grant access to that application.  It will also
display the metadata that the client is interested in so that the user knows exactly what information the client is getting access to.
If you've ever done a social login to Google, you'll often see a similar page.  {project_name} provides the same functionality.

[[_access-type]]
*Access Type*

This defines the type of the OIDC client.

_confidential_::
  Confidential access type is for server-side clients that need to perform a browser login and require a client secret when they turn an access code into an access token,
  (see https://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details). This type should be used for server-side applications.

_public_::
  Public access type is for client-side clients that need to perform a browser login. With a client-side application there is no way to keep a secret safe. Instead it is very important to restrict  access by configuring correct redirect URIs for the client.

_bearer-only_::
  Bearer-only access type means that the application only allows bearer token requests.
  If this is turned on, this application cannot participate in browser logins.

*Root URL*

If {project_name} uses any configured relative URLs, this value is prepended to them.

*Valid Redirect URIs*

This is a required field.  Enter in a URL pattern 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!
Wildcards (*) are only allowed at the end of a URI, i.e. $$http://host.com/*$$

You should take extra precautions when registering valid redirect URI patterns. If you make
them too general you are vulnerable to attacks.  See <<_unspecific-redirect-uris, Threat Model Mitigation>> chapter
for more information.

*Base URL*

If {project_name} needs to link to the client, this URL is used.

*Standard Flow Enabled*

If this is on, clients are allowed to use the OIDC <<_oidc-auth-flows,Authorization Code Flow>>.

*Implicit Flow Enabled*

If this is on, clients are allowed to use the OIDC <<_oidc-auth-flows,Implicit Flow>>.

*Direct Access Grants Enabled*

If this is on, clients are allowed to use the OIDC <<_oidc-auth-flows,Direct Access Grants>>.

*Admin URL*

For {project_name} specific client adapters, this is the callback endpoint for the client.  The {project_name}
server will use this URI to make callbacks like pushing revocation policies, performing backchannel logout, and other
administrative operations.  For {project_name} servlet adapters, this can be the root URL of the servlet application.
For more information see link:{adapterguide_link}[{adapterguide_name}].

*Web Origins*

This option centers around link:http://www.w3.org/TR/cors/[CORS] which stands for Cross-Origin Resource Sharing.
If browser JavaScript tries to make an AJAX HTTP request to a server whose domain is different from the one the
JavaScript code came from, then the request must use CORS.
The server must handle CORS requests in a special way, otherwise the browser will not display or allow the request to be processed.
This protocol exists to protect against XSS, CSRF and other JavaScript-based attacks.

{project_name} has support for validated CORS requests.  The way it works is that the domains listed in the
`Web Origins` setting for the client are embedded within the access token sent to the client application.  The client
application can then use this information to decide whether or not to allow a CORS request to be invoked on it.  This is
an extension to the OIDC protocol so only {project_name} client adapters support this feature.
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 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://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.

[[_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 keycloak'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://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 token according to https://tools.ietf.org/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://tools.ietf.org/html/rfc7517[Json Web Keys (JWK)] specification. The way to do so is defined in `Signed JWT` of <<_client-credentials, Confidential Client Credentials>>. The detailed procedure is as follows:

* open the client's `Credentials` tab
* select `Signed Jwt` from `Client Authenticator` pulldown menu
* set ON to `JWKS URL` switch
* input the client's public key providing URL on `JWKS URL` textbox

Key Encryption's algorithms are defined in https://tools.ietf.org/html/rfc7518#section-4.1[Json Web Algorithm (JWA)] specification. {project_name} supports RSAES-PKCS1-v1_5(RSA1_5) and RSAES OAEP using default parameters (RSA-OAEP). The detailed procedure to select this algorithm is as follows:

* open the client's `Settings` tab
* open `Advanced Settings`
* select `RSA1_5` or `RSA-OAEP` from `ID Token Encryption Key Management Algorithm` pulldown menu

ID token encryption algorithms by CEK are also defined in https://tools.ietf.org/html/rfc7518#section-5.1[JWA] specification. {project_name} supports AES_128_CBC_HMAC_SHA_256 authenticated encryption (A128CBC-HS256) and AES GCM using 128-bit key (A128GCM). The detailed procedure to select this algorithm is as follows:

* open the client's `Settings` tab
* open `Advanced Settings`
* select `A128CBC-HS256` or `A128GCM` from `ID Token Encryption Content Encryption Algorithm` pulldown menu