Procedure

1. In the app-config.yaml file, set the authentication environment to development:

   auth:
     environment: development

2. Restart the Developer Hub application to apply the changes.

Verification

1. Go to the login page of your Developer Hub instance.
2. Verify that the option to log in as a guest is available.

Procedure

1. In the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: production

2. Restart the Developer Hub application to apply the changes.

Verification

1. Go to the login page of your Developer Hub instance.
2. Verify that the option to log in as a guest is no longer available.

Procedure

1. Register your Developer Hub app in RHBK:

   1. Use an existing realm, or create a realm, with a distinctive Name such as <my_realm>. Save the value for the next step:

2. RHBK realm base URL, such as: <your_rhbk_URL>/realms/<your_realm>.

   1. In the created realm, secure the first application, with:

      1. Client ID: A distinctive client ID, such as <RHDH>.
      2. Valid redirect URIs: Set to the OIDC handler URL: https://<my_developer_hub_domain>/api/auth/oidc/handler/frame.
      3. Go to the Credentials tab and copy the Client secret.
      4. Save the values for the next step:
3. Client ID

4. Client Secret

   1. 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.
5. Create a long, complex, and unique string to use as the Developer Hub session secret key.

6. Add the following key-value pairs to your Developer Hub secrets. You can use these secrets in the Developer Hub configuration files by using their environment variable name.

   KEYCLOAK_CLIENT_ID

   Enter the saved Client ID.

   KEYCLOAK_CLIENT_SECRET

   Enter the saved Client Secret.

   KEYCLOAK_BASE_URL

   Enter the saved RHBK realm base URL.

   KEYCLOAK_REALM

   Enter the realm name to provision users.

   KEYCLOAK_LOGIN_REALM

   Enter the realm name to authenticate users.

   SESSION_SECRET

   Enter the created session secret key.

Procedure

1. Collect the following LDAP credentials from your LDAP server:

   LDAP URL

   Your LDAP server URL, such as ldaps://ds.example.net.

   Bind DN

   Your bind distinguished name, such as cn=admin,OU=Users,DC=rhdh,DC=test.

   LDAP secret

   Your LDAP secret.

2. Optional: To use a secure LDAP connection (ldaps://), store your LDAP certificates in the ldap_certs.pem file and your LDAP keys in the ldap_keys.pem file.

   Warning

   In production mode, use a secure LDAP connection.

3. Add the LDAP_SECRET key-value pair to your Developer Hub secrets. You can use this secret in the Developer Hub configuration files by using its environment variable name.

   LDAP_SECRET

   Enter your LDAP secret.

4. Optional: To use a secure LDAP connection (ldaps://), add your LDAP certificates and keys files to a an OpenShift secret.

   $ oc create secret generic my-rhdh-ldap-secrets \
       --from-file=./ldap_certs.pem \
       --from-file=./ldap_keys.pem

Procedure

1. Create a GitHub App for integration.

   Note

   Use a GitHub App instead of an OAuth app to use fine-grained permissions and short-lived tokens, scale with the number of installations by avoiding rate limits, and have a more transparent integration by avoiding to request user input.

   1. Register a GitHub App with the following configuration:

      GitHub App name

      Enter a unique name identifying your GitHub App, such as integrating-with-rhdh-<GUID>.

      Homepage URL

      Enter your Developer Hub URL: https://<my_developer_hub_domain>.

      Webhook

      Clear "Active".

      Repository permissions

      Contents

      Read-only

      Commit statuses

      Read-only

      Organization permissions

      Members

      Read-only

      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:
2. App ID
3. Client ID
4. Client secret
5. Private key

6. Store the integration app credentials: Add the following key/value pairs to your Developer Hub secrets.

   GITHUB_APP_APP_ID

   Enter the saved App ID.

   GITHUB_APP_CLIENT_ID_INTEGRATION

   Enter the saved Client ID.

   GITHUB_APP_CLIENT_SECRET_INTEGRATION

   Enter the saved Client Secret.

   GITHUB_APP_PRIVATE_KEY

   Enter the saved Private key.

   GITHUB_URL

   Enter the GitHub host domain: https://github.com.

   GITHUB_ORG

   Enter your GitHub organization name, such as <your_github_organization_name>.

7. Create a separate GitHub App for authentication.

   1. Register a GitHub App with the following configuration:

      GitHub App name

      Enter a unique name identifying your GitHub App, such as authenticating-with-rhdh-<GUID>.

      Homepage URL

      Enter your Developer Hub URL: https://<my_developer_hub_domain>.

      Authorization callback URL

      Enter your Developer Hub authentication backend URL: https://<my_developer_hub_domain>/api/auth/github/handler/frame.

      Webhook

      Clear "Active".

      Organization permissions

      Enable Read-only access to Members.

      Where can this GitHub App be installed?

      Select Only on this account.

   2. In the General → Clients secrets section, click Generate a new client secret.
   3. Save the following values for the next step:
8. Client ID
9. Client secret

10. Store the authentication app credentials: Add the following key/value pairs to your Developer Hub secrets.

    GITHUB_APP_CLIENT_ID

    Enter the saved Client ID.

    GITHUB_APP_CLIENT_SECRET

    Enter the saved Client Secret.

Procedure

1. Register your Developer Hub app in Azure, by using the Azure portal.

   1. Sign in to the Microsoft Entra admin center.
   2. Optional: If you have access to multiple tenants, use the Settings icon in the top menu to switch to the tenant in which you want to register the application from the Directories + subscriptions menu.

   3. Browse to Applications > App registrations, and create a New registration with the configuration:

      Name

      Enter a name to identify your application in Azure, such as <Authenticating with Developer Hub>.

      Supported account types

      Select Accounts in this organizational directory only.

      Redirect URI

      Select a platform

      Select Web.

      URL

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

   4. On the Applications > App registrations > <Authenticating with Developer Hub> > Manage > API permissions page, Add a Permission, Microsoft Graph, select the following permissions:

      Application Permissions

      GroupMember.Read.All, User.Read.All

      Enter permissions that enable provisioning user and groups to the Developer Hub software catalog.

      Optional: Grant admin consent for these permissions. Even if your company does not require admin consent, consider doing so as it means users do not need to individually consent the first time they access Developer Hub.

      Delegated Permissions

      User.Read, email, offline_access, openid, profile

      Enter permissions that enable authenticating users.

      Optional: Enter optional custom scopes for the Microsoft Graph API that you define both here and in your app-config.yaml Developer Hub configuration file.

   5. On the Applications > App registrations > <Authenticating with Developer Hub> > Manage > Certificates & secrets page, in the Client secrets tab, create a New client secret.

   6. Save the following values for the next step:

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

2. Add your Azure credentials to Developer Hub, by adding the following key/value pairs to your Developer Hub secrets:

   MICROSOFT_TENANT_ID

   Enter your saved Directory (tenant) ID.

   MICROSOFT_CLIENT_ID

   Enter your saved Application (client) ID.

   MICROSOFT_CLIENT_SECRET

   Enter your saved Application (client) secret.

Procedure

1. Register the GitLab OAuth 2 application.

   Important

   You must use the required callback URL and permissions.

   1. Register a GitLab OAuth 2 application using the following configuration:

      GitLab OAuth 2 application name

      Enter a unique name, such as authenticating-with-rhdh-<GUID>.

      Redirect URI

      Enter your Developer Hub URL: https://<my_developer_hub_domain>.

      Authorization callback URL

      Enter your authentication backend URL: https://<my_developer_hub_domain>/api/auth/gitlab/handler/frame.

      Authorized application scope

      Enable email, profile, openid, and read_user.

   2. Save the application and record these values for the next step:
2. OAuth 2 Client ID, available in the Application ID field
3. OAuth 2 Client secret, accessible by selecting Copy in the Secret field
4. Set up a GitLab personal access token (PAT) with read_api scope. Save the token value for the next step.

5. Add your GitLab credentials to your RHDH secrets using the following key/value pairs. Use these environment variables in your RHDH configuration files.

   GITLAB_HOST

   Enter your GitLab host: <gitlab_host>.

   GITLAB_CLIENT_ID

   Enter the saved OAuth 2 Client ID.

   GITLAB_CLIENT_SECRET

   Enter the saved OAuth 2 Client Secret.

   GITLAB_TOKEN

   Enter the saved Personal access token.

   GITLAB_URL

   Enter the GitLab host domain: `<gitlab_host_domain>`.

   GITLAB_PARENT_ORG

   Enter your GitLab organization name, such as <your_gitlab_organization_name>.

Procedure

1. The OIDC provider authentication backend plugin requires Developer Hub to support sessions. Enable session support by adding the session secret to your app-config.yaml file:

   auth:
     session:
       secret: ${SESSION_SECRET}

2. Add an OIDC provider section to your app-config.yaml file:

   auth:
     environment: production
     providers:
       oidc:
         production:
           metadataUrl: ${KEYCLOAK_BASE_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           prompt: auto
   signInPage: oidc

   environment: production

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

   metadataUrl, clientId, clientSecret

   Configure the OIDC provider with your secrets.

   prompt

   Enter auto to allow the identity provider to automatically determine whether to prompt for credentials or bypass the login redirect if an active RHBK session exists.

   The identity provider defaults to none, which assumes that you are already logged in. Sign-in requests without an active session are rejected.

   signInPage

   Enter oidc to enable the OIDC provider as default sign-in provider.

3. Optional: Add optional fields to the OIDC authentication provider section in your app-config.yaml file:

   auth:
     providers:
       oidc:
         production:
           metadataUrl: ${KEYCLOAK_BASE_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           callbackUrl: ${KEYCLOAK_CALLBACK_URL}
           tokenEndpointAuthMethod: ${KEYCLOAK_TOKEN_ENDPOINT_METHOD}
           tokenSignedResponseAlg: ${KEYCLOAK_SIGNED_RESPONSE_ALG}
           additionalScopes: ${KEYCLOAK_SCOPE}
           signIn:
             resolvers:
               - resolver: oidcSubClaimMatchingKeycloakUserId
               - resolver: preferredUsernameMatchingUserEntityName
               - resolver: emailMatchingUserEntityProfileEmail
               - resolver: emailLocalPartMatchingUserEntityName
                 dangerouslyAllowSignInWithoutUserInCatalog: true
           sessionDuration: { hours: 24 }
     backstageTokenExpiration: { minutes: _<user_defined_value>_ }
   signInPage: oidc

   callbackUrl

   RHBK callback URL.

   tokenEndpointAuthMethod

   Enter your token endpoint authentication method.

   tokenSignedResponseAlg

   Token signed response algorithm.

   additionalScopes

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

   signIn

   resolvers

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

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

   Available values:

   oidcSubClaimMatchingKeycloakUserId

   Matches the user with the immutable sub parameter from OIDC to the RHBK user ID. Consider using this resolver for enhanced security.

   oidcLdapUuidMatchingAnnotation

   Matches the user by their immutable LDAP UUID. Requires a custom client scope in Red Hat Build of Keycloak.

   For setup instructions, see Match users by LDAP UUID with Red Hat Build of Keycloak.

   emailLocalPartMatchingUserEntityName

   Matches the email local part with the user entity name.

   emailMatchingUserEntityProfileEmail

   Matches the email with the user entity profile email.

   preferredUsernameMatchingUserEntityName

   Matches the preferred username with the user entity name.

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

   Warning

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

   dangerouslyAllowSignInWithoutUserInCatalog: true

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

   Warning

   In production mode, do not enable the dangerouslyAllowSignInWithoutUserInCatalog option.

   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.

   backstageTokenExpiration

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

   Warning

   If multiple valid refresh tokens are issued due to frequent refresh token requests, older tokens will remain valid until they expire. Enhance security and prevent potential misuse of older tokens by enabling 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.

4. To disable the guest login option, in the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: production

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.

Procedure

1. In the Red Hat Build of Keycloak admin console, go to Client scopes and click Create client scope. Name the scope ldap_uuid.

2. In the ldap_uuid scope, click the Mappers tab, then click Add mapper > Configure a new mapper > User Attribute. Configure the mapper with the following values:

   • Name: LDAP_ID
   • User Attribute: LDAP_ID
   • Token Claim Name: ldap_uuid
   • Claim JSON Type: String
   • Add to ID token: ON
   • Add to userinfo: ON
3. Go to Clients > your Red Hat Developer Hub client > Client scopes. Click Add client scope and add ldap_uuid as a Default scope.

4. Optional: Add the oidcLdapUuidMatchingAnnotation resolver to your app-config.yaml file, to replace the default ldap_uuid resolver:

   auth:
     providers:
       oidc:
         production:
           signIn:
             resolvers:
               - resolver: oidcLdapUuidMatchingAnnotation
                 ldapUuidKey: ldap_uuid

   ldapUuidKey

   Enter the token claim name containing the LDAP UUID value. The default value is ldap_uuid. This value must match the Token Claim Name configured in step 2.

5. Restart the Red Hat Developer Hub application to apply the changes.

Procedure

1. Add a GitHub authentication provider section to your app-config.yaml file:

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${GITHUB_APP_CLIENT_ID}
           clientSecret: ${GITHUB_APP_CLIENT_SECRET}
   signInPage: github

   environment

   Enter production to disable the Guest login option in the Developer Hub login page.

   clientId

   Enter the configured secret variable name: ${GITHUB_APP_CLIENT_ID}.

   clientSecret

   Enter the configured secret variable name: ${GITHUB_APP_CLIENT_SECRET}.

   signInPage

   Enter github to enable the GitHub provider as your Developer Hub sign-in provider.

2. Optional: Add optional fields to the GitHub authentication provider section in your app-config.yaml file:

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

   callbackUrl

   Enter the callback URL that GitHub uses when initiating an OAuth flow, such as: <your_intermediate_service_url/handler>. Define it when Developer Hub is not the immediate receiver, such as in cases when you use one OAuth app for many Developer Hub instances.

   sessionDuration

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

   signIn

   resolvers

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

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

   The authentication provider tries each sign-in resolver in order until it succeeds. If none of the attempts succeed, the sign-in fails.

   Warning

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

   resolver

   Enter the sign-in resolver name. Available resolvers: usernameMatchingUserEntityName, preferredUsernameMatchingUserEntityName, emailMatchingUserEntityProfileEmail.

   dangerouslyAllowSignInWithoutUserInCatalog

   Enter true to configure the sign-in resolver to bypass the user provisioning requirement in the Developer Hub software catalog.

   Warning

   In production mode, do not enable dangerouslyAllowSignInWithoutUserInCatalog.

3. To disable the guest login option, in the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: production

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

Procedure

1. Add the Microsoft authentication provider to your app-config.yaml file:

   auth:
     environment: production
     providers:
       microsoft:
         production:
           clientId: ${MICROSOFT_CLIENT_ID}
           clientSecret: ${MICROSOFT_CLIENT_SECRET}
           tenantId: ${MICROSOFT_TENANT_ID}
   signInPage: microsoft

   environment

   Enter production to disable the Guest login option in the Developer Hub login page.

   clientId

   Enter the configured secret variable name: ${MICROSOFT_CLIENT_ID}.

   clientSecret

   Enter the configured secret variable name: ${MICROSOFT_CLIENT_SECRET}.

   tenantId

   Enter the configured secret variable name: ${MICROSOFT_TENANT_ID}.

   signInPage

   Enter microsoft to set the Azure provider as your Developer Hub sign-in provider.

2. Optional: Add optional fields to the Microsoft authentication provider section in your app-config.yaml file:

   auth:
     environment: production
     providers:
       microsoft:
         production:
           clientId: ${MICROSOFT_CLIENT_ID}
           clientSecret: ${MICROSOFT_CLIENT_SECRET}
           tenantId: ${MICROSOFT_TENANT_ID}
           domainHint: ${MICROSOFT_TENANT_ID}
           additionalScopes:
              - Mail.Send
           sessionDuration:
             hours: 24
           signIn:
             resolvers:
               - resolver: usernameMatchingUserEntityName
                 dangerouslyAllowSignInWithoutUserInCatalog: true
   signInPage: microsoft

   domainHint

   Leave this parameter empty, or enter the tenant ID when your application registration is single-tenant.

   Leave this parameter empty when your application registration is multitenant.

   Enter the tenant ID to reduce login friction for users with accounts in multiple tenants, by automatically filtering out accounts from other tenants. For more information, see Home Realm Discovery.

   additionalScopes

   Enter the list of additional scopes to add scopes for the application registration. The default and mandatory value lists following scopes: openid, offline_access, profile, email, User.Read.

   sessionDuration

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

   signIn.resolvers

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

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

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

   Warning

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

   resolver

   Enter the sign-in resolver name. Available resolvers:

   emailMatchingUserEntityAnnotation

   Use this resolver to look up the user by matching their Microsoft email to the email entity annotation.

   emailLocalPartMatchingUserEntityName

   Use this resolver to look up the user by matching their Microsoft email user name to the user entity name.

   emailMatchingUserEntityProfileEmail

   Use this resolver to look up the user by matching their Microsoft email to the user entity profile email.

   dangerouslyAllowSignInWithoutUserInCatalog

   Enter true to configure the sign-in resolver to bypass the user provisioning requirement in the Developer Hub software catalog.

   Warning

   In production mode, do not enable dangerouslyAllowSignInWithoutUserInCatalog.

3. To disable the guest login option, in the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: production

Verification

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

Procedure

1. Add a GitLab authentication provider section to your RHDH app-config.yaml file:

   includeTransitiveGroupOwnership: true
   signInPage: gitlab
   auth:
     environment: production
     session:
       secret: <name_of_secret>
     providers:
       gitlab:
         production:
           audience: https://${GITLAB_HOST}
           clientId: ${GITLAB_CLIENT_ID}
           clientSecret: ${GITLAB_CLIENT_SECRET}
           callbackUrl: https://__<my_developer_hub_domain>__/api/auth/gitlab/handler/frame

   audience

   Enter your GitLab instance address: https://${GITLAB_HOST}

   clientId

   Enter the configured client ID: ${GITLAB_CLIENT_ID}.

   clientSecret

   Enter the configured secret variable name: ${GITLAB_CLIENT_SECRET}.

   callbackUrl

   Enter your Developer Hub authentication backend URL: https://<my_developer_hub_domain>/api/auth/gitlab/handler/frame

2. To disable the guest login option, in the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: production

Verification

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

Procedure

1. Configure the LDAP Data Store for binary attributes.

   Configure the Data Store to treat unique identifiers as binary data to ensure they are processed correctly for OGNL transformations.

   1. In PingFederate, go to System > Data Stores and edit your LDAP store.
   2. In Advanced options > LDAP Binary Attributes, add objectGUID to the list.
   3. In the Attribute Source lookup configuration, set the Encoding Type for objectGUID to Hex.

2. Create the Authentication Policy Contract.

   The contract bridges the LDAP directory and the OIDC policy, transforming the binary GUID into a string format.

   1. Create a new contract named rhdh-contract.
   2. Add an Attribute Source linked to your LDAP Data Store.
   3. Set the Search Filter to sAMAccountName=${username}.
   4. Expose the LDAP UUID attribute (for example, objectGUID for Active Directory) within the contract. Under Contract Fulfillment, map the sub claim to the objectGUID from LDAP by using an Expression source.

   5. Enter the following OGNL expression to format the binary GUID as a UUID string:

      #GUID = #this.get("ds.<ldap-data-source-id>.objectGUID").toString(),
      #GUID.substring(6,8) + #GUID.substring(4,6) + #GUID.substring(2,4) + #GUID.substring(0,2) + "-" +
      #GUID.substring(10,12) + #GUID.substring(8,10) + "-" +
      #GUID.substring(14,16) + #GUID.substring(12,14) + "-" +
      #GUID.substring(16,20) + "-" + #GUID.substring(20,32)

      Replace <ldap-data-source-id> with the ID of your LDAP Data Store in PingFederate.

3. Configure OAuth and OIDC scopes.

   Ensure PingFederate allows the standard OIDC scopes requested by Developer Hub.

   1. Navigate to System > OAuth Scopes.
   2. Ensure email and profile are added to the Common Scopes list.

4. Bridge the contract to the OIDC policy.

   Configure the policy to deliver the transformed UUID through the sub claim in the ID token and UserInfo endpoint.

   1. Access Token Mapping: Map the sub field from rhdh-contract to your Access Token Manager.
   2. OIDC Policy Fulfillment: Fulfill the sub claim by selecting Access Token as the source and sub as the value.
   3. Enable Delivery: In the OIDC Policy Attribute Contract, select the ID Token and UserInfo checkboxes for the sub claim.
   4. Extend Contract: Add ldap_uuid to the Attribute Contract and map it to the sub value by using the Access Token to ensure consistency.

5. Create the OIDC client.

   1. In PingFederate, go to Applications > OAuth Clients and click Add Client.
   2. Under Client Authentication, select Client Secret, generate a secret, and save it.
   3. Enter the Redirect URI: https://<my_developer_hub_domain>/api/auth/oidc/handler/frame.
   4. Under Allowed Grant Types, select Authorization Code.
   5. Under OpenID Connect > Policy, select the OIDC policy you created.

   6. Save the following values for the next step:

      1. Client ID
      2. Client Secret
      3. OIDC metadata URL: The .well-known/openid-configuration endpoint URL for your PingFederate instance.
6. Create a long, complex, and unique string to use as the Developer Hub session secret key.

7. Add your PingFederate credentials and the session secret key to Developer Hub, by adding the following key-value pairs to your Developer Hub secrets. You can use these secrets in the Developer Hub configuration files by using their environment variable name.

   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 OIDC metadata URL.

   SESSION_SECRET

   Enter the created session secret key.

8. Enable session support by adding the session secret to your app-config.yaml file:

   auth:
     session:
       secret: ${SESSION_SECRET}

9. Enable the PingFederate authentication provider with the LDAP UUID matching resolver by adding the OIDC provider section in your app-config.yaml file:

   auth:
     environment: production
     providers:
       oidc:
         production:
           metadataUrl: ${AUTH_OIDC_METADATA_URL}
           clientId: ${AUTH_OIDC_CLIENT_ID}
           clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
           signIn:
             resolvers:
               - resolver: oidcLdapUuidMatchingAnnotation
                 ldapUuidKey: sub
   signInPage: oidc

   environment: production

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

   metadataUrl

   Enter your PingFederate OIDC metadata URL, defined earlier.

   clientId

   Enter your Developer Hub application client ID in PingFederate, defined earlier.

   clientSecret

   Enter your Developer Hub application client secret in PingFederate, defined earlier.

   oidcLdapUuidMatchingAnnotation

   Match the authenticated user to an LDAP catalog entity by using the LDAP UUID. By default, Developer Hub attempts to match the ldap_uuid claim from the UserInfo endpoint to the LDAP catalog entity.

   ldapUuidKey

   Enter the claim key containing the LDAP UUID. Set to sub to use the sub claim, which contains the transformed UUID from the PingFederate policy contract.

   signInPage

   Enter oidc to enable the OIDC provider as the default sign-in provider.

Verification

1. Go to the Developer Hub login page.
2. Verify that the 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 your PingFederate user credentials.

Procedure

1. Add the auth.providers.github section to your app-config.yaml file:

   auth:
     providers:
       github:
         production:
           clientId: ${GITHUB_APP_CLIENT_ID}
           clientSecret: ${GITHUB_APP_CLIENT_SECRET}
           disableIdentityResolution: true

   where: clientId:: Enter the configured secret variable name: ${GITHUB_APP_CLIENT_ID}.

   clientSecret

   Enter the configured secret variable name: ${GITHUB_APP_CLIENT_SECRET}.

   disableIdentityResolution

   Enter true to skip user identity resolution for this provider to enable sign-in from an auxiliary authentication provider.

   Warning

   Do not enable this setting on the primary authentication provider you plan on using for sign-in and identity management.

2. To disable the guest login option, in the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: production

Verification

1. Go to the Developer Hub login page.
2. Log in with your primary authentication provider account.
3. In the top user menu, go to Settings > Authentication Providers.
4. In the GitHub line, click the Sign in button and log in.
5. In the GitHub line, the button displays Sign out.

Procedure

1. To set the absolute session lifetime for an authentication provider, add the sessionDuration parameter to your app-config.yaml file:

   auth:
     providers:
       <name>:
         <env>:
           sessionDuration: 24h

   sessionDuration

   Enter the session lifetime in milliseconds, ISO duration, or human-readable format (for example, 24h, 2 days). When this duration elapses, the session expires regardless of user activity.

   This parameter is not set by default.

2. Restart the Red Hat Developer Hub application to apply the changes.

Procedure

1. Add the auth.autologout section to your {my-app-config.yaml} file.

   auth:
     autologout:
       enabled: true
       idleTimeoutMinutes: 60
       promptBeforeIdleSeconds: 10
       useWorkerTimers: false
       logoutIfDisconnected: true

   where:

   enabled

   Enter true to enable auto-logout.

   Enter false to disable auto-logout.

   The default value is false.

   idleTimeoutMinutes

   (Optional) Enter the number of minutes of inactivity before automatically logging out the user.

   The default value is 60 minutes.

   promptBeforeIdleSeconds

   (Optional) Enter the number of seconds before the auto-logout occurs to prompt the user about the pending logout.

   The default value is 10 seconds.

   useWorkerTimers

   (Optional) Enter false to use main thread timers, when your browser does not support web workers. Your browser might stop timers in inactive tabs, which can affect the auto-logout functionality.

   Enter true to use web worker timers for tracking user activity, and avoid issues when your browser stops timers in inactive tabs.

   The default value is false.

   logoutIfDisconnected

   (Optional) Enter true to log out the users with no active connection, in case of network issues, or when they have no active Developer Hub tab open in their browser.

   Enter false to keep the user logged in during temporary disconnections, or when they have no active Developer Hub tab open in their browser.

   The default value is true.

2. Restart the Red Hat Developer Hub application to apply the changes.

Verification

1. Log in to the Red Hat Developer Hub application.
2. Remain inactive for the duration specified in idleTimeoutMinutes.
3. Observe that a prompt is displayed before the auto-logout occurs, as specified in promptBeforeIdleSeconds.
4. Confirm that you are automatically logged out after the inactivity period.

Procedure

1. Go to Administration at the bottom of the sidebar in the Developer Hub.

   The RBAC tab is displayed, showing all the created roles in the Developer Hub.

2. (Optional) Click any role to view the role information on the OVERVIEW page.
3. Click CREATE to create a role.
4. Enter the name and description of the role in the given fields and click NEXT.
5. Add users and groups using the search field, and click NEXT.
6. Select Plugin and Permission from the drop-downs in the Add permission policies section.
7. Select or clear the Policy that you want to set in the Add permission policies section, and click NEXT.
8. Review the added information in the Review and create section.
9. Click CREATE.

Procedure

1. Go to Administration at the bottom of the sidebar in the Developer Hub.

   The RBAC tab is displayed, showing all the created roles in the Developer Hub.

2. (Optional) Click any role to view the role information on the OVERVIEW page.
3. Select the edit icon for the role that you want to edit.
4. Edit the details of the role, such as name, description, users and groups, and permission policies, and click NEXT.
5. Review the edited details of the role and click SAVE.

Verification

1. After saving the changes, you can view the edited details of the role on the OVERVIEW page of the role.
2. You can also edit a role’s users and groups or permissions by using the edit icon on the Users and Groups or Permissions cards on the OVERVIEW page.

Procedure

1. Go to Administration at the bottom of the sidebar in the Developer Hub.

   The RBAC tab is displayed, showing all the created roles in the Developer Hub.

2. (Optional) Click any role to view the role information on the OVERVIEW page.

3. Select the delete icon from the Actions column for the role that you want to delete.

   The Delete this role? pop-up is displayed on the screen.

4. Click DELETE.

Procedure

1. Find your Bearer token to authenticate to the REST API.

   1. In your browser, open the web console Network tab.
   2. In the main screen, reload the Developer Hub Homepage.
   3. In the web console Network tab, search for the query?term= network call.
   4. Save the token in the response JSON for the next steps.

2. In a terminal, run the curl command and review the response:

   GET request, or DELETE request not requiring JSON body data

   Enter a curl command with the following parameters and review the response:

   $ curl -v \
     -H "Authorization: Bearer <token>" \
     -X <method> "https://<my_developer_hub_domain>/<endpoint>" \

   POST or PUT request, or DELETE request requiring JSON body data

   Enter a curl command with the following parameters and review the response:

   $ curl -v -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>" \
     -X <method> "https://<my_developer_hub_domain>/<endpoint>" \
     -d <body>

   <token>

   Enter your saved authorization token.

   <method>

   Enter the HTTP method for your API endpoint.

   GET

   To retrieve specified information from a specified resource endpoint.

   POST

   To create or update a resource.

   PUT

   To update a resource.

   DELETE

   To delete a resource.

   https://<my_developer_hub_domain>

   Enter your Developer Hub URL.

   <endpoint>

   Enter the API endpoint to which you want to send a request, such as /api/permission/policies.

   <body>

   Enter the JSON body with data that your API endpoint requires with the HTTP POST, or PUT request, and might require with the HTTP DELETE request.

   • To create a role:

     $ curl -v -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       -X POST "https://<my_developer_hub_domain>/api/permission/roles" \
       -d '{
           "memberReferences": ["group:default/example"],
           "name": "role:default/test",
           "metadata": { "description": "This is a test role" }
         }'

   • To update a role:

     $ curl -v -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       -X PUT "https://<my_developer_hub_domain>/api/permission/roles/role/default/test" \
       -d '{
               "oldRole": {
                 "memberReferences":  [ "group:default/example" ],
                 "name": "role:default/test"
               },
               "newRole": {
                 "memberReferences": [ "group:default/example", "user:default/test" ],
                 "name": "role:default/test"
               }
             }'

   • To create a permission policy:

     $ curl -v -H "Content-Type: application/json" \
       -H "Authorization: Bearer $token" \
       -X POST "https://<my_developer_hub_domain>/api/permission/policies" \
       -d '[{
           "entityReference":"role:default/test",
           "permission": "catalog-entity",
           "policy": "read", "effect":"allow"
         }]'

   • To update a permission policy:

     $ curl -v -H "Content-Type: application/json" \
       -H "Authorization: Bearer $token" \
       -X PUT "https://<my_developer_hub_domain>/api/permission/policies/role/default/test" \
       -d '{
              "oldPolicy": [
                {
                  "permission": "catalog-entity", "policy": "read", "effect": "allow"
                }
              ],
              "newPolicy":
                [
                  {
                    "permission": "policy-entity", "policy": "read", "effect": "allow"
                  }
                ]
            }'

   • To create a condition:

     $ curl -v -H "Content-Type: application/json" \
       -H "Authorization: Bearer $token" \
       -X POST "https://<my_developer_hub_domain>/api/permission/roles/conditions" \
       -d '{
           "result": "CONDITIONAL",
           "roleEntityRef": "role:default/test",
           "pluginId": "catalog",
           "resourceType": "catalog-entity",
           "permissionMapping": ["read"],
           "conditions": {
             "rule": "IS_ENTITY_OWNER",
             "resourceType": "catalog-entity",
             "params": {"claims": ["group:default/janus-authors"]}
           }
         }'

   • To update a condition:

     $ curl -v -H "Content-Type: application/json" \
       -H "Authorization: Bearer $token" \
       -X PUT "https://<my_developer_hub_domain>/api/permission/roles/conditions/1" \
       -d '{
               "result":"CONDITIONAL",
               "roleEntityRef":"role:default/test",
               "pluginId":"catalog",
               "resourceType":"catalog-entity",
               "permissionMapping": ["read",  "update", "delete"],
               "conditions": {
                 "rule": "IS_ENTITY_OWNER",
                 "resourceType": "catalog-entity",
                 "params": {"claims": ["group:default/janus-authors"]}
               }
            }'

Procedure

1. Find your Bearer token to authenticate to the REST API.

   1. In your browser, open the web console Network tab.
   2. In the main screen, reload the Developer Hub Homepage.
   3. In the web console Network tab, search for the query?term= network call.
   4. Save the token in the response JSON for the next steps.

2. In your REST client, run a command with the following parameters and review the response:

   Authorization

   Enter your saved authorization token.

   HTTP method

   Enter the HTTP method for your API endpoint.

   GET

   To retrieve specified information from a specified resource endpoint.

   POST

   To create or update a resource.

   PUT

   To update a resource.

   DELETE

   To delete a resource.

   URL

   Enter your Developer Hub URL and API endpoint: https://<my_developer_hub_domain>/<endpoint>, such as https://<my_developer_hub_domain>/api/permission/policies.

   Body

   Enter the JSON body with data that your API endpoint might need with the HTTP POST request.

Procedure

1. The external service sends a GET request to the RBAC REST API with the service-to-service token in the Authorization header.
2. The RBAC REST API validates the service-to-service token, and then processes the request if the token is valid. Otherwise, the RBAC REST API returns an error response.
3. The RBAC REST API returns the response to the external service.
4. The external service processes the response from the RBAC REST API.

Procedure

1. Define your policies in a rbac-policies.csv CSV file by using the following format:

   1. Define role permissions:

      p, <role_entity_reference>, <permission>, <action>, <allow_or_deny>

      <role_entity_reference>

      Role entity reference, such as: role:default/guest.

      <permission>

      Permission, such as: bulk.import, catalog.entity.read, or catalog.entity.refresh, or permission resource type, such as: bulk-import or catalog-entity.

      See: Permission policies reference.

      <action>

      Action type, such as: use, read, create, update, delete.

      <allow_or_deny>

      Access granted: allow or deny.

   2. Assign the role to a group or a user:

      g, <group_or_user>, <role_entity_reference>

      <group_or_user>

      Group, such as: user:default/mygroup, or user, such as: user:default/myuser.

      p, role:default/guests, catalog-entity, read, allow
      p, role:default/guests, catalog.entity.create, create, allow
      g, user:default/my-user, role:default/guests
      g, group:default/my-group, role:default/guests

2. Define your conditional policies in a rbac-conditional-policies.yaml YAML file by using the following format:

   result: CONDITIONAL
   roleEntityRef: <role_entity_reference>
   pluginId: <plugin_id>
   permissionMapping:
     - read
     - update
     - delete
   conditions: <conditions>

   See: Conditional policies reference.

3. Upload your rbac-policies.csv and rbac-conditional-policies.yaml files to a rbac-policies config map in your OpenShift Container Platform project containing Developer Hub.

   $ oc create configmap rbac-policies \
        --from-file=rbac-policies.csv \
        --from-file=rbac-conditional-policies.yaml

4. Update your Backstage custom resource to mount in the Developer Hub filesystem your files from the rbac-policies config map:

   apiVersion: rhdh.redhat.com/v1alpha5
   kind: Backstage
   spec:
     application:
       extraFiles:
         mountPath: /opt/app-root/src
         configMaps:
           - name: rbac-policies

5. Update your Developer Hub app-config.yaml configuration file to use the rbac-policies.csv and rbac-conditional-policies.yaml external files:

   permission:
     enabled: true
     rbac:
       conditionalPoliciesFile: /opt/app-root/src/rbac-conditional-policies.yaml
       policies-csv-file: /opt/app-root/src/rbac-policies.csv
       policyFileReload: true

Procedure

1. Define your policies in a rbac-policies.csv CSV file by using the following format:

   1. Define role permissions:

      p, <role_entity_reference>, <permission>, <action>, <allow_or_deny>

      <role_entity_reference>

      Role entity reference, such as: role:default/guest.

      <permission>

      Permission, such as: bulk.import, catalog.entity.read, or catalog.entity.refresh, or permission resource type, such as: bulk-import or catalog-entity.

      See: Permission policies reference.

      <action>

      Action type, such as: use, read, create, update, delete.

      <allow_or_deny>

      Access granted: allow or deny.

   2. Assign the role to a group or a user:

      g, <group_or_user>, <role_entity_reference>

      <group_or_user>

      Group, such as: user:default/mygroup, or user, such as: user:default/myuser.

      Sample rbac-policies.csv:

      p, role:default/guests, catalog-entity, read, allow
      p, role:default/guests, catalog.entity.create, create, allow
      g, user:default/my-user, role:default/guests
      g, group:default/my-group, role:default/guests

2. Define your conditional policies in a rbac-conditional-policies.yaml YAML file by using the following format:

   result: CONDITIONAL
   roleEntityRef: <role_entity_reference>
   pluginId: <plugin_id>
   permissionMapping:
     - read
     - update
     - delete
   conditions: <conditions>

   See: Conditional policies reference.

3. Upload your rbac-policies.csv and rbac-conditional-policies.yaml files to a rbac-policies config map in your OpenShift Container Platform project containing Developer Hub.

   $ oc create configmap rbac-policies \
        --from-file=rbac-policies.csv \
        --from-file=rbac-conditional-policies.yaml

4. Update your Developer Hub Backstage Helm chart to mount in the Developer Hub filesystem your files from the rbac-policies config map:

   1. In the Developer Hub Helm Chart, go to Root Schema → Backstage chart schema → Backstage parameters → Backstage container additional volume mounts.

   2. Select Add Backstage container additional volume mounts and add the following values:

      mountPath

      /opt/app-root/src/rbac

      Name

      rbac-policies

   3. Add the RBAC policy to the Backstage container additional volumes in the Developer Hub Helm Chart:

      name

      rbac-policies

      configMap

      defaultMode

      420

      name

      rbac-policies

5. Update your Developer Hub app-config.yaml configuration file to use the rbac-policies.csv and rbac-conditional-policies.yaml external files:

   permission:
     enabled: true
     rbac:
       conditionalPoliciesFile: /opt/app-root/src/rbac-conditional-policies.yaml
       policies-csv-file: /opt/app-root/src/rbac-policies.csv
       policyFileReload: true

Procedure

1. Add the following policies to your CSV file to allow users to view and manage plugins in Extensions:

   g, user:default/<YOUR_USERNAME>, role:default/extensions-admin
   p, role:default/extensions-admin, extensions.plugin.configuration.read, read, allow
   p, role:default/extensions-admin, extensions.plugin.configuration.write, create, allow
   p, role:default/extensions-admin, catalog.entity.read, read, allow

   See Extensions permissions.

2. Optional: Restrict access to specific plugins by defining a conditional policy in the rbac-conditional-policies.yaml file as described in Defining conditional policies:

   result: CONDITIONAL
   roleEntityRef: "role:default/extensions-admin"
   pluginId: extensions
   resourceType: extensions-plugin
   permissionMapping:
     - create
   conditions:
     rule: HAS_NAME
     resourceType: extensions-plugin
     params:
       pluginNames: [<your_plugin_name>]

   where:

   pluginNames

   Enter the plugin name or title for user access.

   This policy allows users to install or update only the specified plugins and restricts access to all other plugins.

3. Optional: Restrict access by annotation by defining a conditional policy:

   result: CONDITIONAL
   roleEntityRef: "role:default/extensions-admin"
   pluginId: extensions
   resourceType: extensions-plugin
   permissionMapping:
     - create
   conditions:
     rule: HAS_ANNOTATION
     resourceType: extensions-plugin
     params:
       annotation: "extensions.backstage.io/certified-by"
       value: "Red Hat"

   This policy allows users to install or update only the plugins that have the specified annotation.