Skip to content

Commit cbda9e6

Browse files
themr0cGerry-Forde
themr0c
and
Gerry-Forde
authored
RHIDP-7834-RHIDP-7634-RHIDP-598 Refactor authenticating with RHBK (#1231)
Co-authored-by: Gerry-Forde <[email protected]>
1 parent a08d49f commit cbda9e6

5 files changed

+188
-201
lines changed

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

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,8 @@
11
[id="assembly-authenticating-with-rhbk"]
22
= Authenticating with {rhbk-brand-name} ({rhbk})
33

4-
To authenticate users with {rhbk-brand-name} ({rhbk}):
54

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].
5+
include::modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc[leveloffset=+1]
86

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]
127

138
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: 185 additions & 35 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.
9-
* You have sufficient permissions in {rhsso} to create and manage a realm.
8+
* You have sufficient permissions in {rhsso} to create and manage a realm and a client.
9+
Alternatively, your {rhbk} administrator can prepare in {rhbk} the required realm and client for you.
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,15 +25,143 @@ 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+
`AUTHENTICATION_OIDC_CLIENT_ID`::
32+
Enter the saved **Client ID**.
33+
34+
`AUTHENTICATION_OIDC_CLIENT_SECRET`::
35+
Enter the saved **Client Secret**.
36+
37+
`AUTHENTICATION_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+
.. Add mandatory fields:
2955
+
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**.
56+
[id=keycloakOrgProviderId]
57+
.`{my-app-config-file}` fragment with mandatory `keycloakOrg` fields
58+
[source,yaml]
59+
----
60+
catalog:
61+
providers:
62+
keycloakOrg:
63+
default:
64+
baseUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
65+
clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
66+
clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET}
67+
realm: master
68+
loginRealm: master
69+
----
70+
71+
`baseUrl`::
72+
Enter your {rhbk} server URL, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}].
73+
74+
`clientId`::
75+
Enter your {product-short} application client ID in {rhbk}, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}].
76+
77+
`clientSecret`::
78+
Enter your {product-short} application client secret in {rhbk}, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}].
79+
80+
`realm`::
81+
Enter the realm name to provision users, such as `master`.
82+
83+
`loginRealm`::
84+
Enter the realm name to authenticate users, such as `master`.
85+
86+
.. Optional: Consider adding optional fields:
87+
88+
`userQuerySize`::
89+
Enter the user count to query simultaneously.
90+
Default value: `100`.
91+
+
92+
.`{my-app-config-file}` fragment with optional `userQuerySize` field
93+
[source,yaml]
94+
----
95+
catalog:
96+
providers:
97+
keycloakOrg:
98+
default:
99+
userQuerySize: 100
100+
----
101+
102+
`groupQuerySize`::
103+
Enter the group count to query simultaneously.
104+
Default value: `100`.
105+
+
106+
.`{my-app-config-file}` fragment with optional `groupQuerySize` field
107+
[source,yaml]
108+
----
109+
catalog:
110+
providers:
111+
keycloakOrg:
112+
default:
113+
groupQuerySize: 100
114+
----
115+
116+
`schedule.frequency`::
117+
Enter the schedule frequency.
118+
Supports cron, ISO duration, and "human duration" as used in code.
119+
+
120+
.`{my-app-config-file}` fragment with optional `schedule.frequency` field
121+
[source,yaml]
122+
----
123+
catalog:
124+
providers:
125+
keycloakOrg:
126+
default:
127+
schedule:
128+
frequency: { hours: 1 }
129+
----
130+
131+
`schedule.timeout`::
132+
Enter the timeout for the user provisioning job.
133+
Supports ISO duration and "human duration" as used in code.
134+
+
135+
.`{my-app-config-file}` fragment with optional `schedule.timeout` field
136+
[source,yaml]
137+
----
138+
catalog:
139+
providers:
140+
keycloakOrg:
141+
default:
142+
schedule:
143+
timeout: { minutes: 50 }
144+
----
145+
146+
`schedule.initialDelay`::
147+
Enter the initial delay to wait for before starting the user provisioning job.
148+
Supports ISO duration and "human duration" as used in code.
149+
+
150+
.`{my-app-config-file}` fragment with optional `schedule.initialDelay` field
151+
[source,yaml]
152+
----
153+
catalog:
154+
providers:
155+
keycloakOrg:
156+
default:
157+
schedule:
158+
initialDelay: { seconds: 15}
159+
----
160+
--
33161

34162
. 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:
35163

36-
.. Configure mandatory fields:
164+
.. Add mandatory fields:
37165
+
38166
.`{my-app-config-file}` fragment with mandatory fields to enable authentication with {rhbk}
39167
[source,yaml]
@@ -43,9 +171,9 @@ auth:
43171
providers:
44172
oidc:
45173
production:
46-
metadataUrl: ${AUTH_OIDC_METADATA_URL}
47-
clientId: ${AUTH_OIDC_CLIENT_ID}
48-
clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
174+
metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
175+
clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
176+
clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET}
49177
prompt: auto
50178
signInPage: oidc
51179
----
@@ -61,12 +189,14 @@ To enable the OIDC provider as default sign-in provider.
61189

62190
`prompt: auto`::
63191
To allow the identity provider to automatically determine whether to prompt for credentials or bypass the login redirect if an active {rhsso} session exists.
64-
192+
+
65193
[NOTE]
66194
====
67195
If `prompt: auto` is not set, the identity provider defaults to `prompt: none`, which assumes that you are already logged in and rejects sign-in requests without an active session.
68196
====
69197

198+
.. Optional: Consider adding optional fields:
199+
70200
`callbackUrl`::
71201
{rhbk} callback URL.
72202
+
@@ -77,7 +207,7 @@ auth:
77207
providers:
78208
oidc:
79209
production:
80-
callbackUrl: ${AUTH_OIDC_CALLBACK_URL}
210+
callbackUrl: ${AUTHENTICATION_OIDC_CALLBACK_URL}
81211
----
82212

83213
`tokenEndpointAuthMethod`::
@@ -90,7 +220,7 @@ auth:
90220
providers:
91221
oidc:
92222
production:
93-
tokenEndpointAuthMethod: ${AUTH_OIDC_TOKEN_ENDPOINT_METHOD}
223+
tokenEndpointAuthMethod: ${AUTHENTICATION_OIDC_TOKEN_ENDPOINT_METHOD}
94224
----
95225

96226
`tokenSignedResponseAlg`::
@@ -103,39 +233,47 @@ auth:
103233
providers:
104234
oidc:
105235
production:
106-
tokenSignedResponseAlg: ${AUTH_OIDC_SIGNED_RESPONSE_ALG}
236+
tokenSignedResponseAlg: ${AUTHENTICATION_OIDC_SIGNED_RESPONSE_ALG}
107237
----
108238

109-
`scope`::
110-
{rhbk} scope.
239+
`additionalScopes`::
240+
Enter additional {rhbk} scopes to request for during the authentication flow.
111241
+
112-
.`{my-app-config-file}` fragment with optional `scope` field
242+
.`{my-app-config-file}` fragment with optional `additionalScopes` field
113243
[source,yaml]
114244
----
115245
auth:
116246
providers:
117247
oidc:
118248
production:
119-
scope: ${AUTH_OIDC_SCOPE}
249+
additionalScopes: ${AUTHENTICATION_OIDC_SCOPE}
120250
----
121251

122252
`signIn`::
123253
`resolvers`:::
124254
After successful authentication, the user signing in must be resolved to an existing user in the {product-short} catalog.
125255
To best match users securely for your use case, consider configuring a specific resolver.
256+
+
126257
Enter the resolver list to override the default resolver: `oidcSubClaimMatchingKeycloakUserId`.
127258
+
259+
Available values:
260+
261+
`oidcSubClaimMatchingKeycloakUserId`::::
262+
Matches the user with the immutable `sub` parameter from OIDC to the {RHBK} user ID.
263+
Consider using this resolver for enhanced security.
264+
265+
`emailLocalPartMatchingUserEntityName`::::
266+
Matches the email local part with the user entity name.
267+
268+
`emailMatchingUserEntityProfileEmail`::::
269+
Matches the email with the user entity profile email.
270+
271+
`preferredUsernameMatchingUserEntityName`::::
272+
Matches the preferred username with the user entity name.
273+
+
128274
The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed.
129275
+
130276
WARNING: In production mode, only configure one resolver to ensure users are securely matched.
131-
132-
`resolver`::::
133-
Enter the sign-in resolver name.
134-
Available values:
135-
* `oidcSubClaimMatchingKeycloakUserId`
136-
* `emailLocalPartMatchingUserEntityName`
137-
* `emailMatchingUserEntityProfileEmail`
138-
* `preferredUsernameMatchingUserEntityName`
139277
+
140278
.`{my-app-config-file}` fragment with optional `resolvers` list
141279
[source,yaml]
@@ -165,9 +303,9 @@ auth:
165303
providers:
166304
oidc:
167305
production:
168-
metadataUrl: ${AUTH_OIDC_METADATA_URL}
169-
clientId: ${AUTH_OIDC_CLIENT_ID}
170-
clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
306+
metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
307+
clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
308+
clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET}
171309
signIn:
172310
resolvers:
173311
- resolver: oidcSubClaimMatchingKeycloakUserID
@@ -212,6 +350,18 @@ If multiple valid refresh tokens are issued due to frequent refresh token reques
212350
====
213351

214352
.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.
353+
354+
. To verify user and group provisioning, check the console logs.
355+
+
356+
.Successful synchronization example:
357+
[source]
358+
----
359+
2025-06-27T16:02:34.647Z catalog info Read 5 Keycloak users and 3 Keycloak groups in 0.4 seconds. Committing... class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01"
360+
361+
2025-06-27T16:02:34.650Z catalog info Committed 5 Keycloak users and 3 Keycloak groups in 0.0 seconds. class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01"
362+
----
363+
364+
. To verify {rhbk} user authentication:
365+
.. Go to the {product-short} login page.
366+
.. Your {product-short} sign-in page displays *Sign in using OIDC* and the Guest user sign-in is disabled.
367+
.. Log in with OIDC by using the saved **Username** and **Password** values.

0 commit comments

Comments
 (0)