Project: Backstage (App Definition and Development / Application Definition & Image Build)
File: provider.md

id: provider title: VMware Cloud Authentication Provider sidebar_label: VMware Cloud description: Adding VMware Cloud as an authentication provider in Backstage Backstage comes with an auth provider module to allow users to sign-in with their VMware Cloud account. This page describes some actions within the VMware Cloud Console and within a Backstage app required to enable this capability. Log in to the . Navigate to and click the tab -- if you are not an Organization Owner or Administrator but only a Member, you will not see this nav entry unless the Developer check box is selected for your role (see the docs for details). Click Create App, choose 'Web/Mobile app' and click Continue. Use default settings except: `App Name` and `App Description` of your choosing. `Redirect URIs`: `${baseUrl}/api/auth/vmwareCloudServices/handler/frame` where `baseUrl` is the URL where your Backstage backend can be reached; note that VMware Cloud does not support the combination of an `http://` scheme and a `localhost` hostname, so when testing locally it may help to set your backend base URL to `http://127.0.0.1:7007`. `Refresh Token`: check `Issue refresh token`; refresh tokens are required to prevent forcing users to re-login when they refresh their browser. `Define Scopes`: check `OpenID` at the bottom. Click Create. Take note of the `App ID` in the resulting modal; this is the client ID to be used by Backstage. Apps using the , can enable the VMware Cloud provider with a small modification like: ```ts title="packages/backend/src/index.ts" import { createBackend } from '@backstage/backend-defaults'; const backend = createBackend(); backend.add(import('@backstage/plugin-auth-backend')); / highlight-add-start / backend.add( import('@backstage/plugin-auth-backend-module-vmware-cloud-provider'), ); / highlight-add-end / backend.start(); ``` This provider was added after the migration of the auth-backend plugin to the new backend system, so no default provider factory was added. Because of this, the installation procedure for old-style backends is slightly more involved: ```ts title="packages/backend/src/plugins/auth.ts" import { DEFAULT_NAMESPACE, stringifyEntityRef, } from '@backstage/catalog-model'; import { createRouter, providers, defaultAuthProviderFactories, } from '@backstage/plugin-auth-backend'; import { Router } from 'express'; import { PluginEnvironment } from '../types'; / highlight-add-start / import { commonSignInResolvers, createOAuthProviderFactory, } from '@backstage/plugin-auth-node'; import { vmwareCloudAuthenticator, } from '@backstage/plugin-auth-backend-module-vmware-cloud-provider'; / highlight-add-end / export default async function createPlugin( env: PluginEnvironment, ): Promise<Router> { return await createRouter({ logger: env.logger, config: env.config, database: env.database, discovery: env.discovery, tokenManager: env.tokenManager, providerFactories: {

/ highlight-add-start / vmwareCloudServices: createOAuthProviderFactory({ authenticator: vmwareCloudAuthenticator, signInResolver: commonSignInResolvers.emailLocalPartMatchingUserEntityName(), }), / highlight-add-end / ``` In the above, `commonSignInResolvers.emailLocalPartMatchingUserEntityName()` can be replaced with a more suitable resolver for the app in question. See the docs for general guidance, but as an example: ```tsx title="packages/app/src/App.tsx" / highlight-add-start / import { vmwareCloudAuthApiRef } from '@backstage/core-plugin-api'; import { SignInPage } from '@backstage/core-components'; / highlight-add-end / const app = createApp({ / highlight-add-start / components: { SignInPage: props => ( <SignInPage {...props} provider={{ id: 'vmware-cloud-auth-provider', title: 'VMware Cloud', message: 'Sign in using VMware Cloud', apiRef: vmwareCloudAuthApiRef, }} /> ), }, / highlight-add-end / // .. }); ``` Add the following to your `app-config.yaml` under the root `auth` configuration: ```yaml auth: session: secret: your session secret environment: development providers: vmwareCloudServices: development: clientId: ${APP_ID} organizationId: ${ORG_ID} signIn: resolvers: resolver: emailMatchingUserEntityProfileEmail resolver: emailLocalPartMatchingUserEntityName resolver: vmwareCloudSignInResolvers ``` Where `APP_ID` refers to the ID retrieved when creating the OAuth App, and `ORG_ID` is the in VMware Cloud for which you wish to enable sign-in. Note that VMware Cloud requires OAuth Apps to use when performing authorization code flows; the library used by this provider requires the use of Express session middleware to do this. Therefore the value `your session secret` under `auth.session.secret` should be replaced with a long, complex and unique string which will act as a key for signing session cookies set by Backstage. 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 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`. `vmwareCloudSignInResolvers`: 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 sign in the user without associating with a catalog user. :::note 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 section of the Sign-in Identities and Resolvers documentation.