Authentication within Red Hat Developer Hub facilitates user sign-in, identification, and access to external resources. It supports multiple authentication providers.

Authentication providers are typically used in the following ways:

  • One provider for sign-in and identification.

  • Additional providers for accessing external resources.

The Red Hat Developer Hub supports the following authentication providers:

Microsoft Azure

microsoft

GitHub

github

Keycloak

oidc

For each provider that you want to use, follow the dedicated procedure to complete the following tasks:

  1. Set up the shared secret that the authentication provider and Red Hat Developer Hub require to communicate.

  2. Configure Red Hat Developer Hub to use the authentication provider.

Chapter 1. Authenticating with the Guest user

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

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

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

Chapter 2. Enabling the OpenID Connect authentication provider

Red Hat Developer Hub uses the OpenID Connect (OIDC) authentication provider to authenticate with third-party services that support the OIDC protocol.

2.1. Overview of using the OIDC authentication provider in Developer Hub

You can configure the OIDC authentication provider in Developer Hub by updating your app-config.yaml file under the root auth configuration. For example:

auth:
  environment: production
  # Providing an auth.session.secret will enable session support in the auth-backend
  session:
    secret: ${SESSION_SECRET}
  providers:
    oidc:
      production:
        metadataUrl: ${AUTH_OIDC_METADATA_URL}
        clientId: ${AUTH_OIDC_CLIENT_ID}
        clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
        prompt: ${AUTH_OIDC_PROMPT} # Recommended to use auto
        ## Uncomment for additional configuration options
        # callbackUrl: ${AUTH_OIDC_CALLBACK_URL}
        # tokenEndpointAuthMethod: ${AUTH_OIDC_TOKEN_ENDPOINT_METHOD}
        # tokenSignedResponseAlg: ${AUTH_OIDC_SIGNED_RESPONSE_ALG}
        # scope: ${AUTH_OIDC_SCOPE}
        ## Declarative resolvers to override the default resolver: `emailLocalPartMatchingUserEntityName`
        ## The authentication provider tries each sign-in resolver until it succeeds, and fails if none succeed. Uncomment the resolvers that you want to use.
        # signIn:
        #   resolvers:
        #     - resolver: preferredUsernameMatchingUserEntityName
        #     - resolver: emailMatchingUserEntityProfileEmail
        #     - resolver: emailLocalPartMatchingUserEntityName
signInPage: oidc

2.2. Configuring Keycloak with the OIDC authentication provider

Red Hat Developer Hub includes an OIDC authentication provider that can authenticate users by using Keycloak.

Important

The user that you create in Keycloak must also be available in the Developer Hub catalog.
Procedure

  1. In Keycloak, create a new realm, for example RHDH.

  2. Add a new user.

    Username

    Username for the user, for example: rhdhuser

    Email

    Email address of the user.

    First name

    First name of the user.

    Last name

    Last name of the user.

    Email verified

    Toggle to On.

  3. Click Create.

  4. Navigate to the Credentials tab.

  5. Click Set password.

  6. Enter the Password for the user account and toggle Temporary to Off.

  7. Create a new Client ID, for example, RHDH.

    Client authentication

    Toggle to On.

    Valid redirect URIs

    Set to the OIDC handler URL, for example, https://<RHDH_URL>/api/auth/oidc/handler/frame.

  8. Navigate to the Credentials tab and copy the Client secret.

  9. Save the Client ID and the Client Secret for the next step.

  10. In Developer Hub, add your Keycloak credentials in your Developer Hub secrets.

    1. Edit your Developer Hub secrets, such as secrets-rhdh.

    2. Add the following key/value pairs:

      AUTH_KEYCLOAK_CLIENT_ID

      Enter the Client ID that you generated in Keycloak, such as RHDH.

      AUTH_KEYCLOAK_CLIENT_SECRET

      Enter the Client Secret that you generated in Keycloak.

  11. Set up the OIDC authentication provider in your Developer Hub custom configuration.

    1. Edit your custom Developer Hub ConfigMap, such as app-config-rhdh.

    2. In the app-config-rhdh.yaml content, add the oidc provider configuration under the root auth configuration, and enable the oidc provider for sign-in:

      app-config-rhdh.yaml fragment
      auth:
  environment: production
  providers:
    oidc:
      production:
      clientId: ${AUTH_KEYCLOAK_CLIENT_ID}
      clientSecret: ${AUTH_KEYCLOAK_CLIENT_SECRET}
      metadataUrl: ${KEYCLOAK_BASE_URL}/auth/realms/${KEYCLOAK_REALM}
      prompt: ${KEYCLOAK_PROMPT} # recommended to use auto
       Uncomment for additional configuration options
      #callbackUrl: ${KEYCLOAK_CALLBACK_URL}
      #tokenEndpointAuthMethod: ${KEYCLOAK_TOKEN_ENDPOINT_METHOD}
      #tokenSignedResponseAlg: ${KEYCLOAK_SIGNED_RESPONSE_ALG}
      #scope: ${KEYCLOAK_SCOPE}
       If you are using the keycloak-backend plugin, use the preferredUsernameMatchingUserEntityName resolver to avoid a login error.
      signIn:
        resolvers:
          - resolver: preferredUsernameMatchingUserEntityName
signInPage: oidc
Verification

  1. Restart your backstage-developer-hub application to apply the changes.

  2. Your Developer Hub sign-in page displays Sign in using OIDC.

2.3. Migrating from OAuth2 Proxy with Keycloak to OIDC in Developer Hub

If you are using OAuth2 Proxy as an authentication provider with Keycloak, and you want to migrate to OIDC, you can update your authentication provider configuration to use OIDC.

Procedure

  1. In Keycloak, update the valid redirect URI to https://<rhdh_url>/api/auth/oidc/handler/frame. Make sure to replace <rhdh_url> with your Developer Hub application URL, such as, my.rhdh.example.com.

  2. Replace the oauth2Proxy configuration values in the auth section of your app-config.yaml file with the oidc configuration values.

  3. Update the signInPage configuration value from oauth2Proxy to oidc.

    The following example shows the auth.providers and signInPage configuration for oauth2Proxy prior to migrating the authentication provider to oidc:

    auth:
  environment: production
  session:
    secret: ${SESSION_SECRET}
  providers:
    oauth2Proxy: {}
signInPage: oauth2Proxy

    The following example shows the auth.providers and signInPage configuration after migrating the authentication provider to oidc:

    auth:
  environment: production
  session:
    secret: ${SESSION_SECRET}
  providers:
    oidc:
      production:
        metadataUrl: ${KEYCLOAK_METADATA_URL}
        clientId: ${KEYCLOAK_CLIENT_ID}
        clientSecret: ${KEYCLOAK_CLIENT_SECRET}
        prompt: ${KEYCLOAK_PROMPT} # recommended to use auto
signInPage: oidc

  4. Remove the OAuth2 Proxy sidecar container and update the upstream.service section of your Helm chart’s values.yaml file as follows:

    • service.ports.backend: 7007

    • service.ports.targetPort: backend

      The following example shows the service configuration for oauth2Proxy prior to migrating the authentication provider to oidc:

      service:
  ports:
    name: http-backend
    backend: 4180
    targetPort: oauth2Proxy

      The following example shows the service configuration after migrating the authentication provider to oidc:

      service:
  ports:
    name: http-backend
    backend: 7007
    targetPort: backend

  5. Upgrade the Developer Hub Helm chart.

Chapter 3. Enabling the GitHub authentication provider

Red Hat Developer Hub uses a built-in GitHub authentication provider to authenticate users in GitHub or GitHub Enterprise.

3.1. GitHub App​ overview

GitHub Apps are generally preferred to OAuth apps because they use fine-grained permissions, give more control over which repositories the application can access, and use short-lived tokens. For more information, see GitHub Apps overview in the GitHub documentation.

3.2. Registering a GitHub​ App

In a GitHub App, you configure the allowed scopes as part of that application, therefore, you must verify the scope that your plugins require. The scope information is available in the plugin README files.

To add GitHub authentication, complete the steps in Registering a GitHub App on the GitHub website.

Use the following examples to enter the information about your production environment into the required fields on the Register new GitHub App page:

  • Application name: Red Hat Developer Hub

  • Homepage URL: https://developer-hub-<NAMESPACE_NAME>.<KUBERNETES_ROUTE_HOST>

  • Authorization callback URL: https://developer-hub-<NAMESPACE_NAME>.<KUBERNETES_ROUTE_HOST>/api/auth/github/handler/frame

Note
 The Homepage URL points to the Developer Hub front end, while the authorization callback URL points to the authentication provider backend.

3.3. Configuring a GitHub App in Developer Hub

To add GitHub authentication for Developer Hub, you must configure the GitHub App in your app-config.yaml file.

The GitHub authentication provider uses the following configuration keys:

  • clientId: the client ID that you generated on GitHub. For example: b59241722e3c3b4816e2

  • clientSecret: the client secret tied to the generated client ID.

  • enterpriseInstanceUrl (optional): the base URL for a GitHub Enterprise instance. For example: https://ghe.<company>.com. The enterpriseInstanceUrl is only needed for GitHub Enterprise.

  • callbackUrl (optional): the callback URL that GitHub uses when initiating an OAuth flow. For example: https://your-intermediate-service.com/handler. The callbackUrl is only needed if Developer Hub is not the immediate receiver, such as in cases when you use one OAuth app for many Developer Hub instances.

To configure the GitHub App, add the provider configuration to your app-config.yaml file under the root auth configuration. For example:

auth:
 environment: production
 providers:
   github:
     production:
       clientId: ${GITHUB_APP_CLIENT_ID}
       clientSecret: ${GITHUB_APP_CLIENT_SECRET}
       ## uncomment if using GitHub Enterprise
       # enterpriseInstanceUrl: ${GITHUB_URL}

3.4. Adding the GitHub provider to the Developer Hub front end​

To add the provider to the front end, add the sign in configuration to your app-config.yaml file. For example:

signInPage: github
Additional resources

Chapter 4. Authentication with Microsoft Azure

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

4.1. Enabling the Microsoft Azure authentication provider

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.

  2. You added a custom Developer Hub application configuration.

Procedure

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

    1. Go to Azure Portal > App registrations, and create an App Registration for Developer Hub.

    2. On your App registration overview page, add a new Web platform configuration, with the configuration:

      Redirect URI

      Enter the backend authentication URI set in Developer Hub: https://<APP_FQDN>/api/auth/microsoft/handler/frame

      Front-channel logout URL

      Leave blank.

      Implicit grant and hybrid flows

      Leave all checkboxes cleared.

    3. On the API permissions tab, click Add Permission, then add the following Delegated permission for the Microsoft Graph API:

      • email

      • offline_access

      • openid

      • profile

      • User.Read

      • Optional custom scopes of the Microsoft Graph API that you define both here and in the Developer Hub configuration (app-config-rhdh.yaml).

        Note

        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 admin consent, a directory admin must go to the admin consent page and click Grant admin consent for COMPANY NAME.

    4. Go to the Certificates & Secrets page, then the Client secrets tab, and create a new client secret.

    5. Save for the next step:

      • Directory (tenant) ID

      • Application (client) ID

      • Application (client) secret

  2. To add your Microsoft Azure credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets, such as secrets-rhdh:

    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.

  3. Set up the Microsoft Azure authentication provider in your Developer Hub custom configuration, such as app-config-rhdh:

    app-config-rhdh.yaml fragment
    auth:
  environment: production
  providers:
    microsoft:
      production:
        clientId: ${AUTH_AZURE_CLIENT_ID}
        clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
        tenantId: ${AUTH_AZURE_TENANT_ID}
signInPage: microsoft
dangerouslyAllowSignInWithoutUserInCatalog: true
    environment: production

    Mark the environment as production to hide the Guest login in the Developer Hub home page.

    clientId, clientSecret and tenantId

    Use your OpenShift secrets.

    signInPage: microsoft

    Enable the Microsoft Azure provider as default sign-in provider.

    dangerouslyAllowSignInWithoutUserInCatalog: true

    Enable authentication without provisioning users to the software catalog.

    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-rhdh.yaml fragment with optional `domainHint field
    auth:
  environment: production
  providers:
    microsoft:
      production:
        domainHint: ${AUTH_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 is ['user.read'].

    app-config-rhdh.yaml fragment with optional additionalScopes field
    auth:
  environment: production
  providers:
    microsoft:
      production:
        additionalScopes:
           - Mail.Send
Note

Optional for environments with restrictions on outgoing access, such as firewall rules. If your environment has outgoing access restrictions make sure your Backstage backend has access to the following hosts:

  • login.microsoftonline.com: To get and exchange authorization codes and access tokens.

  • graph.microsoft.com: To fetch user profile information (as seen in this source code). If this host is unreachable, users might see an Authentication failed, failed to fetch user profile error when they attempt to log in.

4.2. Provisioning users from Microsoft Azure to the software catalog

Prerequisites
Procedure

  • To enable Microsoft Azure member discovery, edit your custom Developer Hub config map, such as app-config-rhdh, and add following lines to the app-config-rhdh.yaml content:

    app-config.yaml fragment with mandatory microsoftGraphOrg fields
    dangerouslyAllowSignInWithoutUserInCatalog: false
catalog:
  providers:
    microsoftGraphOrg:
      providerId:
        target: https://graph.microsoft.com/v1.0
        authority: https://login.microsoftonline.com
        tenantId: ${AUTH_AZURE_TENANT_ID}
        clientId: ${AUTH_AZURE_CLIENT_ID}
        clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
    dangerouslyAllowSignInWithoutUserInCatalog: false

    Allow authentication only for users present in the Developer Hub software catalog.

    target: https://graph.microsoft.com/v1.0

    Defines the MSGraph API endpoint the provider is connecting to. You might change this to use a different version, such as the beta endpoint.

    authority: https://login.microsoftonline.com

    Defines the authority used. Change the value to use a different authority, such as Azure US government.

    tenandId, clientId and clientSecret

    Use your OpenShift secrets.

    Optional: Consider adding following optional microsoftGraphOrg.providerId fields:

    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
    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. Can be combined with [userGroupMember] or [userFilter].

    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 and [userGroupMemberFilter] 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

    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
    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']
    userGroupMember.filter

    To use group membership to get users. To filter groups and fetch their members. This and [userFilter] 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 and [userFilter] 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 https://docs.microsoft.com/en-us/graph/query-parameters#expand-parameter Can be combined with [userGroupMember] instead of [userFilter].

    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

    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']
    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:
    microsoftGraphOrg:
      providerId:
        schedule:
          frequency: { hours: 1 }
    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:
    microsoftGraphOrg:
      providerId:
        schedule:
          timeout: { minutes: 50 }
    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:
    microsoftGraphOrg:
      providerId:
        schedule:
          initialDelay: { seconds: 15}
Verification

  1. Check the console logs to verify the synchronization has been 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"}

  2. Log in with a Microsoft Azure account.