feat(app): dynamic authentication provider support

gashcrumb · gashcrumb · commit 0a51a97a9dec · 2025-02-13T07:09:38.000-05:00
This change adds support for loading authentication providers or modules
from dynamic plugins via 3 main changes to the code.

First, an environment variable `ENABLE_AUTH_PROVIDER_MODULE_OVERRIDE`
controls whether or not the backend installs the default authentication
provider module.  When this override is enabled dynamic plugins can be
used to supply custom authentication providers.

Secondly this change also adds a `signInPage` configuration for frontend
dynamic plugins which is required for dynamic plugins to be able to
provide a custom SignInPage component, for example:

```yaml
dynamicPlugins:
  frontend:
    my-plugin-package:
      signInPage:
	    importName: CustomSignInPage
```

Where the named export `CustomSignInPage` will be mapped to
`components.SignInPage` when the frontend is initialized.

Finally, to ensure authentication providers can be managed by the user a
new `providerSettings` configuration field is available for frontend
dynamic plugins, which can be used to inform the user settings page of
the new provider, for example:

```yaml
dynamicPlugins:
  frontend:
    my-plugin-package:
      providerSettings:
	  - title: Github Two
	    description: Sign in with GitHub Org Two
	    provider: core.auth.github-two
```

Each `providerSettings` item will be turned into a new row under the
"Authentication Providers" tab on the user settings page.  The
`provider` field is used to look up and connect the API ref for the
external authentication provider and should be the same string used when
calling `createApiRef`, for example:

```javascript
export const ghTwoAuthApiRef: ApiRef&lt;
  OAuthApi &amp; ProfileInfoApi &amp; BackstageIdentityApi &amp; SessionApi
&gt; = createApiRef({
  id: 'core.auth.github-two',  // &lt;--- this string
})
```

Signed-off-by: Stan Lewis &lt;gashcrumb@gmail.com&gt;
diff --git a/packages/app/src/components/AppBase/AppBase.tsx b/packages/app/src/components/AppBase/AppBase.tsx
@@ -34,6 +34,7 @@ const AppBase = () => {
     AppRouter,
     dynamicRoutes,
     entityTabOverrides,
+    providerSettings,
     scaffolderFieldExtensions,
   } = useContext(DynamicRootContext);
 
@@ -118,7 +119,7 @@ const AppBase = () => {
               <SearchPage />
             </Route>
             <Route path="/settings" element={<UserSettingsPage />}>
-              {settingsPage}
+              {settingsPage(providerSettings)}
             </Route>
             <Route path="/catalog-graph" element={<CatalogGraphPage />} />
             <Route path="/learning-paths" element={<LearningPaths />} />
diff --git a/packages/app/src/components/DynamicRoot/DynamicRoot.tsx b/packages/app/src/components/DynamicRoot/DynamicRoot.tsx
@@ -3,7 +3,11 @@ import React, { useCallback, useEffect, useRef, useState } from 'react';
 
 import { createApp } from '@backstage/app-defaults';
 import { BackstageApp } from '@backstage/core-app-api';
-import { AnyApiFactory, BackstagePlugin } from '@backstage/core-plugin-api';
+import {
+  AnyApiFactory,
+  AppComponents,
+  BackstagePlugin,
+} from '@backstage/core-plugin-api';
 
 import { useThemes } from '@redhat-developer/red-hat-developer-hub-theme';
 import { AppsConfig } from '@scalprum/core';
@@ -61,7 +65,9 @@ export const DynamicRoot = ({
     React.ComponentType | undefined
   >(undefined);
   // registry of remote components loaded at bootstrap
-  const [components, setComponents] = useState<ComponentRegistry | undefined>();
+  const [componentRegistry, setComponentRegistry] = useState<
+    ComponentRegistry | undefined
+  >();
   const { initialized, pluginStore, api: scalprumApi } = useScalprum();
 
   const themes = useThemes();
@@ -76,10 +82,12 @@ export const DynamicRoot = ({
       menuItems,
       entityTabs,
       mountPoints,
+      providerSettings,
       routeBindings,
       routeBindingTargets,
       scaffolderFieldExtensions,
       themes: pluginThemes,
+      signInPages,
     } = extractDynamicConfig(dynamicPlugins);
     const requiredModules = [
       ...pluginModules.map(({ scope, module }) => ({
@@ -114,6 +122,10 @@ export const DynamicRoot = ({
         scope,
         module,
       })),
+      ...signInPages.map(({ scope, module }) => ({
+        scope,
+        module,
+      })),
     ];
 
     const staticPlugins = Object.keys(staticPluginStore).reduce(
@@ -387,6 +399,25 @@ export const DynamicRoot = ({
       [],
     );
 
+    // the config allows for multiple sign-in pages, discover and use the first
+    // working instance but check all of them
+    const signInPage = signInPages
+      .map<React.ComponentType<{}> | undefined>(
+        ({ scope, module, importName }) => {
+          const candidate = allPlugins[scope]?.[module]?.[
+            importName
+          ] as React.ComponentType<{}>;
+          if (!candidate) {
+            // eslint-disable-next-line no-console
+            console.warn(
+              `Plugin ${scope} is not configured properly: ${module}.${importName} not found, ignoring SignInPage: ${importName}`,
+            );
+          }
+          return candidate;
+        },
+      )
+      .find(candidate => candidate !== undefined);
+
     if (!app.current) {
       const filteredStaticThemes = themes.filter(
         theme =>
@@ -408,7 +439,12 @@ export const DynamicRoot = ({
           ...remoteBackstagePlugins,
         ],
         themes: [...filteredStaticThemes, ...dynamicThemeProviders],
-        components: defaultAppComponents,
+        components: {
+          ...defaultAppComponents,
+          ...(signInPage && {
+            SignInPage: signInPage,
+          }),
+        } as Partial<AppComponents>,
       });
     }
 
@@ -424,16 +460,16 @@ export const DynamicRoot = ({
       scaffolderFieldExtensionComponents;
 
     // make the dynamic UI configuration available to DynamicRootContext consumers
-    setComponents({
+    setComponentRegistry({
       AppProvider: app.current.getProvider(),
       AppRouter: app.current.getRouter(),
       dynamicRoutes: dynamicRoutesComponents,
       menuItems: dynamicRoutesMenuItems,
       entityTabOverrides,
       mountPoints: mountPointComponents,
+      providerSettings,
       scaffolderFieldExtensions: scaffolderFieldExtensionComponents,
     });
-
     afterInit().then(({ default: Component }) => {
       setChildComponent(() => Component);
     });
@@ -449,17 +485,17 @@ export const DynamicRoot = ({
   ]);
 
   useEffect(() => {
-    if (initialized && !components) {
+    if (initialized && !componentRegistry) {
       initializeRemoteModules();
     }
-  }, [initialized, components, initializeRemoteModules]);
+  }, [initialized, componentRegistry, initializeRemoteModules]);
 
-  if (!initialized || !components) {
+  if (!initialized || !componentRegistry) {
     return <Loader />;
   }
 
   return (
-    <DynamicRootContext.Provider value={components}>
+    <DynamicRootContext.Provider value={componentRegistry}>
       {ChildComponent ? <ChildComponent /> : <Loader />}
     </DynamicRootContext.Provider>
   );
diff --git a/packages/app/src/components/DynamicRoot/DynamicRootContext.tsx b/packages/app/src/components/DynamicRoot/DynamicRootContext.tsx
@@ -112,11 +112,18 @@ export type ScaffolderFieldExtension = {
   Component: React.ComponentType<{}>;
 };
 
+export type ProviderSetting = {
+  title: string;
+  description: string;
+  provider: string;
+};
+
 export type DynamicRootConfig = {
   dynamicRoutes: ResolvedDynamicRoute[];
   entityTabOverrides: EntityTabOverrides;
   mountPoints: MountPoints;
   menuItems: ResolvedMenuItem[];
+  providerSettings: ProviderSetting[];
   scaffolderFieldExtensions: ScaffolderFieldExtension[];
 };
 
@@ -132,6 +139,7 @@ const DynamicRootContext = createContext<ComponentRegistry>({
   entityTabOverrides: {},
   mountPoints: {},
   menuItems: [],
+  providerSettings: [],
   scaffolderFieldExtensions: [],
 });
 
diff --git a/packages/app/src/components/DynamicRoot/ScalprumRoot.tsx b/packages/app/src/components/DynamicRoot/ScalprumRoot.tsx
@@ -77,6 +77,7 @@ const ScalprumRoot = ({
       entityTabOverrides: {},
       mountPoints: {},
       scaffolderFieldExtensions: [],
+      providerSettings: [],
     } as DynamicRootConfig,
   };
   return (
diff --git a/packages/app/src/components/UserSettings/SettingsPages.tsx b/packages/app/src/components/UserSettings/SettingsPages.tsx
@@ -1,11 +1,83 @@
+import { ErrorBoundary } from '@backstage/core-components';
 import {
+  AnyApiFactory,
+  ApiRef,
+  configApiRef,
+  ProfileInfoApi,
+  SessionApi,
+  useApi,
+  useApp,
+} from '@backstage/core-plugin-api';
+import {
+  DefaultProviderSettings,
+  ProviderSettingsItem,
   SettingsLayout,
   UserSettingsAuthProviders,
 } from '@backstage/plugin-user-settings';
 
 import { generalPage } from './GeneralPage';
+import Star from '@mui/icons-material/Star';
+
+import { ProviderSetting } from '../DynamicRoot/DynamicRootContext';
+
+const DynamicProviderSettingsItem = ({
+  title,
+  description,
+  provider,
+}: {
+  title: string;
+  description: string;
+  provider: string;
+}) => {
+  const app = useApp();
+  // The provider API needs to be registered with the app
+  const apiRef = app
+    .getPlugins()
+    .flatMap(plugin => Array.from(plugin.getApis()))
+    .filter((api: AnyApiFactory) => api.api.id === provider)
+    .at(0)?.api;
+  if (!apiRef) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `No API factory found for provider ref "${provider}", hiding the related provider settings UI`,
+    );
+    return <></>;
+  }
+  return (
+    <ProviderSettingsItem
+      title={title}
+      description={description}
+      apiRef={apiRef as ApiRef<ProfileInfoApi & SessionApi>}
+      icon={Star}
+    />
+  );
+};
+
+const DynamicProviderSettings = ({
+  providerSettings,
+}: {
+  providerSettings: ProviderSetting[];
+}) => {
+  const configApi = useApi(configApiRef);
+  const providersConfig = configApi.getOptionalConfig('auth.providers');
+  const configuredProviders = providersConfig?.keys() || [];
+  return (
+    <>
+      <DefaultProviderSettings configuredProviders={configuredProviders} />
+      {providerSettings.map(({ title, description, provider }) => (
+        <ErrorBoundary>
+          <DynamicProviderSettingsItem
+            title={title}
+            description={description}
+            provider={provider}
+          />
+        </ErrorBoundary>
+      ))}
+    </>
+  );
+};
 
-export const settingsPage = (
+export const settingsPage = (providerSettings: ProviderSetting[]) => (
   <SettingsLayout>
     <SettingsLayout.Route path="general" title="General">
       {generalPage}
@@ -14,7 +86,11 @@ export const settingsPage = (
       path="auth-providers"
       title="Authentication Providers"
     >
-      <UserSettingsAuthProviders />
+      <UserSettingsAuthProviders
+        providerSettings={
+          <DynamicProviderSettings providerSettings={providerSettings} />
+        }
+      />
     </SettingsLayout.Route>
   </SettingsLayout>
 );
diff --git a/packages/app/src/utils/dynamicUI/extractDynamicConfig.test.ts b/packages/app/src/utils/dynamicUI/extractDynamicConfig.test.ts
@@ -154,14 +154,29 @@ describe('extractDynamicConfig', () => {
       menuItems: [],
       mountPoints: [],
       appIcons: [],
+      providerSettings: [],
       routeBindingTargets: [],
       apiFactories: [],
       scaffolderFieldExtensions: [],
+      signInPages: [],
       themes: [],
     });
   });
 
   it.each([
+    [
+      'a SignInPage',
+      { signInPage: { importName: 'blah' } },
+      {
+        signInPages: [
+          {
+            importName: 'blah',
+            module: 'PluginRoot',
+            scope: 'janus-idp.plugin-foo',
+          },
+        ],
+      },
+    ],
     [
       'a dynamicRoute',
       { dynamicRoutes: [{ path: '/foo' }] },
@@ -495,6 +510,58 @@ describe('extractDynamicConfig', () => {
         ],
       },
     ],
+    [
+      'a providerSettings',
+      {
+        providerSettings: [
+          {
+            title: 'foo',
+            description: 'bar',
+            provider: 'foo.bar',
+          },
+        ],
+      },
+      {
+        providerSettings: [
+          {
+            title: 'foo',
+            description: 'bar',
+            provider: 'foo.bar',
+          },
+        ],
+      },
+    ],
+    [
+      'multiple providerSettings',
+      {
+        providerSettings: [
+          {
+            title: 'foo1',
+            description: 'bar1',
+            provider: 'foo.bar1',
+          },
+          {
+            title: 'foo2',
+            description: 'bar2',
+            provider: 'foo.bar2',
+          },
+        ],
+      },
+      {
+        providerSettings: [
+          {
+            title: 'foo1',
+            description: 'bar1',
+            provider: 'foo.bar1',
+          },
+          {
+            title: 'foo2',
+            description: 'bar2',
+            provider: 'foo.bar2',
+          },
+        ],
+      },
+    ],
   ])('parses %s', (_, source: any, output) => {
     const config = extractDynamicConfig({
       frontend: { 'janus-idp.plugin-foo': source },
@@ -515,7 +582,9 @@ describe('extractDynamicConfig', () => {
       appIcons: [],
       apiFactories: [],
       scaffolderFieldExtensions: [],
+      signInPages: [],
       themes: [],
+      providerSettings: [],
       ...output,
     });
   });
diff --git a/packages/app/src/utils/dynamicUI/extractDynamicConfig.ts b/packages/app/src/utils/dynamicUI/extractDynamicConfig.ts
diff --git a/packages/app/src/utils/test/TestRoot.tsx b/packages/app/src/utils/test/TestRoot.tsx
diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts
