Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Keycloak backend plugin for Backstage

The Keycloak backend plugin integrates Keycloak into Backstage.

1.1. Capabilities
Copy link

The Keycloak backend plugin has the following capabilities:

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

1.2. For administrators
Copy link

1.2.1. Installation
Copy link

Install the Backstage package into the backend. When not integrating with a published package, clone the repository locally and add the Backstage as follows: 

yarn workspace backend add @redhat/backstage-plugin-keycloak-backend

1.2.2. Configuration
Copy link

  1. Add the following configuration to the app-config.yaml file: 

       ```yaml title="app-config.yaml"
   catalog:
     providers:
       keycloakOrg:
         default:
           baseUrl: https://<keycloak_host>/auth
           loginRealm: ${KEYCLOAK_REALM}
           realm: ${KEYCLOAK_REALM}
           clientId: ${KEYCLOAK_CLIENTID}
           clientSecret: ${KEYCLOAK_CLIENTSECRET}
   ```

  2. Register the plugin in the packages/backend/src/plugins/catalog.ts file. You can also configure a schedule in this step. However, there are possible ways of configuration, such as:

    • Configure a schedule inside the app-config.yaml file: 

           ```yaml title="app-config.yaml"
     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
     ```

      Use the configured scheduler inside the packages/backend/src/plugins/catalog.ts as follows: 

           ```ts title="packages/backend/src/plugins/catalog.ts"
     /* highlight-add-start */
     import { KeycloakOrgEntityProvider } from '@redhat/backstage-plugin-keycloak-backend';

     /* highlight-add-end */

     export default async function createPlugin(
       env: PluginEnvironment,
     ): Promise<Router> {
       const builder = await CatalogBuilder.create(env);

       /* ... other processors and/or providers ... */
       /* highlight-add-start */
       builder.addEntityProvider(
         KeycloakOrgEntityProvider.fromConfig(env.config, {
           id: 'development',
           logger: env.logger,
           scheduler: env.scheduler,
         }),
       );
       /* highlight-add-end */

       const { processingEngine, router } = await builder.build();
       await processingEngine.start();
       return router;
     }

    • Add a schedule directly inside the packages/backend/src/plugins/catalog.ts file as follows: 

           ```ts title="packages/backend/src/plugins/catalog.ts"
     + import { KeycloakOrgEntityProvider } from '@redhat/backstage-plugin-keycloak-backend';

     export default async function createPlugin(
       env: PluginEnvironment,
     ): Promise<Router> {
       const builder = await CatalogBuilder.create(env);

       /* ... other processors and/or providers ... */
       builder.addEntityProvider(
         KeycloakOrgEntityProvider.fromConfig(env.config, {
           id: 'development',
           logger: env.logger,
           /* highlight-add-start */
           schedule: env.scheduler.createScheduledTaskRunner({
             frequency: { minutes: 1 },
             timeout: { minutes: 1 },
             initialDelay: { seconds: 15 }
           }),
           /* highlight-add-end */
         }),
       )

       const { processingEngine, router } = await builder.build();
       await processingEngine.start();
       return router;
     }
     ```

  3. Optional: override the default Keycloak query parameters. Configure the parameters inside the app-config.yaml file: 

       ```yaml title="app-config.yaml"
   catalog:
     providers:
       keycloakOrg:
         default:
           # ...
           # highlight-add-start
           userQuerySize: 500 # Optional
           groupQuerySize: 250 # Optional
           # highlight-add-end
   ```

    Communication between Backstage and Keycloak is enabled by using the Keycloak API. Username/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. Note that the newer versions of Keycloak omit the /auth context path.

""

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

1.2.3. Limitations
Copy link

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

NODE_TLS_REJECT_UNAUTHORIZED=0

Note

The solution of setting the environment variable is not recommended.

1.3. For users
Copy link

After configuring the plugin successfully, the plugin imports the users and groups each time when started.

After the first import is complete, you can select User to list the users from the catalog page:

catalog-list

You can see the list of users on the page:

user-list

When you select a user, you can see the information imported from Keycloak:

user-profile

You can also select a group, view the list, and select or view the information imported from Keycloak for a group:

group-profile
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top