Red Hat Developer Hub 1.7

Getting started with Red Hat Developer Hub on Red Hat OpenShift Container Platform for the platform engineer

As a platform engineer, prepare your IT infrastructure including Red Hat OpenShift Container Platform and required external components, and run your first Red Hat Developer Hub (RHDH) instance in production.

Red Hat Customer Content Services

Abstract

As a platform engineer, prepare your IT infrastructure including Red Hat OpenShift Container Platform and required external components, and run your first Red Hat Developer Hub (RHDH) instance in production.

1. Enabling authentication in Red Hat Developer Hub (with mandatory steps only)

1. Enabling authentication in Red Hat Developer Hub (with mandatory steps only)

1.1. Understanding authentication and user provisioning

This module provides an overview of how authentication and user provisioning function within Red Hat Developer Hub. Learn about the process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step. Understanding this process is essential for successfully configuring your Developer Hub instance, securing access through authorization, and enabling features that rely on synchronized user and group data.

To fully enable catalog features, provision user and group data from the Identity Provider to the Developer Hub software catalog. Catalog provider plugins handle this task asynchronously. These plugins query the Identity Provider (IdP) for relevant user and group information, and create or update corresponding entities in the Developer Hub catalog. Scheduled provisioning ensures that the catalog accurately reflects the users and groups in your organization.

When a user attempts to access Developer Hub, Developer Hub redirects them to a configured authentication provider, such as Red Hat Build of Keycloak (RHBK), GitHub, or Microsoft Azure. This external IdP is responsible for authenticating the user.

On successful authentication, the Developer Hub authentication plugin, configured in your app-config.yaml file, processes the response from the IdP, resolves the identity in the Developer Hub software catalog, and establishes a user session within Developer Hub.

Configuring authentication and user provisioning is critical for several reasons.

It secures your Developer Hub instance by ensuring only authenticated users can gain access.
It enables authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP.
Provisioning user and group data to the catalog is necessary for various catalog features that rely on understanding entity ownership and relationships between users, groups, and software components. Without this provisioning step, features like displaying who owns a component in the catalog may not function correctly.

Not recommended for production

To explore Developer Hub features, you can:

To use Developer Hub without external IdP, enable the guest user to skip configuring authentication and authorization, log in as the guest user, and access all Developer Hub features.
To use Developer Hub without authorization policies and features relying on the software catalog, you can enable the dangerouslyAllowSignInWithoutUserInCatalog resolver option. This setting bypasses the check requiring a user to be in the catalog but still enforces authentication.

Important

Developer Hub uses a one-way synchronization model, where user and group data flow from your Identity Provider to the Developer Hub software catalog. As a result, deleting users or groups manually through the Developer Hub Web UI or REST API might be ineffective or cause inconsistencies, since those entities will be recreated during the next ingestion.

1.2. Authenticating with the Guest user

To explore Developer Hub features, you can skip configuring authentication and authorization. You can configure Developer Hub to log in as a Guest user and access Developer Hub features.

1.2.1. Authenticating with the Guest user on an Operator-based installation

After an Operator-based installation, you can configure Developer Hub to log in as a Guest user and access Developer Hub features.

Prerequisites

You installed Developer Hub by using the Operator.
You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.

Procedure

To enable the guest user in your Developer Hub custom configuration, edit your Developer Hub application configuration with following content:
app-config.yaml fragment
```
auth:
  environment: development
  providers:
    guest:
      dangerouslyAllowOutsideDevelopment: true
```

Verification

Go to the Developer Hub login page.
To log in with the Guest user account, click Enter in the Guest tile.
In the Developer Hub Settings page, your profile name is Guest.
You can use Developer Hub features.

1.2.2. Authenticating with the Guest user on a Helm-based installation

On a Helm-based installation, you can configure Developer Hub to log in as a Guest user and access Developer Hub features.

Prerequisites

You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.
You use the Red Hat Developer Hub Helm chart to run Developer Hub.

Procedure

To enable the guest user in your Developer Hub custom configuration, configure your Red Hat Developer Hub Helm Chart with following content:

Red Hat Developer Hub Helm Chart configuration fragment

upstream:
  backstage:
    appConfig:
      app:
        baseUrl: 'https://{{- include "janus-idp.hostname" . }}'
      auth:
        environment: development
        providers:
          guest:
            dangerouslyAllowOutsideDevelopment: true

Verification

Go to the Developer Hub login page.
To log in with the Guest user account, click Enter in the Guest tile.
In the Developer Hub Settings page, your profile name is Guest.
You can use Developer Hub features.

1.3. Enabling user authentication with Red Hat Build of Keycloak (RHBK) (with mandatory steps only)

To authenticate users with Red Hat Build of Keycloak (RHBK), enable and configure the OpenID Connect (OIDC) authentication provider in Red Hat Developer Hub and provision the users and groups from RHBK to the Developer Hub software catalog.

Prerequisites

You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.
You have sufficient permissions in RHSSO to create and manage a realm and a client. Alternatively, your RHBK administrator can prepare in RHBK the required realm and client for you.

Procedure

To allow Developer Hub to authenticate with RHBK, complete the steps in RHBK, to create a realm and a user and secure the first application:
1. Use an existing realm, or create a realm, with a distinctive Name such as <my_realm>. Save the value for the next step:
  - RHBK realm base URL, such as: <your_rhbk_URL>/realms/<your_realm>.
2. To register your Developer Hub in RHBK, in the created realm, secure the first application, with:
  1. Client ID: A distinctive client ID, such as <RHDH>.
  2. Valid redirect URIs: Set to the OIDC handler URL: https://<RHDH_URL>/api/auth/oidc/handler/frame.
  3. Navigate to the Credentials tab and copy the Client secret.
  4. Save the values for the next step:
    Client ID
    Client Secret
3. To prepare for the verification steps, in the same realm, get the credential information for an existing user or create a user. Save the user credential information for the verification steps.
To add your RHSSO credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets. You can use these secrets in the Developer Hub configuration files by using their respective environment variable name.
KEYCLOAK_BASE_URL
Enter the saved RHBK realm base URL.
KEYCLOAK_CLIENT_ID
Enter the saved Client ID.
KEYCLOAK_CLIENT_SECRET
Enter the saved Client Secret.
KEYCLOAK_LOGIN_REALM
Enter the saved RHBK login realm.
KEYCLOAK_REALM
Enter the saved RHBK realm.
Enable the Keycloak organization plugin (backstage-plugin-catalog-backend-module-keycloak-dynamic). The plugin is named after RHBK upstream project. This plugin ingests RHBK users and groups to the Developer Hub software catalog. With the default configuration, the plugin runs every hour and uses your KEYCLOAK_-prefixed variables.
dynamic-plugins.yaml file fragment
```
plugins:
  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-keycloak-dynamic'
    disabled: false
```
To set up the RHBK authentication provider in your Developer Hub custom configuration, edit your custom Developer Hub ConfigMap such as app-config-rhdh, and add the following lines to the app-config.yaml content:
app-config.yaml fragment with mandatory fields to enable authentication with RHBK
```
auth:
  environment: production
  providers:
    oidc:
      production:
        metadataUrl: ${KEYCLOAK_BASE_URL}
        clientId: ${KEYCLOAK_CLIENT_ID}
        clientSecret: ${KEYCLOAK_CLIENT_SECRET}
        prompt: auto
signInPage: oidc
```
environment: production
Mark the environment as production to hide the Guest login in the Developer Hub home page.
metadataUrl, clientId, clientSecret
To configure the OIDC provider with your secrets.
sigInPage: oidc
To enable the OIDC provider as default sign-in provider.
prompt: auto
To allow the identity provider to automatically determine whether to prompt for credentials or bypass the login redirect if an active RHSSO session exists.
Note
If prompt: auto is not set, the identity provider defaults to prompt: none, which assumes that you are already logged in and rejects sign-in requests without an active session.

Verification

To verify user and group provisioning, check the console logs.

Successful synchronization example:

2025-06-27T16:02:34.647Z catalog info Read 5 Keycloak users and 3 Keycloak groups in 0.4 seconds. Committing... class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01"

2025-06-27T16:02:34.650Z catalog info Committed 5 Keycloak users and 3 Keycloak groups in 0.0 seconds. class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01"

To verify RHBK user authentication:
1. Go to the Developer Hub login page.
2. Your Developer Hub sign-in page displays Sign in using OIDC and the Guest user sign-in is disabled.
3. Log in with OIDC by using the saved Username and Password values.

Additional resources

Enabling user authentication with RHBK (with optional steps).

1.4. Enabling user authentication with GitHub (with mandatory steps only)

To authenticate users with GitHub, configure the GitHub authentication provider in Red Hat Developer Hub and provision the users and groups from GitHub to the Developer Hub software catalog.

Prerequisites

You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.
You have sufficient permissions in GitHub to create and manage a GitHub App. Alternatively, you can ask your GitHub administrator to prepare the required GitHub App.

Procedure

To allow Developer Hub to authenticate with GitHub, create a GitHub App. Opt for a GitHub App instead of an OAuth app to use fine-grained permissions and use short-lived tokens.
1. Register a GitHub App with the following configuration:
  GitHub App name
  Enter a unique name identifying your GitHub App, such as authenticating-with-rhdh-<GUID>.
  Homepage URL
  Enter your Developer Hub URL: https://<my_developer_hub_url>.
  Authorization callback URL
  Enter your Developer Hub authentication backend URL: https://<my_developer_hub_url>/api/auth/github/handler/frame.
  Webhook
  Clear "Active", as this is not needed for authentication and catalog providers.
  Organization permissions
  Enable Read-only access to Members.
  Where can this GitHub App be installed?
  Select Only on this account.
2. In the General → Clients secrets section, click Generate a new client secret.
3. In the Install App tab, choose an account to install your GitHub App on.
4. Save the following values for the next step:
  - Client ID
  - Client secret
To add your GitHub credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets. You can use these secrets in the Developer Hub configuration files by using their respective environment variable name.
AUTHENTICATION_GITHUB_CLIENT_ID
Enter the saved Client ID.
AUTHENTICATION_GITHUB_CLIENT_SECRET
Enter the saved Client Secret.
GITHUB_URL
Enter the GitHub host domain: github.com.
GITHUB_ORG
Enter your GitHub organization name, such as <your_github_organization_name>.
Enable the GitHub organization provisioning plugin (backstage-plugin-catalog-backend-module-github-org). This plugin ingests GitHub users and groups to the Developer Hub software catalog. With the default configuration, the plugin runs every hour and uses your GITHUB_URL and GITHUB_ORG variables.
dynamic-plugins.yaml file fragment
```
plugins:
  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'
    disabled: false
```
To set up the GitHub authentication provider, add the auth.providers.github section to the app-config.yaml file content:
app-config.yaml file fragment with mandatory fields to enable authentication with GitHub
```
auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}
signInPage: github
```
environment
Enter production to disable the Guest login option in the Developer Hub login page.
clientId
Enter the configured secret variable name: ${GITHUB_CLIENT_ID}.
clientSecret
Enter the configured secret variable name: ${GITHUB_CLIENT_SECRET}.
signInPage
Enter github to enable the GitHub provider as your Developer Hub sign-in provider.

Verification

To verify user and group provisioning, check the console logs.

Successful synchronization example:

{"class":"GithubMultiOrgEntityProvider","level":"info","message":"Reading GitHub users and teams for org: rhdh-dast","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:58"}
{"class":"GithubMultiOrgEntityProvider","level":"info","message":"Read 7 GitHub users and 2 GitHub groups in 0.4 seconds. Committing...","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:59"}

To verify GitHub authentication:
1. Go to the Developer Hub login page.
2. Your Developer Hub sign-in page displays Sign in using GitHub and the Guest user sign-in is disabled.
3. Log in with a GitHub account.

Additional resources

1.5. Enabling user authentication with Microsoft Azure (with mandatory steps only)

To authenticate users with Microsoft Azure, configure the Azure authentication provider in Red Hat Developer Hub and provision the users and groups from Azure to the Developer Hub software catalog.

Prerequisites

You have the permission to register an application in Azure. Alternatively, you can ask your Azure administrator to prepare the required Azure application.
You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.
Your Developer Hub backend can access the following hosts:
login.microsoftonline.com
This is the Microsoft Azure authorization server, which enables the authentication flow.
graph.microsoft.com
For retrieving organization data, including user and group data, to be ingested into the Developer Hub catalog.

Procedure

To allow Developer Hub to authenticate with Azure, Register an app by using the Azure portal.
1. Sign in to the Microsoft Entra admin center.
2. Optional: If you have access to multiple tenants, use the Settings icon in the top menu to switch to the tenant in which you want to register the application from the Directories + subscriptions menu.
3. Browse to Applications > App registrations, and create a New registration with the configuration:
  Name
  Enter a name to identify your application in Azure, such as <Authenticating with Developer Hub>.
  Supported account types
  Select Accounts in this organizational directory only.
  Redirect URI
  Select a platform
  Select Web.
  URL
  Enter the backend authentication URI set in Developer Hub: https://<my_developer_hub_url>/api/auth/microsoft/handler/frame
4. On the Applications > App registrations > <Authenticating with Developer Hub> > Manage > API permissions page, Add a Permission, Microsoft Graph, select the following permissions:
  Application Permissions
  GroupMember.Read.All, User.Read.All
  Enter permissions that enable provisioning user and groups to the Developer Hub software catalog.
  Optional: Grant admin consent for these permissions. Even if your company does not require admin consent, consider doing so as it means users do not need to individually consent the first time they access Developer Hub.
  Delegated Permissions
  User.Read, email, offline_access, openid, profile
  Enter permissions that enable authenticating users.
  Optional: Enter optional custom scopes for the Microsoft Graph API that you define both in this section and in the app-config.yaml Developer Hub configuration file.
5. On the Applications > App registrations > <Authenticating with Developer Hub> > Manage > Certificates & secrets page, in the Client secrets tab, create a New client secret.
6. Save the following values for the next step:
  - Directory (tenant) ID
  - Application (client) ID
  - Application (client) Secret ID
To add your Azure credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets:
MICROSOFT_TENANT_ID
Enter your saved Directory (tenant) ID.
MICROSOFT_CLIENT_ID
Enter your saved Application (client) ID.
MICROSOFT_CLIENT_SECRET
Enter your saved Application (client) secret.
Enable the Microsoft Graph organization provisioning plugin (backstage-plugin-catalog-backend-module-msgraph-dynamic). This plugin ingests Azure users and groups to the Developer Hub software catalog. With the default configuration, the plugin runs every hour and uses your MICROSOFT_TENANT_ID, MICROSOFT_CLIENT_ID, and MICROSOFT_CLIENT_SECRET variables.
dynamic-plugins.yaml file fragment
```
plugins:
  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic'
    disabled: false
```
Important
These features are for Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information on Red Hat Technology Preview features, see Technology Preview Features Scope.
To set up the Azure authentication provider, add the auth.providers.microsoft section to your app-config.yaml file content:
app-config.yaml file fragment with mandatory fields to enable authentication with Azure
```
auth:
  environment: production
  providers:
    microsoft:
      production:
        clientId: ${MICROSOFT_CLIENT_ID}
        clientSecret: ${MICROSOFT_CLIENT_SECRET}
        tenantId: ${MICROSOFT_TENANT_ID}
signInPage: microsoft
```
environment
Enter production to disable the Guest login option in the Developer Hub login page.
clientId
Enter the configured secret variable name: ${MICROSOFT_CLIENT_ID}.
clientSecret
Enter the configured secret variable name: ${MICROSOFT_CLIENT_SECRET}.
tenantId
Enter the configured secret variable name: ${MICROSOFT_TENANT_ID}.
signInPage
Enter microsoft to set the Azure provider as your Developer Hub sign-in provider.

Verification

To verify user and group provisioning, check the console logs for MicrosoftGraphOrgEntityProvider events.

Successful synchronization example:

2025-06-23T13:37:55.804Z catalog info Read 9 msgraph users and 3 msgraph groups in 1.5 seconds. Committing... class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01"

2025-06-23T13:37:55.811Z catalog info Committed 9 msgraph users and 3 msgraph groups in 0.0 seconds. class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01"

To verify Azure user authentication:
1. Go to the Developer Hub login page.
2. Your Developer Hub sign-in page displays Sign in using Microsoft and the Guest user sign-in is disabled.
3. Log in with an Azure account.

Additional resources

Enabling user authentication with Microsoft Azure (with optional steps).

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.