3 posts tagged with "Keycloak"

A directory service is a common component found in organizations big and small as it includes a facility for maintaining key assets including users, groups and their relationships. The Backstage catalog provides similar capabilities to assemble not only identity records, but other resources related to various software components. Items are added to the catalog manually or they are sourced from external locations. Several plugins associated with external providers including Azure, GitHub, GitLab and LDAP, support ingesting organizational data (Users and Groups) directly into the Backstage catalog.

In a prior article, it was described how Keycloak can be used to act as an identity provider to store users and groups along with enforcing that users accessing Backstage authenticate against the Keycloak instance. Even though users are authenticated into Backstage, records are not added to the Backstage catalog, thus restricting the ability to fully utilize the capabilities of Backstage. Fortunately, a plugin has been developed by the Janus community to perform similar functionality as the other external providers to integrate Keycloak user and group entities into the Backstage catalog.

This article will describe the steps involved to implement its use within Backstage. The keycloak-backend plugin is one of an increasing set of plugins found within the backstage-plugins repository that have been developed by the Janus community to expand the interoperability between Backstage and a variety of open source projects. These plugins are published within the @janus-idp npm repository which allows them to be added to Backstage with ease. Support for ingesting users and groups from Keycloak by way of the plugin only requires a few steps within Backstage itself.

Backstage Configuration​

The Backstage plugin to ingest Keycloak organizational data is implemented as a backend plugin. Architecturally, Backstage is separated into two separate components: the frontend which includes the user interface and many other user facing features, and the backend which powers a variety of plugins including the software catalog. Since the purpose of a provider (plugin) is to synchronize organization data into the Backstage catalog, it is clear to see why it is implemented as a backend plugin.

Unlike the oauth2Proxy provider which was detailed in the prior article, the Keycloak backend plugin is not included as part of the standard installation of Backstage and must be installed. Plugins that are not included by default can be installed using the yarn add command.

From the Backstage root directory, execute the following command to add the Keycloak backend plugin:

yarn --cwd packages/backend add @janus-idp/backstage-plugin-keycloak-backend

Now that the plugin has been installed, register the plugin by adding the following content to the packages/backend/src/plugins/catalog.ts file.

// ..
import { KeycloakOrgEntityProvider } from '@janus-idp/backstage-plugin-keycloak-backend';

export default async function createPlugin(env: PluginEnvironment): Promise<Router> {
  const builder = await CatalogBuilder.create(env);

  builder.addEntityProvider(
    KeycloakOrgEntityProvider.fromConfig(env.config, {
      id: 'development',
      logger: env.logger,
      schedule: env.scheduler.createScheduledTaskRunner({
        frequency: { hours: 1 },
        timeout: { minutes: 50 },
        initialDelay: { seconds: 15 },
      }),
    }),
  );

  // ..
}

Feel free to customize the values of the frequency, timeout, and initialDelay parameters as desired.

Build an updated container image according to the steps described here so that it can be deployed to a Kubernetes environment.

The Keycloak backend plugin as well as the configurations described previously are included within the reference container image is located at quay.io/ablock/backstage-keycloak:latest if there was a desire to once again forgo producing a container image.

Configuring Keycloak​

Even though the majority of the configuration within Keycloak to populate Users, Groups and an OAuth client was completed previously, additional actions must be completed so that the Keycloak backend plugin has the necessary permissions to query the resources that are stored within the backstage Keycloak realm. Keycloak clients can be configured to act as a Service Account allowing for additional permissions to be granted to the client to query the Keycloak API.

To enable a Client to act as a Service Account, this capability, login to the Keycloak instance and navigate to the Keycloak Client created previously within the backstage realm and navigate to the Capability config section and check the Service accounts roles checkbox. Click Save to apply the changes.

By default, Keycloak Service Accounts are not granted the necessary permissions to obtain user and group information within the realm. Additional configurations are needed so that the Backstage Keycloak plugin can perform user and group queries.

1. Login to the Keycloak instance and navigate to the backstage OAuth client within the backstage realm. Click on the Service Account roles tab so that the necessary permissions can be associated with the OAuth client.

2. Click on the Assign role button to associate existing roles and enable permissions against the Keycloak Service Account.

3. Select the Filter by realm roles dropdown and click Filter by clients to display client specific roles.

4. Enter realm-management into the textbox in order to limit the number of values that are returned.

5. Check the following roles keeping in mind that the option to select the role may only be available within a separate page:

   • query-groups
   • query-users
   • view-users

6. Click Assign to add the roles to the backstage service account. Once completed, the values present within the Service accounts role tab is represented by the screenshot below.

With the necessary Service Account roles associated with the OAuth client, the Keycloak backend plugin will be able to query the necessary information from the Keycloak API.

Backstage Kubernetes Deployment​

Now that both a container image of Backstage containing the necessary components to ingest Keycloak organizational data has been created and Keycloak itself has been configured to enable the Keycloak backend plugin to query the Keycloak API, the final step is to deploy an instance of Backstage to a Kubernetes environment using the Backstage Helm chart.

Once again the versatility of the Backstage Helm charts allows for a wide range of options to be configured, including the ability to enable the provider by way of environment variables within the backstage container.

Create a new file called values-backstage-keycloak-plugin.yaml containing the Helm values that will be used to enable the Keycloak backend plugin with the following content:

backstage:
  image:
    registry: quay.io
    repository: ablock/backstage-keycloak
    tag: latest
  extraEnvVars:
    - name: 'APP_CONFIG_app_baseUrl'
      value: 'https://{{ .Values.ingress.host }}'
    - name: 'APP_CONFIG_backend_baseUrl'
      value: 'https://{{ .Values.ingress.host }}'
    - name: 'APP_CONFIG_backend_cors_origin'
      value: 'https://{{ .Values.ingress.host }}'
    - name: 'APP_CONFIG_backend_cors_origin'
      value: 'https://{{ .Values.ingress.host }}'
    - name: 'APP_CONFIG_catalog_providers_keycloakOrg_default_baseUrl'
      value: '{{ required "Keycloak BaseUrl is Required" .Values.keycloak.baseUrl }}'
    - name: 'APP_CONFIG_catalog_providers_keycloakOrg_default_loginRealm'
      value: '{{ required "Keycloak Realm is Required" .Values.keycloak.realm }}'
    - name: 'APP_CONFIG_catalog_providers_keycloakOrg_default_realm'
      value: '{{ required "Keycloak Realm is Required" .Values.keycloak.realm }}'
    - name: 'APP_CONFIG_catalog_providers_keycloakOrg_default_clientId'
      value: '{{ required "Keycloak Client Secret is Required" .Values.keycloak.clientId }}'
    - name: 'APP_CONFIG_catalog_providers_keycloakOrg_default_clientSecret'
      value: '{{ required "Keycloak Client Secret is Required" .Values.keycloak.clientSecret }}'

  extraContainers:
    - name: oauth2-proxy
      env:
        - name: OAUTH2_PROXY_CLIENT_ID
          value: '{{ required "Keycloak Client Secret is Required" .Values.keycloak.clientId }}'
        - name: OAUTH2_PROXY_CLIENT_SECRET
          value: '{{ required "Keycloak Client Secret is Required" .Values.keycloak.clientSecret }}'
        - name: OAUTH2_PROXY_COOKIE_SECRET
          value: '{{ default (randAlpha 32 | lower | b64enc) .Values.keycloak.cookieSecret }}'
        - name: OAUTH2_PROXY_OIDC_ISSUER_URL
          value: '{{ required "Keycloak Issuer URL is Required" .Values.keycloak.baseUrl }}/realms/{{ required "Keycloak Realm is Required" .Values.keycloak.realm }}'
        - name: OAUTH2_PROXY_SSL_INSECURE_SKIP_VERIFY
          value: 'true'
      ports:
        - name: oauth-proxy
          containerPort: 4180
          protocol: TCP
      imagePullPolicy: IfNotPresent
      image: 'quay.io/oauth2-proxy/oauth2-proxy:latest'
      args:
        - '--provider=oidc'
        - '--email-domain=*'
        - '--upstream=http://localhost:7007'
        - '--http-address=0.0.0.0:4180'
        - '--skip-provider-button'

service:
  ports:
    backend: 4180
    targetPort: oauth-proxy

ingress:
  enabled: true
  host: backstage.example.com

keycloak:
  baseUrl: '<KEYCLOAK_URL>'
  realm: 'backstage'
  clientId: 'backstage'
  clientSecret: ''
  cookieSecret: ''

The Keycloak backend plugin is enabled by declaring environment variables with the prefix APP_CONFIG_catalog_providers_keycloakOrg_default_* and when rendered at runtime take a form similar to the following:

catalog:
  providers:
    keycloakOrg:
      default:
        baseUrl: <BASE_URL>
        loginRealm: <KEYCLOAK_LOGIN_REALM>
        realm: <KEYCLOAK_REALM>
        clientId: <KEYCLOAK_CLIENTID>
        clientSecret: <KEYCLOAK_CLIENTSECRET>

Several fields require that the parameters be provided either within the Values file itself or as parameters using the --set option when deploying the chart.

Update the keycloak.baseUrl parameter to reference the location of the Keycloak instance along with specifying the backstage OAuth client secret within the keycloak.clientSecret parameter. In addition, specify the hostname of the backstage instance within the ingress.host property. If a container image was created that includes the configurations to support not only the Keycloak backend plugin as well as OAuth integration as described in the previous article, specify the details within the backstage.image property.

With the necessary parameters configured, perform an upgrade of the Backstage helm chart by executing the following command. If an existing release does not already exist, the inclusion of the -i parameter ensures that it will be installed.

helm upgrade -i -n backstage --create-namespace backstage
backstage/backstage -f values-backstage-keycloak-plugin.yaml

Once the release is complete, the Backstage user interface can be accessed via the created Ingress and continues to be governed by Keycloak based OAuth authentication. However, if the log from the Backstage container is inspected, the Keycloak backend plugin can be seen in action.

Execute the following command to view the Backstage container log:

kubectl -n backstage logs deployment/backstage

2022-12-24T23:24:36.299Z catalog info Reading Keycloak users and groups type=plugin class=KeycloakOrgEntityProvider taskId=KeycloakOrgEntityProvider:default:refresh taskInstanceId=a8c1693c-b5cb-439a-866d-c1b6b7754a77
2022-12-24T23:24:36.382Z catalog info Read 2 Keycloak users and 2 Keycloak groups in 0.1 seconds. Committing... type=plugin class=KeycloakOrgEntityProvider taskId=KeycloakOrgEntityProvider:default:refresh taskInstanceId=a8c1693c-b5cb-439a-866d-c1b6b7754a77
2022-12-24T23:24:36.386Z catalog info **Committed 2 Keycloak users and 2 Keycloak groups in 0.0 seconds.** type=plugin class=KeycloakOrgEntityProvider taskId=KeycloakOrgEntityProvider:default:refresh taskInstanceId=a8c1693c-b5cb-439a-866d-c1b6b7754a77

Observe in the container log that the plugin identified two users and two groups from the Keycloak realm which have been imported into the backstage catalog. The contents of the Backstage catalog can be inspected by querying the Backstage API. Execute the following command to execute a command within the Backstage pod to query the API and format the results using jq. If jq is not installed on the local machine, it can be removed from the command.

kubectl -n backstage exec -c oauth2-proxy deployment/backstage -- wget -q --output-document - "http://localhost:7007/api/catalog/entities?filter=kind=user" | jq -r

[
  {
    "metadata": {
      "namespace": "default",
      "annotations": {
        "backstage.io/managed-by-location": "url:https://keycloak.apps.cluster-cmwgv.cmwgv.sandbox2741.opentlc.com/admin/realms/backstage/users/1e703d12-cb09-4c7e-b615-7ea620725006",
        "backstage.io/managed-by-origin-location": "url:https://keycloak.apps.cluster-cmwgv.cmwgv.sandbox2741.opentlc.com/admin/realms/backstage/users/1e703d12-cb09-4c7e-b615-7ea620725006",
        "backstage.io/view-url": "https://keycloak.apps.cluster-cmwgv.cmwgv.sandbox2741.opentlc.com/admin/realms/backstage/users/1e703d12-cb09-4c7e-b615-7ea620725006",
        "keycloak.org/id": "1e703d12-cb09-4c7e-b615-7ea620725006",
        "keycloak.org/realm": "backstage"
      },
      "name": "backstageadmin",
      "uid": "25f4a1bb-e035-4f3a-b618-4d16876325d7",
      "etag": "ab5c4076701c76d9a6215a9f7e2fd5b1e6035790"
    },
    "apiVersion": "backstage.io/v1beta1",
    "kind": "User",
    "spec": {
      "profile": {
        "email": "backstageadmin@janus-idp.io",
        "displayName": "Backstage Admin"
      },
      "memberOf": [
        "Admins"
      ]
    },
    "relations": [
      {
        "type": "memberOf",
        "targetRef": "group:default/admins",
        "target": {
          "kind": "group",
          "namespace": "default",
          "name": "admins"
        }
      }
    ]
  },
  {
    "metadata": {
      "namespace": "default",
      "annotations": {
        "backstage.io/managed-by-location": "url:https://keycloak.apps.cluster-cmwgv.cmwgv.sandbox2741.opentlc.com/admin/realms/backstage/users/90625bf5-5e63-434e-96b7-288908907134",
        "backstage.io/managed-by-origin-location": "url:https://keycloak.apps.cluster-cmwgv.cmwgv.sandbox2741.opentlc.com/admin/realms/backstage/users/90625bf5-5e63-434e-96b7-288908907134",
        "backstage.io/view-url": "https://keycloak.apps.cluster-cmwgv.cmwgv.sandbox2741.opentlc.com/admin/realms/backstage/users/90625bf5-5e63-434e-96b7-288908907134",
        "keycloak.org/id": "90625bf5-5e63-434e-96b7-288908907134",
        "keycloak.org/realm": "backstage"
      },
      "name": "backstageuser",
      "uid": "96f3f8a1-aaa2-4d4c-89dc-b3e5d22aa049",
      "etag": "ad2d9c10fbfad74bb685ad10fdca178b2869516c"
    },
    "apiVersion": "backstage.io/v1beta1",
    "kind": "User",
    "spec": {
      "profile": {
        "email": "backstageuser@janus-idp.io",
        "displayName": "Backstage User"
      },
      "memberOf": [
        "Users"
      ]
    },
    "relations": [
      {
        "type": "memberOf",
        "targetRef": "group:default/users",
        "target": {
          "kind": "group",
          "namespace": "default",
          "name": "users"
        }
      }
    ]
  }
]

Observe that the relationships between users and groups are also present. Groups imported to the catalog can be inspected by executing the following command to invoke the Backstage API:

kubectl -n backstage exec -c oauth2-proxy deployment/backstage -- wget -q --output-document - "http://localhost:7007/api/catalog/entities?filter=kind=group" | jq -r

Now that the Backstage catalog has been populated, additional metadata will now be associated with users when they authenticate to the Backstage user interface. Launch a web browser and navigate to the Backstage user interface and login using either of the previously created Keycloak users.

Click on the Settings button on the bottom left corner of the page. Ensure the additional relationship details (groups) are present to confirm that the authenticated user has been linked properly to the user in the catalog.

The Keycloak backend plugin will run periodically based on the parameters defined within the catalog.ts file to ensure that the Backstage catalog is updated with the current state as defined within keycloak. By providing the capability to ingest organizational data into the Backstage catalog from Keycloak, the benefits that are offered through the use of Keycloak as an identity source can be realized within Backstage.

The software catalog is the heart of Backstage as it provides a centralized mechanism for organizing all of the assets within a particular domain. This content can include everything from services, websites, pipelines and everything in between and the catalog provides a facility for managing these assets in a declarative fashion along with assigning ownership against them. Identity records within Backstage are represented as Users (individual entities) and Groups (a collection of users) and they enable the association of ownership and policies to resources within the software catalog. The determination of who the user is and their association to a User entity within the software catalog is the core functionality of the authentication system within Backstage. Every installation of Backstage includes a number of built-in authentication providers, and while GitHub is the most common, several alternatives are available to choose from including GitLab, Google and Azure.

Keycloak is an Open Source identity and access management tool and provides capabilities including Single Sign On (SSO), user management and support for fine grained authorization policies. In addition to these features, one of the biggest benefits of Keycloak is that it can federate identities from other external providers including many of the built-in authentication providers within Backstage. By integrating Backstage with Keycloak, a single source of truth as it relates to identity can be attained. The benefits include avoiding the process of having to manage multiple authentication providers along with allowing for a more “cloud native” method of authentication and authorization using the OpenID Connect (OIDC) protocol. Enabling users to authenticate against Keycloak to gain access to Backstage is a straightforward process and will be described throughout the remainder of this article.

Prior to performing any configuration within either Keycloak or Backstage, the first step is to better understand the architecture and the overall process. Unlike other providers, such as those that were introduced previously (GitHub, Google, etc), there is no direct integration between Backstage and Keycloak. Instead, the OAuth2 proxy provider is implemented through the use of the oauth2-proxy to act as an intermediate for offloading the entire authentication process which passes the resulting request for Backstage to process. An overview of the entire flow is described below:

1. OIDC client is created within Keycloak representing the integration with Backstage and configured within the OAuth2 proxy.
2. Users attempts to access Backstage and is redirected to Keycloak by the OAuth2 proxy
3. User authenticates against Keycloak
4. Upon successful authentication to Keycloak, OAuth process verifies user has met all necessary requirements that are needed to access Backstage
5. Request to Backstage for the processing of the authentication
6. Backstage Sign In Resolver ingests request (reading headers provided by the OAuth2 proxy) and either associates the user within an existing entry in the software catalog or a new entry is created
7. Authentication process is complete and the user can make use of Backstage based on their level of access

As this list illustrates, there are several steps involved to enable Backstage users to authenticate against Keycloak. The first step is to set up Backstage with the necessary configurations to enable the OAuth2 provider.

Backstage Configuration​

Similar to the other authentication providers that are included with Backstage, there are steps that must be completed within Backstage itself to support using Keycloak authentication by way of the OAuth 2 Proxy Provider including:

• Adding the provider to the Backstage frontend
• Updating the Backstage app-config.yaml configuration file to enable the OAuth2 Proxy Provider
• Configuring a Sign in Resolver within the Backstage backend

First, update the Backstage frontend by enabling the ProxiedSignInPage by making the following changes in the packages/app/src/App.tsx file:

import { ProxiedSignInPage } from '@backstage/core-components';

const app = createApp({
  // ...
  components: {
    SignInPage: (props) => <ProxiedSignInPage {...props} provider="oauth2Proxy" />,
  },
});

Next, add the oauth2Proxy to the list of authentication providers within the Backstage app-config.yaml configuration file:

auth:
  providers:
    oauth2Proxy: {}

The final required configuration within backstage is to set up an Identity Resolver which will translate the parameters (headers) that are received from the OAuth2 proxy and translate them into an authenticated backstage user. Update the packages/backend/src/plugins/auth.ts file with the following content:

import { DEFAULT_NAMESPACE, stringifyEntityRef } from '@backstage/catalog-model';

export default async function createPlugin(env: PluginEnvironment): Promise<Router> {
  return await createRouter({
    // ...
    providerFactories: {
      ...defaultAuthProviderFactories,
      // ...
      oauth2Proxy: providers.oauth2Proxy.create({
        signIn: {
          async resolver({ result }, ctx) {
            const name = result.getHeader('x-forwarded-preferred-username');
            if (!name) {
              throw new Error('Request did not contain a user');
            }

            try {
              // Attempts to sign in existing user
              const signedInUser = await ctx.signInWithCatalogUser({
                entityRef: { name },
              });

              return Promise.resolve(signedInUser);
            } catch (e) {
              // Create stub user
              const userEntityRef = stringifyEntityRef({
                kind: 'User',
                name: name,
                namespace: DEFAULT_NAMESPACE,
              });
              return ctx.issueToken({
                claims: {
                  sub: userEntityRef,
                  ent: [userEntityRef],
                },
              });
            }
          },
        },
      }),
    },
  });
}

The logic included within the identity resolver above is as follows:

1. Obtain the username that is provided in the x-forwarded-preferred-username by the OAuth2 proxy.
2. Attempt to locate the user in the Backstage catalog
   1. If found, sign in the user
3. If a user is not found, create a user on the fly and sign them in

Once each of the actions detailed within this section have been completed, the final step is to produce a build of Backstage. Since the target environment for this demonstration will be a Kubernetes environment, a container image will be the end result of the build process. The steps for producing a container image can be found here.

A reference container image is located at quay.io/ablock/backstage-keycloak:latest if there was a desire to forgo producing a container image.

Configuring Keycloak​

Now that Backstage has been configured to support OAuth based authentication, the next step is to set up and configure Keycloak as an identity provider. Keycloak supports being installed in a variety of different ways including as a standalone application or within a container. Consult the documentation for instructions on how to get started and the process involved to install Keycloak. The easiest method, especially when deploying to a Kubernetes environment, is to use the Keycloak Operator. Once Keycloak has been installed and is running, launch a web browser and navigate to the web administration console and login.

After authenticating to Keycloak, either create a new Realm called backstage or select the name of an existing Realm that will be reused.

In order to demonstrate users authenticating against Backstage, several users and groups will be created within the Realm. First select Groups on the left hand navigation pane and then enter the names of the two groups that should be created:

1. Admins
2. Users

Once the groups have been provisioned, select Users from the left hand navigation pane and create two users with the following details:

After the accounts have been created, click the Credentials tab and then select Set Password to set an initial password for each account. Feel free to specify a password of your choosing for each user. Uncheck the temporary options so that a password reset is not required upon first login.

Next, an OAuth client needs to be created that will be used by the Backstage OAuth proxy. Select the Clients button on the left hand navigation pane and then click Create Client.

Retain the Client Type as OpenID Connect, enter backstage as the Client ID, and then optionally set a name and description that should be applied to the newly created client and click Next.

On the Capability Config page, ensure the Client authentication checkbox is enabled and click Save to create the client.

Only one configuration needs to be specified on the Settings tab, the Valid redirect URI's. This value represents the endpoint that is exposed by the OAuth2 proxy that will be sitting in front of the Backstage instance, so there is a requirement that the hostname that will be used for Backstage be known.

The OAuth callback url that needs to be configured in the Keycloak Valid Redirect URI's field takes the form <BACKSTAGE_URL>/oauth2/callback. So for example, if Backstage is to be accessed at https://backstage.example.com, the value that should be entered into the field would be https://backstage.example.com/oauth2/callback. Once the value has been entered, click Save.

The next step is to obtain the Client Secret so that it can be used later on as part of the OAuth2-proxy configuration. Navigate to the Credentials page and copy the value present in the Client Secret textbox.

Deploying Backstage using the Backstage Helm Chart​

Given that the required prerequisites have been completed and there is a container image of Backstage available and Keycloak has been configured as an Identity Provider, the final step is to deploy Backstage. As previously mentioned, Backstage can be deployed in a variety of ways, but in this case, a deployment to a Kubernetes cluster will be used and the easiest method for deploying Backstage to Kubernetes is to use the Backstage Helm chart as it not only streamlines the deployment process, but provides the capabilities to define the required configurations to enable OAuth authentication with Keycloak. A full writeup on the Backstage Helm chart including the various configurations that it enables can be found here.

The OAuth2 proxy that bridges the integration between Backstage and Keycloak is deployed as a sidecar container alongside Backstage. Sidecar containers can be enabled by specifying the backstage.extraContainer Helm Value. The entire definition of the OAuth proxy container as well as the ability to templatize the required configurations is also supported.

Create a new file called values-backstage-keycloak.yaml with the following content.

backstage:
  image:
    registry: quay.io
    repository: ablock/backstage-keycloak
    tag: latest
  extraEnvVars:
    - name: 'APP_CONFIG_app_baseUrl'
      value: 'https://{{ .Values.ingress.host }}'
    - name: 'APP_CONFIG_backend_baseUrl'
      value: 'https://{{ .Values.ingress.host }}'
    - name: 'APP_CONFIG_backend_cors_origin'
      value: 'https://{{ .Values.ingress.host }}'

  extraContainers:
    - name: oauth2-proxy
      env:
        - name: OAUTH2_PROXY_CLIENT_ID
          value: '{{ required "Keycloak Client Secret is Required" .Values.keycloak.clientId }}'
        - name: OAUTH2_PROXY_CLIENT_SECRET
          value: '{{ required "Keycloak Client Secret is Required" .Values.keycloak.clientSecret }}'
        - name: OAUTH2_PROXY_COOKIE_SECRET
          value: '{{ default (randAlpha 32 | lower | b64enc) .Values.keycloak.cookieSecret }}'
        - name: OAUTH2_PROXY_OIDC_ISSUER_URL
          value: '{{ required "Keycloak Issuer URL is Required" .Values.keycloak.issuerUrl }}'
        - name: OAUTH2_PROXY_SSL_INSECURE_SKIP_VERIFY
          value: 'true'
      ports:
        - name: oauth2-proxy
          containerPort: 4180
          protocol: TCP
      imagePullPolicy: IfNotPresent
      image: 'quay.io/oauth2-proxy/oauth2-proxy:latest'
      args:
        - '--provider=oidc'
        - '--email-domain=*'
        - '--upstream=http://localhost:7007'
        - '--http-address=0.0.0.0:4180'
        - '--skip-provider-button'

service:
  ports:
    backend: 4180
    targetPort: oauth2-proxy

ingress:
  enabled: true
  host: backstage.example.com

keycloak:
  issuerUrl: '<KEYCLOAK_URL>/realms/backstage'
  clientId: 'backstage'
  clientSecret: ''
  cookieSecret: ''

Before installing the Helm chart into the Kubernetes cluster, let’s review the contents of the Values file for the significance of certain parameters. The backstage.extraContainers parameter includes the definition of the OAuth2 Proxy and configurations are provided through a combination of container arguments and environment variables.

The location of the Keycloak instance is specified by providing the location of the OpenID Endpoint Configuration. This address can be identified within the Realm Settings page of the backstage Keycloak realm.

Update the keycloak.issuerURL parameter by providing the value that was obtained from the OpenID Endpoint Configuration. The /.well-known/openid-configuration portion of the URL can be omitted as it is inferred automatically.

Update the keycloak.clientId and keycloak.clientSecret parameters with the values that were obtained from the backstage OAuth client Credentials tab previously.

Next, specify the hostname of the backstage instance by updating the ingress.host parameter.

Finally, if there was a desire to make use of a custom Backstage image that was built previously instead of the provided image, update the set of parameters underneath the backstage.image parameter.

Alternatively, instead of updating the contents of the values-backstage-keycloak.yaml Values file, parameters can be provided during the installation of the Helm chart by each parameter using the --set option of the helm install command.

Before the chart can be installed, add the Backstage chart repository as well as the dependant Bitnami repository using the following commands:

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add backstage https://backstage.github.io/charts

Install the Backstage Helm chart to the Kubernetes cluster in a new namespace called backstage by executing the following command referencing the customized Values file:

helm install -n backstage --create-namespace backstage backstage/backstage -f values-backstage-keycloak.yaml

Once the Helm release is complete and the backstage container is running, open a web browser and navigate to the location of the Backstage instance.

When navigating to the Backstage, the OAuth2 proxy will intercept the request and redirect the browser to the Keycloak login page.

Login with either of the users that were created previously and if successful, the browser will redirect back to the Backstage user interface.

Verify the user details have been passed from Keycloak to Backstage by clicking the Settings button on the left hand navigation pane.

Notice how the username and email address associated with the Keycloak user were passed along to Backstage for which policies and relationships can be created to customize their interactions within the portal.

The integration between Keycloak and Backstage enables Backstage to take advantage of the robust identity capabilities that are provided by Keycloak. By enabling users to authenticate against an instance of Keycloak, the same set of credentials can be used to access the Backstage instance and simplifies the adoption of Backstage within organizations big and small.

Not so long ago, Red Hat pledged its intention to join the Backstage community. Several weeks later we're starting to see the first fruits of the effort. The Janus community is pleased to announce the availability of the first 2 Backstage plugins created at Red Hat. These plugins target upstream community projects, namely Keycloak and Open Cluster Management. Both plugins are in the early stages of development and are not meant to be used yet in production environments, however we welcome any feedback and suggestions as they continue to mature. Please join us on our path to building a better Internal Developer Platforms for Kubernetes and OpenShift on the Janus IDP community website.

Details related to the first Keycloak and Multicluster Engine plugins for Backstage can be found in the following sections:

Keycloak plugin for Backstage​

The need for Identity management is a common concern for any Internal Developer Platform. Backstage already contains the functionality to connect to external identity providers to enable authentication and apply proper RBAC. However, these concerns are not the sole role of identity management in relation to development portals. These portals also focus on accountability, responsibility and relationship of users and contributors to their project. Backstage achieves that through entity relations within a service catalog. All actors and objects are modeled as entities in this catalog and the Keycloak plugin ensures that all of your Keycloak users and groups are properly represented and mapped within the catalog. It allows the Backstage instance to interface with Keycloak directly and perform automatic and recurring importing of assets. Once imported, these user and group entities can be used in the standard Backstage catalog model with the added benefits of Keycloak’s diverse identity brokering capabilities.

MultiCluster Engine plugin for Backstage​

One of the key focus areas for Backstage is the ability to provide a full, transparent service catalog to their developers. This includes mapping service dependencies on other components, resource ownership, and many more. Service dependencies should not include only the requirements of other services, but also model the underlying consumed resources. This plugin aims to provide a seamless, automated resource import for companies that use MulticlusterEngine from Open Cluster Management or Red Hat Advanced Cluster Management for Kubernetes (RHACM) for their cluster fleet management. By connecting the Backstage instance to the Hub cluster, all managed clusters are discovered and imported into Backstage as standard catalog resources. In addition, the plugin also provides frontend components that fetch data from the hub cluster through the Kubernetes plugin on the Backstage instance as a proxy allowing users to quickly observe the current status of each of their clusters and providing quick access to the OpenShift console.

What's Next?​

We'll be investigating a way to import the managed clusters into the Backstage Kubernetes plugin configuration. This capability will enable Backstage users the ability to observe workloads on the managed clusters and further simplify Backstage catalog maintenance and integration with Kubernetes cluster fleets.