RHIDP-5489 Enabling authentication with your authentication provider

artifacts/attributes.adoc

@@ -109,8 +109,8 @@
 :release-notes-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/release_notes/index
 :release-notes-title: Release notes
 
-:installing-and-viewing-dynamic-plugins-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_and_viewing_dynamic_plugins/index
-:installing-and-viewing-dynamic-plugins-title: Installing and viewing dynamic plugins
+:installing-and-viewing-dynamic-plugins-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/installing_and_viewing_plugins/index
+:installing-and-viewing-dynamic-plugins-title: Installing and viewing plugins
 
 :authentication-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/authentication/index
 :authentication-book-title: Authentication

assemblies/assembly-enabling-authentication.adoc

@@ -61,3 +61,5 @@ include::assembly-authenticating-with-github.adoc[leveloffset=+1]
 
 include::assembly-authenticating-with-microsoft-azure.adoc[leveloffset=+1]
 
+
+include::modules/authentication/proc-enabling-authentication-with-your-custom-authentication-provider.adoc[leveloffset=+1]

modules/authentication/proc-enabling-authentication-with-your-custom-authentication-provider.adoc

@@ -0,0 +1,74 @@
+[id="enabling-authentication-with-your-custom-authentication-provider"]
+= Enabling authentication with your custom authentication provider
+
+By default, {product} supports all the documented authentication providers, such as GitHub or Microsoft Azure.
+However, you can extend {product-short} with your custom authentication provider by using dynamic plugins that either adds more configuration options for an existing provider, or adds a new authentication provider altogether.
+
+.Prerequisites
+* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have enough permissions to change it.
+* link:{installing-and-viewing-dynamic-plugins-url}#assembly-third-party-plugins[Exporting, packaging, and installing third-party plugins] knowledge.
+* You collected the relevant information to connect to your custom authentication provider.
+
+.Procedure
+. Create your custom authentication provider backend plugin, which:
+* Provides an authentication provider API.
+* Bridges authentication to your custom authentication provider.
+* Includes an example backend configuration in an `app-config.yaml`file.
+
+. Create your custom authentication provider front-end plugin, which:
+* Provides a custom `SignInPage` component.
+The `SignInPage` component is the place in a {product-short} app where the front-end API reference connects to the appropriate backend authentication provider API service.
+* Provides an API client for the backend authentication provider service.
+* Includes an example backend configuration in an `app-config.yaml`file.
+
+. link:{installing-and-viewing-dynamic-plugins-url}#assembly-third-party-plugins[Export, package, and install your custom plugins].
+. Add your custom plugins configuration to your `dynamic-plugins.yaml` file.
+
+. {product-short} users expect to see all authentication providers listed in the *User settings* section, *Authentication Providers* tab.
+To add entries for an authentication provider from a dynamic plugin, use the `providerSettings` configuration in your `{my-app-config-file}` file:
++
+[source,yaml,subs="+quotes"]
+----
+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 next to the user profile image if available.
+
+`description`:: The short description of the authentication provider, which {product-short} displays on the login page.
+
+`provider`:: The authentication provider ID as provided to the `createApiRef` API call, which is using this value to look up the corresponding API factory for the authentication provider to connect to the provider's Sign In and Sign Out button.
+
+. Use a custom `SignInPage` component.
+{product-short} is using the `SignInPage` component to connect one or more authentication providers to the application sign-in process.
+By default, {product-short} has a static `SignInPage` that supports all the built-in authentication providers.
+To use a different authentication provider, for example from a dynamic plugin use the `signInPage` configuration in your `{my-app-config-file}` file:
++
+[source,yaml,subs="+quotes"]
+----
+dynamicPlugins:
+  frontend:
+    _<package_name>_:
+      signInPage:
+        importName: CustomSignInPage
+----
++
+Only one `signInPage` is specified and used by the application, this configuration object supports the following properties:
+
+`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.
+
+`module`:: Optional setting to specify which set of assets the dynamic plugin might access.
+The default value is `PluginRoot`.
+
+.Verification
+. Go to the {product-short} login page.
+. Your {product-short} sign-in page displays *_<Sign in using My Custom Auth Provider>_* and the Guest user sign-in is disabled.
+. Log in with your custom authentication provider.
+