paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 50 Packages Projects Releases Wiki Activity

Added backend install steps for various auth providers

Browse Source 
Signed-off-by: Andre Wanlin <awanlin@spotify.com>
This commit is contained in:
Andre Wanlin
2024-07-05 12:07:22 -05:00
parent e43d17bea7
commit 0976bbd152
16 changed files with 439 additions and 551 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/auth/vmware-cloud/provider.md
+30 -103
View File
@@ -33,108 +33,6 @@ Cloud Console and within a Backstage app required to enable this capability.
1. Take note of the `App ID` in the resulting modal; this is the client ID to be
used by Backstage.
## Install the provider in the backend
### New backend system
Apps using the [new backend system](../../backend-system/index.md),
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();
```
### Old backend system
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: {
...defaultAuthProviderFactories,
/* 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.
## Add to Sign-in Page
See the [Sign-In Configuration](../index.md#sign-in-configuration) 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 */
// ..
});
```
## Configuration
Add the following to your `app-config.yaml` under the root `auth` configuration:
@@ -161,13 +59,17 @@ Where `APP_ID` refers to the ID retrieved when creating the OAuth App, and
`ORG_ID` is the [long ID of the Organization](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html#view-the-organization-id-1)
in VMware Cloud for which you wish to enable sign-in.
Note that VMware Cloud requires OAuth Apps to use
:::note Note
VMware Cloud requires OAuth Apps to use
[PKCE](https://oauth.net/2/pkce/) 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.
:::
### Resolvers
This provider includes several resolvers out of the box that you can use:
@@ -183,3 +85,28 @@ The resolvers will be tried in order, but will only be skipped if they throw a `
:::
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#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:
```bash title="from your Backstage root directory"
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-vmware-cloud-provider
```
Then we will need to this line:
```ts title="in packages/backend/src/index.ts"
backend.add(import('@backstage/plugin-auth-backend'));
/* highlight-add-start */
backend.add(
import('@backstage/plugin-auth-backend-module-vmware-cloud-provider'),
);
/* highlight-add-end */
```
## Adding the provider to the Backstage frontend
To add the provider to the frontend, add the `vmwareCloudAuthApiRef` reference and
`SignInPage` component as shown in
[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page).