Skip to content

Commit ad2a49f

Browse files
themr0cthemr0c
committed
RHIDP-5489 Enabling authentication with your custom authentication provider
Signed-off-by: Fabrice Flore-Thébault <[email protected]>
1 parent 7b35cc2 commit ad2a49f

File tree

3 files changed

+235
-2
lines changed

3 files changed

+235
-2
lines changed

Diff for: ‎artifacts/attributes.adoc

+2-2
Original file line numberDiff line numberDiff line change
@@ -109,8 +109,8 @@
109109
:release-notes-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/release_notes/index
110110
:release-notes-title: Release notes
111111

112-
: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
113-
:installing-and-viewing-dynamic-plugins-title: Installing and viewing dynamic plugins
112+
: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
113+
:installing-and-viewing-dynamic-plugins-title: Installing and viewing plugins
114114

115115
:authentication-book-url: https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/{product-version}/html-single/authentication/index
116116
:authentication-book-title: Authentication

Diff for: ‎assemblies/assembly-enabling-authentication.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -61,3 +61,5 @@ include::assembly-authenticating-with-github.adoc[leveloffset=+1]
6161

6262
include::assembly-authenticating-with-microsoft-azure.adoc[leveloffset=+1]
6363

64+
65+
include::modules/authentication/proc-enabling-authentication-with-your-custom-authentication-provider.adoc[leveloffset=+1]

Diff for: ‎modules/authentication/proc-enabling-authentication-with-your-custom-authentication-provider.adoc

+231
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
[id="enabling-authentication-with-your-custom-authentication-provider"]
2+
= Enabling authentication with your custom authentication provider
3+
4+
To authenticate users with your custom authentication provider, create, install and configure your custom authentication backend and frontend plugins in {product}.
5+
6+
.Prerequisites
7+
* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
8+
* link:{installing-and-viewing-dynamic-plugins-url}#assembly-third-party-plugins[Exporting, packaging, and installing third-party plugins] knowledge.
9+
* You collected the relevant information to connect to your custom authentication provider.
10+
+
11+
[WARNING]
12+
====
13+
This procedure is using a custom LDAP authentication provider as an example.
14+
This example is not intended for production use.
15+
====
16+
17+
.Procedure
18+
19+
. Add the identified key/value pairs to link:{plugins-configure-book-url}#provisioning-your-custom-configuration[your {product-short} secrets].
20+
.. To allow {product-short} to use plugins for authentication rather than the builtin authentication providers, set the `ENABLE_AUTH_PROVIDER_MODULE_OVERRIDE` environment variable to true.
21+
`ENABLE_AUTH_PROVIDER_MODULE_OVERRIDE`:: `true`
22+
.. To add your custom authentication provider credentials to {product-short}, add the identified key/value pairs.
23+
+
24+
.Secrets for the LDAP example
25+
====
26+
LDAP_URL:: Your LDAP server URL, such as `ldap://_<my_host>_:3893`.
27+
LDAP_BIND_DN:: Your LDAP bind distinguished name, such as `cn=serviceuser,ou=svcaccts,dc=glauth,dc=com`.
28+
LDAP_BIND_PASSWORD:: Your LDAP password, such as `mysecret`.
29+
====
30+
31+
. Create your custom authentication provider backend plugin, that:
32+
* Provides an authentication provider API.
33+
* Bridges authentication to your custom authentication provider.
34+
* Includes an example backend configuration in an `app-config.yaml`file.
35+
+
36+
--
37+
.LDAP backend plugin
38+
====
39+
.`src/index.ts` wrapper re-exporting the original plugin
40+
[source,javascript]
41+
----
42+
export { default as default } from "@immobiliarelabs/backstage-plugin-ldap-auth-backend";
43+
----
44+
45+
.`app-config.yaml` backend configuration
46+
[source,yaml]
47+
----
48+
auth:
49+
environment: production
50+
providers:
51+
ldap:
52+
production:
53+
ldapAuthenticationOptions:
54+
userSearchBase: ou=users,dc=glauth,dc=com
55+
usernameAttribute: uid
56+
adminDn: ${LDAP_BIND_DN}
57+
adminPassword: ${LDAP_BIND_PASSWORD}
58+
ldapOpts:
59+
url:
60+
- ${LDAP_URL}
61+
----
62+
====
63+
--
64+
65+
. Create your custom authentication provider frontend plugin, that:
66+
* Provides a custom `SignInPage` component.
67+
The `SignInPage` component is the place in a {product-short} app where the frontend API reference is connected to the appropriate backend authentication provider API service.
68+
* Provides an API client for the backend authentication provider service.
69+
* Includes an example backend configuration in an `app-config.yaml`file.
70+
+
71+
--
72+
.LDAP frontend plugin
73+
====
74+
The exported `SignInPage` component delegates to the `LDAPSignInPage` component that is provided by the `backstage-plugin-ldap-auth` package.
75+
76+
.`src/index.ts` wrapper re-exporting the original plugin
77+
[source,javascript]
78+
----
79+
export * from '@immobiliarelabs/backstage-plugin-ldap-auth';
80+
export { SignInPage } from './components/SignInPage/SignInPage';
81+
----
82+
83+
.`src/components/SignInPage.ts` `SignInPage` component
84+
[source,javascript]
85+
----
86+
import React from 'react';
87+
import { SignInPageProps } from '@backstage/core-plugin-api';
88+
import { LdapAuthFrontendPage } from '@immobiliarelabs/backstage-plugin-ldap-auth';
89+
90+
export function SignInPage(props: SignInPageProps): React.JSX.Element {
91+
return <LdapAuthFrontendPage {...props} provider="ldap" />;
92+
}
93+
----
94+
95+
.`app-config.yaml` frontend configuration
96+
[source,yaml]
97+
----
98+
dynamicPlugins:
99+
frontend:
100+
immobiliarelabs-backstage-plugin-ldap-auth:
101+
components:
102+
- name: SignInPage
103+
module: PluginRoot
104+
importName: SignInPage
105+
----
106+
====
107+
--
108+
109+
. link:{installing-and-viewing-dynamic-plugins-url}#assembly-third-party-plugins[Export, package, and install your custom plugins].
110+
. Add your custom plugins configuration to `dynamic-plugins.yaml` in {product-short}.
111+
+
112+
.`dynamic-plugins.yaml` excerpt for LDAP catalog support
113+
====
114+
----
115+
plugins:
116+
- package: ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-ldap-dynamic
117+
disabled: false
118+
pluginConfig:
119+
catalog:
120+
providers:
121+
ldapOrg:
122+
default:
123+
target: ${LDAP_URL}
124+
bind:
125+
dn: ${LDAP_BIND_DN}
126+
secret: ${LDAP_BIND_PASSWORD}
127+
users:
128+
- dn: ou=users,dc=glauth,dc=com
129+
options:
130+
scope: sub
131+
filter: (accountStatus=active)
132+
attributes: ['*', '+']
133+
paged: false
134+
map:
135+
rdn: uid
136+
name: uid
137+
description: description
138+
displayName: uid
139+
email: mail
140+
picture: <nothing, left out>
141+
memberOf: memberOf
142+
groups:
143+
- dn: ou=groups,dc=glauth,dc=com
144+
options:
145+
scope: sub
146+
filter: (gidNumber=*)
147+
attributes: ['*', '+']
148+
paged: false
149+
map:
150+
rdn: uid
151+
name: uid
152+
uid: uid
153+
displayName: uid
154+
description: description
155+
type: groupType
156+
email: <nothing, left out>
157+
picture: <nothing, left out>
158+
memberOf: memberOf
159+
members: member
160+
schedule:
161+
frequency: PT10M
162+
timeout: PT10M
163+
# optional, this is just to suppress any examples
164+
import: {}
165+
rules:
166+
- allow: [Component, System, Group, Resource, Location, Template, API, User]
167+
locations: []
168+
- package: ./local-plugins/immobiliarelabs-backstage-plugin-ldap-auth
169+
disabled: false
170+
pluginConfig:
171+
dynamicPlugins:
172+
frontend:
173+
immobiliarelabs-backstage-plugin-ldap-auth:
174+
components:
175+
- name: SignInPage
176+
module: PluginRoot
177+
importName: SignInPage
178+
----
179+
====
180+
181+
182+
. To set up your custom authentication provider, edit your custom {product-short} ConfigMap such as `app-config-rhdh`, and add the following lines to the `app-config-rhdh.yaml` content:
183+
+
184+
--
185+
.`app-config-rhdh.yaml` fragment with mandatory fields to enable authentication with
186+
[source,yaml,subs="+attributes,+quotes"]
187+
----
188+
auth:
189+
environment: production
190+
providers:
191+
_<your_custom_provider_id>_:
192+
production:
193+
_<your_custom_provider_configuration>_
194+
signInPage: _<your_custom_provider_id>_
195+
----
196+
197+
.`app-config.yaml` excerpt for the LDAP example
198+
====
199+
----
200+
auth:
201+
environment: production
202+
providers:
203+
ldap:
204+
production:
205+
ldapAuthenticationOptions:
206+
userSearchBase: ou=users,dc=glauth,dc=com
207+
usernameAttribute: uid
208+
adminDn: ${LDAP_BIND_DN}
209+
adminPassword: ${LDAP_BIND_PASSWORD}
210+
ldapOpts:
211+
url:
212+
- ${LDAP_URL}
213+
signInPage: ldap
214+
----
215+
====
216+
217+
`environment: production`::
218+
Mark the environment as `production` to hide the Guest login in the {product-short} home page.
219+
220+
`_<your_custom_provider_id>_` section::
221+
Use the {product-short} application information that you have created in your custom authentication provider and configured in OpenShift as secrets.
222+
223+
`sigInPage: _<your_custom_provider_id>_`::
224+
To enable the custom authentication provider as default sign-in provider.
225+
--
226+
227+
.Verification
228+
. Go to the {product-short} login page.
229+
. Your {product-short} sign-in page displays *Sign in using _<your_custom_authentication_provider_name>_* and the Guest user sign-in is disabled.
230+
. Log in with your custom authentication provider.
231+

0 commit comments

Comments
 (0)