From b7d51f78edcc191fe6cf53cdc9d98148d12b9eec Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Thu, 28 Dec 2023 13:00:09 -0600 Subject: [PATCH 1/2] Added section on migrating auth plugin and related modules Signed-off-by: Andre Wanlin --- .../building-backends/08-migrating.md | 252 ++++++++++++++++++ 1 file changed, 252 insertions(+) diff --git a/docs/backend-system/building-backends/08-migrating.md b/docs/backend-system/building-backends/08-migrating.md index e38b0f8c3a..ac54d6d3ef 100644 --- a/docs/backend-system/building-backends/08-migrating.md +++ b/docs/backend-system/building-backends/08-migrating.md @@ -754,3 +754,255 @@ going easily, but feel free to move it out to where it fits best. As you migrate your entire plugin flora to the new backend system, you will probably make more and more of these modules as "first class" things, living right next to the implementations that they represent, and being exported from there. + +### The Auth Plugin + +A basic installation of the auth plugin will look as follows. + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-microsoft-provider')); +/* highlight-add-end */ +``` + +An additional step you'll need to take is to add the resolvers to your configuration, here's an example: + +```yaml title:"app-config.yaml +auth: + environment: development + providers: + microsoft: + development: + clientId: ${AZURE_CLIENT_ID} + clientSecret: ${AZURE_CLIENT_SECRET} + tenantId: ${AZURE_TENANT_ID} + signIn: + resolvers: + - resolver: emailMatchingUserEntityAnnotation + - resolver: emailMatchingUserEntityProfileEmail + - resolver: emailLocalPartMatchingUserEntityName +``` + +> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`. + +#### Auth Plugin Modules and Their Resolvers + +As you may have noticed in the above example you'll need to import the `auth-backend` and an `auth-backend-module`. The following sections outline each of them and their resolvers. + +All of the following modules include the following common resolvers: + +- [emailMatchingUserEntityProfileEmail](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-node/src/sign-in/commonSignInResolvers.ts#L29) +- [emailLocalPartMatchingUserEntityName](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-node/src/sign-in/commonSignInResolvers.ts#L54) + +##### Atlassian + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-atlassian-provider')); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [usernameMatchingUserEntityName](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-atlassian-provider/src/resolvers.ts#L33C16-L33C46) + +##### GCP IAM + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-gcp-iap-provider')); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [emailMatchingUserEntityAnnotation](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-gcp-iap-provider/src/resolvers.ts#L32C16-L32C49) + +##### GitHub + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-github-provider')); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [usernameMatchingUserEntityName](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-github-provider/src/resolvers.ts#L33C16-L33C46) + +##### GitLab + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-gitlab-provider')); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [usernameMatchingUserEntityName](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-gitlab-provider/src/resolvers.ts#L33C16-L33C46) + +##### Google + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-google-provider')); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [emailMatchingUserEntityAnnotation](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-google-provider/src/resolvers.ts#L33C16-L33C49) + +##### Microsoft + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-microsoft-provider')); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [emailMatchingUserEntityAnnotation](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-microsoft-provider/src/resolvers.ts#L33C16-L33C49) + +##### oauth2 + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-oauth2-provider')); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [usernameMatchingUserEntityName](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-oauth2-provider/src/resolvers.ts#L33C16-L33C46) + +##### oauth2 Proxy + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add( + import('@backstage/plugin-auth-backend-module-oauth2-proxy-provider'), +); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [forwardedUserMatchingUserEntityName](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-oauth2-proxy-provider/src/resolvers.ts#L27C16-L27C51) + +##### Okta + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-okta-provider')); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [emailMatchingUserEntityAnnotation](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-okta-provider/src/resolvers.ts#L34C16-L34C49) + +##### Pinniped + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(import('@backstage/plugin-auth-backend-module-pinniped-provider')); +/* highlight-add-end */ +``` + +##### VMware Cloud + +Setup: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add( + import('@backstage/plugin-auth-backend-module-vmware-cloud-provider'), +); +/* highlight-add-end */ +``` + +Additional resolvers: + +- [vmwareCloudSignInResolvers](https://github.com/backstage/backstage/blob/5447cffd23cf00772988fb799ced0ec5e54efb2e/plugins/auth-backend-module-vmware-cloud-provider/src/resolvers.ts#L29C18-L29C44) + +#### Custom Resolver + +You may have a case where the common resolvers or the ones that are included with the auth module you use won't work for your needs. In this case you will need to create a custom resolver. Instead of the 2nd import for your auth provider module you would provide your own: + +```ts title="packages/backend/src/index.ts" +/* highlight-add-start */ +export const authModuleGoogleProvider = createBackendModule({ + pluginId: 'auth', + moduleId: 'googleProvider', + register(reg) { + reg.registerInit({ + deps: { providers: authProvidersExtensionPoint }, + async init({ providers }) { + providers.registerProvider({ + providerId: 'google', + factory: createOAuthProviderFactory({ + authenticator: googleAuthenticator, + async signInResolver(info, ctx) { + // custom resolver ... + }, + }), + }); + }, + }); + }, +}); +/* highlight-add-end */ + +const backend = createBackend(); +/* highlight-add-start */ +backend.add(import('@backstage/plugin-auth-backend')); +backend.add(authModuleGoogleProvider); +/* highlight-add-end */ +``` From 4b1a4d8bbe8864306c1e339d9a59f0b0a90e07b7 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 10 Jan 2024 12:49:06 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Signed-off-by: Patrik Oldsberg --- docs/backend-system/building-backends/08-migrating.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/backend-system/building-backends/08-migrating.md b/docs/backend-system/building-backends/08-migrating.md index ac54d6d3ef..2514f0925e 100644 --- a/docs/backend-system/building-backends/08-migrating.md +++ b/docs/backend-system/building-backends/08-migrating.md @@ -757,7 +757,7 @@ implementations that they represent, and being exported from there. ### The Auth Plugin -A basic installation of the auth plugin will look as follows. +A basic installation of the auth plugin with a microsoft provider will look as follows. ```ts title="packages/backend/src/index.ts" const backend = createBackend(); @@ -769,7 +769,7 @@ backend.add(import('@backstage/plugin-auth-backend-module-microsoft-provider')); An additional step you'll need to take is to add the resolvers to your configuration, here's an example: -```yaml title:"app-config.yaml +```yaml title:"app-config.yaml" auth: environment: development providers: