You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To explore {product-short} features, you can skip configuring authentication and authorization.
7
-
You can configure {product-short} to log in as a Guest user and access {product-short} features.
6
+
For trial or non-production environments, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features.
Copy file name to clipboardExpand all lines: modules/authentication/con-understanding-authentication-and-user-provisioning.adoc
+14-7Lines changed: 14 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,7 @@
2
2
3
3
= Understanding authentication and user provisioning
4
4
5
-
This module provides an overview of how authentication and user provisioning function within {product}.
6
-
Learn about the process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step.
5
+
Learn about the authentication process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step.
7
6
Understanding this process is essential for successfully configuring your {product-short} instance, securing access through authorization, and enabling features that rely on synchronized user and group data.
8
7
9
8
To fully enable catalog features, provision user and group data from the Identity Provider to the {product-short} software catalog.
@@ -18,21 +17,29 @@ On successful authentication, the {product-short} authentication plugin, configu
18
17
19
18
Configuring authentication and user provisioning is critical for several reasons.
20
19
21
-
* It secures your {product-short} instance by ensuring only authenticated users can gain access.
22
-
* It enables authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP.
20
+
* Securing your {product-short} instance by ensuring only authenticated users can gain access.
21
+
* Enabling authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP.
23
22
* Provisioning user and group data to the catalog is necessary for various catalog features that rely on understanding entity ownership and relationships between users, groups, and software components.
24
-
Without this provisioning step, features like displaying who owns a component in the catalog may not function correctly.
23
+
+
24
+
[IMPORTANT]
25
+
====
26
+
Without this provisioning step, features such as displaying who owns a catalog entity might not function correctly.
27
+
====
25
28
26
29
[TIP]
27
30
====
28
31
To explore {product-short} features in a non-production environment, you can:
29
32
30
33
* To use {product-short} without external IdP, enable the guest user to skip configuring authentication and authorization, log in as the guest user, and access all {product-short} features.
31
34
32
-
* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option. This setting bypasses the check requiring a user to be in the catalog but still enforces authentication.
35
+
* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option.
36
+
This setting bypasses the check requiring a user to be in the catalog but still enforces authentication.
33
37
====
34
38
35
39
[IMPORTANT]
36
40
====
37
-
{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog. As a result, deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies, since those entities will be recreated during the next ingestion.
41
+
{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog.
42
+
As a result,
43
+
deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies,
44
+
since {product-short} will create those entities again during the next import.
= Authenticating with the Guest user on a Helm-based installation
5
5
6
-
On a Helm-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features.
6
+
For trial or non-production environments installed by using the {product} Helm chart, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features.
7
7
8
8
.Prerequisites
9
-
* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
9
+
* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
10
10
* You {configuring-book-link}#using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[use the {product} Helm chart to run {product-short}].
11
11
12
12
.Procedure
13
-
* To enable the guest user in your {product-short} custom configuration, {configuring-book-link}#using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[configure your {product} Helm Chart] with following content:
13
+
* Add following content to your {product} Helm Chart:
= Authenticating with the Guest user on an Operator-based installation
5
5
6
-
After an Operator-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features.
6
+
For trial or non-production environments installed by using the {product} Operator, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features.
7
7
8
8
.Prerequisites
9
-
* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
9
+
* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
10
10
* You {configuring-book-link}#using-the-operator-to-run-rhdh-with-your-custom-configurationn[use the {product} Operator to run {product-short}].
11
11
12
12
.Procedure
13
-
* To enable the guest user in your {product-short} custom configuration, {configuring-book-link}#provisioning-your-custom-configuration[edit your {product-short} application configuration] with following content:
13
+
* Add the following content to the `{my-app-config-file}` file:
Copy file name to clipboardExpand all lines: modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc
= Creating a custom transformer to provision users from {rhbk-brand-name} ({rhbk}) to the software catalog
5
5
6
-
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.
6
+
Customize how {product} provisions users and groups to {product} software catalog entities,
7
+
by creating a backend module that uses the `keycloakTransformerExtensionPoint` to offer custom user and group transformers for the Keycloak backend.
7
8
8
9
.Prerequisites
9
10
* You have xref:enabling-user-authentication-with-rhbk[enabled provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog].
@@ -14,9 +15,8 @@ To customize how {rhbk} users and groups are mapped to {product} entities, you c
14
15
. Add your custom user and group transformers to the `keycloakTransformerExtensionPoint`.
15
16
16
17
+
17
-
The following is an example of how the backend module can be defined:
18
+
The following is an example `plugins/__<module_name>__/src/module.ts` file defining the backend module:
* {product-short} imports the users and groups each time when started.
79
-
Check the console logs to verify that the synchronization is completed.
79
+
Check the console logs to verify the synchronization result.
80
+
+
81
+
Successful synchronization example:
80
82
+
81
-
.Successful synchronization example:
82
83
[source,json]
83
84
----
84
85
{"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"}
85
86
{"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"}
86
87
----
87
88
88
-
* After the first import is complete, navigate to the *Catalog* page and select **User** to view the list of users.
89
+
* After the first import is complete, go to the *Catalog* page and select **User** to view the list of users.
89
90
90
91
* When you select a user, you see the information imported from {rhbk}.
Copy file name to clipboardExpand all lines: modules/authentication/proc-enabling-user-authentication-with-github.adoc
+42-38Lines changed: 42 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,12 +3,12 @@
3
3
[id="enabling-user-authentication-with-github"]
4
4
= Enabling user authentication with GitHub
5
5
6
-
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.
6
+
Authenticate users with GitHub by provisioning the users and groups from GitHub to the {product-short} software catalog, and configuring the GitHub authentication provider in {product}.
7
7
8
8
.Prerequisites
9
-
* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
9
+
* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
10
10
11
-
* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
11
+
* You have enough permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
12
12
Alternatively, you can ask your GitHub administrator to prepare the required GitHub App.
13
13
14
14
.Procedure
@@ -45,44 +45,43 @@ Select `Only on this account`.
45
45
* **Client secret**
46
46
47
47
. To add your GitHub credentials to {product-short}, add the following key/value pairs to {configuring-book-link}#provisioning-your-custom-configuration[your {product-short} secrets].
48
-
You can use these secrets in the {product-short} configuration files by using their respective environment variable name.
48
+
You can use these secrets in the {product-short} configuration files by using their environment variable name.
49
49
50
-
`AUTHENTICATION_GITHUB_CLIENT_ID`::
50
+
`GITHUB_CLIENT_ID`::
51
51
Enter the saved **Client ID**.
52
52
53
-
`AUTHENTICATION_GITHUB_CLIENT_SECRET`::
53
+
`GITHUB_CLIENT_SECRET`::
54
54
Enter the saved **Client Secret**.
55
55
56
-
`AUTHENTICATION_GITHUB_HOST_DOMAIN`::
56
+
`GITHUB_URL`::
57
57
Enter the GitHub host domain: `github.com`.
58
58
59
-
`AUTHENTICATION_GITHUB_ORGANIZATION`::
59
+
`GITHUB_ORG`::
60
60
Enter your GitHub organization name, such as `__<your_github_organization_name>__`.
61
61
62
62
. Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`).
63
-
This plugin ingests GitHub users and groups to the {product-short} software catalog.
63
+
This plugin imports GitHub users and groups to the {product-short} software catalog.
. 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:
74
+
. Provision GitHub users and groups to the {product-short} software catalog by adding the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
74
75
+
75
-
--
76
76
[id=githubProviderId]
77
-
.`{my-app-config-file}` fragment with mandatory `catalog.providers.githubOrg` fields
78
77
[source,yaml]
79
78
----
80
79
catalog:
81
80
providers:
82
81
githubOrg:
83
82
id: githuborg
84
-
githubUrl: "${AUTHENTICATION_GITHUB_HOST_DOMAIN}"
85
-
orgs: [ "${AUTHENTICATION_GITHUB_ORGANIZATION}" ]
83
+
githubUrl: "${GITHUB_URL}"
84
+
orgs: [ "${GITHUB_ORG}" ]
86
85
schedule:
87
86
frequency:
88
87
minutes: 30
@@ -94,13 +93,13 @@ catalog:
94
93
95
94
`id`::
96
95
Enter a stable identifier for this provider, such as `githuborg`.
97
-
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.
96
+
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 or conflicts.
98
97
99
98
`githubUrl`::
100
-
Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_HOST_DOMAIN}`.
99
+
Enter the configured secret variable name: `$\{GITHUB_URL}`.
101
100
102
101
`orgs`::
103
-
Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_ORGANIZATION}`.
102
+
Enter the configured secret variable name: `$\{GITHUB_ORG}`.
104
103
105
104
`schedule.frequency`::
106
105
Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.
@@ -110,48 +109,47 @@ Enter your schedule timeout, in the ISO duration or "human duration" format.
110
109
111
110
`schedule.initialDelay`::
112
111
Enter your schedule initial delay, in the ISO duration or "human duration" format.
113
-
--
114
112
115
-
. To set up the GitHub authentication provider, add the `auth.providers.github` section to the `{my-app-config-file}` file content:
113
+
. To set up the GitHub authentication provider, add the `auth.providers.github` section to your `{my-app-config-file}` file:
116
114
+
117
-
--
118
-
.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with GitHub
Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog.
193
194
+
194
-
WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production.
195
-
--
195
+
[WARNING]
196
+
====
197
+
Do not use `dangerouslyAllowSignInWithoutUserInCatalog` in production. Use this configuration only to explore {product-short} features.
198
+
====
199
+
endif::[]
196
200
197
201
.Verification
198
-
. To verify user and group provisioning, check the console logs.
202
+
. Verify user and group provisioning by checking the console logs.
203
+
+
204
+
Successful synchronization example:
199
205
+
200
-
.Successful synchronization example:
201
206
[source,json]
202
207
----
203
208
{"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"}
@@ -210,6 +215,5 @@ WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-sh
0 commit comments