diff --git a/assemblies/configure_configuring-rhdh/assembly-configure-trust-for-corporate-certificate-authority-in-rhdh.adoc b/assemblies/configure_configuring-rhdh/assembly-configure-trust-for-corporate-certificate-authority-in-rhdh.adoc new file mode 100644 index 00000000000..17b9ad11399 --- /dev/null +++ b/assemblies/configure_configuring-rhdh/assembly-configure-trust-for-corporate-certificate-authority-in-rhdh.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: ASSEMBLY +ifdef::context[:parent-context: {context}] + +[id="configure-trust-for-corporate-certificate-authority-in-rhdh_{context}"] += Configure trust for corporate Certificate Authority in {product} + +:previouscontext: {context} +:context: configure-trust-for-corporate-ca-in-rhdh + +[role="_abstract"] +Set up trust for certificates issued by corporate Certificate Authority (CA) in your {product} deployment. + +include::../modules/configure_configuring-rhdh/proc-configure-trust-for-corporate-certificate-authority-with-node-extra-ca-certs.adoc[leveloffset=+1] + +:context: {previouscontext} +:!previouscontext: + +ifdef::parent-context[:context: {parent-context}] +ifndef::parent-context[:!context:] diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-enable-and-configure-the-keycloak-plugin.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-enable-and-configure-the-keycloak-plugin.adoc deleted file mode 100644 index 35bdf9a1cc2..00000000000 --- a/assemblies/extend_configuring-dynamic-plugins/assembly-enable-and-configure-the-keycloak-plugin.adoc +++ /dev/null @@ -1,18 +0,0 @@ -:_mod-docs-content-type: ASSEMBLY -ifdef::context[:parent-context: {context}] - -[id="enable-and-configure-the-keycloak-plugin_{context}"] -= Enable and configure the Keycloak plugin -:context: enable-and-configure-the-keycloak-plugin - -[role="_abstract"] -Integrate Keycloak into {product} to synchronize users and groups from your {rhbk-brand-name} ({rhbk}) realm. The supported {rhbk} version is `{keycloak-version}`. - -include::../modules/shared/proc-enable-the-keycloak-plugin.adoc[leveloffset=+1] - -include::../modules/shared/proc-configure-the-keycloak-plugin.adoc[leveloffset=+1] - -include::../modules/shared/ref-keycloak-plugin-metrics.adoc[leveloffset=+1] - -ifdef::parent-context[:context: {parent-context}] -ifndef::parent-context[:!context:] diff --git a/assemblies/observability_monitoring-and-logging/assembly-rhbk-metrics-for-rhdh.adoc b/assemblies/observability_monitoring-and-logging/assembly-rhbk-metrics-for-rhdh.adoc new file mode 100644 index 00000000000..7b8fc8a00d0 --- /dev/null +++ b/assemblies/observability_monitoring-and-logging/assembly-rhbk-metrics-for-rhdh.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: ASSEMBLY +ifdef::context[:parent-context: {context}] + +[id="rhbk-metrics-for-rhdh_{context}"] += {rhbk-brand-name} metrics for {product} +:context: rhbk-metrics-for-rhdh + +[role="_abstract"] +Use {rhbk-brand-name} ({rhbk}) metrics to troubleshoot authentication issues. + +include::../modules/shared/ref-rhbk-metrics.adoc[leveloffset=+1] + +ifdef::parent-context[:context: {parent-context}] +ifndef::parent-context[:!context:] diff --git a/modules/configure_configuring-rhdh/proc-configure-trust-for-corporate-certificate-authority-with-node-extra-ca-certs.adoc b/modules/configure_configuring-rhdh/proc-configure-trust-for-corporate-certificate-authority-with-node-extra-ca-certs.adoc new file mode 100644 index 00000000000..10c081635fd --- /dev/null +++ b/modules/configure_configuring-rhdh/proc-configure-trust-for-corporate-certificate-authority-with-node-extra-ca-certs.adoc @@ -0,0 +1,42 @@ +:_mod-docs-content-type: PROCEDURE + +[id="configure-trust-for-corporate-certificate-authority-with-node-extra-ca-certs_{context}"] += Configure trust for corporate Certificate Authority with `NODE_EXTRA_CA_CERTS` + +[role="_abstract"] +The best practice for configuring {product-very-short} to trust a certificate issued by your corporate Certificate Authority (CA) is +to use the `NODE_EXTRA_CA_CERTS` environmental variable. + +[NOTE] +==== +The steps +to set up {product-very-short} to trust a CA may vary +depending on how your specific {product-very-short} deployment is configured. +The following instructions capture only the general outline of the procedure. +==== + +.Prerequisites +* You have access to the public root or intermediate certificate of the CA you wish to trust. + +.Procedure +. Export the corporate CA certificate chain (root and intermediate certificates) from its source. +. Convert the certificate or the entire certificate chain to `.pem` format. ++ +[IMPORTANT] +==== +The maximum of file paths in `.pem` format supported by `NODE_EXTRA_CA_CERTS` is *one*. +You cannot concatenate multiple file paths as values of the environment variable. + +If you want to inject multiple CAs or certificate chains into your `.pem` file, +you must first convert them into `.pem` format and then concatenate them into a single file. +==== +. Create a secret containing the CA. +. Mount the secret into {product-very-short} environment. +. Set the `NODE_EXTRA_CA_CERTS` to point to the mount path of the secret. ++ +[IMPORTANT] +==== +You can only use the file path of the CA as a mount path. +Setting the CA directly as an environmental value is not supported. +==== + diff --git a/modules/shared/proc-configure-the-keycloak-plugin.adoc b/modules/shared/proc-configure-the-keycloak-plugin.adoc deleted file mode 100644 index dc7541eb652..00000000000 --- a/modules/shared/proc-configure-the-keycloak-plugin.adoc +++ /dev/null @@ -1,113 +0,0 @@ -:_mod-docs-content-type: PROCEDURE - -[id="configure-the-keycloak-plugin_{context}"] -= Configure the Keycloak plugin - -[role="_abstract"] -Configure schedule frequency, query parameters, and authentication methods for synchronizing Keycloak users and groups. - -.Procedure -. To configure the Keycloak plugin, add the following in your `{my-app-config-file}` file: -`schedule`:: -Configure the schedule frequency, timeout, and initial delay. -The fields support cron, ISO duration, "human duration" as used in code. -+ -[source,yaml] ----- - catalog: - providers: - keycloakOrg: - default: - schedule: - frequency: { minutes: 1 } - timeout: { minutes: 1 } - initialDelay: { seconds: 15 } ----- - -`userQuerySize` and `groupQuerySize`:: -Optionally, configure the Keycloak query parameters to define the number of users and groups to query at a time. -Default values are 100 for both fields. -+ -[source,yaml] ----- - catalog: - providers: - keycloakOrg: - default: - userQuerySize: 100 - groupQuerySize: 100 ----- - -Authentication:: -Communication between {product-short} and Keycloak is enabled by using the Keycloak API. Username and password, or client credentials are supported authentication methods. -+ -The following table describes the parameters that you can configure to enable the plugin under `catalog.providers.keycloakOrg.` object in the `{my-app-config-file}` file: -+ -|=== -| Name | Description | Default Value | Required - -| `baseUrl` -| Location of the Keycloak server, such as `pass:c[https://localhost:8443/auth]`. -| "" -| Yes - -| `realm` -| Realm to synchronize -| `master` -| No - -| `loginRealm` -| Realm used to authenticate -| `master` -| No - -| `username` -| Username to authenticate -| "" -| Yes if using password based authentication - -| `password` -| Password to authenticate -| "" -| Yes if using password based authentication - -| `clientId` -| Client ID to authenticate -| "" -| Yes if using client credentials based authentication - -| `clientSecret` -| Client Secret to authenticate -| "" -| Yes if using client credentials based authentication - -| `userQuerySize` -| Number of users to query at a time -| `100` -| No - -| `groupQuerySize` -| Number of groups to query at a time -| `100` -| No -|=== - -. When using client credentials -.. Set the access type to `confidential`. -.. Enable service accounts. -.. Add the following roles from the `realm-management` client role: -+ -. `query-groups` -. `query-users` -. `view-users` - -. Optionally, if you have self-signed or corporate certificate issues, you can set the following environment variable before starting {product-short}: -+ ----- -NODE_TLS_REJECT_UNAUTHORIZED=0 ----- -+ -[WARNING] -==== -Setting the environment variable is not recommended. -==== diff --git a/modules/shared/proc-enable-authentication-with-rhbk.adoc b/modules/shared/proc-enable-authentication-with-rhbk.adoc index e8e784c82b5..e6c3ba1ff42 100644 --- a/modules/shared/proc-enable-authentication-with-rhbk.adoc +++ b/modules/shared/proc-enable-authentication-with-rhbk.adoc @@ -152,7 +152,7 @@ Enhance security and prevent potential misuse of older tokens by enabling a refr . From the *Realm Settings* page, click the *Tokens* tab. . From the *Refresh tokens* section of the *Tokens* tab, toggle the *Revoke Refresh Token* to the *Enabled* position. ==== - +. Optional: Enable xref:assemblies/observability_monitoring-and-logging/assembly-rhbk-metrics-for-rhdh.adoc[{rhbk} metrics]. . To disable the guest login option, in the `{my-app-config-file}` file, set the authentication environment to `production`: + [source,yaml] diff --git a/modules/shared/proc-enable-the-keycloak-plugin.adoc b/modules/shared/proc-enable-the-keycloak-plugin.adoc deleted file mode 100644 index edfcdd32ead..00000000000 --- a/modules/shared/proc-enable-the-keycloak-plugin.adoc +++ /dev/null @@ -1,34 +0,0 @@ -:_mod-docs-content-type: PROCEDURE - -[id="enable-the-keycloak-plugin_{context}"] -= Enable the Keycloak plugin - -[role="_abstract"] -Enable the Keycloak plugin to synchronize users and groups from your {rhbk-brand-name} realm into {product}. - -.Prerequisites -* To enable the Keycloak plugin, you must set the following environment variables: - -** `KEYCLOAK_BASE_URL` - -** `KEYCLOAK_LOGIN_REALM` - -** `KEYCLOAK_REALM` - -** `KEYCLOAK_CLIENT_ID` - -** `KEYCLOAK_CLIENT_SECRET` - -.Procedure -* The Keycloak plugin is pre-loaded in {product-short} with basic configuration properties. To enable it, set the `disabled` property to `false` in your `dynamic-plugins.yaml` file as follows: -+ --- -[source,yaml,subs="+quotes"] ----- -plugins: - - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-catalog-backend-module-keycloak-dynamic:____ - disabled: false ----- - -include::{docdir}/artifacts/snip-tag-for-OCI-package-paths.adoc[] --- diff --git a/modules/shared/ref-keycloak-plugin-metrics.adoc b/modules/shared/ref-rhbk-metrics.adoc similarity index 84% rename from modules/shared/ref-keycloak-plugin-metrics.adoc rename to modules/shared/ref-rhbk-metrics.adoc index 33452fd7a25..621c328d07a 100644 --- a/modules/shared/ref-keycloak-plugin-metrics.adoc +++ b/modules/shared/ref-rhbk-metrics.adoc @@ -1,16 +1,16 @@ :_mod-docs-content-type: REFERENCE -[id="keycloak-plugin-metrics_{context}"] -= Keycloak plugin metrics +[id="rhbk-metrics_{context}"] += {rhbk-brand-name} metrics [role="_abstract"] -Monitor Keycloak fetch operations and diagnose issues by using OpenTelemetry metrics with Prometheus or Grafana. +Monitor {rhbk-brand-name} ({rhbk}) fetch operations and diagnose issues by using OpenTelemetry metrics with Prometheus or Grafana. -The Keycloak backend plugin supports OpenTelemetry metrics that you can use to monitor fetch operations and diagnose potential issues. +The {rhbk} backend plugin supports OpenTelemetry metrics that you can use to monitor fetch operations and diagnose potential issues. == Available Counters -Keycloak metrics: +{rhbk} metrics: [cols="60%,40%", frame="all", options="header"] |=== diff --git a/titles/configure_configuring-rhdh/master.adoc b/titles/configure_configuring-rhdh/master.adoc index 97350e8a60f..d4b63804b11 100644 --- a/titles/configure_configuring-rhdh/master.adoc +++ b/titles/configure_configuring-rhdh/master.adoc @@ -34,6 +34,8 @@ include::assemblies/configure_configuring-rhdh/assembly-configure-high-availabil include::assemblies/configure_configuring-rhdh/assembly-run-rhdh-behind-a-corporate-proxy.adoc[leveloffset=+1] +include::assemblies/configure_configuring-rhdh/assembly-configure-trust-for-corporate-certificate-authority-in-rhdh.adoc[leveloffset=+1] + include::assemblies/configure_configuring-rhdh/assembly-use-the-dynamic-plugins-cache.adoc[leveloffset=+1] include::modules/configure_configuring-rhdh/proc-enable-the-rhdh-plugin-assets-cache.adoc[leveloffset=+1] diff --git a/titles/extend_configuring-dynamic-plugins/master.adoc b/titles/extend_configuring-dynamic-plugins/master.adoc index 78cf30939bd..ea5ddcfbf57 100644 --- a/titles/extend_configuring-dynamic-plugins/master.adoc +++ b/titles/extend_configuring-dynamic-plugins/master.adoc @@ -20,8 +20,6 @@ include::assemblies/extend_configuring-dynamic-plugins/assembly-install-and-conf include::assemblies/extend_configuring-dynamic-plugins/assembly-enable-and-configure-the-jfrog-plugin.adoc[leveloffset=+1] -include::assemblies/extend_configuring-dynamic-plugins/assembly-enable-and-configure-the-keycloak-plugin.adoc[leveloffset=+1] - include::assemblies/extend_configuring-dynamic-plugins/assembly-enable-and-configure-the-nexus-repository-manager-plugin.adoc[leveloffset=+1] include::modules/shared/proc-enable-the-tekton-plugin.adoc[leveloffset=+1] diff --git a/titles/observability_monitoring-and-logging/master.adoc b/titles/observability_monitoring-and-logging/master.adoc index f5a1706cc4c..5ba7f6d9f90 100644 --- a/titles/observability_monitoring-and-logging/master.adoc +++ b/titles/observability_monitoring-and-logging/master.adoc @@ -21,3 +21,5 @@ include::assemblies/observability_monitoring-and-logging/assembly-enable-observa include::assemblies/observability_monitoring-and-logging/assembly-monitoring-and-logging-rhdh-on.adoc[leveloffset=+1] include::assemblies/observability_monitoring-and-logging/assembly-monitor-and-log-with-in-rhdh.adoc[leveloffset=+1] + +include::assemblies/observability_monitoring-and-logging/assembly-rhbk-metrics-for-rhdh.adoc[leveloffset=+1]