155 lines
7.4 KiB
Text
155 lines
7.4 KiB
Text
|
|
=== 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 Grants Enabled*
|
|
|
|
If this is on, clients are allowed to use the OIDC <<_oidc-auth-flows,Direct 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 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. 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.
|
|
|
|
|
|
|
|
|
|
|