Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 4. Enabling and configuring the Keycloak plugin

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. Enabling the Keycloak plugin
Link kopieren

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

  1. 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. Configuring the Keycloak plugin
Link kopieren

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.3. Metrics
Link kopieren

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

4.3.1. Available Counters
Link kopieren

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.3.2. Labels
Link kopieren

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.3.3. Exporting Metrics
Link kopieren

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

See the Backstage OpenTelemetry setup guide for integration instructions.

4.4. Limitations
Link kopieren

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.

Nach oben
Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2025 Red Hat