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:
-
Set up the shared secret that the authentication provider and Red Hat Developer Hub require to communicate.
-
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.
-
You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.
-
To enable the guest user in your Developer Hub custom configuration, edit your Developer Hub application configuration with following content:
app-config-rhdh.yaml
fragmentauth: environment: development providers: guest: dangerouslyAllowOutsideDevelopment: true
-
Go to the Developer Hub login page.
-
To log in with the Guest user account, click Enter in the Guest tile.
-
In the Developer Hub Settings page, your profile name is Guest.
-
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.
-
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 fragmentupstream: backstage: appConfig: app: baseUrl: 'https://{{- include "janus-idp.hostname" . }}' auth: environment: development providers: guest: dangerouslyAllowOutsideDevelopment: true
-
Go to the Developer Hub login page.
-
To log in with the Guest user account, click Enter in the Guest tile.
-
In the Developer Hub Settings page, your profile name is Guest.
-
You can use Developer Hub features.
Chapter 2. Authenticating with Red Hat Single Sign-On (RHSSO)
To authenticate users with Red Hat SSO (RHSSO), enable the OpenID Connect (OIDC) authentication provider in RHDH.
2.1. Enabling authentication with Red Hat Single-Sign On (RHSSO)
To authenticate users with Red Hat SSO (RHSSO), enable the OpenID Connect (OIDC) authentication provider in Red Hat Developer Hub.
-
You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.
-
You have sufficient permissions in RHSSO to create and manage a realm.
-
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:
-
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>.
-
-
To register your Developer Hub in RHSSO, in this realm, create a Client ID, with:
-
Client ID: A distinctive client ID, such as <RHDH>.
-
Valid redirect URIs: Set to the OIDC handler URL:
https://<RHDH_URL>/api/auth/oidc/handler/frame
. -
Navigate to the Credentials tab and copy the Client secret.
-
Save the values for the next step:
-
Client ID
-
Client Secret
-
-
-
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.
-
-
To add your RHSSO credentials in 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.
-
To set up the RHSSO authentication provider in your Developer Hub custom configuration, edit your custom Developer Hub config map, such as
app-config-rhdh
, and add following lines to theapp-config-rhdh.yaml
content:app-config-rhdh.yaml
fragmentauth: environment: production # (1) providers: oidc: production: metadataUrl: ${AUTH_OIDC_METADATA_URL} # (2) clientId: ${AUTH_OIDC_CLIENT_ID} # (2) clientSecret: ${AUTH_OIDC_CLIENT_SECRET} # (2) ## 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 # (3) dangerouslyAllowSignInWithoutUserInCatalog: true # (4)
-
Mark the environment as
production
to hide the Guest login in the Developer Hub home page. -
To configure the OIDC provider with your secrets.
-
To enable the OIDC provider as default sign-in provider.
-
To enable authentication without requiring to provision users in the Developer Hub software catalog.
-
-
Go to the Developer Hub login page.
-
Your Developer Hub sign-in page displays Sign in using OIDC and the Guest user sign-in is disabled.
-
Log in with OIDC by using the saved Username and Password values.
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
. TheenterpriseInstanceUrl
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. ThecallbackUrl
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
-
For information about authenticating Backstage access with GitHub, see GitHub Authentication Provider in the community documentation.
-
For information about adding the provider to the Backstage front end, see Enabling authentication in Showcase in the community documentation.
Chapter 4. Enabling the Microsoft Azure authentication provider
Red Hat Developer Hub includes a Microsoft Azure authentication provider that can authenticate users by using OAuth.
-
To allow Developer Hub to authenticate with Microsoft Azure, create an OAuth Application in Microsoft Azure.
-
Go to Azure Portal > App registrations, and create an App Registration for Developer Hub.
-
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.
-
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
).NoteYour 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.
-
-
Go to the Certificates & Secrets page, then the Client secrets tab, and create a new client secret. Save the Client secret for the next step.
-
-
Add your Microsoft Azure credentials in your Developer Hub secrets.
-
Edit your Developer Hub secrets, such as
secrets-rhdh
. -
Add the following key/value pairs:
-
AUTH_AZURE_CLIENT_ID
: Enter the Application ID that you generated on Microsoft Azure. -
AUTH_AZURE_CLIENT_SECRET
: Enter the Client secret that you generated on Microsoft Azure. -
AUTH_AZURE_TENANT_ID
: Enter your Tenant ID on Microsoft Azure.
-
-
-
Set up the Microsoft Azure authentication provider in your Developer Hub custom configuration.
Edit your custom Developer Hub config map, such as
app-config-rhdh
.In the
app-config-rhdh.yaml
content, add themicrosoft
provider configuration under the rootauth
configuration, and enable themicrosoft
provider for sign-in:app-config-rhdh.yaml
fragmentauth: environment: production providers: microsoft: production: clientId: ${AUTH_AZURE_CLIENT_ID} clientSecret: ${AUTH_AZURE_CLIENT_SECRET} tenantId: ${AUTH_AZURE_TENANT_ID} # domainHint: ${AUTH_AZURE_TENANT_ID} # (1) # additionalScopes: # (2) # - Mail.Send signInPage: microsoft # (3)
-
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.
-
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']
. -
To enable the Microsoft Azure provider as default sign-in provider.
-
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:
|