Skip to content

Commit c07d777

Browse files
themr0cthemr0c
committed
RHIDP-7834-RHIDP-7634-RHIDP-598 Refactor authenticating with RHBK
Signed-off-by: Fabrice Flore-Thébault <[email protected]>
1 parent 5da9619 commit c07d777

5 files changed

+185
-180
lines changed

‎assemblies/assembly-authenticating-with-rhbk.adoc‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,7 @@
33

44
To authenticate users with {rhbk-brand-name} ({rhbk}):
55

6-
. xref:enabling-authentication-with-rhbk[Enable the OpenID Connect (OIDC) authentication provider in RHDH].
7-
. xref:provisioning-users-from-rhbk-to-the-software-catalog[Provision users from {rhbk-brand-name} ({rhbk}) to the software catalog].
6+
include::modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc[leveloffset=+1]
87

9-
include::modules/authentication/proc-enabling-authentication-with-rhbk.adoc[leveloffset=+1]
10-
11-
include::modules/authentication/proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc[leveloffset=+1]
128

139
include::modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc[leveloffset=+1]

‎modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
To customize how {rhbk} users and groups are mapped to {product} entities, you can create a backend module that uses the `keycloakTransformerExtensionPoint` to provide custom user and group transformers for the Keycloak backend.
55

66
.Prerequisites
7-
* You have xref:provisioning-users-from-rhbk-to-the-software-catalog[enabled provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog].
7+
* You have xref:enabling-user-authentication-with-rhbk[enabled provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog].
88

99
.Procedure
1010
. Create a new backend module with the `yarn new` command.

‎modules/authentication/proc-enabling-user-authentication-with-github.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ Enter your GitHub organization name, such as `__<your_github_organization_name>_
6161
This plugin ingests GitHub users and groups to the {product-short} software catalog.
6262
+
6363
.`dynamic-plugins.yaml` file fragment
64-
[code,yaml]
64+
[source,yaml]
6565
----
6666
plugins:
6767
- package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'

modules/authentication/proc-enabling-authentication-with-rhbk.adoc renamed to modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc

Lines changed: 182 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
[id="enabling-authentication-with-rhbk"]
2-
= Enabling authentication with {rhbk-brand-name} ({rhbk})
3-
4-
To authenticate users with {rhbk-brand-name} ({rhbk}), enable the OpenID Connect (OIDC) authentication provider in {product}.
1+
[id="enabling-user-authentication-with-rhbk"]
2+
= Enabling user authentication with {rhbk-brand-name} ({rhbk})
53

4+
To authenticate users with {rhbk-brand-name} ({rhbk}), enable and configure the OpenID Connect (OIDC) authentication provider in {product} and provision the users and groups from {rhbk} to the {product-short} software catalog.
65

76
.Prerequisites
87
* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
98
* You have sufficient permissions in {rhsso} to create and manage a realm.
9+
Alternatively, you can ask your {rhbk} administrator to prepare the required {rhbk} App.
1010

1111
.Procedure
1212
. To allow {product-short} to authenticate with {rhbk}, complete the steps in {rhbk}, to link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[create a realm and a user] and link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-secure-the-first-application[secure the first application]:
@@ -25,11 +25,158 @@ Save the value for the next step:
2525

2626
.. To prepare for the verification steps, in the same realm, get the credential information for an existing user or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html-single/getting_started_guide/index#getting-started-zip-create-a-user[create a user]. Save the user credential information for the verification steps.
2727

28-
. To add your {rhsso} credentials to your {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]:
28+
. To add your {rhsso} credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets].
29+
You can use these secrets in the {product-short} configuration files by using their respective environment variable name.
30+
+
31+
`AUTH_OIDC_CLIENT_ID`::
32+
Enter the saved **Client ID**.
33+
34+
`AUTH_OIDC_CLIENT_SECRET`::
35+
Enter the saved **Client Secret**.
36+
37+
`AUTH_OIDC_METADATA_URL`::
38+
Enter the saved **{rhbk} realm base URL**.
39+
40+
. Enable the Keycloak organization plugin (`backstage-plugin-catalog-backend-module-keycloak-dynamic`).
41+
The plugin is named after {rhbk} upstream project.
42+
This plugin ingests {rhbk} users and groups to the {product-short} software catalog.
43+
+
44+
.`dynamic-plugins.yaml` file fragment
45+
[source,yaml]
46+
----
47+
plugins:
48+
- package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-keycloak-dynamic'
49+
disabled: false
50+
----
51+
52+
. To provision {rhbk} users and groups to the {product-short} software catalog, add the `catalog.providers.keycloakOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
53+
+
54+
--
55+
[id=keycloakOrgProviderId]
56+
.`{my-app-config-file}` fragment with mandatory `keycloakOrg` fields
57+
[source,yaml]
58+
----
59+
catalog:
60+
providers:
61+
keycloakOrg:
62+
default:
63+
baseUrl: ${AUTH_OIDC_METADATA_URL}
64+
clientId: ${AUTH_OIDC_CLIENT_ID}
65+
clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
66+
----
67+
68+
`baseUrl`::
69+
Your {rhbk} server URL, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}].
70+
71+
`clientId`::
72+
Your {product-short} application client ID in {rhbk}, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}].
73+
74+
`clientSecret`::
75+
Your {product-short} application client secret in {rhbk}, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}].
76+
77+
Optional: Consider adding the following optional fields:
78+
79+
`realm`::
80+
Realm to synchronize.
81+
Default value: `master`.
82+
+
83+
.`{my-app-config-file}` fragment with optional `realm` field
84+
[source,yaml]
85+
----
86+
catalog:
87+
providers:
88+
keycloakOrg:
89+
default:
90+
realm: master
91+
----
92+
93+
`loginRealm`::
94+
Realm used to authenticate.
95+
Default value: `master`.
2996
+
30-
`AUTH_OIDC_CLIENT_ID`:: Enter the saved **Client ID**.
31-
`AUTH_OIDC_CLIENT_SECRET`:: Enter the saved **Client Secret**.
32-
`AUTH_OIDC_METADATA_URL`:: Enter the saved **{rhbk} realm base URL**.
97+
.`{my-app-config-file}` fragment with optional `loginRealm` field
98+
[source,yaml]
99+
----
100+
catalog:
101+
providers:
102+
keycloakOrg:
103+
default:
104+
loginRealm: master
105+
----
106+
107+
`userQuerySize`::
108+
User number to query simultaneously.
109+
Default value: `100`.
110+
+
111+
.`{my-app-config-file}` fragment with optional `userQuerySize` field
112+
[source,yaml]
113+
----
114+
catalog:
115+
providers:
116+
keycloakOrg:
117+
default:
118+
userQuerySize: 100
119+
----
120+
121+
`groupQuerySize`::
122+
Group number to query simultaneously.
123+
Default value: `100`.
124+
+
125+
.`{my-app-config-file}` fragment with optional `groupQuerySize` field
126+
[source,yaml]
127+
----
128+
catalog:
129+
providers:
130+
keycloakOrg:
131+
default:
132+
groupQuerySize: 100
133+
----
134+
135+
`schedule.frequency`::
136+
To specify custom schedule frequency.
137+
Supports cron, ISO duration, and "human duration" as used in code.
138+
+
139+
.`{my-app-config-file}` fragment with optional `schedule.frequency` field
140+
[source,yaml]
141+
----
142+
catalog:
143+
providers:
144+
keycloakOrg:
145+
default:
146+
schedule:
147+
frequency: { hours: 1 }
148+
----
149+
150+
`schedule.timeout`::
151+
To specify custom timeout.
152+
Supports ISO duration and "human duration" as used in code.
153+
+
154+
.`{my-app-config-file}` fragment with optional `schedule.timeout` field
155+
[source,yaml]
156+
----
157+
catalog:
158+
providers:
159+
keycloakOrg:
160+
default:
161+
schedule:
162+
timeout: { minutes: 50 }
163+
----
164+
165+
`schedule.initialDelay`::
166+
To specify custom initial delay.
167+
Supports ISO duration and "human duration" as used in code.
168+
+
169+
.`{my-app-config-file}` fragment with optional `schedule.initialDelay` field
170+
[source,yaml]
171+
----
172+
catalog:
173+
providers:
174+
keycloakOrg:
175+
default:
176+
schedule:
177+
initialDelay: { seconds: 15}
178+
----
179+
--
33180

34181
. To set up the {rhbk} authentication provider in your {product-short} custom configuration, edit your custom {product-short} ConfigMap such as `app-config-rhdh`, and add the following lines to the `{my-app-config-file}` content:
35182

@@ -132,10 +279,19 @@ WARNING: In production mode, only configure one resolver to ensure users are sec
132279
`resolver`::::
133280
Enter the sign-in resolver name.
134281
Available values:
135-
* `oidcSubClaimMatchingKeycloakUserId`
136-
* `emailLocalPartMatchingUserEntityName`
137-
* `emailMatchingUserEntityProfileEmail`
138-
* `preferredUsernameMatchingUserEntityName`
282+
283+
`oidcSubClaimMatchingKeycloakUserId`:::::
284+
Matches the user with the immutable `sub` parameter from OIDC to the {RHBK} user ID.
285+
Consider using this resolver for enhanced security.
286+
287+
`emailLocalPartMatchingUserEntityName`:::::
288+
Matches the email local part with the user entity name.
289+
290+
`emailMatchingUserEntityProfileEmail`:::::
291+
Matches the email with the user entity profile email.
292+
293+
`preferredUsernameMatchingUserEntityName`:::::
294+
Matches the preferred username with the user entity name.
139295
+
140296
.`{my-app-config-file}` fragment with optional `resolvers` list
141297
[source,yaml]
@@ -212,6 +368,17 @@ If multiple valid refresh tokens are issued due to frequent refresh token reques
212368
====
213369

214370
.Verification
215-
. Go to the {product-short} login page.
216-
. Your {product-short} sign-in page displays *Sign in using OIDC* and the Guest user sign-in is disabled.
217-
. Log in with OIDC by using the saved **Username** and **Password** values.
371+
372+
. To verify user and group provisioning, check the console logs.
373+
+
374+
.Successful synchronization example:
375+
[source,json]
376+
----
377+
{"class":"KeycloakOrgEntityProvider","level":"info","message":"Read 3 Keycloak users and 2 Keycloak groups in 1.5 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"}
378+
{"class":"KeycloakOrgEntityProvider","level":"info","message":"Committed 3 Keycloak users and 2 Keycloak groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"}
379+
----
380+
381+
. To verify {rhbk} user authentication:
382+
.. Go to the {product-short} login page.
383+
.. Your {product-short} sign-in page displays *Sign in using OIDC* and the Guest user sign-in is disabled.
384+
.. Log in with OIDC by using the saved **Username** and **Password** values.

0 commit comments

Comments
 (0)