diff --git a/header-maven-plugin/src/main/java/sample/plugin/HeaderMojo.java b/header-maven-plugin/src/main/java/sample/plugin/HeaderMojo.java index 1e9cdf64d8..aa5dc0a1d7 100644 --- a/header-maven-plugin/src/main/java/sample/plugin/HeaderMojo.java +++ b/header-maven-plugin/src/main/java/sample/plugin/HeaderMojo.java @@ -114,7 +114,7 @@ public class HeaderMojo extends AbstractMojo { try(PrintStream ps = new PrintStream(new FileOutputStream(out));BufferedReader br = new BufferedReader(new FileReader(f));){ for (String l = br.readLine(); l != null; l = br.readLine()) { ps.println(l); - if (l.contains("=")) { + if (l.startsWith("=")) { break; } } diff --git a/openshift/topics/get_started.adoc b/openshift/topics/get_started.adoc index c52901c545..0f4a0fbe65 100644 --- a/openshift/topics/get_started.adoc +++ b/openshift/topics/get_started.adoc @@ -5,7 +5,7 @@ [IMPORTANT] ==== -Red Hat JBoss Middleware for OpenShift images are pulled on demand from the secured Red Hat Registry: link:https://access.redhat.com/containers/[registry.redhat.io], which requires authentication. To retrieve content, you will need to log into the registry using the Red Hat account. +Red Hat JBoss Middleware for OpenShift images are pulled on demand from the secured Red Hat Registry: link:https://catalog.redhat.com[registry.redhat.io], which requires authentication. To retrieve content, you will need to log into the registry using the Red Hat account. To consume container images from *_registry.redhat.io_* in shared environments such as OpenShift, it is recommended for an administrator to use a Registry Service Account, also referred to as authentication tokens, in place of an individual person's Red Hat Customer Portal credentials. @@ -37,7 +37,7 @@ $ oc login -u system:admin ---- $ oc login -u kubeadmin -p password \https://openshift.example.com:6443 ---- - + . Run the following commands to update the core set of {project_name} {project_version} resources for OpenShift in the `openshift` project: + [source,bash,subs="attributes+,macros+"] diff --git a/release-details b/release-details index 525b9d5e20..791d78ebfc 100644 --- a/release-details +++ b/release-details @@ -1,3 +1,3 @@ -VERSION=15.0.1 +VERSION=15.0.2 SHORT_VERSION=15.0 -NPM_VERSION=15.0.1 +NPM_VERSION=15.0.2 diff --git a/securing_apps/topics/oidc/java/jetty9-adapter.adoc b/securing_apps/topics/oidc/java/jetty9-adapter.adoc index 27265b0cbd..bb5b90ea79 100644 --- a/securing_apps/topics/oidc/java/jetty9-adapter.adoc +++ b/securing_apps/topics/oidc/java/jetty9-adapter.adoc @@ -12,7 +12,7 @@ Let's go over these steps. Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak download site. They are also available as a maven artifact. -You must unzip the Jetty 9.x distro into Jetty 9.x's link:https://www.eclipse.org/jetty/documentation/current/#quickstart-common-config[base directory]. +You must unzip the Jetty 9.x distro into Jetty 9.x's link:https://www.eclipse.org/jetty/documentation/jetty-9/index.html[base directory]. Including adapter's jars within your WEB-INF/lib directory will not work! In the example below, the Jetty base is named `your-base`: diff --git a/securing_apps/topics/oidc/java/spring-security-adapter.adoc b/securing_apps/topics/oidc/java/spring-security-adapter.adoc index 5e814eaa72..dfb92474c0 100644 --- a/securing_apps/topics/oidc/java/spring-security-adapter.adoc +++ b/securing_apps/topics/oidc/java/spring-security-adapter.adoc @@ -167,11 +167,7 @@ While Spring Security's XML namespace simplifies configuration, customizing the -<<<<<<< HEAD -======= - ->>>>>>> correction to themes diff --git a/securing_apps/topics/overview/basic-steps.adoc b/securing_apps/topics/overview/basic-steps.adoc deleted file mode 100644 index 5d4fb40aec..0000000000 --- a/securing_apps/topics/overview/basic-steps.adoc +++ /dev/null @@ -1,23 +0,0 @@ -=== Basic steps to secure applications and services - -These are the basic steps for setting up an application or a service in Keycloak. - -Configure a client adapter using one of these options: - -* A {project_name} adapter - -* A third party library adapter - -Register a client using one of these options: - -* The Admin Console - -* The client registration service - -* The CLI - -[role="_additional-resources"] -.Additional resources - -This guide provide the detailed instructions for these steps. Additional information on using the Admin Console exists in the Server Administration Guide. That guide refers to creating a client rather than registering a client. - diff --git a/securing_apps/topics/overview/basic-steps.adoc~ b/securing_apps/topics/overview/basic-steps.adoc~ deleted file mode 100644 index 4167e087f8..0000000000 --- a/securing_apps/topics/overview/basic-steps.adoc~ +++ /dev/null @@ -1,21 +0,0 @@ -These are the basic steps for setting up an application or a service in Keycloak. - -Configure a client adapter using one of these options: - -* A {project_name} adapter - -* A third party library adapter - -Register a client using one of these options: - -* The Admin Console - -* The client registration service - -* The CLI - -[role="_additional-resources"] -== Additional resources - -This guide provide the detailed instructions for these steps. Additional information on using the Admin Console exists in the Server Administration Guide. That guide refers to creating a client rather than registering a client. - diff --git a/securing_apps/topics/overview/terminology.adoc b/securing_apps/topics/overview/terminology.adoc deleted file mode 100644 index 8429e1db2b..0000000000 --- a/securing_apps/topics/overview/terminology.adoc +++ /dev/null @@ -1,13 +0,0 @@ -=== Terminology - -These terms are used in this guide: - -* `Clients` are entities that can request Keycloak to authenticate a user. Most often, clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution. Clients can also be entities that just want to request identity information or an access token so that they can securely invoke other services on the network that are secured by Keycloak. - -* `Applications` include a wide range of applications that work for specific platforms for each protocol - -* A `service account` is built-in account that exists for each client. The client uses this account to obtain an access token. - -* `Client adapters` are libraries that make it very easy to secure applications and services with Keycloak. We call them adapters rather than libraries as they provide a tight integration to the underlying platform and framework. This makes our adapters easy to use and they require less boilerplate code than what is typically required by a library. - -* `Creating a client` and `registering a client` are the same action. The Admin Console includes a Create Client option which performs the same action that is performed by using the Client Registration Services. \ No newline at end of file diff --git a/server_admin/keycloak-images/sessions.png b/server_admin/keycloak-images/sessions.png index b45bcd202e..f5e74b6f7b 100644 Binary files a/server_admin/keycloak-images/sessions.png and b/server_admin/keycloak-images/sessions.png differ diff --git a/server_admin/master-docinfo.xml b/server_admin/master-docinfo.xml index 5ac17232e2..5d1b3dc317 100644 --- a/server_admin/master-docinfo.xml +++ b/server_admin/master-docinfo.xml @@ -10,7 +10,7 @@ Red Hat Customer Content Services - Copyright 2019 Red Hat, Inc. + Copyright 2021 Red Hat, Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at diff --git a/server_admin/rhsso-images/client-oidc-keys.png b/server_admin/rhsso-images/client-oidc-keys.png deleted file mode 100644 index b94e9fca88..0000000000 Binary files a/server_admin/rhsso-images/client-oidc-keys.png and /dev/null differ diff --git a/server_admin/rhsso-images/sessions.png b/server_admin/rhsso-images/sessions.png index b45bcd202e..f5e74b6f7b 100644 Binary files a/server_admin/rhsso-images/sessions.png and b/server_admin/rhsso-images/sessions.png differ diff --git a/server_admin/topics.adoc b/server_admin/topics.adoc index a5211cb2d0..1146869803 100644 --- a/server_admin/topics.adoc +++ b/server_admin/topics.adoc @@ -54,11 +54,11 @@ include::topics/identity-broker/session-data.adoc[] include::topics/identity-broker/first-login-flow.adoc[] include::topics/identity-broker/tokens.adoc[] include::topics/identity-broker/logout.adoc[] +include::topics/sso-protocols.adoc[] include::topics/admin-console-permissions.adoc[] include::topics/admin-console-permissions/master-realm.adoc[] include::topics/admin-console-permissions/per-realm.adoc[] include::topics/admin-console-permissions/fine-grain.adoc[] -include::topics/sso-protocols.adoc[] include::topics/assembly-managing-clients.adoc[] include::topics/vault.adoc[] include::topics/events.adoc[] @@ -74,12 +74,14 @@ include::topics/threat/clickjacking.adoc[] include::topics/threat/ssl.adoc[] include::topics/threat/csrf.adoc[] include::topics/threat/redirect.adoc[] +include::topics/threat/fapi-compliance.adoc[] include::topics/threat/compromised-tokens.adoc[] include::topics/threat/compromised-codes.adoc[] include::topics/threat/open-redirect.adoc[] include::topics/threat/password-db-compromised.adoc[] include::topics/threat/scope.adoc[] include::topics/threat/audience-limit.adoc[] +include::topics/threat/auth-sessions-limit.adoc[] include::topics/threat/sql.adoc[] include::topics/account.adoc[] include::topics/admin-cli.adoc[] diff --git a/server_admin/topics/admin-console-permissions/fine-grain.adoc b/server_admin/topics/admin-console-permissions/fine-grain.adoc index c5c0fe0b4f..6dc92dea43 100644 --- a/server_admin/topics/admin-console-permissions/fine-grain.adoc +++ b/server_admin/topics/admin-console-permissions/fine-grain.adoc @@ -1,6 +1,6 @@ [[_fine_grain_permissions]] -=== Fine Grain Admin Permissions +=== Fine grain admin permissions :tech_feature_name: Fine Grain Admin Permissions :tech_feature_setting: -Dkeycloak.profile.feature.admin_fine_grained_authz=enabled @@ -27,7 +27,7 @@ There are some important things to note about fine grain admin permissions: * Fine grain permissions are used to grant additional permissions. You cannot override the default behavior of the built in admin roles. -==== Managing One Specific Client +==== Managing one specific client Let's look first at allowing an admin to manage one client and one client only. In our example, we have a realm @@ -36,17 +36,17 @@ user in that realm permission to only manage that application. IMPORTANT: You cannot do cross realm fine grain permissions. Admins in the `master` realm are limited to the predefined admin roles defined in previous chapters. -===== Permission Setup +===== Permission setup The first thing we must do is login to the Admin Console so we can set up permissions for that client. We navigate to the management section of the client, we want to define fine-grain permissions for. -.Client Management +.Client management image:{project_images}/fine-grain-client.png[] You should see a tab menu item called `Permissions`. Click on that tab. -.Client Permissions Tab +.Client permissions tab image:{project_images}/fine-grain-client-permissions-tab-off.png[] By default, each client is not enabled to do fine grain permissions. So turn the `Permissions Enabled` switch to on @@ -54,7 +54,7 @@ to initialize permissions. IMPORTANT: If you turn the `Permissions Enabled` switch to off, it will delete any and all permissions you have defined for this client. -.Client Permissions Tab +.Client permissions tab image:{project_images}/fine-grain-client-permissions-tab-on.png[] When you switch `Permissions Enabled` to on, it initializes various permission objects behind the scenes @@ -63,7 +63,7 @@ interested in the `manage` permission for the client. Clicking on that will red to the permission that handles the `manage` permission for the client. All authorization objects are contained in the `realm-management` client's `Authorization` tab. -.Client Manage Permission +.Client manage permission image:{project_images}/fine-grain-client-manage-permissions.png[] When first initialized the `manage` permission does not have any policies associated with it. @@ -74,13 +74,13 @@ There's a pull down menu on this page called `Create policy`. There's a multitu you can define. You can define a policy that is associated with a role or a group or even define rules in JavaScript. For this simple example, we're going to create a `User Policy`. -.User Policy +.User policy image:{project_images}/fine-grain-client-user-policy.png[] This policy will match a hard-coded user in the user database. In this case, it is the `sales-admin` user. We must then go back to the `sales-application` client's `manage` permission page and assign the policy to the permission object. -.Assign User Policy +.Assign user policy image:{project_images}/fine-grain-client-assign-user-policy.png[] The `sales-admin` user can now has permission to manage the `sales-application` client. @@ -98,17 +98,17 @@ role tells the Admin Console that it should render client menus for the `sales-a IMPORTANT If you do not set the `query-clients` role, restricted admins like `sales-admin` will not see any menu options when they log into the Admin Console -===== Testing It Out. +===== Testing it out Next, we log out of the master realm and re-login to the <<_per_realm_admin_permissions, dedicated admin console>> for the `test` realm using the `sales-admin` as a username. This is located under `/auth/admin/test/console`. -.Sales Admin Login +.Sales admin login image:{project_images}/fine-grain-sales-admin-login.png[] This admin is now able to manage this one client. -==== Restrict User Role Mapping +==== Restrict user role mapping Another thing you might want to do is to restrict the set of roles an admin is allowed to assign to a user. Continuing our last example, let's expand the permission set of the 'sales-admin' @@ -119,26 +119,26 @@ and not perform any other types of user administration. The `sales-application` has defined three different client roles. -.Sales Application Roles +.Sales application roles image:{project_images}/fine-grain-sales-application-roles.png[] We want the `sales-admin` user to be able to map these roles to any user in the system. The first step to do this is to allow the role to be mapped by the admin. If we click on the `viewLeads` role, you'll see that there is a `Permissions` tab for this role. -.View Leads Role Permission Tab +.View leads role permission tab image:{project_images}/fine-grain-view-leads-role-tab.png[] If we click on that tab and turn the `Permissions Enabled` on, you'll see that there are a number of actions we can apply policies to. -.View Leads Permissions +.View leads permissions image:{project_images}/fine-grain-view-leads-permissions.png[] The one we are interested in is `map-role`. Click on this permission and add the same User Policy that was created in the earlier example. -.Map-roles Permission +.Map-roles permission image:{project_images}/fine-grain-map-roles-permission.png[] What we've done is say that the `sales-admin` can map the `viewLeads` role. What we have @@ -147,7 +147,7 @@ we must go to the `Users` section of the admin console for this realm. Clicking `Users` left menu item brings us to the users interface of the realm. You should see a `Permissions` tab. Click on that and enable it. -.Users Permissions +.Users permissions image:{project_images}/fine-grain-users-permissions.png[] The permission we are interested in is `map-roles`. This is a restrictive policy @@ -162,7 +162,7 @@ allow the admin to view users in the realm he wants to add the `sales-applicatio image:{project_images}/fine-grain-add-view-users.png[] -===== Testing It Out. +===== Testing it out Next, we log out of the master realm and re-login to the <<_per_realm_admin_permissions, dedicated admin console>> for the `test` realm using the `sales-admin` as a username. This is located under `/auth/admin/test/console`. @@ -172,25 +172,25 @@ users you'll see that each user detail page is read only, except for the `Role M Going to this tab you'll find that there are no `Available` roles for the admin to map to the user except when we browse the `sales-application` roles. -.Add viewLeads +.Add viewleads image:{project_images}/fine-grain-add-view-leads.png[] We've only specified that the `sales-admin` can map the `viewLeads` role. -===== Per Client map-roles Shortcut +===== Per client map-roles shortcut It would be tedious if we had to do this for every client role that the `sales-application` published. to make things easier, there's a way to specify that an admin can map any role defined by a client. If we log back into the admin console to our master realm admin and go back to the `sales-application` permissions page, you'll see the `map-roles` permission. -.Client map-roles Permission +.Client map-roles permission image:{project_images}/fine-grain-client-permissions-tab-on.png[] If you grant access to this particular permission to an admin, that admin will be able map any role defined by the client. -==== Full List of Permissions +==== Full list of permissions You can do a lot more with fine grain permissions beyond managing a specific client or the specific roles of a client. This chapter defines the whole list of permission types that can be described for diff --git a/server_admin/topics/admin-console-permissions/master-realm.adoc b/server_admin/topics/admin-console-permissions/master-realm.adoc index 95a561f659..c9848adb76 100644 --- a/server_admin/topics/admin-console-permissions/master-realm.adoc +++ b/server_admin/topics/admin-console-permissions/master-realm.adoc @@ -1,5 +1,5 @@ -=== Master Realm Access Control +=== Master realm access control The `master` realm in {project_name} is a special realm and treated differently than other realms. Users in the {project_name} `master` realm can be granted permission to manage zero or more realms that are deployed on the {project_name} server. @@ -7,7 +7,7 @@ When a realm is created, {project_name} automatically creates various roles that Access to The Admin Console and Admin REST endpoints can be controlled by mapping these roles to users in the `master` realm. It's possible to create multiple super users, as well as users that can only manage specific realms. -==== Global Roles +==== Global roles There are two realm-level roles in the `master` realm. These are: @@ -18,7 +18,7 @@ These are: Users with the `admin` role are super users and have full access to manage any realm on the server. Users with the `create-realm` role are allowed to create new realms. They will be granted full access to any new realm they create. -==== Realm Specific Roles +==== Realm specific roles Admin users within the `master` realm can be granted management privileges to one or more other realms in the system. Each realm in {project_name} is represented by a client in the `master` realm. diff --git a/server_admin/topics/admin-console-permissions/per-realm.adoc b/server_admin/topics/admin-console-permissions/per-realm.adoc index 2b97d875df..bc3883bf24 100644 --- a/server_admin/topics/admin-console-permissions/per-realm.adoc +++ b/server_admin/topics/admin-console-permissions/per-realm.adoc @@ -1,6 +1,6 @@ [[_per_realm_admin_permissions]] -=== Dedicated Realm Admin Consoles +=== Dedicated realm admin consoles Each realm has a dedicated Admin Console that can be accessed by going to the url `/auth/admin/{realm-name}/console`. Users within that realm can be granted realm management permissions by assigning specific user role mappings. diff --git a/server_admin/topics/assembly-managing-clients.adoc b/server_admin/topics/assembly-managing-clients.adoc index 31d17ae912..1196e9fe4c 100644 --- a/server_admin/topics/assembly-managing-clients.adoc +++ b/server_admin/topics/assembly-managing-clients.adoc @@ -17,3 +17,4 @@ include::clients/con-client-links.adoc[leveloffset=+2] include::clients/con-protocol-mappers.adoc[leveloffset=+2] include::clients/proc-generating-client-adapter-config.adoc[leveloffset=+2] include::clients/con-client-scopes.adoc[leveloffset=+2] +include::clients/client-policies.adoc[leveloffset=+2] diff --git a/server_admin/topics/assembly-managing-users.adoc b/server_admin/topics/assembly-managing-users.adoc index 794ac80efb..86a2b9ae0b 100644 --- a/server_admin/topics/assembly-managing-users.adoc +++ b/server_admin/topics/assembly-managing-users.adoc @@ -28,4 +28,5 @@ include::users/proc-registering-new-user.adoc[leveloffset=3] include::users/proc-enabling-recaptcha.adoc[leveloffset=+2] include::users/ref-personal-data-collected.adoc[leveloffset=+2] +include::users/user-profile.adoc[leveloffset=+2] diff --git a/server_admin/topics/authentication.adoc b/server_admin/topics/authentication.adoc index b46b46bd49..0464ad2263 100644 --- a/server_admin/topics/authentication.adoc +++ b/server_admin/topics/authentication.adoc @@ -1,5 +1,5 @@ -== Configuring Authentication +== Configuring authentication This chapter covers several authentication topics. These topics include: diff --git a/server_admin/topics/authentication/clients/client-oidc.adoc b/server_admin/topics/authentication/clients/client-oidc.adoc deleted file mode 100644 index 7ad53563c6..0000000000 --- a/server_admin/topics/authentication/clients/client-oidc.adoc +++ /dev/null @@ -1,14 +0,0 @@ - -[[_oidc_clients]] -=== OIDC Clients -[role="_abstract"] -xref:con-oidc_{context}[OpenID Connect] is the recommended protocol to secure applications. It was designed from the ground up to be web friendly and it works best with HTML5/JavaScript applications. - -include::proc-creating-oidc-client.adoc[] -include::con-basic-settings.adoc[] -include::con-advanced-settings.adoc[] -======= ->>>>>>> ee3211e6... applying indentation using leveloffsets - ->>>>>>> 25f32ee4... applying indentation using leveloffsets -include::oidc/con-audience.adoc[] diff --git a/server_admin/topics/authentication/clients/client-saml.adoc b/server_admin/topics/authentication/clients/client-saml.adoc deleted file mode 100644 index 5a197080cd..0000000000 --- a/server_admin/topics/authentication/clients/client-saml.adoc +++ /dev/null @@ -1,129 +0,0 @@ -[[_client-saml-configuration]] -=== SAML Clients - -{project_name} supports <<_saml,SAML 2.0>> for registered applications. -POST and Redirect bindings are supported. You can choose to require client signature validation. You can have the server sign and/or encrypt responses as well. - -.Procedure -. Click `Clients` in the left navigation pane. - -. Click *Create* to go to the `Add Client` page. -+ -.Add Client -image:{project_images}/add-client-saml.png[] - -. Enter the `Client ID` of the client. This is often a URL and is the expected `issuer` value in SAML requests sent by the application. - -. Select `saml` in the `Client Protocol` drop down box. - -. Enter the `Client SAML Endpoint` URL. This URL is where you want the {project_name} server to send SAML requests and responses. Generally, applications have one URL for processing SAML requests. Multiple URLs can be set in the `Settings` tab of the client. - -. Click *Save*. This action creates the client and brings you to the `Settings` tab. -+ -.Client Settings -image:{project_images}/client-settings-saml.png[] -+ -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. This value must match the issuer value sent with AuthNRequests. {project_name} pulls the issuer from the Authn SAML request and match it to a client by this value. - -`Name`:: The name for the client in a {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 set to OFF, the client cannot request authentication. - -`Consent Required`:: When set to ON, users see a consent page that grants access to that application. The page also displays the metadata of the information that the client can access. If you have ever done a social login to Facebook, you often see a similar page. Red Hat Single Sign-On provides the same functionality. - -`Include AuthnStatement`:: SAML login responses may specify the authentication method used, such as password, as well as timestamps of the login and the session expiration. -This switch is enabled by default, so that the `AuthnStatement` element will be included in login responses. Setting this to OFF prevents clients from determining the maximum session length, which can create client sessions that do not expire. - -`Sign Documents`:: When set to ON, {project_name} signs the document using the realms private key. - -`Optimize REDIRECT signing key lookup`:: When set to ON, the SP messages include the {project_name} native extension. This extension contains a hint with the signing key ID. The SP uses the extension for signature validation instead of attempting to validate the signature using keys. -+ -This option applies to REDIRECT bindings where the signature is transferred in query parameters and this information is not found in the signature information. This is contrary to POST binding messages where key ID is always included in document signature. -+ -This option is used when {project_name} server and adapter provide the IDP and SP. This option is only relevant when `Sign Documents` is set to ON. - -`Sign Assertions`:: The assertion is signed and embedded in the SAML XML Auth response. - -`Signature Algorithm`:: The algorithm used in signing SAML documents. - -`SAML Signature Key Name`:: Signed SAML documents sent using POST binding contain the identification of the signing key in the `KeyName` element. This action can be controlled by the `SAML Signature Key Name` option. This option controls the contents of the `Keyname`. -+ --- -* _KEY_ID_:: The `KeyName` contains the key ID. This option is the default option. -* _CERT_SUBJECT_:: The `KeyName` contains the subject from the certificate corresponding to the realm key. This option is expected by Microsoft Active Directory Federation Services. -* _NONE_:: The `KeyName` hint is completely omitted from the SAML message. --- -+ -`Canonicalization Method`:: The canonicalization method for XML signatures. - -`Encrypt Assertions`:: Encrypts the assertions in SAML documents with the realms private key. The AES algorithm uses a key size of 128 bits. - -`Client Signature Required`:: If this switch is set to ON, documents coming from a client are expected to be signed. {project_name} validates this signature using the client public key or certificate set up in the `SAML Keys` tab. - -`Force POST Binding`:: By default, {project_name} responds using the initial SAML binding of the original request. By setting this switch to ON, {project_name} responds using the SAML POST binding even if the original request used the redirect binding. - -`Front Channel Logout`:: If this switch is set to ON, the application requires a browser redirect to perform a logout. For example, the application may require a cookie to be reset which could only be done via a redirect. If this switch is set to OFF, {project_name} invokes a background SAML request to log out of the application. - -`Force Name ID Format`:: If a request has a name ID policy, ignore it and use the value configured in the admin console under `Name ID Format`. - -`Name ID Format`:: The Name ID Format for the subject. This format is used if no name ID policy is specified in a request, or if the Force Name ID Format attribute is set to ON. - -<<<<<<< HEAD -Client Signature Required:: - Expect that documents coming from a client are signed. - {project_name} will validate this signature using the client public key or cert set up in the `Keys` tab. -======= -`Root URL`:: When {project_name} uses a configured relative URL, this value is prepended to the URL. ->>>>>>> c775d1cd... removing client-saml.adoc - -`Valid Redirect URIs`:: Enter a URL pattern and click the + sign to add. Click the - sign to remove. Click the `Save` button to save these changes. -Wildcards values are allowed only at the end of a URL. For example, http://host.com/*$$. -This field is used when the exact SAML endpoints are not registered and {project_name} pulls the Assertion Consumer URL from a request. - -`Base URL`:: If {project_name} needs to link to a client, this URL is used. - -`Master SAML Processing URL`:: This URL is used for all SAML requests and the response is directed to the SP. It is used as the Assertion Consumer Service URL and the Single Logout Service URL. -+ -If login requests contain the Assertion Consumer Service URL then those login requests will take precedence. This URL must be validated by a registered Valid Redirect URI pattern. - -<<<<<<< HEAD -Name ID Format:: - Name ID Format for the subject. - If no name ID policy is specified in the request or if the Force Name ID Format attribute is true, this value is used. - Properties used for each of the respective formats are defined below. - You can change the attribute used by the NameID Mapper. - -|=== -|Name ID Format|Properties/Attributes Used|Example - -|username (unspecified) -|Username Property -|example_user - -|email -|Email Property -|example_user@example.com - -|persistent -|saml.persistent.name.id.for.$clientId Attribute -|G-6e2a1050-0fc0-479b-bf6e-29cd3ccb373b - -|transient -|property and attribute values are not used -|G-bfb85c10-57d7-4331-81bc-52f104599d79 - -|=== -======= -`Assertion Consumer Service POST Binding URL`:: POST Binding URL for the Assertion Consumer Service. ->>>>>>> fa08830f... removing client-saml.adoc - -`Assertion Consumer Service Redirect Binding URL`:: Redirect Binding URL for the Assertion Consumer Service. - -`Logout Service POST Binding URL`:: POST Binding URL for the Logout Service. - -`Logout Service Redirect Binding URL`:: Redirect Binding URL for the Logout Service. diff --git a/server_admin/topics/authentication/clients/client-scopes.adoc b/server_admin/topics/authentication/clients/client-scopes.adoc deleted file mode 100644 index 6498d6a33a..0000000000 --- a/server_admin/topics/authentication/clients/client-scopes.adoc +++ /dev/null @@ -1,193 +0,0 @@ -[[_client_scopes]] -=== Client Scopes - -If you have many applications you need to secure and register within your organization, it can become tedious to configure the -<<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>> for each of these clients. {project_name} allows -you to define a shared client configuration in an entity called a _client scope_. - -Client scopes also provide support for the OAuth 2 `scope` parameter, which allows a client application to request more or fewer -claims or roles in the access token, according to the application needs. - -To create a client scope, follow these steps: - -* Go to the `Client Scopes` left menu item. This initial screen shows you a list of currently defined client scopes. - -.Client Scopes List -image:{project_images}/client-scopes-list.png[] - -* Click the `Create` button. Name the client scope and save. A _client scope_ will have similar tabs to a regular clients. You can -define <<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>>, which can be inherited by other clients, -and which are configured to inherit from this client scope. - -==== Protocol - -When you are creating the client scope, you must choose the `Protocol`. Only the clients which use same protocol can then be linked -with this client scope. - -Once you have created new realm, you can see that there is a list of pre-defined (builtin) client scopes in the menu. - -* For the SAML protocol, there is one builtin client scope, `roles_list`, which contains one protocol mapper for showing the roles -list in the SAML assertion. -* For the OpenID Connect protocol, there are client scopes `profile`, `email`, `address`, `phone`, `offline_access`, `roles`, -`web-origins` and `microprofile-jwt`. - -The client scope, `offline_access`, is useful when client wants to obtain offline tokens. Learn about offline tokens in the -<<_offline-access, Offline Access section>> or in the https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification], -where scope parameter is defined with the value `offline_access`. - -The client scopes `profile`, `email`, `address` and `phone` are also defined in the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[OpenID Connect specification]. -These client scopes do not have any role scope mappings defined, but they have some protocol mappers defined, and these mappers correspond -to the claims defined in the OpenID Connect specification. - -For example, when you click to open the `phone` client scope and open the `Mappers` tab, you will see the protocol mappers, which -correspond to the claims defined in the specification for the scope `phone`. - -.Client Scope Mappers -image:{project_images}/client-scopes-phone.png[] - -When the `phone` client scope is linked to a client, that client automatically inherits all the protocol mappers defined in the -`phone` client scope. Access tokens issued for this client will contain the phone number information about the user, assuming that -the user has a defined phone number. - -Builtin client scopes contain exactly the protocol mappers as defined per the specification, -however you are free to edit client scopes and create/update/remove any protocol mappers (or role scope mappings). - -The client scope `roles` is not defined in the OpenID Connect specification and it is also not added automatically to the `scope` -claim in the access token. This client scope has some mappers, which are used to add roles of the user to the access token and -possibly add some audiences for the clients with at least one client role as described in the <<_audience_resolve, Audience section>>. - -The client scope `web-origins` is also not defined in the OpenID Connect specification and not added to the `scope` claim. This is used -to add allowed web origins to the access token `allowed-origins` claim. - -The client scope `microprofile-jwt` was created to handle the claims defined in the https://wiki.eclipse.org/MicroProfile/JWT_Auth[MicroProfile/JWT Auth Specification]. -This client scope defines a user property mapper for the `upn` claim and also a realm role mapper for the `groups` claim. These mappers -can be changed as needed so that different properties can be used to create the MicroProfile/JWT specific claims. - -==== Consent related settings - -Client scope contains options related to the consent screen. Those options are useful only if the linked client is configured to -require consent (if the `Consent Required` switch is enabled on the client). - -Display On Consent Screen:: - If on, and if this client scope is added to a client with consent required, then the text specified by `Consent Screen Text` will - be displayed on the consent screen, which is shown once the user is authenticated and right before he is redirected from {project_name} - to the client. If the switch is off, then this client scope will not be displayed on the consent screen. - -Consent Screen Text:: - The text shown on the consent screen when this client scope is added to some client with consent required defaults to - the name of client scope. The value for this text is localizable by specifying a substitution variable - with `${var-name}` strings. The localized value is then configured within property files in your theme. See the - link:{developerguide_link}[{developerguide_name}] for more information on localization. - -[[_client_scopes_linking]] -==== Link Client Scope with the Client - -Linking between client scope and client is configured in the `Client Scopes` tab of the particular client. There are 2 ways of -linking between client scope and client. - -Default Client Scopes:: - This is applicable for both OpenID Connect and SAML clients. Default client scopes are always applied when issuing OpenID Connect tokens - or SAML assertions for this client. The client will inherit Protocol mappers and Role Scope Mappings defined on the client - scope. For the OpenID Connect Protocol, the Mappers and Role Scope Mappings are always applied, regardless of the value used for the scope - parameter in the OpenID Connect authorization request. - -Optional Client Scopes:: - This is applicable only for OpenID Connect clients. Optional client scopes are applied when issuing tokens for this client, - but only when they are requested by the `scope` parameter in the OpenID Connect authorization request. - -===== Example - -For this example, we assume that the client has `profile` and `email` linked as default client scopes, and `phone` and `address` -are linked as optional client scopes. The client will use the value of the scope parameter when sending a request to the OpenID Connect authorization -endpoint: - -``` -scope=openid phone -``` - -The scope parameter contains the string, with the scope values divided by space (which is also the reason why a client scope name -cannot contain a space character in it). The value `openid` is the meta-value used for all OpenID Connect requests, so we will ignore -it for this example. The token will contain mappers and role scope mappings from the client scopes `profile`, `email` (which are -default scopes) and `phone` (an optional client scope requested by the scope parameter). - -[[_client_scopes_evaluate]] -==== Evaluating Client Scopes - -The tabs `Mappers` and `Scope` of the client contain the protocol mappers and role scope mappings declared solely for this client. -They do not contain the mappers and scope mappings inherited from client scopes. However, it may be useful to see what the -effective protocol mappers will be (protocol mappers defined on the client itself as well as inherited from the linked client scopes) -and the effective role scope mappings used when you generate the token for the particular client. - -You can see all of these when you click the `Client Scopes` tab for the client and then open the sub-tab `Evaluate`. From here you -can select the optional client scopes that you want to apply. This will also show you the value of the `scope` parameter, which needs to -be sent from the application to the {project_name} OpenID Connect authorization endpoint. - -.Evaluating Client Scopes -image:{project_images}/client-scopes-evaluate.png[] - -NOTE: If you want to see how you can send a custom value for a `scope` parameter from your application, see the -link:{adapterguide_link}#_params_forwarding[parameters forwarding section], if your application uses the servlet adapter, or the -link:{adapterguide_link}#_javascript_adapter[javascript adapter section], if your application uses the javascript adapter. - -===== Generating Example Tokens and User Info - -If you select a user in the `Evaluate` screen, the following example data is generated: - -* Generated Access Token: An access token that will be generated and sent to the client when the selected user is authenticated. -* Generated ID Token: An ID Token that will be generated and sent to the client when the selected user is authenticated. -* Generated User Info: The information about the user that is returned by the UserInfo Endpoint. - -All examples are generated for the particular user and issued for the particular client, with the specified -value of `scope` parameter. The examples include all of the claims and role mappings used. - -==== Client Scopes Permissions - -When issuing tokens for a particular user, the client scope is applied only if the user is permitted to use it. In the case that -a client scope does not have any role scope mappings defined on itself, then each user is automatically permitted to use this -client scope. However, when a client scope has any role scope mappings defined on itself, then the user must be a member of at least -one of the roles. In other words, there must be an intersection between the user roles and the roles of the client scope. Composite -roles are taken into account when evaluating this intersection. - -If a user is not permitted to use the client scope, then no protocol mappers or role scope mappings will be used when generating tokens -and the client scope will not appear in the _scope_ value in the token. - -==== Realm Default Client Scopes - -The `Realm Default Client Scopes` allow you to define set of client scopes, which will be automatically linked to newly created clients. - -Open the left menu item `Client Scopes` and then select `Default Client Scopes`. - -From here, select the client scopes that you want to add as `Default Client Scopes` to newly created clients and `Optional Client Scopes` -to newly created clients. - -.Default Client Scopes -image:{project_images}/client-scopes-default.png[] - -Once the client is created, you can unlink the default client scopes, if needed. This is similar to how you -remove <<_default_roles, Default Roles>>. - -==== Scopes explained - -The term `scope` is used in {project_name} on few places. Various occurrences of scopes are related to each other, but may have -a different context and meaning. To clarify, here we explain the various `scopes` used in {project_name}. - -Client scope:: - Referenced in this chapter. Client scopes are entities in {project_name}, which are configured at the realm level and they can be - linked to clients. The client scopes are referenced by their name when a request is sent to the {project_name} authorization endpoint - with a corresponding value of the `scope` parameter. The details are described in the <<_client_scopes_linking, section about - client scopes linking>>. - -Role scope mapping:: - This can be seen when you open tab `Scope` of a client or client scope. Role scope mapping allows you to limit the roles which can - be used in the access tokens. The details are described in the <<_role_scope_mappings, Role Scope Mappings section>>. - -ifeval::[{project_community}==true] - -Authorization scopes:: - This is used by the Authorization feature. The `Authorization Scope` is the action which can be done in the application. - More details in the link:{authorizationguide_link}[Authorization Services Guide]. - -endif::[] - - - diff --git a/server_admin/topics/authentication/clients/oidc/confidential.adoc b/server_admin/topics/authentication/clients/oidc/confidential.adoc deleted file mode 100644 index 73c0d6daeb..0000000000 --- a/server_admin/topics/authentication/clients/oidc/confidential.adoc +++ /dev/null @@ -1,80 +0,0 @@ - -[[_client-credentials]] - -==== Confidential Client Credentials - -If you've set the client's <<_access-type, access type>> to `confidential` in the client's -`Settings` tab, a new `Credentials` tab will show up. Note that the `Credentials` tab only -shows up after you've clicked the `Save` button at the bottom of the settings screen with a -`confidential` access type. As part of dealing with this type of client you have to configure -the client's credentials. - -.Credentials Tab -image:{project_images}/client-credentials.png[] - -The `Client Authenticator` list box specifies the type of credential you are going to use for your confidential client. -It defaults to client ID and secret. The secret is automatically generated for you and the `Regenerate Secret` -button allows you to recreate this secret if you want or need to. - -Alternatively, you can opt to use a signed Json Web Token (JWT) or x509 certificate validation (also called Mutual TLS) instead of a secret. - -.Signed JWT -image:{project_images}/client-credentials-jwt.png[] - -When choosing this credential type you will have to also generate a private key and certificate for the client in the tab `Keys`. -The private key will be used to sign the JWT, while the certificate is used by the server to verify the signature. - -.Keys Tab -image:images/client-oidc-keys.png[] - -Click on the `Generate new keys and certificate` button to start this process. - -.Generate Keys -image:{project_images}/generate-client-keys.png[] - -When you generate these keys, {project_name} will store the certificate, and you'll need to download the private key -and certificate for your client to use. Pick the archive format you want and specify the password for the private key -and store. - -You can also opt to -generate these via an external tool and just import the client's certificate. - -.Import Certificate -image:{project_images}/import-client-cert.png[] - -There are multiple formats you can import from, just choose the archive format you have the certificate stored in, -select the file, and click the `Import` button. - -Finally note that you don't even need to import certificate if you choose to `Use JWKS URL` . In that case, you can provide the URL where -client publishes its public key in https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK] format. This is flexible because when -client changes its keys, {project_name} will automatically download them without need to re-import anything on {project_name} side. - -If you use client secured by {project_name} adapter, you can configure the JWKS URL like https://myhost.com/myapp/k_jwks assuming that https://myhost.com/myapp is the -root URL of your client application. See link:{developerguide_link}[{developerguide_name}] for additional details. - -WARNING: For the performance purposes, {project_name} caches the public keys of the OIDC clients. If you think that private key of your client -was compromised, it is obviously good to update your keys, but it's also good to clear the keys cache. See <<_clear-cache, Clearing the cache>> -section for more details. - -.Signed JWT with Client Secret - -If you select this option in the `Client Authenticator` list box, you can use a JWT signed by client secret instead of the private key. - -This client secret will be used to sign the JWT by the client. - -.X509 Certificate - -By enabling this option {project_name} will validate if the client uses proper X509 certificate during the TLS Handshake. - -NOTE: This option requires mutual TLS in {project_name}, see <<_enable-mtls-wildfly, Enable mutual SSL in WildFly>>. - -.X509 Certificate -image:{project_images}/x509-client-auth.png[] - -The validator checks also the certificate's Subject DN field with configured regexp validation expression. For some -use cases, it is sufficient to accept all certificates. In that case, you can use `(.*?)(?:$)` expression. - -There are two ways for {project_name} to obtain the Client ID from the request. The first option is the `client_id` -parameter in the query (described in Section 2.2 of the https://datatracker.ietf.org/doc/html/rfc6749[OAuth 2.0 Specification]). -The second option is to supply `client_id` as a form parameter. - diff --git a/server_admin/topics/authentication/conditions.adoc b/server_admin/topics/authentication/conditions.adoc index 0d721b457b..e7606fdf6c 100644 --- a/server_admin/topics/authentication/conditions.adoc +++ b/server_admin/topics/authentication/conditions.adoc @@ -1,12 +1,11 @@ - -=== Conditions in Conditional flows +=== Conditions in conditional flows As was mentioned in <<_execution-requirements, Execution requirements>>, _Condition_ executions can be only contained in _Conditional_ subflow. If all _Condition_ executions evaluate as true, then the _Conditional_ sub-flow acts as _Required_. You can process the next execution in the _Conditional_ sub-flow. If some executions included in the _Conditional_ sub-flow evaluate as false, then the whole sub-flow is considered as _Disabled_. -==== Available Conditions +==== Available conditions `Condition - User Role`:: This execution has the ability to determine if the user has a role defined by _User role_ field. @@ -72,10 +71,10 @@ This example includes `Condition - User Role` and `Deny Access` executions. .Browser flow image:images/deny-access-flow.png[] -.Condition - User Role configuration +.Condition - user role configuration image:images/deny-access-role-condition.png[] -.Configuration of the `Deny Access` is really easy. You can specify an arbitrary alias and required message like this: +.Configuration of the `Deny Access` is really easy. You can specify an arbitrary Alias and required message like this: image:images/deny-access-execution-cond.png[] The last thing is defining the property with an error message in the login theme `messages_en.properties` (for English): diff --git a/server_admin/topics/authentication/flows.adoc b/server_admin/topics/authentication/flows.adoc index 0a17d7e04f..4a09dcc300 100644 --- a/server_admin/topics/authentication/flows.adoc +++ b/server_admin/topics/authentication/flows.adoc @@ -1,6 +1,6 @@ [[_authentication-flows]] -=== Authentication Flows +=== Authentication flows An _authentication flow_ is a container of authentications, screens, and actions, during log in, registration, and other {project_name} workflows. To view all the flows, actions, and checks, each flow requires: @@ -15,7 +15,7 @@ To view all the flows, actions, and checks, each flow requires: In the drop-down list, select *browser* to display the Browser Flow screen. -.Browser Flow +.Browser flow image:{project_images}/browser-flow.png[Browser Flow] Hover over the question-mark tooltip of the drop-down list to view a description of the flow. Two sections exist. @@ -39,20 +39,18 @@ This action is configured through the *Actions* > *Config* link. It redirects to + Since this sub-flow is marked as _alternative_, it will not be executed if the *Cookie* authentication type passed. This sub-flow contains an additional authentication type that needs to be executed. {project_name} loads the executions for this sub-flow and processes them. -.. The first execution is the *Username Password Form*, an authentication type that renders the username and password page. It is marked as _required_, so the user must enter a valid username and password. +The first execution is the *Username Password Form*, an authentication type that renders the username and password page. It is marked as _required_, so the user must enter a valid username and password. -.. The second execution is the *Browser - Conditional OTP* sub-flow. This sub-flow is _conditional_ and executes depending on the result of the *Condition - User Configured* execution. If the result is true, {project_name} loads the executions for this sub-flow and processes them. +The second execution is the *Browser - Conditional OTP* sub-flow. This sub-flow is _conditional_ and executes depending on the result of the *Condition - User Configured* execution. If the result is true, {project_name} loads the executions for this sub-flow and processes them. -.. The next execution is the *Condition - User Configured* authentication. This authentication checks if {project_name} has configured other executions in the flow for the user. The *Browser - Conditional OTP* sub-flow executes only when the user has a configured OTP credential. +The next execution is the *Condition - User Configured* authentication. This authentication checks if {project_name} has configured other executions in the flow for the user. The *Browser - Conditional OTP* sub-flow executes only when the user has a configured OTP credential. -.. The final execution is the *OTP Form*. {project_name} marks this execution as _required_ but it runs only when the user has an OTP credential set up because of the setup in the _conditional_ sub-flow. If not, the user does not see an OTP form. - -[[_execution-requirements]] -==== Execution requirements +The final execution is the *OTP Form*. {project_name} marks this execution as _required_ but it runs only when the user has an OTP credential set up because of the setup in the _conditional_ sub-flow. If not, the user does not see an OTP form. ===== Requirement A set of radio buttons that control the execution of an action executes. +[[_execution-requirements]] ====== Required All _Required_ elements in the flow must be successfully sequentially executed. The flow terminates if a required element fails. @@ -162,7 +160,7 @@ To illustrate the creation of flows, this section describes creating an advanced .The common part with the browser flow image:images/Passwordless-browser-login-common.png[] + -. Click *Actions* for the *Forms* execution. +. Click *Actions for the *Forms* execution. . Select *Add execution*. . Select *Username Form* from the drop-down list. . Click *Save*. diff --git a/server_admin/topics/authentication/kerberos.adoc b/server_admin/topics/authentication/kerberos.adoc index 471882f643..d4985389ca 100644 --- a/server_admin/topics/authentication/kerberos.adoc +++ b/server_admin/topics/authentication/kerberos.adoc @@ -57,7 +57,7 @@ Install a Kerberos client on your machine. .Procedure . Install a Kerberos client. If your machine runs Fedora, Ubuntu, or RHEL, install the link:https://www.freeipa.org/page/Downloads[freeipa-client] package, containing a Kerberos client and other utilities. -. Configure the Kerberos client (on Linux, the configuration settings are in the link:https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html`[/etc/krb5.conf] file ). +. Configure the Kerberos client (on Linux, the configuration settings are in the link:https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html[/etc/krb5.conf] file ). + Add your Kerberos realm to the configuration and configure the HTTP domains your server runs on. + @@ -74,16 +74,16 @@ For example, for the MYDOMAIN.ORG realm, you can configure the `domain_realm` se + For the MIT Kerberos example above, we exported keytab to the `/tmp/http.keytab` file. If your _Key Distribution Centre (KDC)_ and {project_name} run on the same host, the file is already available. -===== Enabling SPNEGO Processing +===== Enabling SPNEGO processing By default, {project_name} disables SPNEGO protocol support. To enable it, go to the <<_authentication-flows, browser flow>> and enable *Kerberos*. -.Browser Flow +.Browser flow image:{project_images}/browser-flow.png[Browser Flow] Set the *Kerberos* requirement from _disabled_ to _alternative_ (Kerberos is optional) or _required_ (browser must have Kerberos enabled). If you have not configured the browser to work with SPNEGO or Kerberos, {project_name} falls back to the regular login screen. -===== Configure Kerberos User Storage Federation Provider +===== Configure Kerberos user storage federation providerxs You must now use <<_user-storage-federation,User Storage Federation>> to configure how {project_name} interprets Kerberos tickets. Two different federation providers exist with Kerberos authentication support. @@ -92,7 +92,7 @@ To authenticate with Kerberos backed by an LDAP server, configure the <<_ldap, L .Procedure . Go to the configuration page for your LDAP provider. + -.LDAP Kerberos Integration +.Ldap kerberos integration image:{project_images}/ldap-kerberos.png[LDAP Kerberos Integration] + . Toggle *Allow Kerberos authentication* to *ON* @@ -105,7 +105,7 @@ If an LDAP server is not backing up your Kerberos solution, use the *Kerberos* U . Click *User Federation* in the menu. . Select *Kerberos* from the *Add provider* select box. + -.Kerberos User Storage Provider +.Kerberos user storage provider image:{project_images}/kerberos-provider.png[Kerberos User Storage Provider] The *Kerberos* provider parses the Kerberos ticket for simple principal information and imports the information into the local {project_name} database. @@ -122,7 +122,7 @@ In Windows domains, clients do not need to adjust their configuration. Internet ifeval::[{project_community}==true] ==== Example setups -===== {project_name} and FreeIPA docker image +===== {Project_name} and FreeIPA docker image When you install https://www.docker.com/[docker], run a docker image with the FreeIPA server installed. FreeIPA provides an integrated security solution with MIT Kerberos and 389 LDAP server. The image also contains a {project_name} server configured with an LDAP Federation provider and enabled SPNEGO/Kerberos authentication against the FreeIPA server. See details https://github.com/mposolda/keycloak-freeipa-docker/blob/master/README.md[here]. @@ -131,7 +131,7 @@ When you install https://www.docker.com/[docker], run a docker image with the Fr For quick testing and unit tests, use a simple http://directory.apache.org/apacheds/[ApacheDS] Kerberos server. You must build {project_name} from the source and then run the Kerberos server with the maven-exec-plugin from our test suite. See details https://github.com/keycloak/keycloak/blob/master/docs/tests.md#kerberos-server[here]. endif::[] -==== Credential Delegation +==== Credential delegation Kerberos supports the credential delegation. Applications may need access to the Kerberos ticket so they can re-use it to interact with other services secured by Kerberos. Because the {project_name} server processed the SPNEGO protocol, you must propagate the GSS credential to your application within the OpenID Connect token claim or a SAML assertion attribute. {project_name} transmits this to your application from the {project_name} server. To insert this claim into the token or assertion, each application must enable the built-in protocol mapper `gss delegation credential`. This mapper is available in the *Mappers* tab of the application's client page. See <<_protocol-mappers, Protocol Mappers>> chapter for more details. diff --git a/server_admin/topics/authentication/otp-policies.adoc b/server_admin/topics/authentication/otp-policies.adoc index 61d6b3869d..8f19407d74 100644 --- a/server_admin/topics/authentication/otp-policies.adoc +++ b/server_admin/topics/authentication/otp-policies.adoc @@ -1,14 +1,14 @@ -=== One Time Password (OTP) Policies +=== One Time Password (OTP) policies {project_name} has several policies for setting up a FreeOTP or Google Authenticator One-Time Password generator. Click the *Authentication* menu and click the *OTP Policy* tab. -.OTP Policy +.Otp policy image:{project_images}/otp-policy.png[OTP Policy] {project_name} generates a QR code on the OTP set-up page, based on information configured in the *OTP Policy* tab. FreeOTP and Google Authenticator scan the QR code when configuring OTP. -==== Time-Based or Counter-Based One Time Passwords +==== Time-based or counter-based one time passwords The algorithms available in {project_name} for your OTP generators are time-based and counter-based. @@ -20,37 +20,37 @@ TOTP is more secure than HOTP because the matchable OTP is valid for a short win HOTP requires a database update every time the server increments the counter. This update is a performance drain on the authentication server during heavy load. To increase efficiency, TOTP does not remember passwords used, so there is no need to perform database updates. The drawback is that it is possible to re-use TOTPs in the valid time interval. -==== TOTP Configuration Options +==== TOTP configuration options -===== OTP Hash Algorithm +===== OTP hash algorithm The default algorithm is SHA1. The other, more secure options are SHA256 and SHA512. -===== Number of Digits +===== Number of digits The length of the OTP. Short OTP's are user-friendly, easier to type, and easier to remember. Longer OTP's are more secure than shorter OTP's. -===== Look Ahead Window +===== Look ahead window The number of intervals the server attempts to match the hash. This option is present in {project_name} if the clock of the TOTP generator or authentication server become out-of-sync. The default value of 1 is adequate. For example, if the time interval for a token is 30 seconds, the default value of 1 means it will accept valid tokens in the 30-second window. Every increment of this value increases the valid window by 30 seconds. -===== OTP Token Period +===== OTP token period The time interval in seconds the server matches a hash. Each time the interval passes, the token generator generates a TOTP. -==== HOTP Configuration Options +==== HOTP configuration options -===== OTP Hash Algorithm +===== OTP hash algorithm The default algorithm is SHA1. The other, more secure options are SHA256 and SHA512. -===== Number of Digits +===== Number of digits The length of the OTP. Short OTPs are user-friendly, easier to type, and easier to remember. Longer OTPs are more secure than shorter OTPs. -===== Look Ahead Window +===== Look ahead window The number of intervals the server attempts to match the hash. This option is present in {project_name} if the clock of the TOTP generator or authentication server become out-of-sync. The default value of 1 is adequate. This option is present in {project_name} to cover when the user's counter gets ahead of the server. -===== Initial Counter +===== Initial counter The value of the initial counter. diff --git a/server_admin/topics/authentication/password-policies.adoc b/server_admin/topics/authentication/password-policies.adoc index 2ed2971969..9476f1f665 100644 --- a/server_admin/topics/authentication/password-policies.adoc +++ b/server_admin/topics/authentication/password-policies.adoc @@ -1,7 +1,7 @@ [[_password-policies]] -=== Password Policies +=== Password policies When {project_name} creates a realm, it does not associate password policies with the realm. You can set a simple password with no restrictions on its length, security, or complexity. Simple passwords are unacceptable in production environments. {project_name} has a set of password policies available through the Admin Console. @@ -12,15 +12,15 @@ When {project_name} creates a realm, it does not associate password policies wit . Enter a value for the *Policy Value* corresponding with the policy chosen. . Click *Save*. + -Password Policy +Password policy image:{project_images}/password-policy.png[Password Policy] After saving the policy, {project_name} enforces the policy for new users and sets an Update Password action for existing users to ensure they change their password the next time they log in. For example: -.Failed Password Policy +.Failed password policy image:{project_images}/failed-password-policy.png[Failed Password Policy] -==== Password Policy Types +==== Password policy types ifeval::[{project_community}==true] @@ -36,13 +36,13 @@ If you change the hashing algorithm, password hashes in storage will not change endif::[] ifeval::[{project_product}==true] -===== Hashing Algorithm +===== Hashing algorithm Passwords are not stored in clear text. Before storage or validation, {project_name} hashes passwords using standard hashing algorithms {project_name} that support the PBKDF2, PBKDF2-SHA256 and PBKDF-SHA512 hashing algorithms. endif::[] -===== Hashing Iterations +===== Hashing iterations Specifies the number of times {project_name} hashes passwords before storage or verification. The default value is 27,500. {project_name} hashes passwords to ensure that hostile actors with access to the password database cannot read passwords through reverse engineering. @@ -56,39 +56,39 @@ A high hashing iteration value can impact performance as it requires higher CPU The number of numerical digits required in the password string. -===== Lowercase Characters +===== Lowercase characters The number of lower case letters required in the password string. -===== Uppercase Characters +===== Uppercase characters The number of upper case letters required in the password string. -===== Special Characters +===== Special characters The number of special characters required in the password string. -===== Not Username +===== Not username The password cannot be the same as the username. -===== Not Email +===== Not email The password cannot be the same as the email address of the user. -===== Regular Expression +===== Regular expression Password must match one or more defined regular expression patterns. -===== Expire Password +===== Expire password The number of days the password is valid. When the number of days has expired, the user must change their password. -===== Not Recently Used +===== Not recently used Password cannot be already used by the user. {project_name} stores a history of used passwords. The number of old passwords stored is configurable in {project_name}. -===== Password Blacklist +===== Password blacklist Password must not be in a blacklist file. * Blacklist files are UTF-8 plain-text files with Unix line endings. Every line represents a blacklisted password. diff --git a/server_admin/topics/authentication/webauthn.adoc b/server_admin/topics/authentication/webauthn.adoc index caee84ec9d..9a9c63e2c2 100644 --- a/server_admin/topics/authentication/webauthn.adoc +++ b/server_admin/topics/authentication/webauthn.adoc @@ -2,7 +2,7 @@ === W3C Web Authentication (WebAuthn) -{project_name} provides limited support for https://www.w3.org/TR/webauthn/[W3C Web Authentication (WebAuthn)]. {project_name} works as a WebAuthn's https://www.w3.org/TR/webauthn/#rp-operations[Relying Party (RP)]. +{project_name} provides limited support for https://www.w3.org/TR/webauthn/[W3C Web Authentication (WebAuthn)]. {project_name} works as a WebAuthn's https://www.w3.org/TR/webauthn/#webauthn-relying-party[Relying Party (RP)]. ifeval::[{project_product}==true] :tech_feature_name: WebAuthn @@ -29,7 +29,7 @@ WebAuthn's operations success depends on the user's WebAuthn supporting authenti The setup procedure of WebAuthn support for 2FA is the following : [[_webauthn-register]] -===== Enable WebAuthn Authenticator Registration +===== Enable WebAuthn authenticator registration . Click *Authentication* in the menu. . Click the *Required Actions* tab. @@ -41,7 +41,7 @@ The setup procedure of WebAuthn support for 2FA is the following : Mark the *Default Action* checkbox if you want all new users to be required to register their WebAuthn credentials. [[_webauthn-authenticator-setup]] -===== Adding WebAuthn Authentication to a Browser Flow +===== Adding WebAuthn authentication to a browser flow . Click *Authentication* in the menu. . Click the *Browser* flow. @@ -107,7 +107,7 @@ The user can choose between using WebAuthn and OTP for the second factor: + image:images/webauthn-browser-flow-conditional-with-OTP.png[] -==== Authenticate with WebAuthn Authenticator +==== Authenticate with WebAuthn authenticator After registering a WebAuthn authenticator, the user carries out the following operations: @@ -116,7 +116,7 @@ After registering a WebAuthn authenticator, the user carries out the following o ==== Managing WebAuthn as an administrator -===== Managing Credentials +===== Managing credentials {project_name} manages WebAuthn credentials similarly to other credentials from xref:ref-user-credentials_{context}[User credential management]: @@ -126,7 +126,7 @@ After registering a WebAuthn authenticator, the user carries out the following o * Administrators can set a label for the credential by setting a value in the *User Label* field and saving the data. [[_webauthn-policy]] -===== Managing Policy +===== Managing policy Administrators can configure WebAuthn related operations as *WebAuthn Policy* per realm. @@ -145,19 +145,19 @@ The configurable items and their description are as follows: |The readable server name as a WebAuthn Relying Party. This item is mandatory and applies to the registration of the WebAuthn authenticator. The default setting is "keycloak". For more details, see https://www.w3.org/TR/webauthn/#dictionary-pkcredentialentity[WebAuthn Specification]. |Signature Algorithms -|The algorithms telling the WebAuthn authenticator which signature algorithms to use for the https://www.w3.org/TR/webauthn/#public-key-credential[Public Key Credential]. {project_name} uses the Public Key Credential to sign and verify https://www.w3.org/TR/webauthn/#authentication-assertion[Authentication Assertions]. If no algorithms exist, the default https://tools.ietf.org/html/rfc8152#section-8.1[ES256] is adapted. ES256 is an optional configuration item applying to the registration of WebAuthn authenticators. For more details, see https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialparameters[WebAuthn Specification]. +|The algorithms telling the WebAuthn authenticator which signature algorithms to use for the https://www.w3.org/TR/webauthn/#iface-pkcredential[Public Key Credential]. {project_name} uses the Public Key Credential to sign and verify https://www.w3.org/TR/webauthn/#authentication-assertion[Authentication Assertions]. If no algorithms exist, the default https://datatracker.ietf.org/doc/html/rfc8152#section-8.1[ES256] is adapted. ES256 is an optional configuration item applying to the registration of WebAuthn authenticators. For more details, see https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialparameters[WebAuthn Specification]. |Relying Party ID -|The ID of a WebAuthn Relying Party that determines the scope of https://www.w3.org/TR/webauthn/#public-key-credential[Public Key Credentials]. The ID must be the origin's effective domain. This ID is an optional configuration item applied to the registration of WebAuthn authenticators. If this entry is blank, {project_name} adapts the host part of {project_name}'s base URL. For more details, see https://www.w3.org/TR/webauthn/#rp-id[WebAuthn Specification]. +|The ID of a WebAuthn Relying Party that determines the scope of https://www.w3.org/TR/webauthn/#public-key-credential[Public Key Credentials]. The ID must be the origin's effective domain. This ID is an optional configuration item applied to the registration of WebAuthn authenticators. If this entry is blank, {project_name} adapts the host part of {project_name}'s base URL. For more details, see https://www.w3.org/TR/webauthn/[WebAuthn Specification]. |Attestation Conveyance Preference -|The WebAuthn API implementation on the browser (https://www.w3.org/TR/webauthn/#webauthn-client[WebAuthn Client]) is the preferential method to generate Attestation statements. This preference is an optional configuration item applying to the registration of the WebAuthn authenticator. If no option exists, its behavior is the same as selecting "none". For more details, see https://www.w3.org/TR/webauthn/#attestation-convey[WebAuthn Specification]. +|The WebAuthn API implementation on the browser (https://www.w3.org/TR/webauthn/#webauthn-client[WebAuthn Client]) is the preferential method to generate Attestation statements. This preference is an optional configuration item applying to the registration of the WebAuthn authenticator. If no option exists, its behavior is the same as selecting "none". For more details, see https://www.w3.org/TR/webauthn/[WebAuthn Specification]. |Authenticator Attachment |The acceptable attachment pattern of a WebAuthn authenticator for the WebAuthn Client. This pattern is an optional configuration item applying to the registration of the WebAuthn authenticator. For more details, see https://www.w3.org/TR/webauthn/#enumdef-authenticatorattachment[WebAuthn Specification]. |Require Resident Key -|The option requiring that the WebAuthn authenticator generates the Public Key Credential as https://www.w3.org/TR/webauthn/#client-side-resident-public-key-credential-source[Client-side-resident Public Key Credential Source]. This option applies to the registration of the WebAuthn authenticator. If left blank, its behavior is the same as selecting "No". For more details, see https://www.w3.org/TR/webauthn/#dom-authenticatorselectioncriteria-requireresidentkey[WebAuthn Specification]. +|The option requiring that the WebAuthn authenticator generates the Public Key Credential as https://www.w3.org/TR/webauthn/[Client-side-resident Public Key Credential Source]. This option applies to the registration of the WebAuthn authenticator. If left blank, its behavior is the same as selecting "No". For more details, see https://www.w3.org/TR/webauthn/#dom-authenticatorselectioncriteria-requireresidentkey[WebAuthn Specification]. |User Verification Requirement |The option requiring that the WebAuthn authenticator confirms the verification of a user. This is an optional configuration item applying to the registration of a WebAuthn authenticator and the authentication of a user by a WebAuthn authenticator. If no option exists, its behavior is the same as selecting "preferred". For more details, see https://www.w3.org/TR/webauthn/#dom-authenticatorselectioncriteria-userverification[WebAuthn Specification for registering a WebAuthn authenticator] and https://www.w3.org/TR/webauthn/#dom-publickeycredentialrequestoptions-userverification[WebAuthn Specification for authenticating the user by a WebAuthn authenticator]. @@ -173,7 +173,7 @@ The configurable items and their description are as follows: |=== -==== Attestation Statement Verification +==== Attestation statement verification When registering a WebAuthn authenticator, {project_name} verifies the trustworthiness of the attestation statement generated by the WebAuthn authenticator. {project_name} requires the trust anchor's certificates for this. {project_name} uses the link:{installguide_truststore_link}[{installguide_truststore_name}], so you must import these certificates into it in advance. @@ -182,7 +182,7 @@ To omit this validation, disable this truststore or set the WebAuthn policy's co ==== Managing WebAuthn credentials as a user -===== Register WebAuthn Authenticator +===== Register WebAuthn authenticator The appropriate method to register a WebAuthn authenticator depends on whether the user has already registered an account on {project_name}. @@ -201,10 +201,10 @@ After successfully registering, the browser asks the user to enter the text of t ===== Existing user -[[_webauthn_passwordless]] -==== Passwordless WebAuthn together with Two-Factor +If `WebAuthn Authenticator` is set up as required as shown in the first example, then when existing users try to log in, they are required to register their WebAuthn authenticator automatically: .Procedure + . Open the login form. . Enter the items on the form. . Click *Save*. @@ -212,6 +212,7 @@ After successfully registering, the browser asks the user to enter the text of t After successful registration, the user's browser asks the user to enter the text of their WebAuthn authenticator's label. +[[_webauthn_passwordless]] ==== Passwordless WebAuthn together with Two-Factor {project_name} uses WebAuthn for two-factor authentication, but you can use WebAuthn as the first-factor authentication. In this case, users with `passwordless` WebAuthn credentials can authenticate to {project_name} without a password. {project_name} can use WebAuthn as both the passwordless and two-factor authentication mechanism in the context of a realm and a single authentication flow. diff --git a/server_admin/topics/authentication/x509.adoc b/server_admin/topics/authentication/x509.adoc index 686a25e730..87a26a7d37 100644 --- a/server_admin/topics/authentication/x509.adoc +++ b/server_admin/topics/authentication/x509.adoc @@ -1,6 +1,6 @@ -[[_x509]] -=== X.509 Client Certificate User Authentication +[[_x509]] +=== X.509 client certificate user authentication {project_name} supports logging in with an X.509 client certificate if you have configured the server to use mutual SSL authentication. @@ -44,7 +44,7 @@ Supported Certificate Identity Sources: * SHA-256 Certificate thumbprint * Full certificate in PEM format -===== Regular Expressions +===== Regular expressions {project_name} extracts the certificate identity from Subject DN or Issuer DN by using a regular expression as a filter. For example, this regular expression matches the email attribute: ``` @@ -65,21 +65,21 @@ The certificate identity mapping can map the extracted user identity to an exist * Using `Full certificate in PEM format` as an identity source is limited to the custom attributes mapped to external federation sources, such as LDAP. {project_name} cannot store certificates in its database due to length limitations, so in the case of LDAP, you must enable `Always Read Value From LDAP`. ==== -====== Extended Certificate Validation +====== Extended certificate validation * Revocation status checking using CRL. * Revocation status checking using CRL/Distribution Point. * Revocation status checking using OCSP/Responder URI. * Certificate KeyUsage validation. * Certificate ExtendedKeyUsage validation. -==== Enable X.509 Client Certificate User Authentication +==== Enable X.509 client certificate user authentication The following sections describe how to configure {appserver_name}/Undertow and the {project_name} Server to enable X.509 client certificate authentication. [[_enable-mtls-wildfly]] ===== Enable mutual SSL in {appserver_name} -See link:https://docs.wildfly.org/19/Admin_Guide.html#enable-ssl[Enable SSL] for the instructions to enable SSL in {appserver_name}. +See link:https://docs.wildfly.org/24/Admin_Guide.html#enable-ssl[Enable SSL] for the instructions to enable SSL in {appserver_name}. * Open {project_dirref}/standalone/configuration/standalone.xml and add a new realm: ```xml @@ -134,9 +134,9 @@ The password to open the truststore. ===== Enable HTTPS listener -See link:https://docs.wildfly.org/19/Admin_Guide.html#https-listener[HTTPS Listener] for the instructions to enable HTTPS in WildFly. +See link:https://docs.wildfly.org/24/Admin_Guide.html#https-listener[HTTPS Listener] for the instructions to enable HTTPS in WildFly. -Add the element as shown below: +* Add the element. [source,xml,subs="attributes+"] ---- @@ -159,7 +159,7 @@ If set to *REQUESTED*, the server optionally asks for a client certificate. If set to *REQUIRED*, the server refuses inbound connections if no client certificate has been provided. [[_browser_flow]] -==== Adding X.509 Client Certificate Authentication to browser flows +==== Adding X.509 client certificate authentication to browser flows . Click *Authentication* in the menu. . Click the "Browser" flow. @@ -171,13 +171,13 @@ If set to *REQUIRED*, the server refuses inbound connections if no client certif . Click "X509/Validate Username Form". . Click *Save*. + -.X509 Execution +.X509 execution image:images/x509-execution.png[X509 Execution] + . Click the up/down arrow buttons to move the "X509/Validate Username Form" over the "Browser Forms" execution. . Set the requirement to "ALTERNATIVE". + -.X509 Browser Flow +.X509 browser flow image:images/x509-browser-flow.png[X509 Browser Flow] + . Click the *Bindings* tab. @@ -185,56 +185,53 @@ image:images/x509-browser-flow.png[X509 Browser Flow] . Click the copy of the browser flow from the drop-down list. . Click *Save*. + -.X509 Browser Flow Bindings +.X509 browser flow bindings image:images/x509-browser-flow-bindings.png[X509 Browser Flow Bindings] -==== Configuring X.509 Client Certificate Authentication +==== Configuring X.509 client certificate authentication -.X509 Configuration +.X509 configuration image:images/x509-configuration.png[X509 Configuration] *User Identity Source*:: Defines the method for extracting the user identity from a client certificate. -*Canonical DN representation enabled (optional)*:: +*Canonical DN representation enabled*:: Defines whether to use canonical format to determine a distinguished name. The official link:https://docs.oracle.com/javase/8/docs/api/javax/security/auth/x500/X500Principal.html#getName-java.lang.String-[Java API documentation] describes the format. This option affects the two User Identity Sources _Match SubjectDN using regular expression_ and _Match IssuerDN using regular expression_ only. Enable this option when you set up a new {project_name} instance. Disable this option to retain backward compatibility with existing {project_name} instances. -*Enable Serial Number hexadecimal representation (optional)*:: -Represent the link:https://tools.ietf.org/html/rfc5280#section-4.1.2.2[serial number] as hexadecimal. The serial number with the sign bit set to 1 must be left padded with 00 octet. For example, a serial number with decimal value _161_, or _a1_ in hexadecimal representation is encoded as _00a1_, according to RFC5280. See link:https://tools.ietf.org/html/rfc5280#appendix-B[RFC5280, appendix-B] for more details. +*Enable Serial Number hexadecimal representation*:: +Represent the link:https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.2[serial number] as hexadecimal. The serial number with the sign bit set to 1 must be left padded with 00 octet. For example, a serial number with decimal value _161_, or _a1_ in hexadecimal representation is encoded as _00a1_, according to RFC5280. See link:https://datatracker.ietf.org/doc/html/rfc5280#appendix-B[RFC5280, appendix-B] for more details. -*A regular expression (optional)*:: +*A regular expression*:: A regular expression to use as a filter for extracting the certificate identity. The expression must contain a single group. *User Mapping Method*:: Defines the method to match the certificate identity with an existing user. _Username or email_ searches for existing users by username or email. _Custom Attribute Mapper_ searches for existing users with a custom attribute that matches the certificate identity. The name of the custom attribute is configurable. -*A name of user attribute (optional)*:: +*A name of user attribute*:: A custom attribute whose value matches against the certificate identity. Use multiple custom attributes when attribute mapping is related to multiple values, For example, 'Certificate Serial Number and IssuerDN'. -WARNING: It is highly recommended that attribute used here is read-only for the users. By default, only the `usercertificate` attribute is read-only by {project_name}. -If you use a different attribute name, you may need to add it to the list of read-only attributes. See the details in the link:#_read_only_user_attributes[Threat model mitigation chapter]. - -*CRL Checking Enabled (optional)*:: +*CRL Checking Enabled*:: Check the revocation status of the certificate by using the Certificate Revocation List. The location of the list is defined in the *CRL file path* attribute. -*Enable CRL Distribution Point to check certificate revocation status (optional)*:: +*Enable CRL Distribution Point to check certificate revocation status*:: Use CDP to check the certificate revocation status. Most PKI authorities include CDP in their certificates. -*CRL file path (optional)*:: +*CRL file path*:: The path to a file containing a CRL list. The value must be a path to a valid file if the *CRL Checking Enabled* option is enabled. -*OCSP Checking Enabled (optional)*:: +*OCSP Checking Enabled*:: Checks the certificate revocation status by using Online Certificate Status Protocol. -*OCSP Responder URI (optional)*:: +*OCSP Responder URI*:: Override the value of the OCSP responder URI in the certificate. -*Validate Key Usage (optional)*:: +*Validate Key Usage*:: Verifies the certificate's KeyUsage extension bits are set. For example, "digitalSignature,KeyEncipherment" verifies if bits 0 and 2 in the KeyUsage extension are set. -Leave this parameter empty to disable the Key Usage validation. See link:https://tools.ietf.org/html/rfc5280#section-4.2.1.3[RFC5280, Section-4.2.1.3] for more information. {project_name} raises an error when a key usage mismatch occurs. +Leave this parameter empty to disable the Key Usage validation. See link:https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3[RFC5280, Section-4.2.1.3] for more information. {project_name} raises an error when a key usage mismatch occurs. -*Validate Extended Key Usage (optional)*:: -Verifies one or more purposes defined in the Extended Key Usage extension. See link:https://tools.ietf.org/html/rfc5280#section-4.2.1.12[RFC5280, Section-4.2.1.12] for more information. Leave this parameter empty to disable the Extended Key Usage validation. {project_name} raises an error when flagged as critical by the issuing CA and a key usage extension mismatch occurs. +*Validate Extended Key Usage*:: +Verifies one or more purposes defined in the Extended Key Usage extension. See link:https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12[RFC5280, Section-4.2.1.12] for more information. Leave this parameter empty to disable the Extended Key Usage validation. {project_name} raises an error when flagged as critical by the issuing CA and a key usage extension mismatch occurs. *Bypass identity confirmation*:: If enabled, X.509 client certificate authentication does not prompt the user to confirm the certificate identity. {project_name} signs in the user upon successful authentication. @@ -257,7 +254,7 @@ If set, the client certificate trust chain will be always verified at the applic . Click "X509/Validate Username". . Click *Save*. + -.X509 Direct Grant Execution +.X509 direct grant execution image:images/x509-directgrant-execution.png[X509 Direct Grant Execution] + . Set up the x509 authentication configuration by following the steps described in the <<_browser_flow, x509 Browser Flow>> section. @@ -266,7 +263,7 @@ image:images/x509-directgrant-execution.png[X509 Direct Grant Execution] . Click the newly created "x509 Direct Grant" flow. . Click *Save*. + -.X509 Direct Grant Flow Bindings +.X509 direct grant flow bindings image:images/x509-directgrant-flow-bindings.png[X509 Direct Grant Flow Bindings] ==== Client certificate lookup diff --git a/server_admin/topics/authentication/clients/assembly-client-oidc.adoc b/server_admin/topics/clients/assembly-client-oidc.adoc similarity index 91% rename from server_admin/topics/authentication/clients/assembly-client-oidc.adoc rename to server_admin/topics/clients/assembly-client-oidc.adoc index df4f9746fd..747220bdc4 100644 --- a/server_admin/topics/authentication/clients/assembly-client-oidc.adoc +++ b/server_admin/topics/clients/assembly-client-oidc.adoc @@ -1,6 +1,6 @@ -[id="assembly-oidc-clients_{context}"] -= OIDC Clients +[[_oidc_clients]] += OIDC clients [role="_abstract"] xref:con-oidc_{context}[OpenID Connect] is the recommended protocol to secure applications. It was designed from the ground up to be web friendly and it works best with HTML5/JavaScript applications. diff --git a/server_admin/topics/authentication/clients/client-policies.adoc b/server_admin/topics/clients/client-policies.adoc similarity index 98% rename from server_admin/topics/authentication/clients/client-policies.adoc rename to server_admin/topics/clients/client-policies.adoc index 4cb1313c5f..1ba9d9e9d8 100644 --- a/server_admin/topics/authentication/clients/client-policies.adoc +++ b/server_admin/topics/clients/client-policies.adoc @@ -1,5 +1,6 @@ + [[_client_policies]] -=== Client Policies += Client Policies To make it easy to secure client applications, it is beneficial to realize the following points in a unified way. @@ -9,7 +10,7 @@ To make it easy to secure client applications, it is beneficial to realize the f To realize these points in a unified way, _Client Policies_ concept is introduced. -==== Use-cases +== Use-cases Client Policies realize the following points mentioned as follows. @@ -34,15 +35,15 @@ Conformance to a required security standards and profiles such as FAPI:: be compliant with the FAPI. The administrator can configure client profiles and client policies, so that {project_name} clients can be easily made compliant with various other security profiles like SPA, Native App, Open Banking and so on. -==== Protocol +== Protocol The client policy concept is independent of any specific protocol. However, {project_name} currently supports it only just for the link:{adapterguide_link}#_oidc[OpenID Connect (OIDC) protocol]. -==== Architecture +== Architecture Client Policies consists of the four building blocks: Condition, Executor, Profile and Policy. -===== Condition +=== Condition A condition determines to which client a policy is adopted and when it is adopted. Some conditions are checked at the time of client create/update when some other conditions are checked during client requests (OIDC Authorization request, Token endpoint request and so on). The condition checks whether one specified criteria is satisfied. For example, @@ -83,7 +84,7 @@ Client Domain Name, Host or IP Address:: Any Client:: This condition always evaluates to true. It can be used for example to ensure that all clients in the particular realm are FAPI compliant. -===== Executor +=== Executor An executor specifies what action is executed on a client to which a policy is adopted. The executor executes one or several specified actions. For example, some executor checks whether the value of the parameter `redirect_uri` in the authorization request matches exactly with one of the pre-registered redirect URIs on @@ -123,20 +124,20 @@ One of several purposes for this executor is to realize the security requirement * Enforce `binding_message` parameter is used for CIBA requests [[_client_policy_profile]] -===== Profile +=== Profile A profile consists of several executors, which can realize a security profile like FAPI. Profile can be configured by the Admin REST API (Admin Console) together with its executors. Three _global profiles_ exist and they are configured in {project_name} by default with pre-configured executors compliant with the FAPI Baseline, FAPI Advanced and FAPI CIBA specifications. More details exist in the FAPI section of the link:{adapterguide_link}#_fapi-support[{adapterguide_name}]. [[_client_policy_policy]] -===== Policy +=== Policy A policy consists of several conditions and profiles. The policy can be adopted to clients satisfying all conditions of this policy. The policy refers several profiles and all executors of these profiles execute their task against the client that this policy is adopted to. -==== Configuration +== Configuration Policies, profiles, conditions, executors can be configured by Admin REST API, which means also the Admin Console. To do so, there is a tab _Realm_ -> _Realm Settings_ -> _Client Policies_ , which means the administrator can have client policies per realm. @@ -146,7 +147,7 @@ configured by default. This means that the administrator is always required to c profiles cannot be updated, but the administrator can easily use them as a template and create their own profile if they want to do some slight changes in the global profile configurations. There is JSON Editor available in the Admin Console, which simplifies the creation of new profile based on some global profile. -==== Backward Compatibility +== Backward Compatibility Client Policies can replace Client Registration Policies described in the link:{adapterguide_link}#_client_registration_policies[{adapterguide_name}]. However, Client Registration Policies also still co-exist. This means that for example during a Dynamic Client Registration request to create/update a client, both client policies and diff --git a/server_admin/topics/authentication/clients/con-client-links.adoc b/server_admin/topics/clients/con-client-links.adoc similarity index 98% rename from server_admin/topics/authentication/clients/con-client-links.adoc rename to server_admin/topics/clients/con-client-links.adoc index 7788e282f7..0a443c7169 100644 --- a/server_admin/topics/authentication/clients/con-client-links.adoc +++ b/server_admin/topics/clients/con-client-links.adoc @@ -1,6 +1,6 @@ [id="con-client-links_{context}"] -= Client Links += Client links [role="_abstract"] To link from one client to another, {project_name} provides a redirect endpoint: `/realms/realm_name/clients/\{client-id}/redirect`. diff --git a/server_admin/topics/authentication/clients/con-client-scopes.adoc b/server_admin/topics/clients/con-client-scopes.adoc similarity index 96% rename from server_admin/topics/authentication/clients/con-client-scopes.adoc rename to server_admin/topics/clients/con-client-scopes.adoc index 8fe3ed39ce..58c2186771 100644 --- a/server_admin/topics/authentication/clients/con-client-scopes.adoc +++ b/server_admin/topics/clients/con-client-scopes.adoc @@ -1,7 +1,7 @@ -[id="con-client-scopes_{context}"] +//[id="con-client-scopes_{context}"]// [[_client_scopes]] -= Client Scopes += Client scopes [role="_abstract"] Use {project_name} to define a shared client configuration in an entity called a _client scope_. A _client scope_ configures <<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>> for multiple clients. @@ -10,6 +10,7 @@ Client scopes also support the OAuth 2 *scope* parameter. Client applications us include::proc-creating-client-scopes.adoc[] + == Protocol When you create a client scope, choose the *Protocol*. Clients linked in the same scope must have the same protocol. @@ -43,7 +44,7 @@ The client scopes *profile*, *email*, *address* and *phone* are defined in the h For example, when you open the *phone* client scope and open the *Mappers* tab, you will see the protocol mappers which correspond to the claims defined in the specification for the scope *phone*. -.Client Scope Mappers +.Client scope mappers image:{project_images}/client-scopes-phone.png[] When the *phone* client scope is linked to a client, the client automatically inherits all the protocol mappers defined in the *phone* client scope. Access tokens issued for this client contain the phone number information about the user, assuming that the user has a defined phone number. @@ -60,7 +61,7 @@ Consent Screen Text:: The text displayed on the consent screen when this client scope is added to a client when consent required defaults to the name of client scope. The value for this text can be customised by specifying a substitution variable with *${var-name}* strings. The customised value is configured within the property files in your theme. See the link:{developerguide_link}[{developerguide_name}] for more information on customisation. [[_client_scopes_linking]] -== Link Client Scope with the Client +== Link client scope with the client Linking between a client scope and a client is configured in the *Client Scopes* tab of the client. Two ways of linking between client scope and client are available. Default Client Scopes:: @@ -83,7 +84,7 @@ The scope parameter contains the string, with the scope values divided by spaces == Evaluating Client Scopes include::proc-evaluating-client-scopes.adoc[] -== Client Scopes Permissions +== Client scopes permissions When issuing tokens to a user, the client scope applies only if the user is permitted to use it. @@ -91,7 +92,7 @@ When a client scope does not have any role scope mappings defined, each user is If a user is not permitted to use the client scope, no protocol mappers or role scope mappings will be used when generating tokens. The client scope will not appear in the _scope_ value in the token. -== Realm Default Client Scopes +== Realm default client scopes include::proc-updating-default-scopes.adoc[] == Scopes explained @@ -104,6 +105,7 @@ This is available under the *Scope* tab of a client or client scope. Use *Role s ifeval::[{project_community}==true] Authorization scopes:: -The *Authorization Scope* covers the actions that can be perfoemdd in the application. See the link:{authorizationguide_link}[Authorization Services Guide] for more details. +The *Authorization Scope* covers the actions that can be performed in the application. See the link:{authorizationguide_link}[Authorization Services Guide] for more details. endif::[] + diff --git a/server_admin/topics/authentication/clients/con-protocol-mappers.adoc b/server_admin/topics/clients/con-protocol-mappers.adoc similarity index 96% rename from server_admin/topics/authentication/clients/con-protocol-mappers.adoc rename to server_admin/topics/clients/con-protocol-mappers.adoc index eb1c75cc30..17864c4337 100644 --- a/server_admin/topics/authentication/clients/con-protocol-mappers.adoc +++ b/server_admin/topics/clients/con-protocol-mappers.adoc @@ -1,7 +1,7 @@ [id="con-protocol-mappers_{context}"] [[_protocol-mappers]] -= OIDC Token and SAML Assertion Mappings += OIDC token and SAML assertion mappings [role="_abstract"] Applications receiving ID tokens, access tokens, or SAML assertions may require different roles and user metadata. @@ -14,7 +14,7 @@ You can use {project_name} to: You perform these actions in the *Mappers* tab in the Admin Console. -.Mappers Tab +.Mappers tab image:{project_images}/mappers-oidc.png[] New clients do not have built-in mappers but they can inherit some mappers from client scopes. See the <<_client_scopes, client scopes section>> for more details. @@ -24,7 +24,7 @@ a specific claim in the identity and access token. The function of a mapper shou Each mapper has a set of common settings. Additional settings are available, depending on the mapper type. Click *Edit* next to a mapper to access the configuration screen to adjust these settings. -.Mapper Config +.Mapper config image:{project_images}/mapper-config.png[] Details on each option can be viewed by hovering over its tooltip. @@ -45,7 +45,7 @@ For example, to compute the roles which will be included with a token: . Process a JavaScript script that uses the roles and audiences already available in the token. [[_protocol-mappers_oidc-user-session-note-mappers]] -== OIDC User Session Note Mappers +== OIDC user session note mappers User session details are defined using mappers and are automatically included when you use or enable a feature on a client. Click *Add builtin* to include session details. @@ -60,7 +60,7 @@ Service account sessions provide the following details: * *clientAddress*: The remote host IP of the service account's authenticated device. * *clientHost*: The remote host name of the service account's authenticated device. -== Script Mapper +== Script mapper Use the *Script Mapper* to map claims to tokens by running user-defined JavaScript code. For more details about deploying scripts to the server, see link:{developerguide_jsproviders_link}[{developerguide_jsproviders_name}]. diff --git a/server_admin/topics/authentication/clients/oidc/con-advanced-settings.adoc b/server_admin/topics/clients/oidc/con-advanced-settings.adoc similarity index 79% rename from server_admin/topics/authentication/clients/oidc/con-advanced-settings.adoc rename to server_admin/topics/clients/oidc/con-advanced-settings.adoc index bced9b759b..5f2deedd3b 100644 --- a/server_admin/topics/authentication/clients/oidc/con-advanced-settings.adoc +++ b/server_admin/topics/clients/oidc/con-advanced-settings.adoc @@ -1,5 +1,5 @@ [id="con-advanced-settings_{context}"] -= Advanced Settings += Advanced settings [role="_abstract"] When you click _Advanced Settings_, additional fields are displayed. @@ -30,7 +30,7 @@ In the following cases, {project_name} will verify the client sending the access * 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. -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. +See https://datatracker.ietf.org/doc/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. [NOTE] ==== @@ -48,28 +48,28 @@ An administrator can select one of these options: *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. -See https://tools.ietf.org/html/rfc7636[RFC 7636 Proof Key for Code Exchange by OAuth Public Clients] for more details. +See https://datatracker.ietf.org/doc/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 tokens according to the https://tools.ietf.org/html/rfc7516[Json Web Encryption (JWE)] specification. The administrator determines if ID tokens are encrypted for each client. +{project_name} can encrypt ID tokens according to the https://datatracker.ietf.org/doc/html/rfc7516[Json Web Encryption (JWE)] specification. The administrator determines if ID tokens are encrypted for each client. The key used for encrypting the ID token is the Content Encryption Key (CEK). {project_name} and a client must negotiate which CEK is used and how it is delivered. The method used to determine the CEK is the Key Management Mode. The Key Management Mode that {project_name} supports is Key Encryption. In Key Encryption: . The client generates an asymmetric cryptographic key pair. -. The public key is used to encrypt the CEK. +. The public key is used to encrypt the CEK. . {project_name} generates a CEK per ID token . {project_name} encrypts the ID token using this generated CEK -. {project_name} encrypts the CEK using the client's public key. +. {project_name} encrypts the CEK using the client's public key. . The client decrypts this encrypted CEK using their private key -. The client decrypts the ID token using the decrypted CEK. +. The client decrypts the ID token using the decrypted CEK. No party, other than the client, can decrypt the ID token. -The client must pass its public key for encrypting CEK to {project_name}. {project_name} supports downloading public keys from a URL provided by the client. The client must provide public keys according to the https://tools.ietf.org/html/rfc7517[Json Web Keys (JWK)] specification. +The client must pass its public key for encrypting CEK to {project_name}. {project_name} supports downloading public keys from a URL provided by the client. The client must provide public keys according to the https://datatracker.ietf.org/doc/html/rfc7517[Json Web Keys (JWK)] specification. The procedure is: @@ -77,7 +77,7 @@ The procedure is: . Toggle *JWKS URL* to ON. . Input the client's public key URL in the *JWKS URL* textbox. -Key Encryption's algorithms are defined in the https://tools.ietf.org/html/rfc7518#section-4.1[Json Web Algorithm (JWA)] specification. {project_name} supports: +Key Encryption's algorithms are defined in the https://datatracker.ietf.org/doc/html/rfc7518#section-4.1[Json Web Algorithm (JWA)] specification. {project_name} supports: * RSAES-PKCS1-v1_5(RSA1_5) * RSAES OAEP using default parameters (RSA-OAEP) diff --git a/server_admin/topics/authentication/clients/oidc/con-audience.adoc b/server_admin/topics/clients/oidc/con-audience.adoc similarity index 88% rename from server_admin/topics/authentication/clients/oidc/con-audience.adoc rename to server_admin/topics/clients/oidc/con-audience.adoc index 9cf58d09bd..11573a3592 100644 --- a/server_admin/topics/authentication/clients/oidc/con-audience.adoc +++ b/server_admin/topics/clients/oidc/con-audience.adoc @@ -1,10 +1,9 @@ - -[id="con-audience_{context}"] -= Audience Support +[[audience-support]] += Audience support [role="_abstract"] Typically, the environment where {project_name} is deployed consists of a set of _confidential_ or _public_ client applications that use {project_name} for authentication. -_Services_ (_Resource Servers_ in the https://tools.ietf.org/html/draft-ietf-oauth-mtls-08#section-4.2[OAuth 2 specification]) are also available that serve requests from client applications and provide resources to these applications. These services require an _Access token_ (Bearer token) to be sent to them to authenticate a request. This token is obtained by the frontend application upon login to {project_name}. +_Services_ (_Resource Servers_ in the https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mtls-08#section-4.2[OAuth 2 specification]) are also available that serve requests from client applications and provide resources to these applications. These services require an _Access token_ (Bearer token) to be sent to them to authenticate a request. This token is obtained by the frontend application upon login to {project_name}. In the environment where trust among services is low, you may encounter this scenario: @@ -50,9 +49,9 @@ Use this value to invoke the **. When setting up audience checking: -* Ensure that services are configured to check audience on the access token sent to them by adding the flag *_verify-token-audience_* in the adapter configuration. See link:{adapterguide_link}#_java_adapter_config[Adapter configuration] for details. +* Ensure that services are configured to check audience on the access token sent to them by adding the flag *_verify-token-audience_* in the adapter configuration. See link:{adapterguide_link_latest}#_java_adapter_config[Adapter configuration] for details. -* Ensure that access tokens issued by {project_name} contain all necessary audiences. Audiences can be added using the client roles as described in the <<_audience_resolve, next section>> or hardcoded as described in <<_audience_hardcoded, below>>. +* Ensure that access tokens issued by {project_name} contain all necessary audiences. Audiences can be added using the client roles as described in the <<_audience_resolve, next section>> or hardcoded. See <<_audience_hardcoded, Hardcoded audience>>. [[_audience_resolve]] == Automatically add audience @@ -93,14 +92,14 @@ You can add the protocol mapper directly to the frontend client. If the protocol For more control over the protocol mapper, you can create the protocol mapper on the dedicated client scope, which will be called for example *good-service*. -.Audience Protocol Mapper +.Audience protocol mapper image:{project_images}/audience_mapper.png[] * From the <<_client_installation, Installation tab>> of the *good-service* client, you can generate the adapter configuration and you can confirm that _verify-token-audience_ option will be set to *true*. This forces the adapter to verify the audience if you use this configuration. -* You need to ensure that the *my-app* frontend client is able to request *good-service* as an audience in its tokens. +* You need to ensure that the confidential client is able to request *good-service* as an audience in its tokens. + -On the *my-app* client: +On the confidential client: + . Click the _Client Scopes_ tab. . Assign *good-service* as an optional (or default) client scope. @@ -109,7 +108,7 @@ See <<_client_scopes_linking, Client Scopes Linking section>> for more details. * You can optionally <<_client_scopes_evaluate, Evaluate Client Scopes>> and generate an example access token. *good-service* will be added to the audience of the generated access token if *good-service* is included in the _scope_ parameter, when you assigned it as an optional client scope. -* In your *my-app* application, ensure that the _scope_ parameter is used. The value *good-service* must be included when you want to issue the token for accessing *good-service*. +* In your confidential client application, ensure that the _scope_ parameter is used. The value *good-service* must be included when you want to issue the token for accessing *good-service*. + See: + diff --git a/server_admin/topics/authentication/clients/oidc/con-basic-settings.adoc b/server_admin/topics/clients/oidc/con-basic-settings.adoc similarity index 89% rename from server_admin/topics/authentication/clients/oidc/con-basic-settings.adoc rename to server_admin/topics/clients/oidc/con-basic-settings.adoc index 0c474f5363..57c3f06bc8 100644 --- a/server_admin/topics/authentication/clients/oidc/con-basic-settings.adoc +++ b/server_admin/topics/clients/oidc/con-basic-settings.adoc @@ -1,5 +1,5 @@ [id="con-basic-settings_{context}"] -= Basic Settings += Basic settings [role="_abstract"] When you create an OIDC client, you see the following fields on the *Settings* tab. @@ -33,11 +33,12 @@ _Bearer-only_:: *Direct Access Grants Enabled*:: When enabled, clients can use the OIDC xref:_oidc-auth-flows-direct[Direct Access Grants]. -*OAuth 2.0 Device Authorization Grant Enabled* +*OAuth 2.0 Device Authorization Grant Enabled*:: If this is on, clients are allowed to use the OIDC xref:con-oidc-auth-flows_server_administration_guide[Device Authorization Grant]. -If this is on, clients are allowed to use the OIDC xref:con-oidc-auth-flows_server_administration_guide[Device Authorization Grant]. +*OpenID Connect Client Initiated Backchannel Authentication Grant Enabled*:: +If this is on, clients are allowed to use the OIDC xref:con-oidc-auth-flows_{context}[Client Initiated Backchannel Authentication Grant]. -*Root URL*:: This value adds a prefix to any configured URLS that {project_name} uses. +*Root URL*:: If {project_name} uses any configured relative URLs, this value is prepended to them. *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/*$$ + diff --git a/server_admin/topics/authentication/clients/oidc/con-confidential-client-credentials.adoc b/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc similarity index 89% rename from server_admin/topics/authentication/clients/oidc/con-confidential-client-credentials.adoc rename to server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc index b97c1e3a9b..e1d1a0478f 100644 --- a/server_admin/topics/authentication/clients/oidc/con-confidential-client-credentials.adoc +++ b/server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc @@ -1,11 +1,11 @@ [id="con-confidential-client-credentials_{context}"] [[_client-credentials]] -= Confidential 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 +.Credentials tab image:{project_images}/client-credentials.png[Credentials Tab] The *Client Authenticator* drop-down list specifies the type of credential to use for your client. @@ -19,10 +19,14 @@ image:{project_images}/client-credentials-jwt.png[] *Signed JWT* is "Signed Json Web Token". -When choosing this credential type you will have to also generate a private key and certificate for the client in the *Keys* tab. The private key will be used to sign the JWT, while the certificate is used by the server to verify the signature. -Click *Generate new keys and certificate* to start this process. +When choosing this credential type you will have to also generate a private key and certificate for the client in the tab `Keys`. The private key will be used to sign the JWT, while the certificate is used by the server to verify the signature. -.Generate Keys +.Keys tab +image:images/client-oidc-keys.png[] + +Click on the `Generate new keys and certificate` button to start this process. + +.Generate keys image:{project_images}/generate-client-keys.png[] . Select the archive format you want to use. @@ -34,7 +38,7 @@ When you generate the keys, {project_name} will store the certificate and you do You can also generate keys using an external tool and then import the client's certificate by clicking *Import Certificate*. -.Import Certificate +.Import certificate image:{project_images}/import-client-cert.png[Import Certificate] . Select the archive format of the certificate. @@ -67,7 +71,7 @@ The client secret will be used to sign the JWT by the client. NOTE: This option requires mutual TLS in {project_name}. See <<_enable-mtls-wildfly, Enable mutual SSL in WildFly>>. -.X509 Certificate +.X509 certificate image:{project_images}/x509-client-auth.png[] The validator also checks the Subject DN field of the certificate with a configured regexp validation expression. For some @@ -75,5 +79,5 @@ use cases, it is sufficient to accept all certificates. In that case, you can us Two ways exist for {project_name} to obtain the Client ID from the request: -* The `client_id` parameter in the query (described in Section 2.2 of the https://tools.ietf.org/html/rfc6749[OAuth 2.0 Specification]). +* The `client_id` parameter in the query (described in Section 2.2 of the https://datatracker.ietf.org/doc/html/rfc6749[OAuth 2.0 Specification]). * Supply `client_id` as a form parameter. diff --git a/server_admin/topics/authentication/clients/oidc/proc-creating-oidc-client.adoc b/server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc similarity index 92% rename from server_admin/topics/authentication/clients/oidc/proc-creating-oidc-client.adoc rename to server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc index 78ccd7fc3d..0693ddd92e 100644 --- a/server_admin/topics/authentication/clients/oidc/proc-creating-oidc-client.adoc +++ b/server_admin/topics/clients/oidc/proc-creating-oidc-client.adoc @@ -8,7 +8,7 @@ To protect an application that uses the OpenID connect protocol, you create a cl . Click *Create* to go to the *Add Client* page. + -.Add Client +.Add client image:{project_images}/add-client-oidc.png[Add Client] . Enter any name for *Client ID.* @@ -39,11 +39,10 @@ ifdef::standalone[] This action creates the client and bring you to the *Settings* tab. -.Client Settings +.Client settings image:{project_images}/client-settings-oidc.png[Client Settings] [role="_additional-resources"] .Additional resources -* For more information about fields on the *Settings* tab, see xref:con-basic-settings_{context}[Basic Settings]. * For more information about the OIDC protocol, see xref:con-oidc_{context}[OpenID Connect]. endif::[] diff --git a/server_admin/topics/authentication/clients/oidc/proc-using-a-service-account.adoc b/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc similarity index 93% rename from server_admin/topics/authentication/clients/oidc/proc-using-a-service-account.adoc rename to server_admin/topics/clients/oidc/proc-using-a-service-account.adoc index 21727b2bbb..86b227733a 100644 --- a/server_admin/topics/authentication/clients/oidc/proc-using-a-service-account.adoc +++ b/server_admin/topics/clients/oidc/proc-using-a-service-account.adoc @@ -1,7 +1,7 @@ [id="proc-using-service-account_{context}"] [[_service_accounts]] -= Using a Service Account += Using a service account [role="_abstract"] Each OIDC client has a built-in _service account_. Use this _service account_ to obtain an access token. @@ -43,7 +43,7 @@ For example, the POST invocation to retrieve a service account can look like thi grant_type=client_credentials ---- -The response would be similar to this https://tools.ietf.org/html/rfc6749#section-4.4.3[Access Token Response] from the OAuth 2.0 specification. +The response would be similar to this https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.3[Access Token Response] from the OAuth 2.0 specification. [source] ---- diff --git a/server_admin/topics/authentication/clients/oidc/service-accounts.adoc b/server_admin/topics/clients/oidc/service-accounts.adoc similarity index 100% rename from server_admin/topics/authentication/clients/oidc/service-accounts.adoc rename to server_admin/topics/clients/oidc/service-accounts.adoc diff --git a/server_admin/topics/authentication/clients/proc-creating-client-scopes.adoc b/server_admin/topics/clients/proc-creating-client-scopes.adoc similarity index 96% rename from server_admin/topics/authentication/clients/proc-creating-client-scopes.adoc rename to server_admin/topics/clients/proc-creating-client-scopes.adoc index bdf1c177f9..4537d37e5b 100644 --- a/server_admin/topics/authentication/clients/proc-creating-client-scopes.adoc +++ b/server_admin/topics/clients/proc-creating-client-scopes.adoc @@ -5,7 +5,7 @@ To create a client scope, follow these steps: . Click *Client Scopes* in the menu. + -.Client Scopes List +.Client scopes list image:{project_images}/client-scopes-list.png[] + . Click *Create*. @@ -14,3 +14,4 @@ image:{project_images}/client-scopes-list.png[] A _client scope_ has similar tabs to regular clients. You can define <<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>>. These mappings can be inherited by other clients and are configured to inherit from this client scope. + diff --git a/server_admin/topics/authentication/clients/proc-creating-mappers.adoc b/server_admin/topics/clients/proc-creating-mappers.adoc similarity index 95% rename from server_admin/topics/authentication/clients/proc-creating-mappers.adoc rename to server_admin/topics/clients/proc-creating-mappers.adoc index b3b26a94a7..41fb2a07dd 100644 --- a/server_admin/topics/authentication/clients/proc-creating-mappers.adoc +++ b/server_admin/topics/clients/proc-creating-mappers.adoc @@ -7,7 +7,7 @@ You can add mapper types as follows: . Go to the *Mappers* tab. . Click *Create*. + -.Add Mapper +.Add mapper image:{project_images}/add-mapper.png[] + . Select a *Mapper Type* from the list box. diff --git a/server_admin/topics/authentication/clients/proc-evaluating-client-scopes.adoc b/server_admin/topics/clients/proc-evaluating-client-scopes.adoc similarity index 68% rename from server_admin/topics/authentication/clients/proc-evaluating-client-scopes.adoc rename to server_admin/topics/clients/proc-evaluating-client-scopes.adoc index 587a7f988c..7508109b2b 100644 --- a/server_admin/topics/authentication/clients/proc-evaluating-client-scopes.adoc +++ b/server_admin/topics/clients/proc-evaluating-client-scopes.adoc @@ -10,12 +10,12 @@ The *Mappers* tab contains the protocol mappers and the *Scope* tab contains the This will also show you the value of the *scope* parameter. This parameter needs to be sent from the application to the {project_name} OpenID Connect authorization endpoint. -.Evaluating Client Scopes +.Evaluating client scopes image:{project_images}/client-scopes-evaluate.png[] [NOTE] ==== -To send a custom value for a *scope* parameter from your application, see the link:{adapterguide_link}#_params_forwarding[parameters forwarding section], for servlet adapters or the link:{adapterguide_link}#_javascript_adapter[javascript adapter section], for javascript adapters. +To send a custom value for a *scope* parameter from your application, see the link:{adapterguide_link_latest}#_params_forwarding[parameters forwarding section], for servlet adapters or the link:{adapterguide_link_latest}#_javascript_adapter[javascript adapter section], for javascript adapters. ==== -An example of a generated access token, specific to the user, client and *scope* parameter, is automatically generated under the *Generated Access Token* tab. +All examples are generated for the particular user and issued for the particular client, with the specified value of the *scope* parameter. The examples include all of the claims and role mappings used. \ No newline at end of file diff --git a/server_admin/topics/authentication/clients/proc-generating-client-adapter-config.adoc b/server_admin/topics/clients/proc-generating-client-adapter-config.adoc similarity index 95% rename from server_admin/topics/authentication/clients/proc-generating-client-adapter-config.adoc rename to server_admin/topics/clients/proc-generating-client-adapter-config.adoc index 75d7f23abd..739e627a9c 100644 --- a/server_admin/topics/authentication/clients/proc-generating-client-adapter-config.adoc +++ b/server_admin/topics/clients/proc-generating-client-adapter-config.adoc @@ -2,7 +2,7 @@ [[_client_installation]] -= Generating Client Adapter Config += Generating client adapter config [role="_abstract"] {project_name} can generate configuration files that you can use to install a client adapter in your application's deployment environment. A number of adapter types are supported for OIDC and SAML. diff --git a/server_admin/topics/authentication/clients/proc-updating-default-scopes.adoc b/server_admin/topics/clients/proc-updating-default-scopes.adoc similarity index 96% rename from server_admin/topics/authentication/clients/proc-updating-default-scopes.adoc rename to server_admin/topics/clients/proc-updating-default-scopes.adoc index 14200f3186..fd06ee643f 100644 --- a/server_admin/topics/authentication/clients/proc-updating-default-scopes.adoc +++ b/server_admin/topics/clients/proc-updating-default-scopes.adoc @@ -9,7 +9,7 @@ Use *Realm Default Client Scopes* to define sets of client scopes that are autom From here, select the client scopes that you want to add as *Default Client Scopes* to newly created clients and *Optional Client Scopes*. -.Default Client Scopes +.Default client scopes image:{project_images}/client-scopes-default.png[] When a client is created, you can unlink the default client scopes, if needed. This is similar to removing <<_default_roles, Default Roles>>. diff --git a/server_admin/topics/authentication/clients/saml/idp-initiated-login.adoc b/server_admin/topics/clients/saml/idp-initiated-login.adoc similarity index 99% rename from server_admin/topics/authentication/clients/saml/idp-initiated-login.adoc rename to server_admin/topics/clients/saml/idp-initiated-login.adoc index f713cb6789..48f7b5f761 100644 --- a/server_admin/topics/authentication/clients/saml/idp-initiated-login.adoc +++ b/server_admin/topics/clients/saml/idp-initiated-login.adoc @@ -1,5 +1,5 @@ -= IDP Initiated Login += IDP Initiated login [role="_abstract"] IDP Initiated Login is a feature that allows you to set up an endpoint on the {project_name} server that will log you into a specific application/client. In the *Settings* tab for your client, you need to specify the *IDP Initiated SSO URL Name*. diff --git a/server_admin/topics/authentication/clients/saml/proc-creating-saml-client.adoc b/server_admin/topics/clients/saml/proc-creating-saml-client.adoc similarity index 85% rename from server_admin/topics/authentication/clients/saml/proc-creating-saml-client.adoc rename to server_admin/topics/clients/saml/proc-creating-saml-client.adoc index c75b72c5f2..dd2b36466f 100644 --- a/server_admin/topics/authentication/clients/saml/proc-creating-saml-client.adoc +++ b/server_admin/topics/clients/saml/proc-creating-saml-client.adoc @@ -1,16 +1,16 @@ -[id="proc-creating-saml-client_{context}"] -= Creating a SAML Client +[[_client-saml-configuration]] += Creating a SAML client [role="_abstract"] {project_name} supports <<_saml,SAML 2.0>> for registered applications. POST and Redirect bindings are supported. You can choose to require client signature validation. You can have the server sign and/or encrypt responses as well. .Procedure -. Click *Clients* in the menu. +. Click *Clients* in the menu. . Click *Create* to go to the *Add Client* page. + -.Add Client +.Add client image:{project_images}/add-client-saml.png[] . Enter the *Client ID* of the client. This is often a URL and is the expected *issuer* value in SAML requests sent by the application. @@ -21,7 +21,7 @@ image:{project_images}/add-client-saml.png[] . Click *Save*. This action creates the client and brings you to the *Settings* tab. + -.Client Settings +.Client settings image:{project_images}/client-settings-saml.png[] + The following list describes each setting: @@ -42,9 +42,9 @@ the name, set up a replacement string value. For example, a string value such as *Sign Documents*:: When set to ON, {project_name} signs the document using the realms private key. -*Optimize REDIRECT signing key lookup*:: When set to ON, the SAML protocol messages include the {project_name} native extension. This extension contains a hint with the signing key ID. The SP uses the extension for signature validation instead of attempting to validate the signature using keys. +*Optimize REDIRECT signing key lookup*:: When set to ON, the SAML protocol messages include the {project_name} native extension. This extension contains a hint with the signing key ID. The SP uses the extension for signature validation instead of attempting to validate the signature using keys. + -This option applies to REDIRECT bindings where the signature is transferred in query parameters and this information is not found in the signature information. This is contrary to POST binding messages where key ID is always included in document signature. +This option applies to REDIRECT bindings where the signature is transferred in query parameters and this information is not found in the signature information. This is contrary to POST binding messages where key ID is always included in document signature. + This option is used when {project_name} server and adapter provide the IDP and SP. This option is only relevant when *Sign Documents* is set to ON. @@ -55,14 +55,14 @@ This option is used when {project_name} server and adapter provide the IDP and S *SAML Signature Key Name*:: Signed SAML documents sent using POST binding contain the identification of the signing key in the *KeyName* element. This action can be controlled by the *SAML Signature Key Name* option. This option controls the contents of the *Keyname*. + -- -* _KEY_ID_:: The *KeyName* contains the key ID. This option is the default option. -* _CERT_SUBJECT_:: The *KeyName* contains the subject from the certificate corresponding to the realm key. This option is expected by Microsoft Active Directory Federation Services. -* _NONE_:: The *KeyName* hint is completely omitted from the SAML message. +* *KEY_ID* The *KeyName* contains the key ID. This option is the default option. +* *CERT_SUBJECT* The *KeyName* contains the subject from the certificate corresponding to the realm key. This option is expected by Microsoft Active Directory Federation Services. +* *NONE* The *KeyName* hint is completely omitted from the SAML message. -- + *Canonicalization Method*:: The canonicalization method for XML signatures. -*Encrypt Assertions*:: Encrypts the assertions in SAML documents with the realms private key. The AES algorithm uses a key size of 128 bits. +*Encrypt Assertions*:: Encrypts the assertions in SAML documents with the realms private key. The AES algorithm uses a key size of 128 bits. *Client Signature Required*:: If *Client Signature Required* is enabled, documents coming from a client are expected to be signed. {project_name} will validate this signature using the client public key or cert set up in the `Keys` tab. @@ -82,14 +82,20 @@ This field is used when the exact SAML endpoints are not registered and {project *Base URL*:: If {project_name} needs to link to a client, this URL is used. -*Master SAML Processing URL*:: This URL is used for all SAML requests and the response is directed to the SP. It is used as the Assertion Consumer Service URL and the Single Logout Service URL. +*Master SAML Processing URL*:: This URL is used for all SAML requests and the response is directed to the SP. It is used as the Assertion Consumer Service URL and the Single Logout Service URL. + If login requests contain the Assertion Consumer Service URL then those login requests will take precedence. This URL must be validated by a registered Valid Redirect URI pattern. *Assertion Consumer Service POST Binding URL*:: POST Binding URL for the Assertion Consumer Service. -*Assertion Consumer Service Redirect Binding URL*:: Redirect Binding URL for the Assertion Consumer Service. +*Assertion Consumer Service Redirect Binding URL*:: Redirect Binding URL for the Assertion Consumer Service. *Logout Service POST Binding URL*:: POST Binding URL for the Logout Service. -*Logout Service Redirect Binding URL*:: Redirect Binding URL for the Logout Service. +*Logout Service Redirect Binding URL*:: Redirect Binding URL for the Logout Service. + +*Logout Service Artifact Binding URL*:: _Artifact_ Binding URL for the Logout Service. When set together with the `Force Artifact Binding` option, _Artifact_ binding is forced for both login and logout flows. _Artifact_ binding is not used for logout unless this property is set. + +*Artifact Binding URL*:: URL to send the HTTP artifact messages to. + +*Artifact Resolution Service*:: URL of the client SOAP endpoint where to send the `ArtifactResolve` messages to. diff --git a/server_admin/topics/authentication/clients/saml/proc-using-an-entity-descriptor.adoc b/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc similarity index 98% rename from server_admin/topics/authentication/clients/saml/proc-using-an-entity-descriptor.adoc rename to server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc index 5eb5ada6e4..30cf46d92e 100644 --- a/server_admin/topics/authentication/clients/saml/proc-using-an-entity-descriptor.adoc +++ b/server_admin/topics/clients/saml/proc-using-an-entity-descriptor.adoc @@ -6,7 +6,7 @@ Instead of registering a SAML 2.0 client manually, you can import the client usi The Add Client page includes an *Import* option. -.Add Client +.Add client image:{project_images}/add-client-saml.png[] .Procedure diff --git a/server_admin/topics/events/admin.adoc b/server_admin/topics/events/admin.adoc index 279a64e11f..9c98c650c5 100644 --- a/server_admin/topics/events/admin.adoc +++ b/server_admin/topics/events/admin.adoc @@ -1,5 +1,5 @@ -=== Admin Events +=== Admin events You can record all actions that are performed by an administrator in the Admin Console. The Admin Console performs administrative actions by invoking the {project_name} REST interface and {project_name} audits these REST invocations. You can view the resulting events in the Admin Console. @@ -9,12 +9,12 @@ To enable auditing of Admin actions: . Click *Events* in the menu. . Click the *Config* tab. + -.Event Configuration +.Event configuration image:{project_images}/login-events-config.png[Event Configuration] + . Toggle *Save Events* to *ON* in the *Admin Events Settings* section. {project_name} displays the *Include Representation* switch. + -.Admin Event Configuration +.Admin event configuration image:{project_images}/admin-events-settings.png[Admin Event Configuration] + . Toggle *Include Representation* to *ON*. @@ -23,15 +23,15 @@ The `Include Representation` switch includes JSON documents sent through the adm To view the admin events, click the *Admin Events* tab. -.Admin Events +.Admin events image:{project_images}/admin-events.png[Admin Events] If the `Details` column has a *Representation* button, click the *Representation* button to view the JSON {project_name} sent with the operation. -.Admin Representation +.Admin representation image:{project_images}/admin-events-representation.png[Admin Representation] Click `Filter` to view specific events. -.Admin Event Filter +.Admin event filter image:{project_images}/admin-events-filter.png[Admin Event Filter] diff --git a/server_admin/topics/events/login.adoc b/server_admin/topics/events/login.adoc index c11c4fd177..d25829797a 100644 --- a/server_admin/topics/events/login.adoc +++ b/server_admin/topics/events/login.adoc @@ -1,5 +1,5 @@ -=== Login Events +=== Login events You can record and view every event that affects users. {project_name} triggers login events for actions such as successful user login, a user entering an incorrect password, or a user account updating. By default, {project_name} does not store or display events in the Admin Console. Only the error events are logged to the Admin Console and the server’s log file. @@ -30,12 +30,12 @@ image:{project_images}/login-events.png[Login Events] You can filter events using the *Filter* button. -.Login Event Filter -image:{project_images}/login-events-filter.png[Login Event Filter] +.Login Events Filter +image:{project_images}/login-events-filter.png[Login Events Filter] In this example, we filter only `Login` events. Click *Update* to run the filter. -==== Event Types +==== Event types *Login events:* @@ -98,11 +98,11 @@ In this example, we filter only `Login` events. Click *Update* to run the filter Each event has a corresponding error event. -==== Event Listener +==== Event listener Event listeners listen for events and perform actions based on that event. {project_name} includes two built-in listeners, the Logging Event Listener and Email Event Listener. -===== The Logging Event Listener +===== The logging event listener When the Logging Event Listener is enabled, this listener writes to a log file when an error event occurs. An example log message from a Logging Event Listener: diff --git a/server_admin/topics/export-import.adoc b/server_admin/topics/export-import.adoc index 362a08168d..2b9f8225b6 100644 --- a/server_admin/topics/export-import.adoc +++ b/server_admin/topics/export-import.adoc @@ -4,7 +4,7 @@ [role="_abstract"] {project_name} includes the ability to export and import its entire database. -You can migrate the whole {project_name} database from one environment to another or migrate to another database (for example from MySQL to Oracle). The export/import triggers at server boot time, and its parameters pass through Java properties. +You can migrate the whole {project_name} database from one environment to another or migrate to another database. The export/import triggers at server boot time, and its parameters pass through Java properties. [NOTE] ==== diff --git a/server_admin/topics/identity-broker/configuration.adoc b/server_admin/topics/identity-broker/configuration.adoc index 7a70cf0dc4..2d38e7a7c0 100644 --- a/server_admin/topics/identity-broker/configuration.adoc +++ b/server_admin/topics/identity-broker/configuration.adoc @@ -1,7 +1,7 @@ [[_general-idp-config]] -=== General Configuration +=== General configuration The foundations of the identity broker configuration are identity providers (IDPs). {project_name} creates identity providers for each realm and enables them for every application by default. Users from a realm can use any of the registered identity providers when signing in to an application. @@ -13,7 +13,7 @@ image:{project_images}/identity-providers.png[Identity Providers] + . From the `Add provider` list, select the identity provider you want to add. {project_name} displays the configuration page for the identity provider you selected. + -.Add Facebook Identity Provider +.Add facebook identity Provider image:{project_images}/add-identity-provider.png[Add Facebook Identity Provider] + When you configure an identity provider, the identity provider appears on the {project_name} login page as an option. You can place custom icons on the login screen for each identity provider. See link:{developerguide_link}#custom-identity-providers-icons[custom icons] for more information. diff --git a/server_admin/topics/identity-broker/first-login-flow.adoc b/server_admin/topics/identity-broker/first-login-flow.adoc index 788b514737..7c94e78b84 100644 --- a/server_admin/topics/identity-broker/first-login-flow.adoc +++ b/server_admin/topics/identity-broker/first-login-flow.adoc @@ -1,7 +1,7 @@ [[_identity_broker_first_login]] -=== First Login Flow +=== First login flow When users log in through identity brokering, {project_name} imports and links aspects of the user within the realm's local database. When {project_name} successfully authenticates users through an external identity provider, two situations can exist: @@ -16,7 +16,7 @@ ifeval::[{project_community}==true] You can also create a new authentication flow, write your own Authenticator implementations, and use it in your flow. See link:{developerguide_link}[{developerguide_name}] for more information. endif::[] -==== Default First Login Flow Authenticators +==== Default first login flow authenticators Review Profile:: * This authenticator displays the profile information page, so the users can review their profile that {project_name} retrieves from an identity provider. @@ -26,12 +26,16 @@ Review Profile:: * When *OFF*, the profile page does not display unless the user clicks in a later phase on the `Review profile info` link in the page displayed by the `Confirm Link Existing Account` authenticator. Create User If Unique:: + This authenticator checks if there is already an existing {project_name} account with the same email or username like the account from the identity provider. + If it's not, then the authenticator just creates a new local {project_name} account and links it with the identity provider and the whole flow is finished. + Otherwise it goes to the next `Handle Existing Account` subflow. + If you always want to ensure that there is no duplicated account, you can mark this authenticator as `REQUIRED`. In this case, the user + will see the error page if there is an existing {project_name} account and the user will need to link the identity provider account through Account management. * This authenticator verifies that there is already a {project_name} account with the same email or username as the identity provider's account. * If an account does not exist, the authenticator creates a local {project_name} account, links this account with the identity provider, and terminates the flow. * If an account exists, the authenticator implements the next `Handle Existing Account` sub-flow. * To ensure there is no duplicated account, you can mark this authenticator as `REQUIRED`. The user sees the error page if a {project_name} account exists, and users must link their identity provider account through Account management. -NOTE: If you want to skip the ability to create new users, but you want that users authenticated from identity provider must already exists in {project_name} with same username or email like the user from identity provider, you can create new flow and replace `Create User If Exists` authenticator with `Detect Existing Broker User` . More details in the <>. Confirm Link Existing Account:: * On the information page, users see a {project_name} account with the same email. Users can review their profile again and use a different email or username. The flow restarts and goes back to the `Review Profile` authenticator. @@ -48,7 +52,8 @@ Verify Existing Account By Re-authentication:: * Users can also re-authenticate with another identity provider already linked to their {project_name} account. * You can force users to use OTP. Otherwise, it is optional and used if you have set OTP for the user account. -==== Automatically Link Existing First Login Flow +==== Automatically link existing first login flow + [WARNING] ==== The AutoLink authenticator is dangerous in a generic environment where users can register themselves using arbitrary usernames or email addresses. Do not use this authenticator unless you are carefully curating user registration and assigning usernames and email addresses. @@ -70,7 +75,7 @@ This setup is the simplest setup available, but it is possible to use other auth ==== [[_disabling_automatic_user_creation]] -==== Disabling Automatic User Creation +==== Disabling automatic user creation The Default first login flow looks up the {project_name} account matching the external identity and offers to link them. If no matching {project_name} account exists, the flow automatically creates one. This default behavior may be unsuitable for some setups. One example is when you use a read-only LDAP user store, where all users are pre-created. In this case, you must switch off automatic user creation. @@ -87,7 +92,7 @@ This configuration also implies that Keycloak itself won't be able to determine Therefore, the `Verify Existing Account By Re-authentication` authenticator will ask the user to provide both username and password. [[_detect_existing_user_first_loging_flow]] -==== Detect Existing User First Login Flow +==== Detect existing user first login flow In order to configure a first login flow in which: - only users already registered in this realm can log in, @@ -102,12 +107,8 @@ Automatically Set Existing User:: Automatically sets an existing user to the authentication context without any verification. Set the authenticator requirement to `Mandatory`. You have to set the `First Login Flow` of the identity provider configuration to that flow. -You could set the also set `Sync Mode` to `force` if you want to update the user profile (Last Name, First Name, and so on) with the identity provider attributes. +You could set the also set `Sync Mode` to `force` if you want to update the user profile (Last Name, First Name...) with the identity provider attributes. -======= -NOTE: This flow can be used if you want to delegate the identity to other identity providers (such as github, facebook, and so on) but you want to manage which users that can log in. -======= +NOTE: This flow can be used if you want to delegate the identity to other identity providers (such as github, facebook ...) but you want to manage which users that can log in. With this configuration, {project_name} is unable to determine which internal account corresponds to the external identity. The *Verify Existing Account By Re-authentication* authenticator asks the provider for the username and password. - - diff --git a/server_admin/topics/identity-broker/mappers.adoc b/server_admin/topics/identity-broker/mappers.adoc index 2e5ba2e005..c54749baba 100644 --- a/server_admin/topics/identity-broker/mappers.adoc +++ b/server_admin/topics/identity-broker/mappers.adoc @@ -1,6 +1,6 @@ [[_mappers]] -=== Mapping Claims and Assertions +=== Mapping claims and assertions You can import the SAML and OpenID Connect metadata, provided by the external IDP you are authenticating with, into the realm. After importing, you can extract user profile metadata and other information, so you can make it available to your applications. @@ -11,12 +11,12 @@ Each user logging into your realm using an external identity provider has an ent . Select one of the identity providers in the list. . Click the *Mappers* tab. + -.identity provider mappers +.Identity provider mappers image:{project_images}/identity-provider-mappers.png[identity provider mappers] + . Click *Create*. + -.identity provider mapper +.Identity provider mapper image:{project_images}/identity-provider-mapper.png[identity provider mapper] + . Select a value for *Sync Mode Override*. The mapper updates user information when users log in repeatedly according to this setting. diff --git a/server_admin/topics/identity-broker/oidc.adoc b/server_admin/topics/identity-broker/oidc.adoc index 28916ed19e..a34f365f61 100644 --- a/server_admin/topics/identity-broker/oidc.adoc +++ b/server_admin/topics/identity-broker/oidc.adoc @@ -1,6 +1,6 @@ [[_identity_broker_oidc]] -=== OpenID Connect v1.0 Identity Providers +=== OpenID Connect v1.0 identity providers {project_name} brokers identity providers based on the OpenID Connect protocol. These identity providers (IDPs) must support the xref:proc-creating-oidc-client_{context}[Authorization Code Flow] defined in the specification to authenticate users and authorize access. @@ -9,12 +9,12 @@ . Click *Identity Providers* in the menu. . From the `Add provider` list, select `OpenID Connect v1.0`. + -.Add Identity Provider +.Add identity provider image:{project_images}/oidc-add-identity-provider.png[Add Identity Provider] + . Enter your initial configuration options. See <<_general-idp-config, General IDP Configuration>> for more information about configuration options. + -.OpenID Connect Config +.OpenID connect config |=== |Configuration|Description diff --git a/server_admin/topics/identity-broker/overview.adoc b/server_admin/topics/identity-broker/overview.adoc index fc0409c6e0..1ec4ba4825 100644 --- a/server_admin/topics/identity-broker/overview.adoc +++ b/server_admin/topics/identity-broker/overview.adoc @@ -1,7 +1,7 @@ [[_identity_broker_overview]] -=== Brokering Overview +=== Brokering overview When using {project_name} as an identity broker, {project_name} does not force users to provide their credentials to authenticate in a specific realm. {project_name} displays a list of identity providers from which they can authenticate. @@ -12,8 +12,8 @@ If you configure a default identity provider, {project_name} redirects users to Different protocols may require different authentication flows. All the identity providers supported by {project_name} use the following flow. ==== -.Identity Broker Flow -image:images/identity_broker_flow.png[Identity Broker Flow] +.Identity broker flow +image:images/identity_broker_flow.png[Identity broker flow] . The unauthenticated user requests a protected resource in a client application. . The client application redirects the user to {project_name} to authenticate. diff --git a/server_admin/topics/identity-broker/saml.adoc b/server_admin/topics/identity-broker/saml.adoc index bf99baf5bd..6aeba9ffed 100644 --- a/server_admin/topics/identity-broker/saml.adoc +++ b/server_admin/topics/identity-broker/saml.adoc @@ -7,7 +7,7 @@ . Click *Identity Providers* in the menu. . From the `Add provider` list, select `SAML v2.0`. + -.Add Identity Provider +.Add identity provider image:{project_images}/saml-add-identity-provider.png[Add Identity Provider] + . Enter your initial configuration options. See <<_general-idp-config, General IDP Configuration>> for more information about configuration options. @@ -32,6 +32,8 @@ image:{project_images}/saml-add-identity-provider.png[Add Identity Provider] |Principal Type |Specifies which part of the SAML assertion will be used to identify and track external user identities. Can be either Subject NameID or SAML attribute (either by name or by friendly name). Subject NameID value can not be set together with 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' NameID Policy Format value. +======= +|Specifies the part of the SAML assertion {project_name} uses to identify and track external user identities. The Principal Type can be Subject NameID or SAML attribute (by name or by friendly name). |Principal Attribute |If a Principal type is non-blank, this field specifies the name ("Attribute [Name]") or the friendly name ("Attribute [Friendly Name]") of the identifying attribute. @@ -110,7 +112,7 @@ http[s]://{host:port}/auth/realms/{realm-name}/broker/{broker-alias}/endpoint/de Ensure you save any configuration changes before accessing the descriptor. [[_identity_broker_saml_login_hint]] -==== Send Subject in SAML requests +==== Send subject in SAML requests By default, a social button pointing to a SAML Identity Provider redirects the user to the following login URL: diff --git a/server_admin/topics/identity-broker/session-data.adoc b/server_admin/topics/identity-broker/session-data.adoc index 91f066f89c..2e352bb950 100644 --- a/server_admin/topics/identity-broker/session-data.adoc +++ b/server_admin/topics/identity-broker/session-data.adoc @@ -1,5 +1,5 @@ -=== Available User Session Data +=== Available user session data After a user login from an external IDP, {project_name} stores user session note data that you can access. This data can be propagated to the client requesting log in using the token or SAML assertion passed back to the client using an appropriate client mapper. diff --git a/server_admin/topics/identity-broker/social/bitbucket.adoc b/server_admin/topics/identity-broker/social/bitbucket.adoc index 6114e049de..c8b46ce8d8 100644 --- a/server_admin/topics/identity-broker/social/bitbucket.adoc +++ b/server_admin/topics/identity-broker/social/bitbucket.adoc @@ -7,7 +7,7 @@ To log in with Bitbucket, perform the following procedure. . Click *Identity Providers* in the menu. . From the `Add provider` list, select `Bitbucket`. + -.Add Identity Provider +.Add identity provider image:{project_images}/bitbucket-add-identity-provider.png[Add Identity Provider] + . Copy the value of *Redirect URI* to your clipboard. diff --git a/server_admin/topics/identity-broker/social/facebook.adoc b/server_admin/topics/identity-broker/social/facebook.adoc index 9346031053..5c83c67479 100644 --- a/server_admin/topics/identity-broker/social/facebook.adoc +++ b/server_admin/topics/identity-broker/social/facebook.adoc @@ -6,7 +6,7 @@ . Click *Identity Providers* in the menu. . From the `Add provider` list, select `Facebook`. {project_name} displays the configuration page for the Facebook identity provider. + -.Add Identity Provider +.Add identity provider image:{project_images}/facebook-add-identity-provider.png[Add Identity Provider] . Copy the value of *Redirect URI* to your clipboard. . In a separate browser tab, follow the https://developers.facebook.com/docs/development/[Facebook Developer Guide's] instructions to create a project and client in Facebook. diff --git a/server_admin/topics/identity-broker/social/github.adoc b/server_admin/topics/identity-broker/social/github.adoc index a1d4b19851..80733a656e 100644 --- a/server_admin/topics/identity-broker/social/github.adoc +++ b/server_admin/topics/identity-broker/social/github.adoc @@ -3,17 +3,17 @@ ==== GitHub -To log in with Github, perform the following procedure. +To log in with Github, perform the following procedure. .Procedure . Click *Identity Providers* in the menu. . From the `Add provider` list, select `Github`. + -.Add Identity Provider +.Add identity provider image:{project_images}/github-add-identity-provider.png[Add Identity Provider] + . Copy the value of *Redirect URI* to your clipboard. -. In a separate browser tab, https://docs.github.com/en/developers/apps/creating-an-oauth-app[create an OAUTH app]. +. In a separate browser tab, https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[create an OAUTH app]. .. Enter the value of *Redirect URI* into the `Authorization callback URL` field when creating the app. .. Note the Client ID and Client secret on the management page of your OAUTH app. . In {project_name}, paste the value of the `Client ID` into the *Client ID* field. diff --git a/server_admin/topics/identity-broker/social/gitlab.adoc b/server_admin/topics/identity-broker/social/gitlab.adoc index b7c06ec0c5..23c2d206d5 100644 --- a/server_admin/topics/identity-broker/social/gitlab.adoc +++ b/server_admin/topics/identity-broker/social/gitlab.adoc @@ -5,8 +5,8 @@ . Click *Identity Providers* in the menu. . From the `Add provider` list, select `GitLab`. + -.Add Identity Provider -image:{project_images}/github-add-identity-provider.png[Add Identity Provider] +.Add identity provider +image:{project_images}/github-add-identity-provider.png[Add identity provider] + . Copy the value of *Redirect URI* to your clipboard. . In a separate browser tab, https://docs.gitlab.com/ee/integration/oauth_provider.html[add a new GitLab application]. diff --git a/server_admin/topics/identity-broker/social/google.adoc b/server_admin/topics/identity-broker/social/google.adoc index 357abde0f9..b74cc68a22 100644 --- a/server_admin/topics/identity-broker/social/google.adoc +++ b/server_admin/topics/identity-broker/social/google.adoc @@ -6,7 +6,7 @@ . Click *Identity Providers* in the menu. . From the `Add provider` list, select `Google`. + -.Add Identity Provider +.Add identity provider image:{project_images}/google-add-identity-provider.png[Add Identity Provider] + . In a separate browser tab, https://support.google.com/googleapi/answer/6251787[create a google project]. diff --git a/server_admin/topics/identity-broker/social/instagram.adoc b/server_admin/topics/identity-broker/social/instagram.adoc index 5a3aad4b61..1128b00ef9 100644 --- a/server_admin/topics/identity-broker/social/instagram.adoc +++ b/server_admin/topics/identity-broker/social/instagram.adoc @@ -5,33 +5,33 @@ . Click *Identity Providers* in the menu. . From the `Add provider` list, select `Instagram`. {project_name} displays the configuration page for the Instagram identity provider. + -.Add Identity Provider +.Add identity provider image:{project_images}/instagram-add-identity-provider.png[Add Identity Provider] . Copy the value of *Redirect URI* to your clipboard. . In a separate browser tab, open the https://developers.facebook.com/[Facebook Developer Console]. .. Click *My Apps*. .. Select *Add a New App*. + -.Add a New App +.Add a new app image:images/instagram-add-new-app.png[Add a New App] + .. Select `For Everything Else`. + -.Create a New App ID +.Create a new app ID image:images/instagram-create-app-id.png[] + .. Fill in all required fields. .. Click *Create App*. Facebook then brings you to the dashboard. .. In the navigation panel, select *Settings* - *Basic*. + -.Add Platform +.Add platform image:images/instagram-add-platform.png[Add Platform] + .. Select *+ Add Platform*. .. Click *[Website]*. .. Enter a URL for your site. + -.Add a Product +.Add a product image:images/instagram-add-product.png[] + .. Select `Dashboard` from the menu. @@ -39,12 +39,12 @@ image:images/instagram-add-product.png[] .. Select *Instagram* - *Basic Display* from the menu. .. Click *Create New App*. + -.Create a New Instagram App ID +.Create a new Instagram app ID image:images/instagram-create-instagram-app-id.png[Create a New Instagram App ID] + .. Enter a value into *Display Name*. + -.Setup the App +.Setup the app image:images/instagram-app-settings.png[Setup the App] + .. Paste the *Redirect URL* from {project_name} into the *Valid OAuth Redirect URIs* field. diff --git a/server_admin/topics/identity-broker/social/linked-in.adoc b/server_admin/topics/identity-broker/social/linked-in.adoc index a926b2c49b..ca6fcf9000 100644 --- a/server_admin/topics/identity-broker/social/linked-in.adoc +++ b/server_admin/topics/identity-broker/social/linked-in.adoc @@ -7,7 +7,7 @@ . Click *Identity Providers* in the menu. . From the `Add provider` list, select `LinkedIn`. + -.Add Identity Provider +.Add identity provider image:{project_images}/google-add-identity-provider.png[Add Identity Provider] + . Copy the value of *Redirect URI* to your clipboard. diff --git a/server_admin/topics/identity-broker/social/microsoft.adoc b/server_admin/topics/identity-broker/social/microsoft.adoc index 263943050a..b1947c085d 100644 --- a/server_admin/topics/identity-broker/social/microsoft.adoc +++ b/server_admin/topics/identity-broker/social/microsoft.adoc @@ -7,7 +7,7 @@ . Click *Identity Providers* in the menu. . From the `Add provider` list, select `Microsoft`. + -.Add Identity Provider +.Add identity provider image:{project_images}/google-add-identity-provider.png[Add Identity Provider] + . Copy the value of *Redirect URI* to your clipboard. diff --git a/server_admin/topics/identity-broker/social/openshift.adoc b/server_admin/topics/identity-broker/social/openshift.adoc index e7cf43ebfa..6acb637b92 100644 --- a/server_admin/topics/identity-broker/social/openshift.adoc +++ b/server_admin/topics/identity-broker/social/openshift.adoc @@ -5,7 +5,7 @@ . Click *Identity Providers* in the menu. . From the `Add provider` list, select `Openshift`. + -.Add Identity Provider +.Add identity provider image:images/openshift-add-identity-provider.png[Add Identity Provider] + . Copy the value of *Redirect URI* to your clipboard. @@ -51,7 +51,7 @@ curl -s -k -H "Authorization: Bearer $(oc whoami -t)" \https://>. To specify default roles go to the *Roles* left menu item, and click the *Default Roles* tab. -.Default Roles +.Default roles image:{project_images}/default-roles.png[] This screenshot shows that some _default roles_ already exist. diff --git a/server_admin/topics/roles-groups/con-role-scope-mappings.adoc b/server_admin/topics/roles-groups/con-role-scope-mappings.adoc index f934cd021e..7763a88e3a 100644 --- a/server_admin/topics/roles-groups/con-role-scope-mappings.adoc +++ b/server_admin/topics/roles-groups/con-role-scope-mappings.adoc @@ -2,7 +2,7 @@ [[_role_scope_mappings]] -= Role Scope Mappings += Role scope mappings [role="_abstract"] On creation of an OIDC access token or SAML assertion, the user role mappings become claims within the token or assertion. Applications use these claims to make access decisions on the resources controlled by the application. {project_name} digitally signs access tokens and applications re-use them to invoke remotely secured REST services. However, these tokens have an associated risk. An attacker can obtain these tokens and use their permissions to compromise your networks. To prevent this situation, use _Role Scope Mappings_. @@ -10,10 +10,10 @@ _Role Scope Mappings_ limit the roles declared inside an access token. When a c By default, each client gets all the role mappings of the user. You can view the role mappings in the *Scope* tab of each client. -.Full Scope -image:{project_images}/full-client-scope.png[] +.Full scope +image:{project_images}/full-client-scope.png[Full scope] -By default, the effective roles of scopes are every declared role in the realm. To change this default behavior, toggle *Full Scope Allowed* to ON and declare the specific roles you want in each client. You can also use <<_client_scopes, client scopes>> to define the same role scope mappings for a set of clients. +By default, the effective roles of scopes are every declared role in the realm. To change this default behavior, toggle *Full Scope Allowed* to *ON* and declare the specific roles you want in each client. You can also use <<_client_scopes, client scopes>> to define the same role scope mappings for a set of clients. -.Partial Scope -image:{project_images}/client-scope.png[] +.Partial scope +image:{project_images}/client-scope.png[Partial scope] diff --git a/server_admin/topics/roles-groups/proc-assigning-role-mappings.adoc b/server_admin/topics/roles-groups/proc-assigning-role-mappings.adoc index bb2a2c3c0b..d072181776 100644 --- a/server_admin/topics/roles-groups/proc-assigning-role-mappings.adoc +++ b/server_admin/topics/roles-groups/proc-assigning-role-mappings.adoc @@ -1,6 +1,6 @@ [id="proc-assigning-role-mappings_{context}"] -= Asssiging Role Mappings += Asssiging role mappings [role="_abstract"] You can assign role mappings to a user through the *Role Mappings* tab for that user. @@ -11,12 +11,12 @@ You can assign role mappings to a user through the *Role Mappings* tab for that . Click the role you want to assign to the user in the *Available Roles* box. . Click *Add selected*. -.Role Mappings -image:{project_images}/user-role-mappings.png[] +.Role mappings +image:{project_images}/user-role-mappings.png[Role mappings] In the preceding example, we are assigning the composite role *developer* to a user. That role was created in the <<_composite-roles, Composite Roles>> topic. -.Effective Role Mappings -image:{project_images}/effective-role-mappings.png[] +.Effective role mappings +image:{project_images}/effective-role-mappings.png[Effective role mappings] When the *developer* role is assigned, the *employee* role associated with the *developer* composite is displayed in the *Effective Roles* box. *Effective Roles* are the roles explicitly assigned to users and roles that are inherited from composites. diff --git a/server_admin/topics/roles-groups/proc-converting-composite-roles.adoc b/server_admin/topics/roles-groups/proc-converting-composite-roles.adoc index 3815edbe4b..878caa2fef 100644 --- a/server_admin/topics/roles-groups/proc-converting-composite-roles.adoc +++ b/server_admin/topics/roles-groups/proc-converting-composite-roles.adoc @@ -12,8 +12,8 @@ Any realm or client level role can become a _composite role_. A _composite role_ . Click the role that you want to convert. . Toggle *Composite Roles* to *ON*. -.Composite Role -image:{project_images}/composite-role.png[] +.Composite role +image:{project_images}/composite-role.png[Composite role] The role selection UI is displayed on the page and you can associate realm level and client level roles to the composite role you are creating. diff --git a/server_admin/topics/roles-groups/proc-creating-realm-roles.adoc b/server_admin/topics/roles-groups/proc-creating-realm-roles.adoc index c8766d3d98..1a9d9c05ab 100644 --- a/server_admin/topics/roles-groups/proc-creating-realm-roles.adoc +++ b/server_admin/topics/roles-groups/proc-creating-realm-roles.adoc @@ -1,6 +1,6 @@ [id="proc-creating-realm-roles_{context}"] -= Creating a Realm Role += Creating a realm role [role="_abstract"] Realm-level roles are a namespace for defining your roles. To see the list of roles, click *Roles* in the menu. @@ -12,7 +12,7 @@ image:{project_images}/roles.png[] . Enter a *Description*. . Click *Save*. -.Add Role -image:{project_images}/role.png[] +.Add role +image:{project_images}/role.png[Add role] The *description* field can be localizable by specifying a substitution variable with `$\{var-name}` strings. The localized value is configured to your theme within the themes property files. See the link:{developerguide_link}[{developerguide_name}] for more details. diff --git a/server_admin/topics/roles-groups/proc-managing-groups.adoc b/server_admin/topics/roles-groups/proc-managing-groups.adoc index 12dc36d829..7d342ce421 100644 --- a/server_admin/topics/roles-groups/proc-managing-groups.adoc +++ b/server_admin/topics/roles-groups/proc-managing-groups.adoc @@ -35,7 +35,7 @@ To add a user to a group: . Click the user that you want to perform a role mapping on. If the user is not displayed, click *View all users*. . Click *Groups*. + -.User Groups +.User groups image:{project_images}/user-groups.png[] + . Select a group from the *Available Groups* tree. @@ -48,5 +48,5 @@ To remove a group from a user: In this example, the user _jimlincoln_ is in the _North America_ group. You can see _jimlincoln_ displayed under the *Members* tab for the group. -.Group Membership +.Group membership image:{project_images}/group-membership.png[] diff --git a/server_admin/topics/roles-groups/proc-specifying-default-groups.adoc b/server_admin/topics/roles-groups/proc-specifying-default-groups.adoc index 55177582bc..f291ace45e 100644 --- a/server_admin/topics/roles-groups/proc-specifying-default-groups.adoc +++ b/server_admin/topics/roles-groups/proc-specifying-default-groups.adoc @@ -1,13 +1,13 @@ [id="proc-specifying-default-groups_{context}"] -= Using Default Groups += Using default groups [role="_abstract"] To automatically assign group membership to any users who is created or who is imported through <<_identity_broker, Identity Brokering>>, you use default groups. . Click *Groups* in the menu. . Click the *Default Groups* tab. -.Default Groups -image:{project_images}/default-groups.png[] +.Default groups +image:{project_images}/default-groups.png[Default groups] This screenshot shows that some _default groups_ already exist. diff --git a/server_admin/topics/roles-groups/proc-using-default-roles.adoc b/server_admin/topics/roles-groups/proc-using-default-roles.adoc index ef422c689c..b96224c12b 100644 --- a/server_admin/topics/roles-groups/proc-using-default-roles.adoc +++ b/server_admin/topics/roles-groups/proc-using-default-roles.adoc @@ -1,7 +1,7 @@ [id="proc-using-default-roles_{context}"] [[_default_roles]] -= Using Default Roles += Using default roles [role="_abstract"] Use default roles to automatically assign user role mappings when a user is created or imported through <<_identity_broker, Identity Brokering>>. @@ -10,7 +10,7 @@ Use default roles to automatically assign user role mappings when a user is crea . Click *Roles* in the menu . Click the *Default Roles* tab. -.Default Roles -image:{project_images}/default-roles.png[] +.Default roles +image:{project_images}/default-roles.png[Default roles] This screenshot shows that some _default roles_ already exist. diff --git a/server_admin/topics/sessions/administering.adoc b/server_admin/topics/sessions/administering.adoc index 4bc506fb52..099848b049 100644 --- a/server_admin/topics/sessions/administering.adoc +++ b/server_admin/topics/sessions/administering.adoc @@ -1,10 +1,10 @@ -=== Administering Sessions +=== Administering sessions To see a top-level view of the active clients and sessions in {project_name}, click *Sessions* from the menu. .Sessions -image:{project_images}/sessions.png[] +image:{project_images}/sessions.png[Sessions] ==== The *Logout all* Operation @@ -17,14 +17,14 @@ When you click the *Logout all* button, all SSO cookies become invalid, and clie Clicking *Logout all* does not revoke outstanding access tokens. Outstanding tokens must expire naturally. For clients using the {project_name} OIDC client adapter, you can push a <<_revocation-policy, revocation policy>> to revoke the token, but this does not work for other adapters. ==== -==== Application Navigation +==== Application navigation On the `Sessions` page, you can click on each client to go to that client's `Sessions` tab. Click the *Show Sessions* button there to see which users are in the application. -.Application Sessions +.Application sessions image:{project_images}/application-sessions.png[] -==== User Navigation +==== User navigation If you go to the `Sessions` tab of an individual user, you can also view the user's session information. diff --git a/server_admin/topics/sessions/offline.adoc b/server_admin/topics/sessions/offline.adoc index dcf310d8f6..349a5f1c21 100644 --- a/server_admin/topics/sessions/offline.adoc +++ b/server_admin/topics/sessions/offline.adoc @@ -1,7 +1,7 @@ [[_offline-access]] -=== Offline Access +=== Offline access [role="_abstract"] During https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[offline access] logins, the client application requests an offline token instead of a refresh token. The client application saves this offline token and can use it for future logins if the user logs out. This action is useful if your application needs to perform offline actions on behalf of the user even when the user is not online. For example, a regular data backup. diff --git a/server_admin/topics/sessions/preloading.adoc b/server_admin/topics/sessions/preloading.adoc index 1038e94c4e..d73c99315a 100644 --- a/server_admin/topics/sessions/preloading.adoc +++ b/server_admin/topics/sessions/preloading.adoc @@ -1,4 +1,4 @@ -=== Offline Sessions Preloading +=== Offline sessions preloading In addition to {jdgserver_name} caches, offline sessions are stored in a database which means they will be available even after server restart. By default, the offline sessions are preloaded from the database into the {jdgserver_name} caches during the server startup. @@ -10,7 +10,7 @@ It can be achieved by setting `preloadOfflineSessionsFromDatabase` property in ` The following example shows how to configure lazy offline sessions loading. [source,xml] ----- +---- ... diff --git a/server_admin/topics/sessions/revocation.adoc b/server_admin/topics/sessions/revocation.adoc index bf928910a4..b976b43dd4 100644 --- a/server_admin/topics/sessions/revocation.adoc +++ b/server_admin/topics/sessions/revocation.adoc @@ -1,7 +1,7 @@ [[_revocation-policy]] -=== Revocation Policies +=== Revocation policies [role="_abstract"] If your system is compromised, you can revoke all active sessions and access tokens by clicking the `Sessions` screen *Revocation* tab. diff --git a/server_admin/topics/sessions/timeouts.adoc b/server_admin/topics/sessions/timeouts.adoc index 295a5a4233..d2ccde58de 100644 --- a/server_admin/topics/sessions/timeouts.adoc +++ b/server_admin/topics/sessions/timeouts.adoc @@ -1,11 +1,11 @@ [[_timeouts]] -=== Session and Token Timeouts +=== Session and token timeouts [role="_abstract"] {project_name} includes control of the session, cookie, and token timeouts through the *Tokens* tab in the *Realm Settings* menu. -.Tokens Tab +.Tokens tab image:{project_images}/tokens-tab.png[] |=== @@ -25,10 +25,10 @@ image:{project_images}/tokens-tab.png[] |The maximum time before a user session expires. |SSO Session Idle Remember Me -|This setting is similar to the standard SSO Session Idle configuration but specific to logins with `Remember Me` enabled. Users can specify longer session idle timeouts when they click `Remember Me` when logging in. This setting is an optional configuration and, if its value is not greater than zero, it uses the same idle timeout as the SSO Session Idle configuration. +|This setting is similar to the standard SSO Session Idle configuration but specific to logins with *Remember Me* enabled. Users can specify longer session idle timeouts when they click *Remember Me* when logging in. This setting is an optional configuration and, if its value is not greater than zero, it uses the same idle timeout as the SSO Session Idle configuration. |SSO Session Max Remember Me -|This setting is similar to the standard SSO Session Max but specific to `Remember Me` logins. Users can specify longer sessions when they click `Remember Me` when logging in. This setting is an optional configuration and, if its value is not greater than zero, it uses the same session lifespan as the SSO Session Max configuration. +|This setting is similar to the standard SSO Session Max but specific to *Remember Me* logins. Users can specify longer sessions when they click *Remember Me* when logging in. This setting is an optional configuration and, if its value is not greater than zero, it uses the same session lifespan as the SSO Session Max configuration. [[_offline-session-idle]] |Offline Session Idle diff --git a/server_admin/topics/sso-protocols.adoc b/server_admin/topics/sso-protocols.adoc index 0e0873d8d3..19403863f1 100644 --- a/server_admin/topics/sso-protocols.adoc +++ b/server_admin/topics/sso-protocols.adoc @@ -1,5 +1,5 @@ -== SSO Protocols +== SSO protocols [role="_abstract"] This section discusses authentication protocols, the {project_name} authentication server and how applications, secured by the {project_name} authentication server, interact with these protocols. diff --git a/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc b/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc index 9debd4dc5e..18b9ce5ecc 100644 --- a/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc +++ b/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc @@ -1,6 +1,6 @@ [id="con-oidc-auth-flows_{context}"] -==== OIDC Auth Flows +==== OIDC auth flows [role="_abstract"] OIDC has several methods, or flows, that clients or applications can use to authenticate users and receive _identity_ and _access_ tokens. The method depends on the type of application or client requesting access. @@ -20,14 +20,14 @@ to exchange the code for an _identity_ and _access_ and _refresh_ token. To pre [NOTE] ==== -A system is vulnerable to a stolen token for the lifetime of that token. For security and scalability reasons, access_ tokens are generally set to expire quickly so subsequent token requests fail. If a token expires, an application can obtain a new access token using the additional _refresh_ token sent by the login protocol. +A system is vulnerable to a stolen token for the lifetime of that token. For security and scalability reasons, access tokens are generally set to expire quickly so subsequent token requests fail. If a token expires, an application can obtain a new access token using the additional _refresh_ token sent by the login protocol. ==== [[_confidential-clients]] _Confidential_ clients provide client secrets when they exchange the temporary codes for tokens. _Public_ clients are not required to provide client secrets. _Public_ clients are secure when HTTPS is strictly enforced and redirect URIs registered for the client are strictly controlled. HTML5/JavaScript clients have to be _public_ clients because there is no way to securely transmit the client secret to HTML5/JavaScript clients. For more details, see the xref:assembly-managing-clients_{context}[Managing Clients] chapter. -{project_name} also supports the https://tools.ietf.org/html/rfc7636[Proof Key for Code Exchange] specification. +{project_name} also supports the https://datatracker.ietf.org/doc/html/rfc7636[Proof Key for Code Exchange] specification. [[_oidc-auth-flows-implicit]] @@ -55,7 +55,7 @@ redirects to the application using the callback URL and additionally adds the _i [[_oidc-auth-flows-direct]] -===== Resource Owner Password Credentials Grant (Direct Access Grants) +===== Resource owner password credentials grant (Direct Access Grants) _Direct Access Grants_ are used by REST clients to obtain tokens on behalf of users. It is a HTTP POST request that contains: @@ -66,13 +66,13 @@ _Direct Access Grants_ are used by REST clients to obtain tokens on behalf of us The HTTP response contains the _identity_, _access_, and _refresh_ tokens. [[_client_credentials_grant]] -===== Client Credentials Grant +===== Client credentials grant The _Client Credentials Grant_ creates a token based on the metadata and permissions of a service account associated with the client instead of obtaining a token that works on behalf of an external user. _Client Credentials Grants_ are used by REST clients. See the <<_service_accounts,Service Accounts>> chapter for more information. -===== Device Authorization Grant +===== Device authorization grant This is used by clients running on internet-connected devices that have limited input capabilities or lack a suitable browser. Here's a brief summary of the protocol: @@ -81,7 +81,7 @@ This is used by clients running on internet-connected devices that have limited . The application repeatedly polls {project_name} to find out if the user completed the user authorization. If user authentication is complete, the application exchanges the device code for an _identity_, _access_ and _refresh_ token. [[_client_initiated_backchannel_authentication_grant]] -===== Client Initiated Backchannel Authentication Grant +===== Client initiated backchannel authentication grant :tech_feature_name: Client Initiated Backchannel Authentication Grant :tech_feature_setting: -Dkeycloak.profile.feature.ciba=enabled @@ -298,3 +298,32 @@ User Resolver Provider is provided as SPI provider so that users of {project_nam * Only support `login_hint` parameter and is used as default. * `username` of UserModel in {project_name} is used to represent the user on CD, {project_name} and the authentication entity. +[[_oidc-logout]] + +==== OIDC Logout + +OIDC has three different specifications relevant to logout mechanisms, all of these are currently in draft status: + +. https://openid.net/specs/openid-connect-session-1_0.html[Session Management] +. https://openid.net/specs/openid-connect-frontchannel-1_0.html[Front-Channel Logout] +. https://openid.net/specs/openid-connect-backchannel-1_0.html[Back-Channel Logout] + +Again since all of this is described in the OIDC specification we will only give a brief overview here. + +===== Session Management + +This is a browser-based logout. The application obtains session status information from {project_name} at a regular basis. +When the session is terminated at {project_name} the application will notice and trigger it's own logout. + +===== Frontchannel Logout + +This is also a browser-based logout. In contrast to the Session Managment based logout approach {project_name} will send logout +requests to the clients. Applications or clients need to have a frontchannel logout URL registered at {project_name}. +After triggering a logout at {project_name}, it will send logout requests to these registered URLs that will terminate the client sessions. + +===== Backchannel Logout + +This is a non browser-based logout that uses direct backchannel communication between {project_name} and clients. +{project_name} sends a HTTP POST request containing a logout token to all clients logged into {project_name}. These +requests are sent to a registered backchannel logout URLs at {project_name} and are supposed to trigger a logout at client side. + diff --git a/server_admin/topics/sso-protocols/con-oidc.adoc b/server_admin/topics/sso-protocols/con-oidc.adoc index db376c30dc..ed6308f790 100644 --- a/server_admin/topics/sso-protocols/con-oidc.adoc +++ b/server_admin/topics/sso-protocols/con-oidc.adoc @@ -2,19 +2,19 @@ === OpenID Connect [role="_abstract"] -link:https://openid.net/connect/[OpenID Connect] (OIDC) is an authentication protocol that is an extension of link:https://tools.ietf.org/html/rfc6749[OAuth 2.0]. +link:https://openid.net/connect/[OpenID Connect] (OIDC) is an authentication protocol that is an extension of link:https://datatracker.ietf.org/doc/html/rfc6749[OAuth 2.0]. OAuth 2.0 is a framework for building authorization protocols and is incomplete. OIDC, however, is a full authentication and authorization protocol that uses the link:https://jwt.io[Json Web Token] (JWT) standards. The JWT standards define an identity token JSON format and methods to digitally sign and encrypt data in a compact and web-friendly way. -In general, OIDC implements two use cases. The first case is an application requesting that a {project_name} server authenticates a user. Upon successful login, the application receives an _identity token_ and an _access token_. +In general, OIDC implements two use cases. The first case is an application requesting that a {project_name} server authenticates a user. Upon successful login, the application receives an _identity token_ and an _access token_. The _identity token_ contains user information including user name, email, and profile information. The realm digitally signs the _access token_ which contains access information (such as user role mappings) that applications use to determine the resources users can access in the application. -The second use case is a client accessing remote services. +The second use case is a client accessing remote services. -* The client requests an _access token_ from {project_name} to invoke on remote services on behalf of the user. +* The client requests an _access token_ from {project_name} to invoke on remote services on behalf of the user. * {project_name} authenticates the user and asks the user for consent to grant access to the requesting client. -* The client receives the _access token_ which is digitally signed by the realm. -* The client makes REST requests on remote services using the _access token_. +* The client receives the _access token_ which is digitally signed by the realm. +* The client makes REST requests on remote services using the _access token_. * The remote REST service extracts the _access token_. * The remote REST service verifies the tokens signature. * The remote REST service decides, based on access information within the token, to process or reject the request. diff --git a/server_admin/topics/sso-protocols/con-saml-bindings.adoc b/server_admin/topics/sso-protocols/con-saml-bindings.adoc index 0182ccca33..e8004f1d1f 100644 --- a/server_admin/topics/sso-protocols/con-saml-bindings.adoc +++ b/server_admin/topics/sso-protocols/con-saml-bindings.adoc @@ -1,10 +1,10 @@ [id="con-saml-bindings_{context}"] -==== SAML Bindings +==== SAML bindings [role="_abstract"] {project_name} supports three binding types. -===== Redirect Binding +===== Redirect binding _Redirect_ binding uses a series of browser redirect URIs to exchange information. @@ -18,19 +18,15 @@ _Redirect_ binding uses a series of browser redirect URIs to exchange informatio . The application receives the redirect URI and extracts the XML document. . The application verifies the realm's signature to ensure it is receiving a valid authentication response. The information inside the SAML assertion is used to make access decisions or display user data. -===== POST Binding +===== POST binding _POST_ binding is similar to _Redirect_ binding but _POST_ binding exchanges XML documents using POST requests instead of using GET requests. _POST_ Binding uses JavaScript to make the browser send a POST request to the {project_name} server or application when exchanging documents. HTTP responds with an HTML document which contains an HTML form containing embedded JavaScript. When the page loads, the JavaScript automatically invokes the form. _POST_ binding is recommended due to two restrictions: -*Security* +* *Security* -- With _Redirect_ binding, the SAML response is part of the URL. It is less secure as it is possible to capture the response in logs. -With _Redirect_ binding, the SAML response is part of the URL. It is less secure as it is possible to capture the response in logs. - -*Size* - -Sending the document in the HTTP payload provides more scope for large amounts of data than in a limited URL. +* *Size* -- Sending the document in the HTTP payload provides more scope for large amounts of data than in a limited URL. ===== ECP diff --git a/server_admin/topics/sso-protocols/con-server-oidc-uri-endpoints.adoc b/server_admin/topics/sso-protocols/con-server-oidc-uri-endpoints.adoc index bd169f57f5..fc17011f41 100644 --- a/server_admin/topics/sso-protocols/con-server-oidc-uri-endpoints.adoc +++ b/server_admin/topics/sso-protocols/con-server-oidc-uri-endpoints.adoc @@ -1,8 +1,8 @@ [id="con-server-oidc-uri-endpoints_{context}"] -==== {project_name} Server OIDC URI Endpoints +==== {project_name} server OIDC URI endpoints [role="_abstract"] -The following is a list of OIDC endpoints that {project_name} publishes. These endpoints can be used when a non-{project_name} client adapter uses OIDC to communicate with the authentication server. They are all relative URLs. The root of the URL consists of the HTTP(S) protocol, hostname, and the path, which is usually prefixed with _/auth_: For example +The following is a list of OIDC endpoints that {project_name} publishes. These endpoints can be used when a non-{project_name} client adapter uses OIDC to communicate with the authentication server. They are all relative URLs. The root of the URL consists of the HTTP(S) protocol, hostname, and the path, which is usually prefixed with _/auth_: For example [source, subs="attributes"] ---- @@ -22,11 +22,11 @@ https://localhost:8080/auth Used for the User Info service described in the OIDC specification. /realms/{realm-name}/protocol/openid-connect/revoke:: - Used for OAuth 2.0 Token Revocation described in https://tools.ietf.org/html/rfc7009[RFC7009]. + Used for OAuth 2.0 Token Revocation described in https://datatracker.ietf.org/doc/html/rfc7009[RFC7009]. /realms/{realm-name}/protocol/openid-connect/certs:: Used for the JSON Web Key Set (JWKS) containing the public keys used to verify any JSON Web Token (jwks_uri) - + /realms/{realm-name}/protocol/openid-connect/auth/device:: Used for Device Authorization Grant to obtain a device code and a user code. diff --git a/server_admin/topics/sso-protocols/con-sso-docker.adoc b/server_admin/topics/sso-protocols/con-sso-docker.adoc index 423624b7e3..3c8f1f4277 100644 --- a/server_admin/topics/sso-protocols/con-sso-docker.adoc +++ b/server_admin/topics/sso-protocols/con-sso-docker.adoc @@ -2,7 +2,7 @@ [[_docker]] -=== Docker Registry v2 Authentication +=== Docker registry v2 authentication [NOTE] ==== @@ -11,12 +11,12 @@ Docker authentication is disabled by default. To enable docker authentication, s [role="_abstract"] link:https://docs.docker.com/registry/spec/auth/[Docker Registry V2 Authentication] is a protocol, similar to OIDC, that authenticates users against Docker registries. {project_name}'s implementation of this protocol lets Docker clients use a {project_name} authentication server authenticate against a registry. This protocol uses standard token and signature mechanisms but it does deviate from a true OIDC implementation. It deviates by using a very specific JSON format for requests and responses as well as mapping repository names and permissions to the OAuth scope mechanism. -==== Docker Authentication Flow +==== Docker authentication flow The authentication flow is described in the link:https://docs.docker.com/registry/spec/auth/token/[Docker API documentation]. The following is a summary from the perspective of the {project_name} authentication server: * Perform a `docker login`. * The Docker client requests a resource from the Docker registry. If the resource is protected and no authentication token is in the request, the Docker registry server responds with a 401 HTTP message with some information on the permissions that are required and the location of the authorization server. -* The Docker client constructs an authentication request based on the 401 HTTP message from the Docker registry. The client uses the locally cached credentials (from the `docker login` command) as part of the link:https://tools.ietf.org/html/rfc2617[HTTP Basic Authentication] request to the {project_name} authentication server. +* The Docker client constructs an authentication request based on the 401 HTTP message from the Docker registry. The client uses the locally cached credentials (from the `docker login` command) as part of the link:https://datatracker.ietf.org/doc/html/rfc2617[HTTP Basic Authentication] request to the {project_name} authentication server. * The {project_name} authentication server attempts to authenticate the user and return a JSON body containing an OAuth-style Bearer token. * The Docker client receives a bearer token from the JSON response and uses it in the authorization header to request the protected resource. * The Docker registry receives the new request for the protected resource with the token from the {project_name} server. The registry validates the token and grants access to the requested resource (if appropriate). diff --git a/server_admin/topics/threat.adoc b/server_admin/topics/threat.adoc index 4ec825ae04..3c09664c7c 100644 --- a/server_admin/topics/threat.adoc +++ b/server_admin/topics/threat.adoc @@ -1,4 +1,4 @@ == Mitigating security threats -Security vulnerabilities exist in any authentication server. See the Internet Engineering Task Force's (IETF) https://tools.ietf.org/html/rfc6819[OAuth 2.0 Threat Model] and the https://tools.ietf.org/html/draft-ietf-oauth-security-topics-15[OAuth 2.0 Security Best Current Practice] for more information. +Security vulnerabilities exist in any authentication server. See the Internet Engineering Task Force's (IETF) https://datatracker.ietf.org/doc/html/rfc6819[OAuth 2.0 Threat Model] and the https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-15[OAuth 2.0 Security Best Current Practice] for more information. diff --git a/server_admin/topics/threat/admin.adoc b/server_admin/topics/threat/admin.adoc index 19a2d0f3e9..ca7e7e1cca 100644 --- a/server_admin/topics/threat/admin.adoc +++ b/server_admin/topics/threat/admin.adoc @@ -1,5 +1,5 @@ -=== Admin Endpoints and Console +=== Admin endpoints and Admin Console {project_name} exposes the administrative REST API and the web console on the same port as non-administrative usage by default. Do not expose administrative endpoints externally if external access is not necessary. If you need to expose administrative endpoints externally, you can expose them directly in {project_name} or use a proxy. @@ -9,7 +9,7 @@ Two options are available in {project_name} to expose endpoints directly, IP res When the Admin Console becomes inaccessible on the frontend URL of {project_name}, configure a fixed admin URL in the default hostname provider. -==== IP Restriction +==== IP restriction You can restrict access to `/auth/admin` to only specific IP addresses. For example, restrict access to `/auth/admin` to IP addresses in the range `10.0.0.1` to `10.0.0.255`. @@ -44,7 +44,7 @@ You can also restrict access to specific IP addresses by using these CLI command For IP restriction using a proxy, configure the proxy to ensure {project_name} receives the client IP address and not the proxy IP address. ==== -==== Port Restriction +==== Port restriction You can expose `/auth/admin` to a different unexposed port. For example, expose `/auth/admin` on port `8444` and prevent access to the default port `8443`. diff --git a/server_admin/topics/threat/audience-limit.adoc b/server_admin/topics/threat/audience-limit.adoc index 81bf099bd2..aeb3cf57a6 100644 --- a/server_admin/topics/threat/audience-limit.adoc +++ b/server_admin/topics/threat/audience-limit.adoc @@ -1,4 +1,5 @@ -=== Limit Token Audience +=== Limit token audience -In environments with low levels of trust among services, limit the audiences on the token. See the https://tools.ietf.org/html/rfc6819#section-5.1.5.5[OAuth2 Threat Model] and the xref:con-audience_{context}[Audience Support] section for more information. +In environments with low levels of trust among services, limit the audiences on the token. See the https://datatracker.ietf.org/doc/html/rfc6819#section-5.1.5.5[OAuth2 Threat Model] and the +<> section for more information. diff --git a/server_admin/topics/threat/auth-sessions-limit.adoc b/server_admin/topics/threat/auth-sessions-limit.adoc index d41500d43a..0ff3140725 100644 --- a/server_admin/topics/threat/auth-sessions-limit.adoc +++ b/server_admin/topics/threat/auth-sessions-limit.adoc @@ -4,31 +4,31 @@ When a login page is opened for the first time in a web browser, {project_name} creates an object called authentication session that stores some useful information about the request. Whenever a new login page is opened from a different tab in the same browser, {project_name} creates a new record called authentication sub-session that is stored within the authentication session. Authentication requests can come from any type of clients such as the Admin CLI. In that case, a new authentication session is also created with one authentication sub-session. -Please note that authentication sessions can be created also in other ways than using a browser flow. The text below is applicable regardless of the source flow. +Please note that authentication sessions can be created also in other ways than using a browser flow. The text below is applicable regardless of the source flow. NOTE: This section describes deployments that use the {jdgserver_name} provider for authentication sessions. Authentication session is internally stored as `RootAuthenticationSessionEntity`. Each `RootAuthenticationSessionEntity` can have multiple authentication sub-sessions stored within the `RootAuthenticationSessionEntity` as a collection of `AuthenticationSessionEntity` objects. {project_name} stores authentication sessions in a dedicated {jdgserver_name} cache. -The number of `AuthenticationSessionEntity` per `RootAuthenticationSessionEntity` contributes to the size of each cache entry. Total memory footprint of authentication session cache is determined by +The number of `AuthenticationSessionEntity` per `RootAuthenticationSessionEntity` contributes to the size of each cache entry. Total memory footprint of authentication session cache is determined by the number of stored `RootAuthenticationSessionEntity` and by the number of `AuthenticationSessionEntity` within each `RootAuthenticationSessionEntity`. The number of maintained `RootAuthenticationSessionEntity` objects corresponds to the number of unfinished login flows from the browser. To keep the number of `RootAuthenticationSessionEntity` under control, using an advanced firewall control to limit ingress network traffic is recommended. - + Higher memory usage may occur for deployments where there are many active `RootAuthenticationSessionEntity` with a lot of `AuthenticationSessionEntity`. If the load balancer does not support or is not configured for link:{installguide_stickysessions_link}[session stickiness], the load over network in a cluster can increase significantly. The reason for this load is that each request that lands on a node that does not own the appropriate authentication session needs to retrieve and update the authentication session record in the owner node which involves a separate network transmission for both the retrieval and the storage. - + The maximum number of `AuthenticationSessionEntity` per `RootAuthenticationSessionEntity` can be configured in `authenticationSessions` SPI by setting property `authSessionsLimit`. The default value is set to 300 `AuthenticationSessionEntity` per a `RootAuthenticationSessionEntity`. When this limit is reached, the oldest authentication sub-session will be removed after a new authentication session request. The following example shows how to limit the number of active `AuthenticationSessionEntity` per a `RootAuthenticationSessionEntity` to 100. [source,xml] ----- +---- ... @@ -50,4 +50,3 @@ Equivalent configuration using CLI commands: /subsystem=keycloak-server/spi=authenticationSessions:add(default-provider=infinispan) /subsystem=keycloak-server/spi=authenticationSessions/provider=infinispan:add(properties={authSessionsLimit => "100"},enabled=true) ---- - diff --git a/server_admin/topics/threat/brute-force.adoc b/server_admin/topics/threat/brute-force.adoc index e7c06d4f7f..d7acdc3dfb 100644 --- a/server_admin/topics/threat/brute-force.adoc +++ b/server_admin/topics/threat/brute-force.adoc @@ -1,5 +1,6 @@ -=== Brute Force Attacks +[[password-guess-brute-force-attacks]] +=== Brute force attacks A brute force attack attempts to guess a user's password by trying to log in multiple times. {project_name} has brute force detection capabilities and can temporarily disable a user account if the number of login failures exceeds a specified threshold. @@ -12,11 +13,11 @@ A brute force attack attempts to guess a user's password by trying to log in mul To enable this protection: -. Click the *Realm Settings* menu +. Click *Realm Settings* in the menu . Click the *Security Defenses* tab. . Click the *Brute Force Detection* tab. + -.Brute Force Detection +.Brute force detection image:{project_images}/brute-force.png[] {project_name} can deploy permanent lockout and temporary lockout actions when it detects an attack. Permanent lockout disables a user account until an administrator re-enables it. Temporary lockout disables a user account for a specific period of time. The time period that the account is disabled increases as the attack continues. @@ -97,6 +98,6 @@ The downside of {project_name} brute force detection is that the server becomes Consider using intrusion prevention software (IPS). {project_name} logs every login failure and client IP address failure. You can point the IPS to the {project_name} server's log file, and the IPS can modify firewalls to block connections from these IP addresses. -==== Password Policies +==== Password policies Ensure you have a complex password policy to force users to choose complex passwords. See the <<_password-policies, Password Policies>> chapter for more information. Prevent password guessing by setting up the {project_name} server to use one-time-passwords. diff --git a/server_admin/topics/threat/clickjacking.adoc b/server_admin/topics/threat/clickjacking.adoc index 442b7b9f84..85cb81d1f0 100644 --- a/server_admin/topics/threat/clickjacking.adoc +++ b/server_admin/topics/threat/clickjacking.adoc @@ -3,18 +3,12 @@ Clickjacking is a technique of tricking users into clicking on a user interface element different from what users perceive. A malicious site loads the target site in a transparent iFrame, overlaid on top of a set of dummy buttons placed directly under important buttons on the target site. When a user clicks a visible button, they are clicking a button on the hidden page. An attacker can steal a user's authentication credentials and access their resources by using this method. -<<<<<<< HEAD By default, every response by {project_name} sets some specific browser headers that can prevent this from happening. Specifically, it sets https://datatracker.ietf.org/doc/html/rfc7034[X-FRAME_OPTIONS] and http://www.w3.org/TR/CSP/[Content-Security-Policy]. You should take a look at the definition of both of these headers as there is a lot of fine-grain browser access you can control. -In the admin console you can specify the values these headers will have. Go to the `Realm Settings` left menu item and -click the `Security Defenses` tab and make sure you are on the `Headers` sub-tab. -======= -By default, every response by {project_name} sets the https://tools.ietf.org/html/rfc7034[X-FRAME_OPTIONS] and http://www.w3.org/TR/CSP/[Content-Security-Policy] browser headers to prevent clickjacking. See the documentation for these headers for details on fine-grain browser access. ->>>>>>> 88fa9a3a... KEYCLOAK-15790 Security Threats rewrite (#57) .Procedure -In the Admin Console, you can specify the values of the X-FRAME_OPTIONS and Content-Security-Policy headers. +In the Admin Console, you can specify the values of the X-FRAME_OPTIONS and Content-Security-Policy headers. . Click the *Realm Settings* menu item. . Click the *Security Defenses* tab. diff --git a/server_admin/topics/threat/compromised-codes.adoc b/server_admin/topics/threat/compromised-codes.adoc index ceefedb8a3..86ab88d9ef 100644 --- a/server_admin/topics/threat/compromised-codes.adoc +++ b/server_admin/topics/threat/compromised-codes.adoc @@ -1,5 +1,5 @@ -=== Compromised Authorization Code +=== Compromised authorization code For the xref:con-oidc-auth-flows_{context}[OIDC Auth Code Flow], {project_name} generates a cryptographically strong random value for its authorization codes. An authorization code is used only once to obtain an access token. diff --git a/server_admin/topics/threat/compromised-tokens.adoc b/server_admin/topics/threat/compromised-tokens.adoc index 756dab89bf..45152cf3ad 100644 --- a/server_admin/topics/threat/compromised-tokens.adoc +++ b/server_admin/topics/threat/compromised-tokens.adoc @@ -1,5 +1,5 @@ -=== Compromised Access and Refresh Tokens +=== Compromised access and refresh tokens {project_name} includes several actions to prevent malicious actors from stealing access tokens and refresh tokens. The crucial action is to enforce SSL/HTTPS communication between {project_name} and its clients and applications. {project_name} does not enable SSL by default. diff --git a/server_admin/topics/threat/csrf.adoc b/server_admin/topics/threat/csrf.adoc index 1d09d81326..f5d3358c99 100644 --- a/server_admin/topics/threat/csrf.adoc +++ b/server_admin/topics/threat/csrf.adoc @@ -1,5 +1,5 @@ -=== CSRF Attacks +=== CSRF attacks A Cross-site request forgery (CSRF) attack uses HTTP requests from users that websites have already authenticated. Any site using cookie-based authentication is vulnerable to CSRF attacks. You can mitigate these attacks by matching a state cookie against a posted form or query parameter. diff --git a/server_admin/topics/threat/read-only-attributes.adoc b/server_admin/topics/threat/read-only-attributes.adoc index 3907047135..c7753d5597 100644 --- a/server_admin/topics/threat/read-only-attributes.adoc +++ b/server_admin/topics/threat/read-only-attributes.adoc @@ -1,5 +1,5 @@ [[_read_only_user_attributes]] -=== Read-only User Attributes +=== Read-only user attributes Typical users who are stored in {project_name} have various attributes related to their user profiles. Such attributes include email, firstName or lastname. However users may also have attributes, which are not typical profile data, but rather metadata. The metadata attributes usually should be read-only for the users diff --git a/server_admin/topics/threat/redirect.adoc b/server_admin/topics/threat/redirect.adoc index ffbf13e105..eeca92d712 100644 --- a/server_admin/topics/threat/redirect.adoc +++ b/server_admin/topics/threat/redirect.adoc @@ -1,5 +1,5 @@ [id="unspecific-redirect-uris_{context}"] -=== Unspecific Redirect URIs +=== Unspecific redirect URIs Make your registered redirect URIs as specific as feasible. Registering vague redirect URIs for xref:con-oidc-auth-flows_{context}[Authorization Code Flows] can allow malicious clients to impersonate another client with broader access. Impersonation can happen if two clients live under the same domain, for example. diff --git a/server_admin/topics/threat/scope.adoc b/server_admin/topics/threat/scope.adoc index 5b409ef21f..6681551cea 100644 --- a/server_admin/topics/threat/scope.adoc +++ b/server_admin/topics/threat/scope.adoc @@ -1,5 +1,5 @@ -=== Limiting Scope +=== Limiting scope By default, new client applications have unlimited `role scope mappings`. Every access token for that client contains all permissions that the user has. If an attacker compromises the client and obtains the client's access tokens, each system that the user can access is compromised. diff --git a/server_admin/topics/threat/sql.adoc b/server_admin/topics/threat/sql.adoc index f4a46351d2..7ac18a716c 100644 --- a/server_admin/topics/threat/sql.adoc +++ b/server_admin/topics/threat/sql.adoc @@ -1,4 +1,4 @@ -=== SQL Injection Attacks +=== SQL injection attacks Currently, {project_name} has no known SQL injection vulnerabilities. diff --git a/server_admin/topics/threat/ssl.adoc b/server_admin/topics/threat/ssl.adoc index 6390d89740..31827d3fd7 100644 --- a/server_admin/topics/threat/ssl.adoc +++ b/server_admin/topics/threat/ssl.adoc @@ -1,5 +1,5 @@ -=== SSL/HTTPS Requirement +=== SSL/HTTPS requirement OAuth 2.0/OpenID Connect uses access tokens for security. Attackers can scan your network for access tokens and use them to perform malicious operations for which the token has permission. This attack is known as a man-in-the-middle attack. Use SSL/HTTPS for communication between the {project_name} auth server and the clients {project_name} secures to prevent man-in-the-middle attacks. diff --git a/server_admin/topics/user-federation.adoc b/server_admin/topics/user-federation.adoc index 1fbab20aca..26084d444d 100644 --- a/server_admin/topics/user-federation.adoc +++ b/server_admin/topics/user-federation.adoc @@ -15,8 +15,8 @@ To add a storage provider, perform the following procedure: .Procedure . Click *User Federation* in the menu. + -.User Federation -image:{project_images}/user-federation.png[User Federation] +.User federation +image:{project_images}/user-federation.png[User federation] + . Select the provider type from the *Add Provider* list. {project_name} brings you to that provider's configuration page. diff --git a/server_admin/topics/user-federation/custom.adoc b/server_admin/topics/user-federation/custom.adoc index 0c899b9995..daf105cbad 100644 --- a/server_admin/topics/user-federation/custom.adoc +++ b/server_admin/topics/user-federation/custom.adoc @@ -1,4 +1,4 @@ -=== Custom Providers +=== Custom providers {project_name} does have a Service Provider Interface (SPI) for User Storage Federation to develop custom providers. You can find documentation on developing customer providers in the link:{developerguide_link}[{developerguide_name}]. diff --git a/server_admin/topics/user-federation/ldap.adoc b/server_admin/topics/user-federation/ldap.adoc index 4ac5590cde..6a9af5a0d7 100644 --- a/server_admin/topics/user-federation/ldap.adoc +++ b/server_admin/topics/user-federation/ldap.adoc @@ -6,17 +6,17 @@ By default, {project_name} maps the username, email, first name, and last name of the user account, but you can also configure additional <<_ldap_mappers,mappings>>. {project_name}'s LDAP/AD provider supports password validation using LDAP/AD protocols and storage, edit, and synchronization modes. -==== Configuring Federated LDAP Storage +==== Configuring federated LDAP storage .Procedure . Click *User Federation* in the menu. + -.User Federation -image:{project_images}/user-federation.png[User Federation] +.User federation +image:{project_images}/user-federation.png[User federation] + . Select _ldap_ from the *Add Provider* list. {project_name} brings you to the LDAP configuration page. -==== Storage Mode +==== Storage mode {project_name} imports users from LDAP into the local {project_name} user database. This copy of the user database synchronizes on-demand or through a periodic background task. An exception exists for synchronizing passwords. {project_name} never imports passwords. Password validation always occurs on the LDAP server. @@ -35,7 +35,7 @@ If you disable *Import Users*, you cannot save user profile attributes into the When you attempt to change the non-LDAP mapped user data, the user update is not possible. For example, you cannot disable the LDAP mapped user unless the user's `enabled` flag maps to an LDAP attribute. ==== -==== Edit Mode +==== Edit mode Users and admins can modify user metadata, users through the <<_account-service, Account Console>>, and administrators through the Admin Console. The `Edit Mode` configuration on the LDAP configuration page defines the user's LDAP update privileges. @@ -95,12 +95,11 @@ When synchronizing, {project_name} creates or updates users created or updated a The best way to synchronize is to click *Synchronize all users* when you first create the LDAP provider, then set up periodic synchronization of changed users. [[_ldap_mappers]] - -==== LDAP Mappers +==== LDAP mappers LDAP mappers are `listeners` triggered by the LDAP Provider. They provide another extension point to LDAP integration. LDAP mappers are triggered when: -* Users log in by using §LDAP. +* Users log in by using LDAP. * Users initially register. * The Admin Console queries a user. @@ -138,11 +137,11 @@ This mapper maps X.509 certificates. {project_name} uses it in conjunction with User Attribute mappers that map basic {project_name} user attributes, such as username, firstname, lastname, and email, to corresponding LDAP attributes. You can extend these and provide your own additional attribute mappings. The Admin Console provides tooltips to help with configuring the corresponding mappers. [[_ldap_password_hashing]] -==== Password Hashing +==== Password hashing When {project_name} updates a password, {project_name} sends the password in plain-text format. This action is different from updating the password in the built-in {project_name} database, where {project_name} hashes and salts the password before sending it to the database. For LDAP, {project_name} relies on the LDAP server to hash and salt the password. -By default, LDAP servers such as MSAD, RHDS, or FreeIPA hash and salt passwords. Other LDAP servers such as OpenLDAP or ApacheDS store the passwords in plain-text unless you use the _LDAPv3 Password Modify Extended Operation_ as described in https://tools.ietf.org/html/rfc3062[RFC3062]. Enable the LDAPv3 Password Modify Extended Operation in the LDAP configuration page. See the documentation of your LDAP server for more details. +By default, LDAP servers such as MSAD, RHDS, or FreeIPA hash and salt passwords. Other LDAP servers such as OpenLDAP or ApacheDS store the passwords in plain-text unless you use the _LDAPv3 Password Modify Extended Operation_ as described in https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3[RFC3062]. Enable the LDAPv3 Password Modify Extended Operation in the LDAP configuration page. See the documentation of your LDAP server for more details. WARNING: Always verify that user passwords are properly hashed and not stored as plaintext by inspecting a changed directory entry using `ldapsearch` and base64 decode the `userPassword` attribute value. @@ -150,6 +149,8 @@ directory entry using `ldapsearch` and base64 decode the `userPassword` attribut [[_ldap_troubleshooting]] ==== Troubleshooting +- It is useful to increase the logging level to TRACE for the category `org.keycloak.storage.ldap`. You increase this level in the logging + It is useful to increase the logging level to TRACE for the category `org.keycloak.storage.ldap`. You increase this level in the logging subsystem in the `standalone(-ha).xml` file. With this setting, many logging messages are sent to the `server.log` file in the `TRACE` level, including the logging for all queries to the LDAP server and the parameters, which were @@ -157,25 +158,26 @@ used to send the queries. When you are creating any LDAP question on user forum enabled TRACE logging. If it is too big, the good alternative is to include just the snippet from server log with the messages, which were added to the log during the operation, which causes the issues to you. -When you create LDAP provider, message appear in the server log in the INFO level starting with: -[source,bash,subs=+attributes] ----- +- When you create LDAP provider, message appear in the server log in the INFO level starting with: + + When you create LDAP provider, message appear in the server log in the INFO level starting with: + +``` Creating new LDAP Store for the LDAP storage provider: ... ----- - +``` It shows the configuration of your LDAP provider. Before you are asking the questions or reporting bugs, it will be nice to include this message to show your LDAP configuration. Eventually feel free to replace some config changes, which you do not want to include, with some placeholder values. One example is `bindDn=some-placeholder` . For `connectionUrl`, feel free to replace it as well, but it is generally useful to include at least the protocol, which was used (`ldap` vs `ldaps`)`. Similarly it can be useful to include the details for configuration of your LDAP mappers, which are displayed with the message like this at the DEBUG level: -[source,bash,subs=+attributes] ----- +``` Mapper for provider: XXX, Mapper name: YYY, Provider: ZZZ ... ----- - +``` Note those messages are displayed just with the enabled DEBUG logging. +- For tracking the performance or connection pooling issues, consider setting the value of property `Connection Pool Debug Level` of + For tracking the performance or connection pooling issues, consider setting the value of property `Connection Pool Debug Level` of the LDAP provider to value `all`. This will add lots of additional messages to server log with the included logging for the LDAP connection pooling. This can be used to track the issues related to connection pooling or performance. @@ -186,8 +188,12 @@ of the LDAP provider connection. If no more messages appear for connection pooling even after server restart, it can indicate that connection pooling does not work with your LDAP server. +- For the case of reporting LDAP issue, you may consider to attach some part of your LDAP tree with the target data, which causes issues +in your environment. For example if login of some user takes lot of time, you can consider attach his LDAP entry showing count of `member` attributes +of various "group" entries. In this case, it might be useful to add if those group entries are mapped to some Group LDAP mapper (or Role LDAP Mapper) +in {project_name} etc. + For the case of reporting LDAP issue, you may consider to attach some part of your LDAP tree with the target data, which causes issues in your environment. For example if login of some user takes lot of time, you can consider attach his LDAP entry showing count of `member` attributes of various "group" entries. In this case, it might be useful to add if those group entries are mapped to some Group LDAP mapper (or Role LDAP Mapper) in {project_name} and so on. - diff --git a/server_admin/topics/user-federation/sssd.adoc b/server_admin/topics/user-federation/sssd.adoc index b83ea069d1..af22cca201 100644 --- a/server_admin/topics/user-federation/sssd.adoc +++ b/server_admin/topics/user-federation/sssd.adoc @@ -1,9 +1,9 @@ [[_sssd]] -=== SSSD and FreeIPA Identity Management Integration +=== SSSD and FreeIPA Identity Management integration -{project_name} includes a https://fedoraproject.org/wiki/Features/SSSD[System Security Services Daemon (SSSD)] plugin. SSSD is part of the Fedora and Red Hat Enterprise Linux (RHEL), and it provides access to multiple identities and authentication providers. SSSD also provides benefits such as failover and offline support. For more information, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system-level_authentication_guide/sssd[the Red Hat Enterprise Linux Identity Management documentation]. +{project_name} includes the https://fedoraproject.org/wiki/Features/SSSD[System Security Services Daemon (SSSD)] plugin. SSSD is part of the Fedora and Red Hat Enterprise Linux (RHEL), and it provides access to multiple identities and authentication providers. SSSD also provides benefits such as failover and offline support. For more information, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system-level_authentication_guide/sssd[the Red Hat Enterprise Linux Identity Management documentation]. SSSD integrates with the FreeIPA identity management (IdM) server, providing authentication and access control. With this integration, {project_name} can authenticate against privileged access management (PAM) services and retrieve user data from SSSD. For more information about using Red Hat Identity Management in Linux environments, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/linux_domain_identity_authentication_and_policy_guide/index[the Red Hat Enterprise Linux Identity Management documentation]. @@ -16,9 +16,9 @@ image:{project_images}/keycloak-sssd-freeipa-integration-overview.png[] {project_name} registers groups and roles automatically but does not synchronize them. Any changes made by the {project_name} administrator in {project_name} do not synchronize with SSSD. ==== -==== FreeIPA/IdM Server +==== FreeIPA/IdM server -A https://hub.docker.com/r/freeipa/freeipa-server/[FreeIPA Docker image] is available in Docker. To set up a FreeIPA server, see the https://www.freeipa.org/page/Quick_Start_Guide[FreeIPA documentation]. +The https://hub.docker.com/r/freeipa/freeipa-server/[FreeIPA Docker image] is available in Docker Hub. To set up the FreeIPA server, see the https://www.freeipa.org/page/Quick_Start_Guide[FreeIPA documentation]. .Procedure . Run your FreeIPA server using this command: @@ -136,7 +136,7 @@ If you do not have permission to access the SSSD service, ensure that the user r allowed_uids = root, your_username ---- -==== Enabling the SSSD Federation Provider +==== Enabling the SSSD federation provider {project_name} uses DBus-Java to communicate at a low level with D-Bus. D-Bus depends on the http://www.matthew.ath.cx/projects/java/[Unix Sockets Library]. @@ -188,7 +188,7 @@ Use the `sssctl user-checks` command to validate your setup: $ sudo sssctl user-checks admin -s keycloak ---- -=== Configuring a Federated SSSD Store +=== Configuring a federated SSSD store After the installation, configure a federated SSSD store. diff --git a/server_admin/topics/users/allow-user-to-delete-account.adoc b/server_admin/topics/users/allow-user-to-delete-account.adoc new file mode 100644 index 0000000000..abdd31ff05 --- /dev/null +++ b/server_admin/topics/users/allow-user-to-delete-account.adoc @@ -0,0 +1,45 @@ + + +=== Enabling account deletion by users + +{project_name} can allow applications end users to delete their account through the Account Console. The functionality is not enabled by default. To enable it, the following steps needs be taken: + +* Enabling the "Delete Account" Required Action + +Allowing the user to delete their account is done through an AIA (Application Initiated Action). You need first of all to enable the action from the admin console. In the Authentication menu, go to the Required Actions tab and tick the enabled checkbox for the "Delete Account" action. + +image:images/enable-delete-account-action.png[] + +* Making sure the user has the "delete-account" as a client role: + +The delete account functionality is enabled on a per user basis. The second requirement to enable the delete account functionality is to make sure the user has the `delete-account` as a client role. + +To enable the delete account role for a user, go to the Users menu, and find the user for which the delete account functionality is to be enabled. In the "Role Mappings" Tab, select the "account" client from "Clients Role" list. + +Finally, select `delete-account` and click on add selected. + +Image:images/delete-account-client-role.png[] + + +=== Deleting a user in action + + +Once the functionality is enabled, the user will see a new section named "Delete Account" appear in the bottom of the "Personal Info" page + +image:images/delete-account-page.png[] + +As stated by the warning message, this action is irreversible, and it implies the deletion of all the user's data in Keycloak. + +Once the user clicks on Delete, he will be prompted to enter his credentials again and redirected to the final confirmation step: + + +image:images/delete-account-confirm.png[] + + + +After confirming, the user's account will be deleted. + + + + + diff --git a/server_admin/topics/users/con-required-actions.adoc b/server_admin/topics/users/con-required-actions.adoc index da6e5052dd..f0e28b29a8 100644 --- a/server_admin/topics/users/con-required-actions.adoc +++ b/server_admin/topics/users/con-required-actions.adoc @@ -3,7 +3,7 @@ // server_admin/topics/users.adoc [id="con-required-actions_{context}"] -= Required Actions += Required actions You can set the actions that a user must perform at the first login. These actions are required after the user provides credentials. After the first login, these actions are no longer required. You add required actions on the *Details* tab of that user. diff --git a/server_admin/topics/users/con-user-impersonation.adoc b/server_admin/topics/users/con-user-impersonation.adoc index 0e158dbe3e..bedb9dd82a 100644 --- a/server_admin/topics/users/con-user-impersonation.adoc +++ b/server_admin/topics/users/con-user-impersonation.adoc @@ -3,13 +3,13 @@ // server_admin/topics/users.adoc [id="con-user-impersonation_{context}"] -= User Impersonation += User impersonation An administrator with the appropriate permissions can impersonate a user. For example, if a user experiences a bug in an application, an administrator can impersonate the user to investigate or duplicate the issue. Any user with the `impersonation` role in the realm can impersonate a user. -image:{project_images}/user-details.png[] +Image:{project_images}/user-details.png[] * If the administrator and the user are in the same realm, then the administrator will be logged out and automatically logged in as the user being impersonated. * If the administrator and user are in different realms, the administrator will remain logged in, and additionally will be logged in as the user in that user's realm. diff --git a/server_admin/topics/users/con-user-registration.adoc b/server_admin/topics/users/con-user-registration.adoc index 630a9c5a13..0050d7844b 100644 --- a/server_admin/topics/users/con-user-registration.adoc +++ b/server_admin/topics/users/con-user-registration.adoc @@ -3,12 +3,12 @@ // server_admin/topics/users.adoc [id="con-user-registration_{context}"] -= User Registration += User registration [role="_abstract"] You can use {project_name} as a third-party authorization server to manage application users, including users who self-register. If you enable self-registration, the login page displays a registration link so that user can create an account. -.Registration Link +.Registration link image:{project_images}/registration-link.png[] A user must add profile information to the registration form to complete registration. The registration form can be customized by removing or adding the fields that must be completed by a user. diff --git a/server_admin/topics/users/proc-allow-user-to-delete-account.adoc b/server_admin/topics/users/proc-allow-user-to-delete-account.adoc index 89046b15fa..1a6d25ff63 100644 --- a/server_admin/topics/users/proc-allow-user-to-delete-account.adoc +++ b/server_admin/topics/users/proc-allow-user-to-delete-account.adoc @@ -1,5 +1,5 @@ [id="proc-allow-user-to-delete-account_{context}"] -= Enabling Account Deletion by Users += Enabling account deletion by users End users and applications can delete their accounts in the Account Console if you enable this capability in the Admin Console. Once you enable this capability, you can give that capability to specific users. @@ -12,10 +12,10 @@ You enable this capability on the *Required Actions* tab. . Click the *Required Actions* tab. . Select *Enabled* on the *Delete Account* row. + -.Delete Account on Required Actions tab +.Delete account on required actions tab image:images/enable-delete-account-action.png[] -== Giving a User the *delete-account* Role +== Giving a user the *delete-account* role You can give specific users a role that allows account deletion. @@ -27,8 +27,8 @@ You can give specific users a role that allows account deletion. . Under *Available Roles*, select *delete-account*. . Click *Add selected*. + -.delete-account role -image:images/delete-account-client-role.png[] +.Delete-account role +image:images/delete-account-client-role.png[delete-account role] == Deleting your account @@ -37,7 +37,7 @@ Once you have the *delete-account* role, you can delete your own account. . Log into the Account Console. . At the bottom of the *Personal Info* page, click *Delete Account*. + -.Delete Account Page +.Delete account page image:images/delete-account-page.png[] . Enter your credentials and confirm the deletion. diff --git a/server_admin/topics/users/proc-configuring-user-attributes.adoc b/server_admin/topics/users/proc-configuring-user-attributes.adoc index 5f8e491e4f..36594f1f4d 100644 --- a/server_admin/topics/users/proc-configuring-user-attributes.adoc +++ b/server_admin/topics/users/proc-configuring-user-attributes.adoc @@ -14,10 +14,15 @@ image:{project_images}/user-attributes.png[] * You are in the realm where the user exists. .Procedure -. Click *Users* in the menu. +. Click *Users* in the menu. . Select a user to manage. . Click the *Attributes* tab. . Enter the attribute name in the *Key* field. . Enter the attribute value in the *Value* field. . Click *Add*. . Click *Save*. + + +NOTE: Some read-only attributes are not supposed to be updated by the administrators. This includes attributes that are read-only +by design like for example `LDAP_ID`, which is filled automatically by the LDAP provider. Some other attributes should be read-only for +typical user administrators due to security reasons. See the details in the xref:_read_only_user_attributes[Mitigating security threats] chapter. diff --git a/server_admin/topics/users/proc-enabling-recaptcha.adoc b/server_admin/topics/users/proc-enabling-recaptcha.adoc index 23706f5201..f7080f6da4 100644 --- a/server_admin/topics/users/proc-enabling-recaptcha.adoc +++ b/server_admin/topics/users/proc-enabling-recaptcha.adoc @@ -31,7 +31,7 @@ reCAPTCHA. . Click *Actions* to the right of the reCAPTCHA flow entry. . Click the *Config* link. + -.Recaptcha Config Page +.Recaptcha config page image:{project_images}/recaptcha-config.png[] .. Enter the *Recaptcha Site Key* generated from the Google reCAPTCHA website. diff --git a/server_admin/topics/users/proc-registering-new-user.adoc b/server_admin/topics/users/proc-registering-new-user.adoc index ddf2f6e1cb..4c9206f4ac 100644 --- a/server_admin/topics/users/proc-registering-new-user.adoc +++ b/server_admin/topics/users/proc-registering-new-user.adoc @@ -8,7 +8,7 @@ [role="_abstract"] As a new user, you must complete a registration form to log in for the first time. You add profile information and a password to register. -.Registration Form +.Registration form image:{project_images}/registration-form.png[] .Prerequisite diff --git a/server_admin/topics/users/ref-user-credentials.adoc b/server_admin/topics/users/ref-user-credentials.adoc index eaa7abf894..df41596cce 100644 --- a/server_admin/topics/users/ref-user-credentials.adoc +++ b/server_admin/topics/users/ref-user-credentials.adoc @@ -3,11 +3,11 @@ // server_admin/topics/users.adoc [id="ref-user-credentials_{context}"] -= User Credentials += User credentials You can manage credentials of a user in the *Credentials* tab. -.Credential Management +.Credential management image:{project_images}/user-credentials.png[] This tab includes the following fields: diff --git a/server_admin/topics/users/user-profile.adoc b/server_admin/topics/users/user-profile.adoc index 29940b4bd1..3d66c5c472 100644 --- a/server_admin/topics/users/user-profile.adoc +++ b/server_admin/topics/users/user-profile.adoc @@ -1,6 +1,5 @@ - -=== User Profile += User Profile In {project_name} a user is associated with a set of attributes. These attributes are used to better describe and identify users within {project_name} as well as to pass over additional information about them to applications. @@ -17,7 +16,7 @@ Among other capabilities, user profile enables administrators to: The User Profile capabilities are backed by the User Profile SPI. By default, these capabilities are disabled and realms are configured to use a default configuration that keeps backward compatibility with the legacy behavior. -[Note] +[NOTE] ==== The legacy behavior is about keeping the default constraints used by {project_name} when managing users root attributes such as username, email, first and last name, without any restriction on how custom attributes are managed. Regarding user flows such as registration, profile update, brokering, and managing accounts through the account console, users are restricted to use the attributes aforementioned with the possibility to change theme templates to support additional attributes. @@ -33,7 +32,7 @@ In the next sections, we'll be looking at how to use the declarative provider to In the future, the legacy behavior will no longer be supported in {project_name}. Ideally, you should start looking at the new capabilities provided by the User Profile and migrate your realms accordingly. ==== -==== Enabling the User Profile +== Enabling the User Profile :tech_feature_name: Declarative User Profile :tech_feature_setting: -Dkeycloak.profile.feature.declarative_user_profile=enabled @@ -54,7 +53,7 @@ By enabling the user profile for a realm, {project_name} is going to impose addi In the next topics, we'll be exploring how to manage the user profile configuration and how it affects your realm. -==== Managing the User Profile +== Managing the User Profile The user profile configuration is managed on a per-realm basis. For that, click on the `Realm Settings` link on the left side menu and then click on the `User Profile` tab. @@ -75,7 +74,7 @@ In the `JSON Editor` sub-tab you can view and edit the configuration using a wel In the next section, you are going to learn how to manage the configuration from the `Attributes` sub-tab. -==== Managing Attributes +== Managing Attributes At the `Attributes` sub-tab you can create, edit, and delete the attributes associated with the user profile. @@ -111,7 +110,7 @@ In this section, you can define the validations that will be performed when mana Annotation:: In this section, you can associate annotations to the attribute. Annotations are mainly useful to pass over additional metadata to frontends for rendering purposes. -===== Managing Permissions +=== Managing Permissions In the `Permission` section, you can define the level of access users and administrators have to read and write to an attribute. @@ -147,7 +146,7 @@ Depending on your privacy requirements, you might also want attributes inaccessi Make sure to set the correct permissions whenever you add a new attribute to the user profile configuration. -===== Managing Validations +=== Managing validations In the `Validation` section, you can choose from different forms of validation to make sure the attribute value conforms to specific rules. @@ -222,7 +221,7 @@ image:images/user-profile-validation.png[] |=== -===== Managing Annotations +==== Managing annotations In order to pass additional information to frontends, attributes can be decorated with annotations to dictate how attributes are rendered. This capability is mainly useful when extending {project_name} themes to render pages dynamically based on the annotations associated with attributes. @@ -230,7 +229,7 @@ annotations to dictate how attributes are rendered. This capability is mainly us .Attribute Annotation image:images/user-profile-annotation.png[] -==== Managing Attribute Groups +== Managing Attribute Groups At the `Attribute Groups` sub-tab you can create, edit, and delete attribute groups. An attribute group allows you to define a container for correlated attributes so that they are rendered together when at the user-facing forms. @@ -261,7 +260,7 @@ A user-friendly text that will be displayed as a tooltip when rendering user-fac Annotation:: In this section, you can associate annotations to the attribute. Annotations are mainly useful to pass over additional metadata to frontends for rendering purposes. -==== Using the JSON Configuration +== Using the JSON configuration The user profile configuration is stored using a well-defined JSON schema. You can choose from editing the user profile configuration directly by clicking on the `JSON Editor` sub-tab. @@ -270,7 +269,7 @@ image:images/user-profile-json-config.png[] The JSON schema is defined as follows: -[source:json] +[source,json] ---- { "attributes": [ @@ -308,13 +307,13 @@ The schema supports as many attributes as you need. For each attribute you should define a `name` and, optionally, the `required`, `permission`, and the `annotations` settings. -===== Required Property +=== Required property The `required` setting defines whether an attribute is required. {project_name} allows you to set an attribute as required based on different conditions. When the `required` setting is defined as an empty object, the attribute is always required. -[source:json] +[source,json] ---- { "attributes": [ @@ -329,7 +328,7 @@ On the other hand, you can choose to make the attribute required only for users, To mark an attribute as required for a user and/or administrator, set the `roles` property as follows: -[source:json] +[source,json] ---- { "attributes": [ @@ -346,7 +345,7 @@ The `roles` property expects an array whose values can be either `user` or `admi Similarly, you can choose to make the attribute required when a set of one or more scopes is requested by a client when authenticating a user. For that, you can use the `scopes` property as follows: -[source:json] +[source,json] ---- { "attributes": [ @@ -361,11 +360,11 @@ Similarly, you can choose to make the attribute required when a set of one or mo The `scopes` property is an array whose values can be any string representing a client scope. -===== Permissions Property +=== Permissions property The attribute-level `permissions` property can be used to define the read and write permissions to an attribute. The permissions are set based on whether these operations can be performed on the attribute by a user, or administrator, or both. -[source:json] +[source,json] ---- { "attributes": [ @@ -383,11 +382,11 @@ Both `view` and `edit` properties expect an array whose values can be either `us When the `edit` permission is granted, the `view` permission is implicitly granted. -===== Annotations Property +=== Annotations property The attribute-level `annotation` property can be used to associate additional metadata to attributes. Annotations are mainly useful for passing over additional information about attributes to frontends rendering user attributes based on the user profile configuration. Each annotation is a key/value pair. -[source:json] +[source,json] ---- { "attributes": [ @@ -401,7 +400,7 @@ The attribute-level `annotation` property can be used to associate additional me } ---- -==== Using Dynamic Forms +== Using dynamic forms One of the main capabilities of User Profile is the possibility to dynamically render user-facing forms based on attributes metadata. When you have the feature enabled to your realm, forms like registration and update profile are rendered using specific theme templates to dynamically render pages based on the user profile configuration. @@ -431,7 +430,7 @@ The default rendering mechanism provides the following capabilities: * Dynamically order fields depending on the order set to the attributes. * Dynamically group fields that belong to a same attribute group. -===== Ordering Attributes +=== Ordering attributes The attributes order is set by clicking on the up and down arrows when at the attribute listing page. @@ -440,7 +439,7 @@ image:images/user-profile-attribute-list-order.png[] The order you set in this page is respected when fields are rendered in dynamic forms. -===== Grouping Attributes +=== Grouping attributes When dynamic forms are rendered, they will try to group together attributes that belong to a same attribute group. @@ -452,7 +451,7 @@ image:images/user-profile-update-profile.png[] When attributes are linked to an attribute group, the attribute order is also important to make sure attributes within the same group are close together, within a same group header. Otherwise, if attributes within a group do not have a sequential order you might have the same group header rendered multiple times in the dynamic form. ==== -==== Forcing User Profile Compliance +== Forcing User Profile compliance In order to make sure user profiles are in compliance with the configuration, administrators may use the `VerifyProfile` required action to eventually force users to update their profiles when authenticating to {project_name}. @@ -473,7 +472,7 @@ By default, the `VerifyProfile` action is disabled. To enabled it, click on the .Registring the VerifyProfile Required Action image:images/user-profile-register-verify-profile-action.png[] -==== Migrating to User Profile +== Migrating to User Profile Before enabling the User Profile capabilities to a realm, there are some important considerations you should be aware of. By providing a single place to manage attribute metadata, the feature is very strict about the attributes that can be set to users and how they are managed. @@ -483,4 +482,4 @@ The same recommendation applies for those accessing the User REST API to query u In regards to {project_name} internal user attributes such as `LDAP_ID`, `LDAP_ENTRY_DN`, or `KERBEROS_PRINCIPAL`, if you want to be able to access those attributes you should have them as attributes in your user profile configuration. The recommendation is to mark these attributes as viewable only to administrators so that you can look at them when managing the user attributes through the administration console or querying users via User API. -In regards to theming, if you already have customizations to the legacy templates (those hardcoded with user root attributes) your custom templates won't be used when rendering user-facing forms but the new templates that render these forms dynamically. Ideally, you should avoid having any customizations to templates and try to stick with the behavior provided by these new templates to dynamically render forms for you. If they are still not enough to address your requirements, you can either customize them or provide us with any feedback so that we discuss whether it makes sense to enhance the new templates. \ No newline at end of file +In regards to theming, if you already have customizations to the legacy templates (those hardcoded with user root attributes) your custom templates won't be used when rendering user-facing forms but the new templates that render these forms dynamically. Ideally, you should avoid having any customizations to templates and try to stick with the behavior provided by these new templates to dynamically render forms for you. If they are still not enough to address your requirements, you can either customize them or provide us with any feedback so that we discuss whether it makes sense to enhance the new templates. diff --git a/server_admin/topics/vault.adoc b/server_admin/topics/vault.adoc index f3e8a26cf5..e13eefd841 100644 --- a/server_admin/topics/vault.adoc +++ b/server_admin/topics/vault.adoc @@ -33,7 +33,7 @@ To use a vault, register a vault provider in {project_name}. You can use the pro [[_providers]] -=== Kubernetes / OpenShift Files Plain-text Vault Provider +=== Kubernetes / OpenShift files plain-text vault provider {project_name} supports vault implementation for https://kubernetes.io/docs/concepts/configuration/secret/[Kubernetes secrets]. You can mount Kubernetes secrets as data volumes, and they appear as a directory with a flat-file structure. {project_name} represents each secret as a file with the file's name as the secret name and the file's contents as the secret value. @@ -61,7 +61,7 @@ Here is the equivalent configuration using CLI commands: /subsystem=keycloak-server/spi=vault/provider=files-plaintext/:add(enabled=true,properties={dir => "${jboss.home.dir}/standalone/configuration/vault"}) ---- -=== Elytron Credential Store Vault Provider +=== Elytron credential store vault provider {project_name} also provides support for reading secrets stored in an Elytron credential store. The `elytron-cs-keystore` vault provider can retrieve secrets from the credential store's keystore based implementation, which is also the default implementation Elytron provides. @@ -116,7 +116,7 @@ For more information about creating and managing elytron credential stores and m {project_name} implements the `elytron-cs-keystore` vault provider as a WildFly extension and is available if the {project_name} server runs on WildFly/JBoss EAP only. ==== -=== Key Resolvers +=== Key resolvers All built-in providers support the configuration of key resolvers. A key resolver implements the algorithm or strategy for combining the realm name with the key, obtained from the `${vault.key}` expression, into the final entry name used to retrieve the secret from the vault. {project_name} uses the `keyResolvers` property to configure the resolvers that the provider uses. The value is a comma-separated list of resolver names. An example of the configuration for the `files-plaintext` provider follows: @@ -181,7 +181,7 @@ The `FACTORY_PROVIDED` resolver provides a hook that you can use to implement a } ---- -The custom factory returns a key resolver that combines the realm and key with a triple `#` character. For example, an entry would be `master_realm###smtp_key`. Install this factory like any custom provider. +The custom factory returns a key resolver that combines the realm and key with a triple # character. For example, an entry would be `master_realm###smtp_key`. Install this factory like any custom provider. [NOTE] ==== diff --git a/server_installation/topics/operating-mode/crossdc.adoc b/server_installation/topics/operating-mode/crossdc.adoc index de9e653a34..a77768383f 100644 --- a/server_installation/topics/operating-mode/crossdc.adoc +++ b/server_installation/topics/operating-mode/crossdc.adoc @@ -671,7 +671,7 @@ There are 2 ways to take the site offline. This is useful especially if the outage is planned. With `jconsole` or CLI, you can connect to the `server1` server and take the `site2` offline. More details about this are available in the ifeval::[{project_product}==true] -link:{jdgserver_crossdcdocs_link}#xsite_auto_offline-xsite[{jdgserver_name} documentation]. +link:{jdgserver_crossdcdocs_link}[{jdgserver_name} documentation]. endif::[] ifeval::[{project_community}==true] link:{jdgserver_crossdcdocs_link}[{jdgserver_name} documentation]. @@ -714,7 +714,7 @@ A bidirectional state transfer will ensure that entities which were created *aft Unfortunately, there is no any universal solution to this. Split-brains and network outages are just state, which is usually impossible to be handled 100% correctly with 100% consistent data between sites. In the case of {project_name}, it typically is not a critical issue. In the worst case, users will need to re-login again to their clients, or have the improper count of loginFailures tracked for brute force protection. See the {jdgserver_name}/JGroups documentation for more tips how to deal with split-brain. The state transfer can be also done on the {jdgserver_name} server side through JMX. The operation name is `pushState`. There are few other operations to monitor status, cancel push state, and so on. -More info about state transfer is available in the link:{jdgserver_crossdcdocs_link}#cli_xsite_push-cli-ops[{jdgserver_name} docs]. +More info about state transfer is available in the link:{jdgserver_crossdcdocs_link}[{jdgserver_name} docs]. [[clearcache]] diff --git a/topics/templates/document-attributes-product.adoc b/topics/templates/document-attributes-product.adoc index 0539457414..42556fe88f 100644 --- a/topics/templates/document-attributes-product.adoc +++ b/topics/templates/document-attributes-product.adoc @@ -1,8 +1,8 @@ :project_community: false :project_product: true :project_name: Red Hat Single Sign-On -:project_versionMvn: 15.0.1.redhat-00002 -:project_versionNpm: 15.0.1.redhat-00002 +:project_versionMvn: 15.0.2.redhat-00001 +:project_versionNpm: 15.0.2.redhat-00001 :project_images: rhsso-images :standalone: diff --git a/upgrading/master-docinfo.xml b/upgrading/master-docinfo.xml index 3519ec3be9..b83c4e75d9 100644 --- a/upgrading/master-docinfo.xml +++ b/upgrading/master-docinfo.xml @@ -10,7 +10,7 @@ Red Hat Customer Content Services - Copyright 2019 Red Hat, Inc. + Copyright 2021 Red Hat, Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at diff --git a/upgrading/topics/rhsso/changes-73.adoc b/upgrading/topics/rhsso/changes-73.adoc index 39e18d46fa..004e3da1ca 100644 --- a/upgrading/topics/rhsso/changes-73.adoc +++ b/upgrading/topics/rhsso/changes-73.adoc @@ -86,7 +86,7 @@ or `resourceAccess` properties, you may need to increase the priority of your ma Audiences of all the clients, for which authenticated user has at least one client role in the token, are automatically added to the `aud` claim in the access token now. On the other hand, an access token may not automatically contain the audience of the -frontend client, for which it was issued. Read the link:{adminguide_link}#_audience[{adminguide_name}] for more details. +frontend client, for which it was issued. See the link:{adminguide_link}#_audience_resolve[{adminguide_name}] for more details. === Upgrade to EAP 7.2 @@ -126,7 +126,7 @@ the native promise. This was causing issues as the error handler was not always resulted in `Uncaught (in promise)` error. === Microsoft Identity Provider updated to use the Microsoft Graph API - + The Microsoft Identity Provider implementation in {project_name} used to rely on the Live SDK endpoints for authorization and obtaining the user profile. From November 2018 onwards, Microsoft is removing support for the Live SDK API in favor of the new Microsoft Graph API. The {project_name} identity provider has been updated