Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 4. Installing and configuring Keycloak

The Keycloak backend plugin, which integrates Keycloak into Developer Hub, has the following capabilities:

  • Synchronization of Keycloak users in a realm.
  • Synchronization of Keycloak groups and their users in a realm.
Note

The supported Red Hat Build of Keycloak (RHBK) version is 26.0.

4.1. Installation
Copier lien

The Keycloak plugin is pre-loaded in Developer Hub with basic configuration properties. To enable it, set the disabled property to false as follows: 

global:
  dynamic:
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - package: ./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic
        disabled: false
Copy to Clipboard Toggle word wrap

4.2. Basic configuration
Copier lien

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

4.3. Advanced configuration
Copier lien

Schedule configuration

You can configure a schedule in the app-config.yaml file, as follows: 

     catalog:
       providers:
         keycloakOrg:
           default:
             # ...
             # highlight-add-start
             schedule: # optional; same options as in TaskScheduleDefinition
               # supports cron, ISO duration, "human duration" as used in code
               frequency: { minutes: 1 }
               # supports ISO duration, "human duration" as used in code
               timeout: { minutes: 1 }
               initialDelay: { seconds: 15 }
               # highlight-add-end
Copy to Clipboard Toggle word wrap
Note

If you have made any changes to the schedule in the app-config.yaml file, then restart to apply the changes.

Keycloak query parameters

You can override the default Keycloak query parameters in the app-config.yaml file, as follows: 

   catalog:
     providers:
       keycloakOrg:
         default:
           # ...
           # highlight-add-start
           userQuerySize: 500 # Optional
           groupQuerySize: 250 # Optional
           # highlight-add-end
Copy to Clipboard Toggle word wrap

Communication between Developer Hub 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.<ENVIRONMENT_NAME> object in the app-config.yaml file:

Expand
NameDescriptionDefault ValueRequired

baseUrl

Location of the Keycloak server, such as 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, the access type must be set to confidential and service accounts must be enabled. You must also add the following roles from the realm-management client role:

  • query-groups
  • query-users
  • view-users

4.4. Metrics
Copier lien

The Keycloak backend plugin supports OpenTelemetry metrics that you can use to monitor fetch operations and diagnose potential issues.

4.4.1. Available Counters
Copier lien

Expand
Table 4.1. Keycloak metrics
Metric NameDescription

backend_keycloak_fetch_task_failure_count_total

Counts fetch task failures where no data was returned due to an error.

backend_keycloak_fetch_data_batch_failure_count_total

Counts partial data batch failures. Even if some batches fail, the plugin continues fetching others.

4.4.2. Labels
Copier lien

All counters include the taskInstanceId label, which uniquely identifies each scheduled fetch task. You can use this label to trace failures back to individual task executions.

Users can enter queries in the Prometheus UI or Grafana to explore and manipulate metric data.

In the following examples, a Prometheus Query Language (PromQL) expression returns the number of backend failures.

Example to get the number of backend failures associated with a taskInstanceId

backend_keycloak_fetch_data_batch_failure_count_total{taskInstanceId="df040f82-2e80-44bd-83b0-06a984ca05ba"} 1
Copy to Clipboard Toggle word wrap

Example to get the number of backend failures during the last hour

sum(backend_keycloak_fetch_data_batch_failure_count_total) - sum(backend_keycloak_fetch_data_batch_failure_count_total offset 1h)
Copy to Clipboard Toggle word wrap

Note

PromQL supports arithmetic operations, comparison operators, logical/set operations, aggregation, and various functions. Users can combine these features to analyze time-series data effectively.

Additionally, the results can be visualized using Grafana.

4.4.3. Exporting Metrics
Copier lien

You can export metrics using any OpenTelemetry-compatible backend, such as Prometheus.

See the Backstage OpenTelemetry setup guide for integration instructions.

4.5. Limitations
Copier lien

If you have self-signed or corporate certificate issues, you can set the following environment variable before starting Developer Hub:

NODE_TLS_REJECT_UNAUTHORIZED=0

Note

The solution of setting the environment variable is not recommended.

Retour au début
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

Theme

© 2025 Red Hat