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.
OAuth2 Proxy does not provide a way to authenticate requests, you must instead ensure that your Backstage instance is only accessible through the OAuth2 Proxy. If you need more strict validation, consider using a different provider.
Configuration
The provider configuration can be added to your app-config.yaml
under the root
auth
configuration:
auth:
environment: development
providers:
oauth2Proxy:
signIn:
resolvers:
# See https://backstage.io/docs/auth/oauth2-proxy/provider#resolvers for more resolvers
- 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 matchingspec.profile.email
. If no match is found it will throw aNotFoundError
.emailLocalPartMatchingUserEntityName
: Matches the local part of the email address from the auth provider with the User entity that has a matchingname
. If no match is found it will throw aNotFoundError
.forwardedUserMatchingUserEntityName
: Matches the value in thex-forwarded-user
header from the auth provider with the User entity that has a matchingname
. If no match is found it will throw aNotFoundError
.
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.
Backend Installation
To add the provider to the backend we will first need to install the package by running this command:
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-oauth2-proxy-provider
Then we will need to this line:
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(
import('@backstage/plugin-auth-backend-module-oauth2-proxy-provider'),
);
Adding the provider to the Backstage frontend
See Sign-In with Proxy Providers for pointers on how to set up the sign-in page, and to also make it work smoothly for local development. You'll use oauth2Proxy
as the provider name.
If you provide a custom sign in resolver, you can skip the signIn
block entirely.