Skip to content

Commit ede5f9a

Browse files
themr0cthemr0c
committed
RHIDP-7975 Enabling authentication procedures with mandatory steps only
Signed-off-by: Fabrice Flore-Thébault <[email protected]>
1 parent 8be4076 commit ede5f9a

6 files changed

+510
-1
lines changed

‎assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[id='enabling-authentication-with-mandatory-steps-only']
2+
= Enabling authentication in {product} (with mandatory steps only)
3+
4+
5+
include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1]
6+
7+
8+
include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1]
9+
10+
11+
include::modules/authentication/proc-enabling-user-authentication-with-rhbk-with-mandatory-steps-only.adoc[leveloffset=+1]
12+
13+
14+
include::modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps-only.adoc[leveloffset=+1]
15+
16+
17+
include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps-only.adoc[leveloffset=+1]
18+

‎modules/authentication/con-understanding-authentication-and-user-provisioning.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Catalog provider plugins handle this task asynchronously.
99
These plugins query the Identity Provider (IdP) for relevant user and group information, and create or update corresponding entities in the {product-short} catalog.
1010
Scheduled provisioning ensures that the catalog accurately reflects the users and groups in your organization.
1111

12-
When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as xref:assembly-authenticating-with-rhbk[{rhbk-brand-name} ({rhbk})], xref:enabling-user-authentication-with-github[GitHub], or xref:enabling-user-authentication-with-microsoft-azure[{azure-brand-name}].
12+
When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as {rhbk-brand-name} ({rhbk}), GitHub, or {azure-brand-name}.
1313
This external IdP is responsible for authenticating the user.
1414

1515
On successful authentication, the {product-short} authentication plugin, configured in your `{my-app-config-file}` file, processes the response from the IdP, resolves the identity in the {product-short} software catalog, and establishes a user session within {product-short}.

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

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
[id="enabling-user-authentication-with-github-with-mandatory-steps-only"]
2+
= Enabling user authentication with GitHub (with mandatory steps only)
3+
4+
To authenticate users with GitHub, configure the GitHub authentication provider in {product} and provision the users and groups from GitHub to the {product-short} software catalog.
5+
6+
.Prerequisites
7+
* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
8+
9+
* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
10+
Alternatively, you can ask your GitHub administrator to prepare the required GitHub App.
11+
12+
.Procedure
13+
. To allow {product-short} to authenticate with GitHub, create a GitHub App.
14+
Opt for a GitHub App instead of an OAuth app to use fine-grained permissions and use short-lived tokens.
15+
16+
.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration:
17+
18+
GitHub App name::
19+
Enter a unique name identifying your GitHub App, such as `authenticating-with-rhdh-__<GUID>__`.
20+
21+
Homepage URL::
22+
Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`.
23+
24+
Authorization callback URL::
25+
Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`.
26+
27+
Webhook::
28+
Clear "Active", as this is not needed for authentication and catalog providers.
29+
30+
Organization permissions::
31+
Enable `Read-only` access to *Members*.
32+
33+
Where can this GitHub App be installed?::
34+
Select `Only on this account`.
35+
36+
.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*.
37+
38+
.. In the *Install App* tab, choose an account to install your GitHub App on.
39+
40+
.. Save the following values for the next step:
41+
42+
* **Client ID**
43+
* **Client secret**
44+
45+
. To add your GitHub 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].
46+
You can use these secrets in the {product-short} configuration files by using their respective environment variable name.
47+
48+
`AUTHENTICATION_GITHUB_CLIENT_ID`::
49+
Enter the saved **Client ID**.
50+
51+
`AUTHENTICATION_GITHUB_CLIENT_SECRET`::
52+
Enter the saved **Client Secret**.
53+
54+
`AUTHENTICATION_GITHUB_HOST_DOMAIN`::
55+
Enter the GitHub host domain: `github.com`.
56+
57+
`AUTHENTICATION_GITHUB_ORGANIZATION`::
58+
Enter your GitHub organization name, such as `__<your_github_organization_name>__`.
59+
60+
. Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`).
61+
This plugin ingests GitHub users and groups to the {product-short} software catalog.
62+
+
63+
.`dynamic-plugins.yaml` file fragment
64+
[source,yaml]
65+
----
66+
plugins:
67+
- package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'
68+
disabled: false
69+
----
70+
71+
. To provision GitHub users and groups to the {product-short} software catalog, add the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
72+
+
73+
[id=githubProviderId]
74+
.`{my-app-config-file}` fragment with mandatory `catalog.providers.githubOrg` fields
75+
[source,yaml]
76+
----
77+
catalog:
78+
providers:
79+
githubOrg:
80+
id: githuborg
81+
githubUrl: "${AUTHENTICATION_GITHUB_HOST_DOMAIN}"
82+
orgs: [ "${AUTHENTICATION_GITHUB_ORGANIZATION}" ]
83+
schedule:
84+
frequency:
85+
minutes: 30
86+
initialDelay:
87+
seconds: 15
88+
timeout:
89+
minutes: 15
90+
----
91+
92+
`id`::
93+
Enter a stable identifier for this provider, such as `githuborg`.
94+
Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities and/or conflicts.
95+
96+
`githubUrl`::
97+
Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_HOST_DOMAIN}`.
98+
99+
`orgs`::
100+
Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_ORGANIZATION}`.
101+
102+
`schedule.frequency`::
103+
Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.
104+
105+
`schedule.timeout`::
106+
Enter your schedule timeout, in the ISO duration or "human duration" format.
107+
108+
`schedule.initialDelay`::
109+
Enter your schedule initial delay, in the ISO duration or "human duration" format.
110+
111+
. To set up the GitHub authentication provider, add the `auth.providers.github` section to the `{my-app-config-file}` file content:
112+
+
113+
.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with GitHub
114+
[source,yaml]
115+
----
116+
auth:
117+
environment: production
118+
providers:
119+
github:
120+
production:
121+
clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID}
122+
clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}
123+
signInPage: github
124+
----
125+
126+
`environment`::
127+
Enter `production` to disable the Guest login option in the {product-short} login page.
128+
129+
`clientId`::
130+
Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_CLIENT_ID}`.
131+
132+
`clientSecret`::
133+
Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_CLIENT_SECRET}`.
134+
135+
`signInPage`::
136+
Enter `github` to enable the GitHub provider as your {product-short} sign-in provider.
137+
138+
.Verification
139+
. To verify user and group provisioning, check the console logs.
140+
+
141+
.Successful synchronization example:
142+
[source,json]
143+
----
144+
{"class":"GithubMultiOrgEntityProvider","level":"info","message":"Reading GitHub users and teams for org: rhdh-dast","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:58"}
145+
{"class":"GithubMultiOrgEntityProvider","level":"info","message":"Read 7 GitHub users and 2 GitHub groups in 0.4 seconds. Committing...","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:59"}
146+
----
147+
148+
. To verify GitHub authentication:
149+
.. Go to the {product-short} login page.
150+
.. Your {product-short} sign-in page displays *Sign in using GitHub* and the Guest user sign-in is disabled.
151+
.. Log in with a GitHub account.
152+
153+
.Additional resources
154+
* link:{integrating-with-github-book-url}[{integrating-with-github-book-title}].
155+
* link:{authentication-book-url}#enabling-user-authentication-with-github[Enabling user authentication with GitHub (with optional steps)].
156+

‎modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps-only.adoc

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
[id="enabling-user-authentication-with-microsoft-azure-with-mandatory-steps-only"]
2+
= Enabling user authentication with {azure-brand-name} (with mandatory steps only)
3+
4+
To authenticate users with {azure-brand-name}, configure the {azure-short} authentication provider in {product} and provision the users and groups from {azure-short} to the {product-short} software catalog.
5+
6+
.Prerequisites
7+
* You have the permission to register an application in {azure-short}.
8+
Alternatively, you can ask your {azure-short} administrator to prepare the required {azure-short} application.
9+
10+
* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
11+
12+
* Your {product-short} backend can access the following hosts:
13+
14+
`login.microsoftonline.com`::
15+
This is the {azure-brand-name} authorization server, which enables the authentication flow.
16+
17+
`graph.microsoft.com`::
18+
For retrieving organization data, including user and group data, to be ingested into the {product-short} catalog.
19+
20+
.Procedure
21+
:my-product-app-name-in-azure: <Authenticating with {product-short}>
22+
. To allow {product-short} to authenticate with {azure-short}, link:https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=aspnetcore#register-an-app-by-using-the-azure-portal[Register an app by using the {azure-short} portal].
23+
24+
.. Sign in to the link:https://entra.microsoft.com/[Microsoft Entra admin center].
25+
26+
.. Optional: If you have access to multiple tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu.
27+
28+
.. Browse to *Applications > App registrations*, and create a **New registration** with the configuration:
29+
30+
Name::
31+
Enter a name to identify your application in {azure-short}, such as __{my-product-app-name-in-azure}__.
32+
33+
Supported account types::
34+
Select *Accounts in this organizational directory only*.
35+
36+
Redirect URI::
37+
38+
Select a platform:::
39+
Select *Web*.
40+
41+
URL:::
42+
Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]`
43+
44+
.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, *Add a Permission*, *Microsoft Graph*, select the following permissions:
45+
46+
Application Permissions::
47+
`GroupMember.Read.All`:::
48+
`User.Read.All`:::
49+
Enter permissions that enable provisioning user and groups to the {product-short} software catalog.
50+
+
51+
Optional: *Grant admin consent* for these permissions.
52+
Even if your company does not require admin consent, consider doing so as it means users do not need to individually consent the first time they access {product-short}.
53+
54+
Delegated Permissions::
55+
`User.Read`:::
56+
`email`:::
57+
`offline_access`:::
58+
`openid`:::
59+
`profile`:::
60+
Enter permissions that enable authenticating users.
61+
+
62+
Optional: Enter optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file.
63+
64+
65+
.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > Certificates & secrets* page, in the *Client secrets* tab, create a *New client secret*.
66+
67+
.. Save the following values for the next step:
68+
- **Directory (tenant) ID**
69+
- **Application (client) ID**
70+
- **Application (client) Secret ID**
71+
72+
. To add your {azure-short} 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]:
73+
74+
`AUTHENTICATION_AZURE_TENANT_ID`::
75+
Enter your saved *Directory (tenant) ID*.
76+
77+
`AUTHENTICATION_AZURE_CLIENT_ID`::
78+
Enter your saved *Application (client) ID*.
79+
80+
`AUTHENTICATION_AZURE_CLIENT_SECRET`::
81+
Enter your saved *Application (client) secret*.
82+
83+
. Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`).
84+
This plugin ingests {azure-short} users and groups to the {product-short} software catalog.
85+
+
86+
.`dynamic-plugins.yaml` file fragment
87+
[source,yaml]
88+
----
89+
plugins:
90+
- package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic'
91+
disabled: false
92+
----
93+
+
94+
include::{docdir}/artifacts/snip-technology-preview.adoc[]
95+
96+
. To provision {azure-short} users and groups to the {product-short} software catalog, add the `catalog.providers.microsoftGraphOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
97+
+
98+
--
99+
[id=microsoftGraphOrgProviderId]
100+
.`{my-app-config-file}` fragment with mandatory `microsoftGraphOrg` fields
101+
[source,yaml]
102+
----
103+
catalog:
104+
providers:
105+
microsoftGraphOrg:
106+
providerId:
107+
target: https://graph.microsoft.com/v1.0
108+
tenantId: ${AUTHENTICATION_AZURE_TENANT_ID}
109+
clientId: ${AUTHENTICATION_AZURE_CLIENT_ID}
110+
clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET}
111+
schedule:
112+
frequency:
113+
hours: 1
114+
timeout:
115+
minutes: 50
116+
initialDelay:
117+
minutes: 50
118+
----
119+
120+
`target`::
121+
Enter `\https://graph.microsoft.com/v1.0` to define the MSGraph API endpoint the provider is connecting to.
122+
You might change this parameter to use a different version, such as the link:https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-beta#call-the-beta-endpoint[beta endpoint].
123+
124+
`tenandId`::
125+
Enter the configured secret variable name: `${AUTHENTICATION_AZURE_TENANT_ID}`.
126+
127+
`clientId`::
128+
Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_ID}`.
129+
130+
`clientSecret`::
131+
Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_SECRET}`.
132+
133+
`schedule`::
134+
135+
`frequency`:::
136+
Enter the schedule frequency in the cron, ISO duration, or human duration format.
137+
In a large organization, user provisioning might take a long time, therefore avoid using a low value.
138+
139+
`timeout`:::
140+
Enter the schedule timeout in the ISO duration or human duration format.
141+
In a large organization, user provisioning might take a long time, therefore avoid using a low value.
142+
143+
`initialDelay`:::
144+
Enter the schedule initial delay in the ISO duration or human duration format.
145+
--
146+
147+
. To set up the {azure-short} authentication provider, add the `auth.providers.microsoft` section to your `{my-app-config-file}` file content:
148+
+
149+
--
150+
.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with {azure-short}
151+
[source,yaml,subs="+quotes,+attributes"]
152+
----
153+
auth:
154+
environment: production
155+
providers:
156+
microsoft:
157+
production:
158+
clientId: ${AUTHENTICATION_AZURE_CLIENT_ID}
159+
clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET}
160+
tenantId: ${AUTHENTICATION_AZURE_TENANT_ID}
161+
signInPage: microsoft
162+
----
163+
164+
`environment`::
165+
Enter `production` to disable the **Guest** login option in the {product-short} login page.
166+
167+
`clientId`::
168+
Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_ID}`.
169+
170+
`clientSecret`::
171+
Enter the configured secret variable name:
172+
`${AUTHENTICATION_AZURE_CLIENT_SECRET}`.
173+
174+
`tenantId`::
175+
Enter the configured secret variable name: `${AUTHENTICATION_AZURE_TENANT_ID}`.
176+
177+
`signInPage`::
178+
Enter `microsoft` to set the {azure-short} provider as your {product-short} sign-in provider.
179+
--
180+
181+
.Verification
182+
. To verify user and group provisioning, check the console logs for `MicrosoftGraphOrgEntityProvider` events.
183+
+
184+
.Successful synchronization example:
185+
[source]
186+
----
187+
2025-06-23T13:37:55.804Z catalog info Read 9 msgraph users and 3 msgraph groups in 1.5 seconds. Committing... class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01"
188+
189+
2025-06-23T13:37:55.811Z catalog info Committed 9 msgraph users and 3 msgraph groups in 0.0 seconds. class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01"
190+
----
191+
192+
. To verify {azure-short} user authentication:
193+
.. Go to the {product-short} login page.
194+
.. Your {product-short} sign-in page displays *Sign in using Microsoft* and the Guest user sign-in is disabled.
195+
.. Log in with an {azure-short} account.
196+
197+
.Additional resources
198+
* link:{authentication-book-url}#enabling-user-authentication-with-microsoft-azure[Enabling user authentication with {azure-brand-name} (with optional steps)].

0 commit comments

Comments
 (0)