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.

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.

Procedure

1. To allow Developer Hub to authenticate with RHSSO, complete the steps in RHSSO, to create a realm and a user and register the Developer Hub 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:

      • RHSSO realm base URL, such as: <your_rhsso_URL>/auth/realms/<your_realm>.

   2. To register your Developer Hub in RHSSO, in the created realm, create a Client ID, 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. Configure your RHSSO realm for performance and security:

      1. Navigate to the Configure > Realm Settings.
      2. Set the Access Token Lifespan to a value greater than five minutes (preferably 10 or 15 minutes) to prevent performance issues from frequent refresh token requests for every API call.
      3. Enable the Revoke Refresh Token option to improve security by enabling the refresh token rotation strategy.
   4. 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 secrets, edit your Developer Hub secrets, such as secrets-rhdh, and add the following key/value pairs:

   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 RHSSO realm base URL.

3. To set up the RHSSO 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-rhdh.yaml content:

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

   auth:
     environment: production
     providers:
       oidc:
         production:
           metadataUrl: ${AUTH_OIDC_METADATA_URL}
           clientId: ${AUTH_OIDC_CLIENT_ID}
           clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
   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.

   Optional: Consider adding the following optional fields:

   dangerouslyAllowSignInWithoutUserInCatalog: true

   To enable authentication without requiring to provision users 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 authenticating 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}
   signInPage: oidc
   dangerouslyAllowSignInWithoutUserInCatalog: true

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.

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

2. Log in with an RHSSO account.

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 '@janus-idp/backstage-plugin-keycloak-backend';
   
   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))

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 your Developer Hub secrets, edit your Developer Hub secrets, such as secrets-rhdh, and add the following key/value pairs:

   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: https://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 ConfigMap such as app-config-rhdh, and add the following lines to the app-config-rhdh.yaml content:

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

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTH_GITHUB_CLIENT_ID}
           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

   environment: production

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

   clientId, clientSecret, host, appId, webhookUrl, webhookSecret, privateKey

   Use the Developer Hub application information that you have created in GitHub and configured in OpenShift as secrets.

   sigInPage: github

   To enable the GitHub provider as default sign-in provider.

   Optional: Consider adding the following optional fields:

   dangerouslyAllowSignInWithoutUserInCatalog: true

   To enable authentication without requiring to provision users 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 authenticating users absent from the software catalog

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTH_GITHUB_CLIENT_ID}
           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
   dangerouslyAllowSignInWithoutUserInCatalog: true

   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-rhdh.yaml fragment with optional enterpriseInstanceUrl field

   auth:
     providers:
       github:
         production:
           callbackUrl: <your_intermediate_service_url/handler>

   enterpriseInstanceUrl

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

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

   auth:
     providers:
       github:
         production:
           enterpriseInstanceUrl: ${GITHUB_HOST_DOMAIN}

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

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.

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

2. Log in with a GitHub account.

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

      • Optional custom scopes for the Microsoft Graph API that you define both in this section 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 administrator consent, a directory administrator must go to the admin consent page and click Grant admin consent for COMPANY NAME.

   4. On the Home > App registrations > <My Developer Hub> > Manage > Certificates & Secrets page, in the Client secrets tab, 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

   environment: production

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

   clientId, clientSecret and tenantId

   Use the Developer Hub application information that you have created in Microsoft Azure and configured in OpenShift as secrets.

   signInPage: microsoft

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

   Optional: Consider adding following optional fields:

   dangerouslyAllowSignInWithoutUserInCatalog: true

   To enable authentication without requiring to provision users 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 authenticating 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}
   signInPage: microsoft
   dangerouslyAllowSignInWithoutUserInCatalog: true

   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 lists: 'openid', 'offline_access', 'profile', 'email', 'User.Read'.

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

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

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

2. Log in with a Microsoft Azure account.