diff --git a/artifacts/attributes.adoc b/artifacts/attributes.adoc index db23e741df..e5dedc13f5 100644 --- a/artifacts/attributes.adoc +++ b/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 diff --git a/assemblies/assembly-enabling-authentication.adoc b/assemblies/assembly-enabling-authentication.adoc index d9100a0bde..e96a6e9ecd 100644 --- a/assemblies/assembly-enabling-authentication.adoc +++ b/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] diff --git a/modules/authentication/proc-enabling-authentication-with-your-custom-authentication-provider.adoc b/modules/authentication/proc-enabling-authentication-with-your-custom-authentication-provider.adoc new file mode 100644 index 0000000000..4b30220783 --- /dev/null +++ b/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: + __: + providerSettings: + - title: __ + description: __ + 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: + __: + 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 *__* and the Guest user sign-in is disabled. +. Log in with your custom authentication provider. +