Add auth-backend-module-azure-easyauth-provider

.changeset/fifty-pumpkins-begin.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend': patch
+---
+
+Refactored the `azure-easyauth` provider to use the implementation from `@backstage/plugin-auth-backend-module-azure-easyauth-provider`.

.changeset/wild-rockets-tell.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend-module-azure-easyauth-provider': minor
+---
+
+New auth backend module to add `azure-easyauth` provider. Note that as part of this change the default provider ID has been changed from `easyAuth` to `azureEasyAuth`, which means that if you switch to this new module you need to update your app config as well as the `provider` prop of the `ProxiedSignInPage` in the frontend.

docs/auth/microsoft/azure-easyauth.md

@@ -7,62 +7,52 @@ description: Adding Azure's EasyAuth Proxy as an authentication provider in Back
 
 The Backstage `core-plugin-api` package comes with a Microsoft authentication provider that can authenticate users using Microsoft Entra ID (formerly Azure Active Directory) for PaaS service hosted in Azure that support Easy Auth, such as Azure App Services.
 
-## Backstage Changes
+## Backend Changes
 
-Add the following into your `app-config.yaml` or `app-config.production.yaml` file
+Add the following into your `app-config.yaml` under the root `auth` configuration:
 
-```yaml
+```yaml title="app-config.yaml"
 auth:
-  environment: development
   providers:
-    azure-easyauth: {}
+    azureEasyAuth:
+      signIn:
+        resolvers:
+          - resolver: idMatchingUserEntityAnnotation
+          - resolver: emailMatchingUserEntityProfileEmail
+          - resolver: emailLocalPartMatchingUserEntityName
 ```
 
-Add a `providerFactories` entry to the router in
-`packages/backend/src/plugins/auth.ts`.
-
-```ts
-import { providers } from '@backstage/plugin-auth-backend';
-
-export default async function createPlugin(
-  env: PluginEnvironment,
-): Promise<Router> {
-  const authProviderFactories = {
-    'azure-easyauth': providers.easyAuth.create({
-      signIn: {
-        resolver: async (info, ctx) => {
-          const {
-            fullProfile: { id },
-          } = info.result;
-
-          if (!id) {
-            throw new Error('User profile contained no id');
-          }
+The `idMatchingUserEntityAnnotation` is
+[a builtin sign-in resolver](../identity-resolver.md#using-builtin-resolvers) from `azureEasyAuth` provider.
+It tries to find a user entity with [a `graph.microsoft.com/user-id` annotation](../../features/software-catalog/well-known-annotations.md#graphmicrosoftcomtenant-id-graphmicrosoftcomgroup-id-graphmicrosoftcomuser-id)
+which matches the object ID of the user attempting to sign in.
+If you want to provide your own sign-in resolver,
+see [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers).
 
-          return await ctx.signInWithCatalogUser({
-            annotations: {
-              'graph.microsoft.com/user-id': id,
-            },
-          });
-        },
-      },
-    }),
-  };
-
-  return await createRouter({
-    logger: env.logger,
-    config: env.config,
-    database: env.database,
-    discovery: env.discovery,
-    tokenManager: env.tokenManager,
-    providerFactories: authProviderFactories,
-  });
-}
+Add the `@backstage/plugin-auth-backend-module-azure-easyauth-provider` to your backend installation.
+
+```sh
+# From your Backstage root directory
+yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-azure-easyauth-provider
+```
+
+Then, add it to your backend's source,
+
+```ts title="packages/backend/src/index.ts"
+const backend = createBackend();
+
+backend.add(import('@backstage/plugin-auth-backend'));
+// highlight-add-next-line
+backend.add(
+  import('@backstage/plugin-auth-backend-module-azure-easyauth-provider'),
+);
+
+await backend.start();
 ```
 
 Now the backend is ready to serve auth requests on the
-`/api/auth/azure-easyauth/refresh` endpoint. All that's left is to update the frontend
-sign-in mechanism to poll that endpoint through the IAP, on the user's behalf.
+`/api/auth/azureEasyAuth/refresh` endpoint. All that's left is to update the frontend
+sign-in mechanism to poll that endpoint through the Easy Auth proxy, on the user's behalf.
 
 ## Frontend Changes
 
@@ -81,7 +71,7 @@ const app = createApp({
     SignInPage: props => {
       const configApi = useApi(configApiRef);
       if (configApi.getString('auth.environment') !== 'development') {
-        return <ProxiedSignInPage {...props} provider="azure-easyauth" />;
+        return <ProxiedSignInPage {...props} provider="azureEasyAuth" />;
       }
       return (
         <SignInPage

plugins/auth-backend-module-azure-easyauth-provider/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/auth-backend-module-azure-easyauth-provider/README.md

@@ -0,0 +1,5 @@
+# Auth Backend Module - Azure Easy Auth Provider
+
+## Links
+
+- [The Backstage homepage](https://backstage.io)

plugins/auth-backend-module-azure-easyauth-provider/api-report.md

@@ -0,0 +1,40 @@
+## API Report File for "@backstage/plugin-auth-backend-module-azure-easyauth-provider"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { BackendFeature } from '@backstage/backend-plugin-api';
+import { Profile } from 'passport';
+import { ProxyAuthenticator } from '@backstage/plugin-auth-node';
+import { SignInResolverFactory } from '@backstage/plugin-auth-node';
+
+// @public (undocumented)
+const authModuleAzureEasyAuthProvider: () => BackendFeature;
+export default authModuleAzureEasyAuthProvider;
+
+// @public (undocumented)
+export const azureEasyAuthAuthenticator: ProxyAuthenticator<
+  void,
+  AzureEasyAuthResult,
+  {
+    accessToken: string | undefined;
+  }
+>;
+
+// @public (undocumented)
+export type AzureEasyAuthResult = {
+  fullProfile: Profile;
+  accessToken?: string;
+};
+
+// @public (undocumented)
+export namespace azureEasyAuthSignInResolvers {
+  const // (undocumented)
+    idMatchingUserEntityAnnotation: SignInResolverFactory<
+      AzureEasyAuthResult,
+      unknown
+    >;
+}
+
+// (No @packageDocumentation comment for this package)
+```

plugins/auth-backend-module-azure-easyauth-provider/catalog-info.yaml

@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backstage-plugin-auth-backend-module-azure-easyauth-provider
+  title: '@backstage/plugin-auth-backend-module-azure-easyauth-provider'
+  description: The azure-easyauth-provider backend module for the auth plugin.
+spec:
+  lifecycle: experimental
+  type: backstage-backend-plugin-module
+  owner: maintainers

plugins/auth-backend-module-azure-easyauth-provider/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@backstage/plugin-auth-backend-module-azure-easyauth-provider",
+  "version": "0.0.0",
+  "description": "The azure-easyauth-provider backend module for the auth plugin.",
+  "backstage": {
+    "role": "backend-plugin-module"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/auth-backend-module-azure-easyauth-provider"
+  },
+  "license": "Apache-2.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "backstage-cli package build",
+    "clean": "backstage-cli package clean",
+    "lint": "backstage-cli package lint",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "start": "backstage-cli package start",
+    "test": "backstage-cli package test"
+  },
+  "dependencies": {
+    "@backstage/backend-plugin-api": "workspace:^",
+    "@backstage/catalog-model": "workspace:^",
+    "@backstage/errors": "workspace:^",
+    "@backstage/plugin-auth-node": "workspace:^",
+    "@types/passport": "^1.0.16",
+    "express": "^4.19.2",
+    "jose": "^5.0.0",
+    "passport": "^0.7.0"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "workspace:^",
+    "@backstage/cli": "workspace:^",
+    "@backstage/plugin-auth-backend": "workspace:^"
+  }
+}

plugins/auth-backend-module-azure-easyauth-provider/src/authenticator.test.ts

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  azureEasyAuthAuthenticator,
+  ID_TOKEN_HEADER,
+  ACCESS_TOKEN_HEADER,
+} from './authenticator';
+import { mockServices } from '@backstage/backend-test-utils';
+import { Request } from 'express';
+import { SignJWT, JWTPayload, errors as JoseErrors } from 'jose';
+import { randomBytes } from 'crypto';
+
+const jwtSecret = randomBytes(48);
+
+async function buildJwt(claims: JWTPayload) {
+  return await new SignJWT(claims)
+    .setProtectedHeader({ alg: 'HS256' })
+    .sign(jwtSecret);
+}
+
+function mockRequest(headers?: Record<string, string>) {
+  return {
+    header: (name: string) => headers?.[name],
+  } as unknown as Request;
+}
+
+describe('EasyAuthAuthProvider', () => {
+  const ctx = azureEasyAuthAuthenticator.initialize({
+    config: mockServices.rootConfig(),
+  });
+
+  describe('should succeed when', () => {
+    const claims = {
+      ver: '2.0',
+      oid: 'c43063d4-0650-4f3e-ba6b-307473d24dfd',
+      name: 'Alice Bob',
+      email: 'alice@bob.com',
+      preferred_username: 'Another name',
+    };
+
+    it('valid id_token provided', async () => {
+      const request = mockRequest({
+        [ID_TOKEN_HEADER]: await buildJwt(claims),
+      });
+      await expect(
+        azureEasyAuthAuthenticator.authenticate({ req: request }, ctx),
+      ).resolves.toEqual({
+        result: {
+          fullProfile: {
+            provider: 'easyauth',
+            id: 'c43063d4-0650-4f3e-ba6b-307473d24dfd',
+            displayName: 'Alice Bob',
+            emails: [{ value: 'alice@bob.com' }],
+            username: 'Another name',
+          },
+          accessToken: undefined,
+        },
+        providerInfo: {
+          accessToken: undefined,
+        },
+      });
+    });
+
+    it('valid id_token and access_token provided', async () => {
+      const request = mockRequest({
+        [ID_TOKEN_HEADER]: await buildJwt(claims),
+        [ACCESS_TOKEN_HEADER]: 'ACCESS_TOKEN',
+      });
+      await expect(
+        azureEasyAuthAuthenticator.authenticate({ req: request }, ctx),
+      ).resolves.toMatchObject({
+        result: { accessToken: 'ACCESS_TOKEN' },
+        providerInfo: { accessToken: 'ACCESS_TOKEN' },
+      });
+    });
+  });
+
+  describe('should fail when', () => {
+    it('id token is missing', async () => {
+      const request = mockRequest();
+      await expect(
+        azureEasyAuthAuthenticator.authenticate({ req: request }, ctx),
+      ).rejects.toThrow('Missing x-ms-token-aad-id-token header');
+    });
+
+    it('id token is invalid', async () => {
+      const request = mockRequest({ [ID_TOKEN_HEADER]: 'not-a-jwt' });
+      await expect(
+        azureEasyAuthAuthenticator.authenticate({ req: request }, ctx),
+      ).rejects.toThrow(JoseErrors.JWTInvalid);
+    });
+
+    it('id token is v1', async () => {
+      const request = mockRequest({
+        [ID_TOKEN_HEADER]: await buildJwt({ ver: '1.0' }),
+      });
+      await expect(
+        azureEasyAuthAuthenticator.authenticate({ req: request }, ctx),
+      ).rejects.toThrow('id_token is not version 2.0');
+    });
+  });
+});