From d75252ff3fa346e71360c17a68a8f891906a3181 Mon Sep 17 00:00:00 2001 From: Brian Dooley Date: Wed, 28 Oct 2020 20:25:47 +0000 Subject: [PATCH] rearranges assembly (#34) Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com> --- server_admin/topics/clients/client-oidc.adoc | 144 +++++++++++++++++- .../{ => oidc}/con-advanced-settings.adoc | 1 + .../con-confidential-client-credentials.adoc | 2 +- .../{ => oidc}/proc-creating-oidc-client.adoc | 1 + .../oidc/proc-using-a-service-account.adoc | 2 +- 5 files changed, 147 insertions(+), 3 deletions(-) rename server_admin/topics/clients/{ => oidc}/con-advanced-settings.adoc (99%) rename server_admin/topics/clients/{ => oidc}/proc-creating-oidc-client.adoc (99%) diff --git a/server_admin/topics/clients/client-oidc.adoc b/server_admin/topics/clients/client-oidc.adoc index e4fec56bc5..19ff3d97be 100644 --- a/server_admin/topics/clients/client-oidc.adoc +++ b/server_admin/topics/clients/client-oidc.adoc @@ -1,10 +1,152 @@ [[_oidc_clients]] === OIDC Clients - +[role="_abstract"] <<_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. +<<<<<<< HEAD include::proc-creating-oidc-client.adoc[] +<<<<<<< HEAD include::con-basic-settings.adoc include::con-advanced-settings.adoc[] +======= +======= +<<<<<<< HEAD +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. + +*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::oidc/proc-creating-oidc-client.adoc[] + +include::oidc/con-advanced-settings.adoc[] + +include::oidc/con-confidential-client-credentials.adoc[] + +include::oidc/proc-using-a-service-account.adoc[] +>>>>>>> rearranges assembly (#34) +>>>>>>> 91a8eb11... rearranges assembly (#34) + +include::oidc/audience.adoc[] +>>>>>>> ee237b2b... rearranges assembly (#34) diff --git a/server_admin/topics/clients/con-advanced-settings.adoc b/server_admin/topics/clients/oidc/con-advanced-settings.adoc similarity index 99% rename from server_admin/topics/clients/con-advanced-settings.adoc rename to server_admin/topics/clients/oidc/con-advanced-settings.adoc index deece8e2db..6b7f4f36f1 100644 --- a/server_admin/topics/clients/con-advanced-settings.adoc +++ b/server_admin/topics/clients/oidc/con-advanced-settings.adoc @@ -1,5 +1,6 @@ [id="con-advanced-settings_{context}"] ==== Advanced Settings +[role="_abstract"] When you click _Advanced Settings_, additional fields are displayed. [[_mtls-client-certificate-bound-tokens]] diff --git a/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc b/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc index c80aa535fe..4264308aa6 100644 --- a/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc +++ b/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc @@ -3,7 +3,7 @@ [[_client-credentials]] ==== Confidential Client Credentials - +[role="_abstract"] If the <<_access-type, access type>> of the client is set to `confidential`, the credentials of the client must be configured under the `Credentials` tab. .Credentials Tab diff --git a/server_admin/topics/clients/proc-creating-oidc-client.adoc b/server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc similarity index 99% rename from server_admin/topics/clients/proc-creating-oidc-client.adoc rename to server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc index 78925a5434..68a8a4335e 100644 --- a/server_admin/topics/clients/proc-creating-oidc-client.adoc +++ b/server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc @@ -1,5 +1,6 @@ [id="proc-creating-oidc-client_{context}"] ==== Creating an Open ID Connect Client +[role="_abstract"] To use xref:_oidc[OpenID Connect], an existing application must be secured as an Open ID connect client. .Procedure diff --git a/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc b/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc index 7bbfa31a46..7bd35172e5 100644 --- a/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc +++ b/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc @@ -1,7 +1,7 @@ [[_service_accounts]] ==== Using a Service Account - +[role="_abstract"] Each OIDC client has a built-in _service account_, which allows it to obtain an access token. .Prerequisites