Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Authentication in Red Hat Developer Hub

Red Hat Developer Hub 1.5

Configuring authentication to external services in Red Hat Developer Hub

Red Hat Customer Content Services

Abstract

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

Preface
Copy link

Depending on your organization’s security policies, you might require to identify and authorize users before giving them access to resources, such as Red Hat Developer Hub.

In Developer Hub, authentication and authorization are two separate processes:

  1. Authentication defines the user identity, and passes on this information to Developer Hub. Read the following chapters to configure authentication in Developer Hub.
  2. Authorization defines what the authenticated identity can access or do in Developer Hub. See Authorization in Red Hat Developer Hub.
Not recommended for production

To explore Developer Hub features, you can enable the guest user to skip configuring authentication and authorization, log in as the guest user, and access all the features.

The authentication system in Developer Hub is handled by external authentication providers.

Developer Hub supports following authentication providers:

  • Red Hat Single-Sign On (RHSSO)
  • GitHub
  • Microsoft Azure

To identify users in Developer Hub, configure:

  • One (and only one) authentication provider for sign-in and identification.
  • Optionally, additional authentication providers for identification, to add more information to the user identity, or enable access to additional external resources.

For each authentication provider, set up the shared secret that the authentication provider and Developer Hub require to communicate, first in the authentication provider, then in Developer Hub.

Developer Hub stores user identity information in the Developer Hub software catalog.

Not recommended for production

To explore the authentication system and use Developer Hub without authorization policies, you can bypass the Developer Hub software catalog and start using Developer Hub without provisioning the Developer Hub software catalog.

To get, store, and update additional user information, such as group or team ownership, with the intention to use this data to define authorization policies, provision users and groups in the Developer Hub software catalog.

Important

Developer Hub uses a one-way synchronization system to provision users and groups from your authentication system to the Developer Hub software catalog. Therefore, deleting users and groups by using Developer Hub Web UI or REST API might have unintended consequences.

Chapter 1. Authenticating with the Guest user
Copy link

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.

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
    Copy to Clipboard Toggle word wrap

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.

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
    Copy to Clipboard Toggle word wrap

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

RHSSO 7.6 is deprecated as an authentication provider. You can continue using RHSSO until the end of its maintenance support. For more information, see RHSSO lifecycle dates. As an alternative, consider migrating to Red Hat Build of Keycloak (RHBK).

To authenticate users with Red Hat Build of Keycloak (RHBK):

  1. Enable the OpenID Connect (OIDC) authentication provider in RHDH.
  2. Provision users from Red Hat Build of Keycloak (RHBK) to the software catalog.

To authenticate users with Red Hat Build of Keycloak (RHBK), enable the OpenID Connect (OIDC) authentication provider in Red Hat Developer Hub.

Prerequisites

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

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

    AUTH_OIDC_CLIENT_ID
    Enter the saved Client ID.
    AUTH_OIDC_CLIENT_SECRET
    Enter the saved Client Secret.
    AUTH_OIDC_METADATA_URL
    Enter the saved RHBK realm base URL.

  3. 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. Configure mandatory fields:

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

      auth:
  environment: production
  providers:
    oidc:
      production:
        metadataUrl: ${AUTH_OIDC_METADATA_URL}
        clientId: ${AUTH_OIDC_CLIENT_ID}
        clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
        prompt: auto
signInPage: oidc
      Copy to Clipboard Toggle word wrap

      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.

callbackUrl

RHBK callback URL.

app-config.yaml fragment with optional callbackURL field

auth:
  providers:
    oidc:
      production:
        callbackUrl: ${AUTH_OIDC_CALLBACK_URL}
Copy to Clipboard Toggle word wrap

tokenEndpointAuthMethod

Token endpoint authentication method.

app-config.yaml fragment with optional tokenEndpointAuthMethod field

auth:
  providers:
    oidc:
      production:
        tokenEndpointAuthMethod: ${AUTH_OIDC_TOKEN_ENDPOINT_METHOD}
Copy to Clipboard Toggle word wrap

tokenSignedResponseAlg

Token signed response algorithm.

app-config.yaml fragment with optional tokenSignedResponseAlg field

auth:
  providers:
    oidc:
      production:
        tokenSignedResponseAlg: ${AUTH_OIDC_SIGNED_RESPONSE_ALG}
Copy to Clipboard Toggle word wrap

scope

RHBK scope.

app-config.yaml fragment with optional scope field

auth:
  providers:
    oidc:
      production:
        scope: ${AUTH_OIDC_SCOPE}
Copy to Clipboard Toggle word wrap

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

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 values:

  • emailLocalPartMatchingUserEntityName
  • emailMatchingUserEntityProfileEmail
  • preferredUsernameMatchingUserEntityName

app-config.yaml fragment with optional resolvers list

auth:
  providers:
    oidc:
      production:
        signIn:
          resolvers:
            - resolver: preferredUsernameMatchingUserEntityName
            - resolver: emailMatchingUserEntityProfileEmail
            - resolver: emailLocalPartMatchingUserEntityName
Copy to Clipboard Toggle word wrap

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: ${AUTH_OIDC_METADATA_URL}
        clientId: ${AUTH_OIDC_CLIENT_ID}
        clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
        signIn:
          resolvers:
            - resolver: emailLocalPartMatchingUserEntityName
              dangerouslyAllowSignInWithoutUserInCatalog: true
signInPage: oidc
Copy to Clipboard Toggle word wrap

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 }
Copy to Clipboard Toggle word wrap

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> }
Copy to Clipboard Toggle word wrap
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. 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.

Prerequisites

Procedure

  1. Enable the backstage-plugin-catalog-backend-module-keycloak-dynamic plugin.

    dynamic-plugins.yaml file fragment

    plugins:
  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-keycloak-dynamic'
    disabled: false
    Copy to Clipboard Toggle word wrap

  2. To enable RHBK member discovery, edit app-config.yaml, your custom Developer Hub configuration file:

    app-config.yaml fragment with mandatory keycloakOrg fields

    catalog:
  providers:
    keycloakOrg:
      default:
        baseUrl: ${AUTH_OIDC_METADATA_URL}
        clientId: ${AUTH_OIDC_CLIENT_ID}
        clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
    Copy to Clipboard Toggle word wrap

    baseUrl
    Your RHBK server URL, defined when enabling authentication with RHBK.
    clientId
    Your Developer Hub application client ID in RHBK, defined when enabling authentication with RHBK.
    clientSecret
    Your Developer Hub application client secret in RHBK, defined when enabling authentication with RHBK.

    Optional: Consider adding the following optional fields:

    realm

    Realm to synchronize. Default value: master.

    app-config.yaml fragment with optional realm field

    catalog:
  providers:
    keycloakOrg:
      default:
        realm: master
    Copy to Clipboard Toggle word wrap

    loginRealm

    Realm used to authenticate. Default value: master.

    app-config.yaml fragment with optional loginRealm field

    catalog:
  providers:
    keycloakOrg:
      default:
        loginRealm: master
    Copy to Clipboard Toggle word wrap

    userQuerySize

    User number to query simultaneously. Default value: 100.

    app-config.yaml fragment with optional userQuerySize field

    catalog:
  providers:
    keycloakOrg:
      default:
        userQuerySize: 100
    Copy to Clipboard Toggle word wrap

    groupQuerySize

    Group number to query simultaneously. Default value: 100.

    app-config.yaml fragment with optional groupQuerySize field

    catalog:
  providers:
    keycloakOrg:
      default:
        groupQuerySize: 100
    Copy to Clipboard Toggle word wrap

    schedule.frequency

    To specify custom 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 }
    Copy to Clipboard Toggle word wrap

    schedule.timeout

    To specify custom timeout. 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 }
    Copy to Clipboard Toggle word wrap

    schedule.initialDelay

    To specify custom initial delay. 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}
    Copy to Clipboard Toggle word wrap

Verification

  1. 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"}
    Copy to Clipboard Toggle word wrap

  2. Log in with an RHBK account.

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 */
      },
    });
  },
});
    Copy to Clipboard Toggle word wrap

    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))
    Copy to Clipboard Toggle word wrap

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"}
    Copy to Clipboard Toggle word wrap

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

Chapter 3. Authenticating with GitHub
Copy link

To authenticate users with GitHub or GitHub Enterprise:

  1. Enable the GitHub authentication provider in Developer Hub.
  2. Provision users from GitHub to the software catalog.

3.1. Enabling authentication with GitHub
Copy link

To authenticate users with GitHub, enable the GitHub authentication provider in Red Hat Developer Hub.

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, gain more control over which repositories the application can access, 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 <Red Hat Developer Hub>-<GUID>.
      • Homepage URL: Your Developer Hub URL: https://<my_developer_hub_url>.
      • Authorization callback URL: Your Developer Hub authentication backend URL: https://<my_developer_hub_url>/api/auth/github/handler/frame.
      • Webhook URL: Your Developer Hub URL: https://<my_developer_hub_url>.
      • Webhook secret: Provide a strong secret.

      • Repository permissions:

        • Enable Read-only access to:

          • Administration
          • Commit statuses
          • Contents
          • Dependabot alerts
          • Deployments
          • Pull Requests

          • Webhooks

            Tip

            If you plan to make changes using the GitHub API, ensure that Read and write permissions are enabled instead of Read-only.

        • Toggle other permissions as per your needs.

      • Organization permissions:

        • Enable Read-only access to Members.
      • For 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 General → Private keys section, click Generate a private key.
    4. In the Install App tab, choose an account to install your GitHub App on.

    5. Save the following values for the next step:

      • App ID
      • Client ID
      • Client secret
      • Private key
      • Webhook secret

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

    AUTH_GITHUB_APP_ID
    Enter the saved App ID.
    AUTH_GITHUB_CLIENT_ID
    Enter the saved Client ID.
    GITHUB_HOST_DOMAIN
    Enter your GitHub host domain: github.com unless you are using GitHub Enterprise.
    GITHUB_ORGANIZATION
    Enter your GitHub organization name, such as `<your_github_organization_name>'.
    GITHUB_ORG_URL
    Enter $GITHUB_HOST_DOMAIN/$GITHUB_ORGANIZATION.
    GITHUB_CLIENT_SECRET
    Enter the saved Client Secret.
    GITHUB_PRIVATE_KEY_FILE
    Enter the saved Private key.
    GITHUB_WEBHOOK_URL
    Enter your Developer Hub URL: https://<my_developer_hub_url>.
    GITHUB_WEBHOOK_SECRET
    Enter the saved Webhook secret.

  3. . To set up the GitHub authentication provider and enable integration with the GitHub API in your Developer Hub custom configuration, edit your custom Developer Hub config map such as my-rhdh-app-config, and add the following lines to the app-config.yaml file content:

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

    auth:
  environment: production
    1 
    
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
    2 
    
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
integrations:
  github:
    - host: ${GITHUB_HOST_DOMAIN}
      apps:
        - appId: ${AUTH_GITHUB_APP_ID}
          clientId: ${AUTH_GITHUB_CLIENT_ID}
          clientSecret: ${GITHUB_CLIENT_SECRET}
          webhookUrl: ${GITHUB_WEBHOOK_URL}
          webhookSecret: ${GITHUB_WEBHOOK_SECRET}
          privateKey: |
            ${GITHUB_PRIVATE_KEY_FILE}
signInPage: github
    3
    Copy to Clipboard Toggle word wrap

    1
    Mark the environment as production and disable the Guest login option in the Developer Hub login page.
    2
    Apply the GitHub credentials configured in your Developer Hub secrets.
    3
    To enable the GitHub provider as your Developer Hub sign-in provider.

    1. Optional: Consider adding the following optional fields:

      callbackUrl

      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.

      app-config.yaml file fragment with optional enterpriseInstanceUrl field

      auth:
  providers:
    github:
      production:
        callbackUrl: <your_intermediate_service_url/handler>
      Copy to Clipboard Toggle word wrap

      enterpriseInstanceUrl

      Your GitHub Enterprise URL. Requires you defined the GITHUB_HOST_DOMAIN secret in the previous step.

      app-config.yaml file fragment with optional enterpriseInstanceUrl field

      auth:
  providers:
    github:
      production:
        enterpriseInstanceUrl: ${GITHUB_HOST_DOMAIN}
      Copy to Clipboard Toggle word wrap

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

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

      auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName
              dangerouslyAllowSignInWithoutUserInCatalog: true
integrations:
  github:
    - host: ${GITHUB_HOST_DOMAIN}
      apps:
        - appId: ${AUTH_GITHUB_APP_ID}
          clientId: ${AUTH_GITHUB_CLIENT_ID}
          clientSecret: ${GITHUB_CLIENT_SECRET}
          webhookUrl: ${GITHUB_WEBHOOK_URL}
          webhookSecret: ${GITHUB_WEBHOOK_SECRET}
          privateKey: |
            ${GITHUB_PRIVATE_KEY_FILE}
signInPage: github
      Copy to Clipboard Toggle word wrap

Tip

To enable GitHub integration with a different authentication provider, complete the following configurations:

  • Add the GitHub provider to the existing auth section.
  • Keep the signInPage section from your authentication provider configuration.

app-config.yaml file fragment with mandatory fields to enable GitHub integration and use a different authentication provider

auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
    <your_other_authentication_providers_configuration>
integrations:
  github:
    - host: ${GITHUB_HOST_DOMAIN}
      apps:
        - appId: ${AUTH_GITHUB_APP_ID}
          clientId: ${AUTH_GITHUB_CLIENT_ID}
          clientSecret: ${GITHUB_CLIENT_SECRET}
          webhookUrl: ${GITHUB_WEBHOOK_URL}
          webhookSecret: ${GITHUB_WEBHOOK_SECRET}
          privateKey: |
            ${GITHUB_PRIVATE_KEY_FILE}
signInPage: <your_main_authentication_provider>
Copy to Clipboard Toggle word wrap

Verification

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

To authenticate users, Red Hat Developer Hub requires their presence in the software catalog. Consider configuring Developer Hub to provision users from GitHub to the software catalog on schedule, rather than provisioning the users manually.

Prerequisites

Procedure

  1. Enable the backstage-plugin-catalog-backend-module-github-dynamic plugin.

    dynamic-plugins.yaml file fragment

    plugins:
  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic'
    disabled: false
    Copy to Clipboard Toggle word wrap

  2. To enable GitHub member discovery, edit app-config.yaml, your custom Developer Hub configuration file:

    app-config.yaml fragment with mandatory github fields

    catalog:
  providers:
    github:
      providerId:
        organization: "${GITHUB_ORGANIZATION}"
        schedule:
          frequency:
            minutes: 30
          initialDelay:
            seconds: 15
          timeout:
            minutes: 15
    githubOrg:
      githubUrl: "${GITHUB_HOST_DOMAIN}"
      orgs: [ "${GITHUB_ORGANIZATION}" ]
      schedule:
        frequency:
          minutes: 30
        initialDelay:
          seconds: 15
        timeout:
          minutes: 15
    Copy to Clipboard Toggle word wrap

    organization, githubUrl, and orgs
    Use the Developer Hub application information that you have created in GitHub and configured in OpenShift as secrets.
    schedule.frequency
    To specify custom schedule frequency. Supports cron, ISO duration, and "human duration" as used in code.
    schedule.timeout
    To specify custom timeout. Supports ISO duration and "human duration" as used in code.
    schedule.initialDelay
    To specify custom initial delay. Supports ISO duration and "human duration" as used in code.

Verification

  1. Check the console logs to verify that the synchronization is completed.

    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:production: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:production:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:59"}
    Copy to Clipboard Toggle word wrap

  2. Log in with a GitHub account.

Chapter 4. Authentication with Microsoft Azure
Copy link

To authenticate users with Microsoft Azure:

  1. Enable authentication with Microsoft Azure.
  2. Provision users from Microsoft Azure to the software catalog.

4.1. Enabling authentication with Microsoft Azure
Copy link

Red Hat Developer Hub includes a Microsoft Azure authentication provider that can authenticate users by using OAuth.

Prerequisites

  1. You have the permission to register an application in Microsoft Azure.

Procedure

  1. To allow Developer Hub to authenticate with Microsoft Azure, create an OAuth application in Microsoft Azure.

    1. In the Azure portal go to App registrations, create a New registration with the configuration:

      Name
      The application name in Azure, such as <My Developer Hub>.

    2. On the Home > App registrations > <My Developer Hub> > Manage > Authentication page, Add a platform, with the following configuration:

      Redirect URI
      Enter the backend authentication URI set in Developer Hub: https://<my_developer_hub_url>/api/auth/microsoft/handler/frame
      Front-channel logout URL
      Leave blank.
      Implicit grant and hybrid flows
      Leave all checkboxes cleared.

    3. On the Home > App registrations > <My Developer Hub> > Manage > API permissions page, Add a Permission, then add the following Delegated permission for the Microsoft Graph API:

      • email
      • offline_access
      • openid
      • profile
      • User.Read.All
      • GroupMember.Read.All
      • 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.

Your company might require you to grant admin consent for these permissions. Even if your company does not require admin consent, you might do so as it means users do not need to individually consent the first time they access backstage. To grant administrator consent, a directory administrator must go to the admin consent page and click Grant admin consent for COMPANY NAME.

  1. On the Home > App registrations > <My Developer Hub> > Manage > Certificates & Secrets page, in the Client secrets tab, create a New client secret.

  2. Save for the next step:

    • Directory (tenant) ID
    • Application (client) ID

    • Application (client) secret

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

        AUTH_AZURE_TENANT_ID
        Enter your saved Directory (tenant) ID.
        AUTH_AZURE_CLIENT_ID
        Enter your saved Application (client) ID.
        AUTH_AZURE_CLIENT_SECRET
        Enter your saved Application (client) secret.

      2. Set up the Microsoft Azure authentication provider in your app-config.yaml file:

        app-config.yaml file fragment

        auth:
  environment: production
        1 
        
  providers:
    microsoft:
      production:
        clientId: ${AUTH_AZURE_CLIENT_ID}
        2 
        
        clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
        tenantId: ${AUTH_AZURE_TENANT_ID}
signInPage: microsoft
        3
        Copy to Clipboard Toggle word wrap

        1
        Mark the environment as production and disable the Guest login option in the Developer Hub login page.
        2
        Apply the Microsoft Azure credentials configured in your Developer Hub secrets.
        3
        Set the Microsoft Azure provider as your Developer Hub sign-in provider.

  3. 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: ${AUTH_AZURE_TENANT_ID}
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    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:
    microsoft:
      production:
        sessionDuration: { hours: 24 }
    Copy to Clipboard Toggle word wrap

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

    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:

    • userIdMatchingUserEntityAnnotation
    • emailLocalPartMatchingUserEntityName
    • 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.

    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: ${AUTH_AZURE_CLIENT_ID}
        clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
        tenantId: ${AUTH_AZURE_TENANT_ID}
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName
              dangerouslyAllowSignInWithoutUserInCatalog: true
signInPage: microsoft
    Copy to Clipboard Toggle word wrap

Note

This step is optional for environments with outgoing access restrictions, such as firewall rules. If your environment has such restrictions, ensure that your RHDH backend can access the following hosts:

  • login.microsoftonline.com: For obtaining and exchanging authorization codes and access tokens.
  • graph.microsoft.com: For retrieving user profile information (as referenced in the source code). If this host is unreachable, you might see an Authentication failed, failed to fetch user profile error when attempting to log in.

To authenticate users with Microsoft Azure, after Enabling authentication with Microsoft Azure, provision users from Microsoft Azure to the Developer Hub software catalog.

Prerequisites

Procedure

  1. Enable the backstage-plugin-catalog-backend-module-msgraph-dynamic plugin.

    dynamic-plugins.yaml file fragment

    plugins:
  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic'
    disabled: false
    Copy to Clipboard Toggle word wrap

  2. To enable Microsoft Azure member discovery, edit app-config.yaml, your custom Developer Hub configuration file::

    app-config.yaml fragment with mandatory microsoftGraphOrg fields

    catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        target: https://graph.microsoft.com/v1.0
        tenantId: ${AUTH_AZURE_TENANT_ID}
        clientId: ${AUTH_AZURE_CLIENT_ID}
        clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
        schedule:
          frequency: { hours: 1 }
          timeout: { minutes: 50 }
          initialDelay: { minutes: 50 }
    Copy to Clipboard Toggle word wrap

    target: https://graph.microsoft.com/v1.0
    Defines 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, clientId and clientSecret
    Use the Developer Hub application information you created in Microsoft Azure and configured in OpenShift as secrets.
    schedule
    frequency
    Enter the schedule frequency as cron, ISO duration, or human duration as used in code.
    timeout
    Enter the schedule timeout as ISO duration or human duration as used in code.
    initialDelay

    Enter the schedule initial delay as ISO duration or human duration as used in code.

    Tip

    In a large organization, this plugin can take a long time. Therefore, avoid setting a low frequency or timeout when importing a large number of users and groups for the first time.

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

authority: https://login.microsoftonline.com

Defines the authority used. Change the value to use a different authority, such as Azure US government. Default value: https://login.microsoftonline.com.

app-config.yaml fragment with optional queryMode field

catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        authority: https://login.microsoftonline.com/
Copy to Clipboard Toggle word wrap

queryMode: basic | advanced

By default, the Microsoft Graph API only provides the basic feature set for querying. Certain features require advanced querying capabilities. See Microsoft Azure Advanced queries.

app-config.yaml fragment with optional queryMode field

catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        queryMode: advanced
Copy to Clipboard Toggle word wrap

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 ] or xref:userFilter[.

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

catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        user:
          expand: manager
Copy to Clipboard Toggle word wrap

user.filter

To filter users. See Microsoft Graph API and Microsoft Graph API query filter parameters syntax. This parameter and ???TITLE??? 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'
Copy to Clipboard Toggle word wrap

user.loadPhotos: true | false

Load photos by default. Set to false to not load user photos.

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

catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        user:
          loadPhotos: true
Copy to Clipboard Toggle word wrap

user.select

Define the Microsoft Graph resource types to retrieve.

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

catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        user:
          select: ['id', 'displayName', 'description']
Copy to Clipboard Toggle word wrap

userGroupMember.filter

To use group membership to get users. To filter groups and fetch their members. This parameter and ???TITLE??? 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'"
Copy to Clipboard Toggle word wrap

userGroupMember.search

To use group membership to get users. To search for groups and fetch their members. This parameter and ???TITLE??? 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")'
Copy to Clipboard Toggle word wrap

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 https://docs.microsoft.com/en-us/graph/query-parameters#expand-parameter This parameter can be combined with ] instead of xref:userFilter[.

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

catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        group:
          expand: member
Copy to Clipboard Toggle word wrap

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')
Copy to Clipboard Toggle word wrap

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")'
Copy to Clipboard Toggle word wrap

group.select

To define the Microsoft Graph resource types to retrieve.

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

catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        group:
          select: ['id', 'displayName', 'description']
Copy to Clipboard Toggle word wrap

Verification

  1. Check the console logs to verify that the synchronization is completed.

    Successful synchronization example:

    backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Read 1 msgraph users and 1 msgraph groups in 2.2 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"}
backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Committed 1 msgraph users and 1 msgraph groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"}
    Copy to Clipboard Toggle word wrap

  2. Log in with a Microsoft Azure account.

Legal Notice
Copy link

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.
Back to top
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

© 2025 Red Hat