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

KEYCLOAK-15614 modularisation of 'Creating an Open ID Connect Client' (#14)

Browse source 
* More changes based on feedback

* Puts back 2 out of 3 screens
This commit is contained in:
Brian Dooley 2020-10-05 21:01:46 +01:00 committed by Marek Posolda
parent 09af683afb
commit f0d4fdd920
3 changed files with 88 additions and 126 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -5,130 +5,7 @@
<<_oidc,OpenID Connect>> is the preferred protocol to secure applications. It was designed from the ground up to be web friendly <<_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. 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. include::proc-creating-oidc-client.adoc[]
.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://datatracker.ietf.org/doc/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.
*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>>.
*OAuth 2.0 Device Authorization Grant Enabled*
If this is on, clients are allowed to use the OIDC <<_oidc-auth-flows,Device Authorization Grant>>.
*OpenID Connect Client Initiated Backchannel Authentication Grant Enabled*
If this is on, clients are allowed to use the OIDC <<_oidc-auth-flows,Client Initiated Backchannel Authentication Grant>>.
*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.
*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:https://fetch.spec.whatwg.org/[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!
*Backchannel Logout URL* *Backchannel Logout URL*
@ -225,6 +102,7 @@ ID token encryption algorithms by CEK are also defined in the https://datatracke
* open the client's `Settings` tab * open the client's `Settings` tab
* open `Fine Grain OpenID Connect Configuration` * open `Fine Grain OpenID Connect Configuration`
* select the algorithm from `ID Token Encryption Content Encryption Algorithm` pulldown menu * select the algorithm from `ID Token Encryption Content Encryption Algorithm` pulldown menu
<<<<<<< HEAD
[[_pushed_authorization_requests]] [[_pushed_authorization_requests]]
*OAuth 2.0 Pushed Authorization Requests* *OAuth 2.0 Pushed Authorization Requests*
@ -252,6 +130,8 @@ The latter can be set up on Realm Setting's Token tab per realm for determining
|Number that represents the lifetime of the request URI in minutes or hours, the default value is 1 minute. |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)

76
server_admin/topics/clients/proc-creating-oidc-client.adoc Normal file
View file

@ -0,0 +1,76 @@
[id="proc-creating-oidc-client_{context}"]
==== Creating an Open ID Connect Client
To use xref:_oidc[OpenID Connect], an existing application must be secured as an Open ID connect client.
.Procedure
. Click `Clients` in the left navigation pane.
+
. Click *Create* to go to the `Add Client` page.
+
.Add Client
image:{project_images}/add-client-oidc.png[Add Client]
. Enter the `Client ID` of the client.
. Select `openid-connect` in the `Client Protocol` drop down box.
. Enter the base URL of your application in the `Root URL` field.
. Click *Save*. This action creates the client and bring you to the `Settings`
tab.
+
.Client Settings
image:{project_images}/client-settings-oidc.png[Client Settings]
+
The following list describes each setting:
+
`Client ID`:: The alpha-numeric ID string that is used in OIDC requests and in the {project_name} database to identify the client.
`Name`:: The name for the client in {project_name} UI screen. To localize
the name, set up a replacement string value. For example, a string value such as $\{myapp}. See the link:{developerguide_link}[{developerguide_name}] for more information.
`Description`:: The description of the client. This setting can also be localized.
`Enabled`:: When turned off, the client cannot request authentication.
`Consent Required`:: When turned on, users see a consent page that they can use to grant access to that application. It will also display metadata so the user knows the exact information that the client can access.
`Access Type`:: The type of OIDC client.
+
* _Confidential_
For server-side clients that perform browser logins and require client secrets when making an Access Token Request. This setting should be used for server-side applications.
+
* _Public_
For client-side clients that perform browser logins. As it is not possible to ensure that secrets can be kept safe with client-side clients, it is important to restrict access by configuring correct redirect URIs.
+
* _Bearer-only_
The application allows only bearer token requests. When turned on, this application cannot participate in browser logins.
`Standard Flow Enabled`:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-authorization[Authorization Code Flow].
`Implicit Flow Enabled`:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-implicit[Implicit Flow].
`Direct Access Grants Enabled`:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-direct[Direct Access Grants].
`Root URL`:: This value adds a prefix to any configured URLS that {project_name} uses.
`Valid Redirect URIs`:: Required field. Enter a URL pattern and click *+* to add and *-* to remove existing URLs and click *Save*. You can use wildcards at the end of the URL pattern. For example $$http://host.com/*$$
+
Exclusive redirect URL patterns are typically more secure. See xref:_unspecific-redirect-uris [Threat Model Mitigation] chapter for more information.
`Base URL`:: This URL is used when {project_name} needs to link to the client.
`Admin URL`:: Callback endpoint for a client. The server uses this URL to make callbacks like pushing revocation policies, performing backchannel logout, and other administrative operations. For {project_name} servlet adapters, this URL can be the root URL of the servlet application.
For more information, see link:{adapterguide_link}[{adapterguide_name}].
`Web Origins`:: Enter a URL pattern and click *+* to add and *-* to remove existing URLs. Click *Save*.
+
This option handles link:https://fetch.spec.whatwg.org/[Cross-Origin Resource Sharing (CORS)].
If browser JavaScript attempts an AJAX HTTP request to a server whose domain is different from the one that the
JavaScript code came from, the request must use CORS. The server must handle CORS requests, otherwise the browser will not display or allow the request to be processed. This protocol protects against XSS, CSRF, and other JavaScript-based attacks.
+
Domain URLs listed here are embedded within the access token sent to the client application. The client application uses this information to decide whether to allow a CORS request to be invoked on it. Only {project_name} client adapters support this feature. See link:{adapterguide_link}[{adapterguide_name}] for more information.

6
server_admin/topics/sso-protocols/oidc.adoc
View file

@ -28,6 +28,8 @@ OIDC has different ways for a client or application to authenticate a user and r
path you use depends greatly on the type of application or client requesting access. All of these flows are described in the path you use depends greatly on the type of application or client requesting access. All of these flows are described in the
OIDC and OAuth 2.0 specifications so only a brief overview will be provided here. OIDC and OAuth 2.0 specifications so only a brief overview will be provided here.
[[_oidc-auth-flows-authorization]]
===== Authorization Code Flow ===== Authorization Code Flow
This is a browser-based protocol and it is what we recommend you use to authenticate and authorize browser-based applications. It makes This is a browser-based protocol and it is what we recommend you use to authenticate and authorize browser-based applications. It makes
@ -59,6 +61,8 @@ into this in the <<_clients, Managing Clients>> chapter.
{project_name} also supports the optional https://datatracker.ietf.org/doc/html/rfc7636[Proof Key for Code Exchange] specification. {project_name} also supports the optional https://datatracker.ietf.org/doc/html/rfc7636[Proof Key for Code Exchange] specification.
[[_oidc-auth-flows-implicit]]
===== Implicit Flow ===== Implicit Flow
This is a browser-based protocol that is similar to Authorization Code Flow except there are fewer requests and no refresh tokens involved. This is a browser-based protocol that is similar to Authorization Code Flow except there are fewer requests and no refresh tokens involved.
@ -75,6 +79,8 @@ Here's a brief summary of the protocol:
_access_ tokens as query parameters in the callback URL. _access_ tokens as query parameters in the callback URL.
. The application extracts the _identity_ and _access_ tokens from the callback URL. . The application extracts the _identity_ and _access_ tokens from the callback URL.
[[_oidc-auth-flows-direct]]
===== Resource Owner Password Credentials Grant (Direct Access Grants) ===== Resource Owner Password Credentials Grant (Direct Access Grants)
This is referred to in the Admin Console as _Direct Access Grants_. This is used by REST clients that want to obtain a token on behalf of a user. It is one HTTP POST request that contains This is referred to in the Admin Console as _Direct Access Grants_. This is used by REST clients that want to obtain a token on behalf of a user. It is one HTTP POST request that contains