KEYCLOAK-15614 modularisation of 'Creating an Open ID Connect Client' (#14)
* More changes based on feedback * Puts back 2 out of 3 screens
This commit is contained in:
Brian Dooley
Marek Posolda
parent
09af683afb
commit
f0d4fdd920
3 changed files with 88 additions and 126 deletions
|
|
@ -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
|
||||
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://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!
|
||||
include::proc-creating-oidc-client.adoc[]
|
||||
|
||||
*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 `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*
|
||||
|
|
@ -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.
|
||||
|
||||
|===
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
=======
|
||||
>>>>>>> a65ad84d... KEYCLOAK-15614 modularisation of 'Creating an Open ID Connect Client' (#14)
|
||||
|
|
|
|||
76
server_admin/topics/clients/proc-creating-oidc-client.adoc
Normal file
76
server_admin/topics/clients/proc-creating-oidc-client.adoc
Normal 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.
|
||||
|
|
@ -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
|
||||
OIDC and OAuth 2.0 specifications so only a brief overview will be provided here.
|
||||
|
||||
[[_oidc-auth-flows-authorization]]
|
||||
|
||||
===== 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
|
||||
|
|
@ -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.
|
||||
|
||||
[[_oidc-auth-flows-implicit]]
|
||||
|
||||
===== 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.
|
||||
|
|
@ -75,6 +79,8 @@ Here's a brief summary of the protocol:
|
|||
_access_ tokens as query parameters in 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)
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue