OpenShift Authentication Provider

The Backstage core-plugin-api package comes with a OpenShift authentication provider that can authenticate users using OpenShift OAuth.

Use Case

This setup enables the Kubernetes plugin to access OpenShift clusters using the user's permissions, leveraging OAuth 2.0 On-Behalf-Of flow via the Kubernetes Client Side Provider.

To make this work, the corresponding User entities must exist in the Backstage catalog, and their names must match the OpenShift users.

Although the OpenShift authentication provider does not support OIDC natively, you can still configure it for use with the Kubernetes integration by treating it as an OIDC provider in the KubernetesAuthProviders configuration.

packages/app/src/apis.ts

import {
  KubernetesAuthProviders,
  kubernetesAuthProvidersApiRef,
} from '@backstage/plugin-kubernetes';
import {
  googleAuthApiRef,
  microsoftAuthApiRef,
  openshiftAuthApiRef,
} from '@backstage/core-plugin-api';

export const apis: AnyApiFactory[] = [
  // ...
  createApiFactory({
    api: kubernetesAuthProvidersApiRef,
    deps: {
      microsoftAuthApi: microsoftAuthApiRef,
      googleAuthApi: googleAuthApiRef,
      openshiftAuthApi: openshiftAuthApiRef,
    },
    factory({ microsoftAuthApi, googleAuthApi, openshiftAuthApi }) {
      return new KubernetesAuthProviders({
        microsoftAuthApi,
        googleAuthApi,
        oidcProviders: {
          openshift: {
            async getIdToken(_) {
              return await openshiftAuthApi.getAccessToken('user:full');
            },
          },
        },
      });
    },
  }),
  //...
];

Note

The OpenShift auth API does not implement the OpenIdConnectApi interface. In other words, it does not return an ID token. Instead, it returns an access token, which is used by the Kubernetes integration in place of an ID token. This is the only functional difference from the standard OIDC-based authentication flow.

Create an OAuth client in OpenShift

Make sure that an OAuth client exists in the OpenShift cluster.

To configure the OpenShift integration, create an OAuthClient.

The redirect URI must be in the following format: https://<fqdn>/api/auth/openshift/handler/frame.

Configuration

The provider configuration can then be added to your app-config.yaml under the root auth configuration:

auth:
  environment: development
  providers:
    openshift:
      development:
        clientId: ${AUTH_OPENSHIFT_CLIENT_ID}
        clientSecret: ${AUTH_OPENSHIFT_CLIENT_SECRET}
        authorizationUrl: ${AUTH_OPENSHIFT_AUTHORIZATION_URL}
        tokenUrl: ${AUTH_OPENSHIFT_TOKEN_URL}
        openshiftApiServerUrl: ${OPENSHIFT_API_SERVER_URL}
        ## uncomment to set lifespan of user session
        # sessionDuration: { hours: 24 } # supports `ms` library format (e.g. '24h', '2 days'), ISO duration, "human duration" as used in code
        # sessionDuration: 1d
        signIn:
          resolvers:
            - resolver: displayNameMatchingUserEntityName

The OpenShift provider is a structure with these configuration keys:

• clientId: The client ID of your OpenShift OAuth client, e.g., my-backstage
• clientSecret: The client secret tied to the OpenShift OAuth client.
• authorizationUrl: The OpenShift OAuth client auth endpoint, format: https://<oauth-client-route>/oauth/authorize.
• tokenUrl: The OpenShift OAuth client token endpoint, format: https://<oauth-client-route>/oauth/token.
• openshiftApiServerUrl: The OpenShift API server endpoint, format: https://<openshift-api>.
• sessionDuration: (optional): Lifespan of the user session.
• signIn: The configuration for the sign-in process, including the resolvers that should be used to match the user from the auth provider with the user entity in the Backstage catalog (typically a single resolver is sufficient).

The provider needs to use the scope user:full.

Backend Installation

To add the provider to the backend we will first need to install the package by running this command:

from your Backstage root directory

yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-openshift-provider

Then we will need to add this line:

in packages/backend/src/index.ts

backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-openshift-provider'));