Red Hat Developer Hub 1.7

Authentication in Red Hat Developer Hub

Configuring authentication to external services in Red Hat Developer Hub

Red Hat Customer Content Services

Abstract

As a Red Hat Developer Hub (RHDH) platform engineer, you can manage authentication of other users to meet the specific needs of your organization.

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.

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.

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

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

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

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

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

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

3. Authenticating with Red Hat Build of Keycloak (RHBK)

3.1. Enabling user authentication with Red Hat Build of Keycloak (RHBK)

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

  1. 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://<my_developer_hub_domain>/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.

  2. 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.

    AUTHENTICATION_OIDC_CLIENT_ID
    Enter the saved Client ID.
    AUTHENTICATION_OIDC_CLIENT_SECRET
    Enter the saved Client Secret.
    AUTHENTICATION_OIDC_METADATA_URL
    Enter the saved RHBK realm base URL.

  3. Enable the Keycloak organization plugin (backstage-community-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.

    dynamic-plugins.yaml file fragment

    plugins:
  - package: './dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic'
    disabled: false

  4. To provision RHBK users and groups to the Developer Hub software catalog, add the catalog.providers.keycloakOrg section to your custom Developer Hub app-config.yaml configuration file:

    1. Add mandatory fields:

      app-config.yaml fragment with mandatory keycloakOrg fields

      catalog:
  providers:
    keycloakOrg:
      default:
        baseUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
        clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
        clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET}
        realm: master
        loginRealm: master

      baseUrl
      Enter your RHBK server URL, defined when enabling authentication with RHBK.
      clientId
      Enter your Developer Hub application client ID in RHBK, defined when enabling authentication with RHBK.
      clientSecret
      Enter your Developer Hub application client secret in RHBK, defined when enabling authentication with RHBK.
      realm
      Enter the realm name to provision users, such as master.
      loginRealm
      Enter the realm name to authenticate users, such as master.

    2. Optional: Consider adding optional fields:

      userQuerySize

      Enter the user count to query simultaneously. Default value: 100.

      app-config.yaml fragment with optional userQuerySize field

      catalog:
  providers:
    keycloakOrg:
      default:
        userQuerySize: 100

      groupQuerySize

      Enter the group count to query simultaneously. Default value: 100.

      app-config.yaml fragment with optional groupQuerySize field

      catalog:
  providers:
    keycloakOrg:
      default:
        groupQuerySize: 100

      schedule.frequency

      Enter the schedule frequency. Supports cron, ISO duration, and "human duration" as used in code.

      app-config.yaml fragment with optional schedule.frequency field

      catalog:
  providers:
    keycloakOrg:
      default:
        schedule:
          frequency: { hours: 1 }

      schedule.timeout

      Enter the timeout for the user provisioning job. Supports ISO duration and "human duration" as used in code.

      app-config.yaml fragment with optional schedule.timeout field

      catalog:
  providers:
    keycloakOrg:
      default:
        schedule:
          timeout: { minutes: 50 }

      schedule.initialDelay

      Enter the initial delay to wait for before starting the user provisioning job. Supports ISO duration and "human duration" as used in code.

      app-config.yaml fragment with optional schedule.initialDelay field

      catalog:
  providers:
    keycloakOrg:
      default:
        schedule:
          initialDelay: { seconds: 15}

  5. 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:

    1. Add mandatory fields:

      app-config.yaml fragment with mandatory fields to enable authentication with RHBK

      auth:
  environment: production
  providers:
    oidc:
      production:
        metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
        clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
        clientSecret: ${AUTHENTICATION_OIDC_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.

    2. Optional: Consider adding optional fields:

      callbackUrl

      RHBK callback URL.

      app-config.yaml fragment with optional callbackURL field

      auth:
  providers:
    oidc:
      production:
        callbackUrl: ${AUTHENTICATION_OIDC_CALLBACK_URL}

      tokenEndpointAuthMethod

      Token endpoint authentication method.

      app-config.yaml fragment with optional tokenEndpointAuthMethod field

      auth:
  providers:
    oidc:
      production:
        tokenEndpointAuthMethod: ${AUTHENTICATION_OIDC_TOKEN_ENDPOINT_METHOD}

      tokenSignedResponseAlg

      Token signed response algorithm.

      app-config.yaml fragment with optional tokenSignedResponseAlg field

      auth:
  providers:
    oidc:
      production:
        tokenSignedResponseAlg: ${AUTHENTICATION_OIDC_SIGNED_RESPONSE_ALG}

      additionalScopes

      Enter additional RHBK scopes to request for during the authentication flow.

      app-config.yaml fragment with optional additionalScopes field

      auth:
  providers:
    oidc:
      production:
        additionalScopes: ${AUTHENTICATION_OIDC_SCOPE}

      signIn
      resolvers

      After successful authentication, the user signing in must be resolved to an existing user in the Developer Hub catalog. To best match users securely for your use case, consider configuring a specific resolver.

      Enter the resolver list to override the default resolver: oidcSubClaimMatchingKeycloakUserId.

      Available values:

      oidcSubClaimMatchingKeycloakUserId
      Matches the user with the immutable sub parameter from OIDC to the RHBK user ID. Consider using this resolver for enhanced security.
      emailLocalPartMatchingUserEntityName
      Matches the email local part with the user entity name.
      emailMatchingUserEntityProfileEmail
      Matches the email with the user entity profile email.
      preferredUsernameMatchingUserEntityName

      Matches the preferred username with the user entity name.

      The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed.

      Warning

      In production mode, only configure one resolver to ensure users are securely matched.

      app-config.yaml fragment with optional resolvers list

      auth:
  providers:
    oidc:
      production:
        signIn:
          resolvers:
            - resolver: oidcSubClaimMatchingKeycloakUserId
            - resolver: preferredUsernameMatchingUserEntityName
            - resolver: emailMatchingUserEntityProfileEmail
            - resolver: emailLocalPartMatchingUserEntityName

      dangerouslyAllowSignInWithoutUserInCatalog: true

      Configure the sign-in resolver to bypass the user provisioning requirement in the Developer Hub software catalog.

      Warning

      Use this option to explore Developer Hub features, but do not use it in production.

      app-config-rhdh.yaml fragment with optional field to allow signing in users absent from the software catalog

      auth:
  environment: production
  providers:
    oidc:
      production:
        metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
        clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
        clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET}
        signIn:
          resolvers:
            - resolver: oidcSubClaimMatchingKeycloakUserID
              dangerouslyAllowSignInWithoutUserInCatalog: true
signInPage: oidc

      sessionDuration

      Lifespan of the user session. Enter a duration in ms library format (such as '24h', '2 days'), ISO duration, or "human duration" as used in code.

      app-config-rhdh.yaml fragment with optional sessionDuration field

      auth:
  providers:
    github:
      production:
        sessionDuration: { hours: 24 }

      auth
      backstageTokenExpiration
      To modify the Developer Hub token expiration from its default value of one hour, note that this refers to the validity of short-term cryptographic tokens, not the session duration. The expiration value must be set between 10 minutes and 24 hours.

      .app-config.yaml fragment with optional auth.backstageTokenExpiration field 

      auth:
  backstageTokenExpiration: { minutes: <user_defined_value> }
      Security consideration

      If multiple valid refresh tokens are issued due to frequent refresh token requests, older tokens will remain valid until they expire. To enhance security and prevent potential misuse of older tokens, enable a refresh token rotation strategy in your RHBK realm.

      1. From the Configure section of the navigation menu, click Realm Settings.
      2. From the Realm Settings page, click the Tokens tab.
      3. From the Refresh tokens section of the Tokens tab, toggle the Revoke Refresh Token to the Enabled position.

Verification

  1. 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"

  2. 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.

3.2. Creating a custom transformer to provision users from Red Hat Build of Keycloak (RHBK) to the software catalog

To customize how RHBK users and groups are mapped to Red Hat Developer Hub entities, you can create a backend module that uses the keycloakTransformerExtensionPoint to provide custom user and group transformers for the Keycloak backend.

Prerequisites

Procedure

  1. Create a new backend module with the yarn new command.

  2. Add your custom user and group transformers to the keycloakTransformerExtensionPoint.

    The following is an example of how the backend module can be defined:

    plugins/<module-name>/src/module.ts

    import {
  GroupTransformer,
  keycloakTransformerExtensionPoint,
  UserTransformer,
} from '@backstage-community/plugin-catalog-backend-module-keycloak';

const customGroupTransformer: GroupTransformer = async (
  entity, // entity output from default parser
  realm, // Keycloak realm name
  groups, // Keycloak group representation
) => {
  /* apply transformations */
  return entity;
};
const customUserTransformer: UserTransformer = async (
  entity, // entity output from default parser
  user, // Keycloak user representation
  realm, // Keycloak realm name
  groups, // Keycloak group representation
) => {
  /* apply transformations */
  return entity;
};

export const keycloakBackendModuleTransformer = createBackendModule({
  pluginId: 'catalog',
  moduleId: 'keycloak-transformer',
  register(reg) {
    reg.registerInit({
      deps: {
        keycloak: keycloakTransformerExtensionPoint,
      },
      async init({ keycloak }) {
        keycloak.setUserTransformer(customUserTransformer);
        keycloak.setGroupTransformer(customGroupTransformer);
        /* highlight-add-end */
      },
    });
  },
});

    Important

    The module’s pluginId must be set to catalog to match the pluginId of the keycloak-backend; otherwise, the module fails to initialize.

  3. Install this new backend module into your Developer Hub backend. 

    backend.add(import(backstage-plugin-catalog-backend-module-keycloak-transformer))

Verification

  • Developer Hub imports the users and groups each time when started. Check the console logs to verify that the synchronization is completed.

    Successful synchronization example:

    {"class":"KeycloakOrgEntityProvider","level":"info","message":"Read 3 Keycloak users and 2 Keycloak groups in 1.5 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"}
{"class":"KeycloakOrgEntityProvider","level":"info","message":"Committed 3 Keycloak users and 2 Keycloak groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"}

  • After the first import is complete, navigate to the Catalog page and select User to view the list of users.
  • When you select a user, you see the information imported from RHBK.
  • You can select a group, view the list, and access or review the information imported from RHBK.
  • You can log in with an RHBK account.

4. Enabling user authentication with GitHub

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

Procedure

  1. 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_domain>.
      Authorization callback URL
      Enter your Developer Hub authentication backend URL: https://<my_developer_hub_domain>/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

  2. 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.
    AUTHENTICATION_GITHUB_HOST_DOMAIN
    Enter the GitHub host domain: github.com.
    AUTHENTICATION_GITHUB_ORGANIZATION
    Enter your GitHub organization name, such as <your_github_organization_name>.

  3. 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.

    dynamic-plugins.yaml file fragment

    plugins:
  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'
    disabled: false

  4. To provision GitHub users and groups to the Developer Hub software catalog, add the catalog.providers.githubOrg section to your custom Developer Hub app-config.yaml configuration file:

    app-config.yaml fragment with mandatory catalog.providers.githubOrg fields

    catalog:
  providers:
    githubOrg:
      id: githuborg
      githubUrl: "${AUTHENTICATION_GITHUB_HOST_DOMAIN}"
      orgs: [ "${AUTHENTICATION_GITHUB_ORGANIZATION}" ]
      schedule:
        frequency:
          minutes: 30
        initialDelay:
          seconds: 15
        timeout:
          minutes: 15

    id
    Enter a stable identifier for this provider, such as githuborg. Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities and/or conflicts.
    githubUrl
    Enter the configured secret variable name: ${AUTHENTICATION_GITHUB_HOST_DOMAIN}.
    orgs
    Enter the configured secret variable name: ${AUTHENTICATION_GITHUB_ORGANIZATION}.
    schedule.frequency
    Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.
    schedule.timeout
    Enter your schedule timeout, in the ISO duration or "human duration" format.
    schedule.initialDelay
    Enter your schedule initial delay, in the ISO duration or "human duration" format.

  5. 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: ${AUTHENTICATION_GITHUB_CLIENT_ID}
        clientSecret: ${AUTHENTICATION_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: ${AUTHENTICATION_GITHUB_CLIENT_ID}.
    clientSecret
    Enter the configured secret variable name: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}.
    signInPage
    Enter github to enable the GitHub provider as your Developer Hub sign-in provider.

    Optional: Consider adding the following optional fields:

    app-config.yaml file fragment including optional fields to enable authentication with GitHub

    auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID}
        clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}
        callbackUrl: <your_intermediate_service_url/handler>
        sessionDuration: { hours: 24 }
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName
              dangerouslyAllowSignInWithoutUserInCatalog: true
signInPage: github

    callbackUrl
    Enter the callback URL that GitHub uses when initiating an OAuth flow, such as: <your_intermediate_service_url/handler>. Define it when Developer Hub is not the immediate receiver, such as in cases when you use one OAuth app for many Developer Hub instances.
    sessionDuration
    Enter the user session lifespan, in ms library format (such as '24h', '2 days'), ISO duration, or "human duration".
    signIn
    resolvers
    After successful authentication, Developer Hub resolves the user signing in to an existing user in the Developer Hub catalog. To best match users securely for your use case, consider configuring a specific resolver.

    Enter the resolver list to override the default resolver: usernameMatchingUserEntityName.

    The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed.

    Warning

    In production mode, only configure one resolver to ensure users are securely matched.

    resolver

    Enter the sign-in resolver name. Available resolvers:

    • usernameMatchingUserEntityName
    • preferredUsernameMatchingUserEntityName
    • emailMatchingUserEntityProfileEmail
    dangerouslyAllowSignInWithoutUserInCatalog: true

    Configure the sign-in resolver to bypass the user provisioning requirement in the Developer Hub software catalog.

    Warning

    Use dangerouslyAllowSignInWithoutUserInCatalog to explore Developer Hub features, but do not use it in production.

Verification

  1. 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"}

  2. 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

5. Enabling user authentication with Microsoft Azure

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

  1. 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_domain>/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

  2. To add your Azure credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets:

    AUTHENTICATION_AZURE_TENANT_ID
    Enter your saved Directory (tenant) ID.
    AUTHENTICATION_AZURE_CLIENT_ID
    Enter your saved Application (client) ID.
    AUTHENTICATION_AZURE_CLIENT_SECRET
    Enter your saved Application (client) secret.

  3. 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.

    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.

  4. To provision Azure users and groups to the Developer Hub software catalog, add the catalog.providers.microsoftGraphOrg section to your custom Developer Hub app-config.yaml configuration file:

    app-config.yaml fragment with mandatory microsoftGraphOrg fields

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        target: https://graph.microsoft.com/v1.0
        tenantId: ${AUTHENTICATION_AZURE_TENANT_ID}
        clientId: ${AUTHENTICATION_AZURE_CLIENT_ID}
        clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET}
        schedule:
          frequency:
            hours: 1
          timeout:
            minutes: 50
          initialDelay:
            minutes: 50

    target
    Enter https://graph.microsoft.com/v1.0 to define the MSGraph API endpoint the provider is connecting to. You might change this parameter to use a different version, such as the beta endpoint.
    tenandId
    Enter the configured secret variable name: ${AUTHENTICATION_AZURE_TENANT_ID}.
    clientId
    Enter the configured secret variable name: ${AUTHENTICATION_AZURE_CLIENT_ID}.
    clientSecret
    Enter the configured secret variable name: ${AUTHENTICATION_AZURE_CLIENT_SECRET}.
    schedule
    frequency
    Enter the schedule frequency in the cron, ISO duration, or human duration format. In a large organization, user provisioning might take a long time, therefore avoid using a low value.
    timeout
    Enter the schedule timeout in the ISO duration or human duration format. In a large organization, user provisioning might take a long time, therefore avoid using a low value.
    initialDelay
    Enter the schedule initial delay in the ISO duration or human duration format.

    Optional: Consider adding the following optional microsoftGraphOrg.providerId fields:

    authority

    Enter your Azure authority URL, when different from the default: https://login.microsoftonline.com.

    app-config.yaml fragment with optional queryMode field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        authority: https://login.microsoftonline.com/

    queryMode: basic | advanced

    Enter advanced when the default basic query mode is not sufficient for your queries to the Microsoft Graph API. See Microsoft Azure advanced queries.

    app-config.yaml fragment with optional queryMode field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        queryMode: advanced

    user.expand

    To include the expanded resource or collection referenced by a single relationship (navigation property) in your results. Only one relationship can be expanded in a single request. See Microsoft Graph query expand parameter. This parameter can be combined with userGroupMember.filter or user.filter.

    app-config.yaml fragment with optional user.expand field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        user:
          expand: manager

    user.filter

    To filter users. See Microsoft Graph API and Microsoft Graph API query filter parameters syntax. This parameter and userGroupMember.filter are mutually exclusive, only one can be specified.

    app-config.yaml fragment with optional user.filter field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        user:
          filter: accountEnabled eq true and userType eq 'member'

    user.loadPhotos: true | false

    Developer Hub loads photos by default. Enter false to avoid loading user photos.

    app-config.yaml fragment with optional user.loadPhotos field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        user:
          loadPhotos: true

    user.select

    Enter the Microsoft Graph resource type list to retrieve.

    app-config.yaml fragment with optional user.select field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        user:
          select: ['id', 'displayName', 'description']

    userGroupMember.filter

    To use group membership to get users. To filter groups and fetch their members. This parameter and user.filter are mutually exclusive, only one can be specified.

    app-config.yaml fragment with optional userGroupMember.filter field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        userGroupMember:
          filter: "displayName eq 'Backstage Users'"

    userGroupMember.search

    To use group membership to get users. To search for groups and fetch their members. This parameter and user.filter are mutually exclusive, only one can be specified.

    app-config.yaml fragment with optional userGroupMember.search field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        userGroupMember:
          search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")'

    group.expand

    Optional parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results. Only one relationship can be expanded in a single request. See Customize Microsoft Graph responses with query parameters. This parameter can be combined with userGroupMember.filter instead of user.filter.

    app-config.yaml fragment with optional group.expand field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        group:
          expand: member

    group.filter

    To filter groups. See Microsoft Graph API query group syntax.

    app-config.yaml fragment with optional group.filter field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        group:
          filter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified')

    group.search

    To search for groups. See Microsoft Graph API query search parameter.

    app-config.yaml fragment with optional group.search field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        group:
          search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")'

    group.select

    Enter the Microsoft Graph resource type list to retrieve.

    app-config.yaml fragment with optional group.select field

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        group:
          select: ['id', 'displayName', 'description']

  5. 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: ${AUTHENTICATION_AZURE_CLIENT_ID}
        clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET}
        tenantId: ${AUTHENTICATION_AZURE_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: ${AUTHENTICATION_AZURE_CLIENT_ID}.
    clientSecret
    Enter the configured secret variable name: ${AUTHENTICATION_AZURE_CLIENT_SECRET}.
    tenantId
    Enter the configured secret variable name: ${AUTHENTICATION_AZURE_TENANT_ID}.
    signInPage
    Enter microsoft to set the Azure provider as your Developer Hub sign-in provider.

    Optional: Consider adding following optional fields:

    domainHint

    Optional for single-tenant applications. You can reduce login friction for users with accounts in multiple tenants by automatically filtering out accounts from other tenants. If you want to use this parameter for a single-tenant application, uncomment and enter the tenant ID. If your application registration is multi-tenant, leave this parameter blank. For more information, see Home Realm Discovery.

    app-config.yaml file fragment with optional domainHint field

    auth:
  environment: production
  providers:
    microsoft:
      production:
        domainHint: ${AUTHENTICATION_AZURE_TENANT_ID}

    additionalScopes

    Optional for additional scopes. To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. The default and mandatory value lists: 'openid', 'offline_access', 'profile', 'email', 'User.Read'.

    app-config.yaml file fragment with optional additionalScopes field

    auth:
  environment: production
  providers:
    microsoft:
      production:
        additionalScopes:
           - Mail.Send

    sessionDuration

    Lifespan of the user session. Enter a duration in ms library (such as '24h', '2 days'), ISO duration, or "human duration" format.

    app-config-rhdh.yaml fragment with optional sessionDuration field

    auth:
  providers:
    microsoft:
      production:
        sessionDuration:
          hours: 24

    signIn
    resolvers
    After successful authentication, Developer Hub resolves the user signing in to an existing user in the Developer Hub catalog. To best match users securely for your use case, consider configuring a specific resolver.

    Enter the resolver list to override the default resolver: userIdMatchingUserEntityAnnotation.

    The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed.

    Warning

    In production mode, only configure one resolver to ensure users are securely matched.

    app-config-rhdh.yaml fragment with optional field to allow signing in users absent from the software catalog

    auth:
  environment: production
  providers:
    microsoft:
      production:
        clientId: ${AUTHENTICATION_AZURE_CLIENT_ID}
        clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET}
        tenantId: ${AUTHENTICATION_AZURE_TENANT_ID}
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName
              dangerouslyAllowSignInWithoutUserInCatalog: true
signInPage: microsoft

    resolver

    Enter the sign-in resolver name. Available resolvers:

    emailMatchingUserEntityAnnotation:

    This resolver looks up the user by matching their Microsoft email to the email entity annotation.

    emailLocalPartMatchingUserEntityName:

    This resolver looks up the user by matching their Microsoft email user name to the user entity name.

    emailMatchingUserEntityProfileEmail:
    This resolver looks up the user by matching their Microsoft email to the user entity profile email.
    dangerouslyAllowSignInWithoutUserInCatalog: true

    Configure the sign-in resolver to bypass the user provisioning requirement in the Developer Hub software catalog.

    Warning

    Use dangerouslyAllowSignInWithoutUserInCatalog to explore Developer Hub features, but do not use it in production.

Verification

  1. 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"

  2. 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.

Legal Notice

Copyright © 2025 Red Hat, Inc.
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.