Skip to main content

OAuth 2 Proxy Provider

The Backstage @backstage/plugin-auth-backend package comes with an oauth2Proxy authentication provider that can authenticate users by using a oauth2-proxy in front of an actual Backstage instance. This enables to reuse existing authentications within a cluster. In general the oauth2-proxy supports all OpenID Connect providers, for more details check this list of supported providers.

Configuration​

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

app-config.yaml
auth:
  environment: development
  providers:
    oauth2Proxy:
      development:
        signIn:
          resolvers:
            # typically you would pick one of these
            - resolver: emailMatchingUserEntityProfileEmail
            - resolver: emailLocalPartMatchingUserEntityName
            - resolver: forwardedUserMatchingUserEntityName

Resolvers​

This provider includes several resolvers out of the box that you can use:

  • emailMatchingUserEntityProfileEmail: Matches the email address from the auth provider with the User entity that has a matching spec.profile.email. If no match is found it will throw a NotFoundError.
  • emailLocalPartMatchingUserEntityName: Matches the local part of the email address from the auth provider with the User entity that has a matching name. If no match is found it will throw a NotFoundError.
  • forwardedUserMatchingUserEntityName: Matches the value in the x-forwarded-user header from the auth provider with the User entity that has a matching name. If no match is found it will throw a NotFoundError.
Note

The resolvers will be tried in order, but will only be skipped if they throw a NotFoundError.

If these resolvers do not fit your needs you can build a custom resolver, this is covered in the Building Custom Resolvers section of the Sign-in Identities and Resolvers documentation.

Adding the provider to the Backstage frontend​

It is recommended to use the ProxiedSignInPage for this provider, which is installed in packages/app/src/App.tsx like this:

packages/app/src/App.tsx
import { ProxiedSignInPage } from '@backstage/core-components';

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

See Sign-In with Proxy Providers for pointers on how to set up the sign-in page to also work smoothly for local development.