chore(docs): document auth via dynamic plugins (#2446)

This change adds the configuration updates and examples related to
installing and configuring authentication providers from dynamic
plugins.  This change also fixes a couple small markdown lint warnings.

Signed-off-by: Stan Lewis <[email protected]>
Co-authored-by: Tomas Kral <[email protected]>

Author: gashcrumb

docs/auth.md

@@ -123,7 +123,8 @@ In an example using Keycloak for authentication with the OIDC provider, there ar
 The default resolver provided by the `oidc` auth provider is the `emailLocalPartMatchingUserEntityName` resolver.
 
 If you want to use a different resolver, add the resolver you want to use in the `auth.providers.oidc.[environment].signIn.resolvers` configuration as soon in the example above, and it will override the default resolver.
-* For enhanced security, consider using the `oidcSubClaimMatchingKeycloakUserId` resolver which matches the user with the immutable `sub` parameter from OIDC to the Keycloak user ID.
+
+- For enhanced security, consider using the `oidcSubClaimMatchingKeycloakUserId` resolver which matches the user with the immutable `sub` parameter from OIDC to the Keycloak user ID.
 
 For more information on setting up the OIDC auth provider, consult the [Backstage documentation](https://backstage.io/docs/auth/oidc#the-configuration).
 
@@ -201,11 +202,11 @@ auth:
 
 ### includeTransitiveGroupOwnership configuration value
 
-This option allows users to add transitive parent groups into the resolved user group membership during the authentication process. i.e., the parent group of the user's direct group will be included in the user ownership entities. By default, this option is set to false. 
+This option allows users to add transitive parent groups into the resolved user group membership during the authentication process. i.e., the parent group of the user's direct group will be included in the user ownership entities. By default, this option is set to false.
 
 For instance, with this group hierarchy:
 
-```
+```text
 group_admin  
   └── group_developers  
         └── user_alice  
@@ -221,4 +222,12 @@ includeTransitiveGroupOwnership: true
 auth:
   providers:
     # provider configs ...
-```
+```
+
+## External authentication providers
+
+External authentication providers can be loaded using the dynamic plugins mechanism.  Typically this will require a backend plugin to provide the authentication provider API implementation and callback handling, and a frontend plugin to connect this API to important parts of the UI in the form of a [custom SignInPage](dynamic-plugins/frontend-plugin-wiring.md#use-a-custom-signinpage-component) and [provider settings](dynamic-plugins/frontend-plugin-wiring.md#adding-custom-authentication-provider-settings) entries for the user settings page.  
+
+The existing Developer Hub authentication module will need to be disabled by setting an [environment variable](dynamic-plugins/override-core-services.md#overriding-the-provided-authentication-module), `ENABLE_AUTH_PROVIDER_MODULE_OVERRIDE` to `true` for the Developer Hub backend.
+
+Some examples of composing dynamic plugins to provide an authentication solution are available in the [dynamic plugins examples](dynamic-plugins/examples.md).

docs/dynamic-plugins/examples.md

@@ -5,7 +5,12 @@ There are several example dynamic plugin projects that have been created to demo
 > [!WARNING]
 > The following examples are maintained on a best-effort basis, some adjustments may be needed to get an example running, especially against a different target RHDH version.
 
-## For RHDH 1.4 (pre-release)
+## For RHDH 1.5 (pre-release)
+
+- [Using an third-party Authentication Provider via dynamic plugins](https://github.com/gashcrumb/dynamic-plugins-custom-authentication-module)
+- [Composing various authentication providers via dynamic plugins](https://github.com/gashcrumb/dynamic-plugins-multiple-auth-modules)
+
+## For RHDH 1.4
 
 - [Installing a custom middleware function using a dynamic plugin](https://github.com/gashcrumb/dynamic-plugins-root-http-middleware)
 

docs/dynamic-plugins/frontend-plugin-wiring.md

@@ -434,7 +434,6 @@ dynamicPlugins:
 
 Users can configure multiple application providers by adding entries to the `mountPoints` field.
 
-
 ## Customizing and Adding Entity tabs
 
 Out of the box the frontend system provides an opinionated set of tabs for catalog entity views. This set of tabs can be further customized and extended as needed via the `entityTabs` configuration:
@@ -551,6 +550,43 @@ dynamicPlugins:
 
 which would override the default `ScmAuth` API factory that Developer Hub defaults to.
 
+## Adding custom authentication provider settings
+
+Out of the box the Backstage user settings page supports all of the documented authentication providers, such as "github" or "microsoft".  However it is possible to install new authentication providers from a dynamic plugin that either adds additional configuration support for an existing provider or adds a new authentication provider altogether.  In either case, these providers are normally listed in the user settings section of the app under the "Authentication Providers" tab.  To add entries for an authentication provider from a dynamic plugin, use the `providerSettings` configuration:
+
+```yaml
+dynamicPlugins:
+  frontend:
+    <package_name>:
+      providerSettings:
+        - title: My Custom Auth Provider
+          description: Sign in using My Custom Auth Provider
+          provider: core.auth.my-custom-auth-provider
+```
+
+Each provider settings entry should define the following attributes:
+
+- `title`: The title for the authentication provider shown above the user's profile image if available.
+- `description`: a short description of the authentication provider.
+- `provider`: The ID of the authentication provider as provided to the `createApiRef` API call.  This value is used to look up the corresponding API factory for the authentication provider to connect the provider's Sign In/Sign Out button.
+
+## Use a custom SignInPage component
+
+In a Backstage app the SignInPage component is used to connect one or more authentication providers to the application sign-in process.  Out of the box in Developer Hub a static SignInPage is already set up and supports all of the built-in authentication providers already.  To use a different authentication provider, for example from a dynamic plugin use the `signInPage` configuration:
+
+```yaml
+dynamicPlugins:
+  frontend:
+    <package_name>:
+      signInPage:
+        importName: CustomSignInPage
+```
+
+Only one `signInPage` is specified and used by the application, this configuration object supports the following properties:
+
+- `module`: optional setting to specify which set of assets should be accessed from the dynamic plugin, defaults to `PluginRoot`
+- `importName`: Required setting that should resolve to a component that returns a configured `SignInPage` component that connects the appropriate authentication provider factories, or a compatible custom implementation.
+
 ## Provide custom Scaffolder field extensions
 
 The Backstage scaffolder component supports specifying [custom form fields](https://backstage.io/docs/features/software-templates/writing-custom-field-extensions/#creating-a-field-extension) for the software template wizard, for example:

docs/dynamic-plugins/override-core-services.md

@@ -56,3 +56,9 @@ To allow a dynamic plugin to load a core service override, start the Developer H
 - `ENABLE_CORE_USERINFO_OVERRIDE` - allow overriding the `core.userInfo` service
 - `ENABLE_CORE_URLREADER_OVERRIDE` - allow overriding the `core.urlReader` service
 - `ENABLE_EVENTS_SERVICE_OVERRIDE` - allow overriding the `events.service` service
+
+## Overriding the provided authentication module
+
+Developer Hub ships with an opinionated authentication module setup that supports many use-cases.  However it is also possible to disable this authentication module entirely and compose an authentication solution from a set of dynamic frontend and backend plugins.  This requires disabling the provided authentication module so it doesn't conflict with any custom authentication configuration.
+
+- `ENABLE_AUTH_PROVIDER_MODULE_OVERRIDE` - set to "true" to disable the Developer Hub provided backend authentication module