Skip to content

Commit 425812f

Browse files
themr0cthemr0c
committed
RHIDP-10991 document custom transformers
Signed-off-by: Fabrice Flore-Thébault <ffloreth@redhat.com>
1 parent 7724c7e commit 425812f

17 files changed

+414
-110
lines changed

‎assemblies/assembly-authenticating-with-the-guest-user.adoc‎

Lines changed: 0 additions & 14 deletions
This file was deleted.

‎assemblies/assembly-enable-authentication-with-azure.adoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:optional-steps: enable
3+
4+
[id='enable-authentication-with-azure']
5+
= Enable authentication with Azure
6+
7+
include::modules/authentication/proc-enabling-user-authentication-with-azure-with-optional-steps.adoc[leveloffset=+1]
8+
9+
10+
include::modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-azure-to-the-software-catalog.adoc[leveloffset=+1]

assemblies/assembly-enabling-authentication-with-github.adoc renamed to assemblies/assembly-enable-authentication-with-github.adoc

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
:_mod-docs-content-type: ASSEMBLY
22
:optional-steps: enable
33

4-
[id='enabling-authentication-with-github']
5-
= Enabling authentication with GitHub
4+
[id='enable-authentication-with-github']
5+
= Enable authentication with GitHub
66

77
include::modules/authentication/proc-enabling-user-authentication-with-github-with-optional-steps.adoc[leveloffset=+1]
88

99

1010
include::modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc[leveloffset=+1]
1111

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

‎assemblies/assembly-enable-authentication-with-gitlab.adoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:optional-steps: enable
3+
4+
[id='enable-authentication-with-gitlab']
5+
= Enable authentication with GitLab
6+
7+
// include::modules/authentication/proc-enabling-user-authentication-with-gitlab-with-optional-steps.adoc[leveloffset=+1]
8+
9+
10+
include::modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-gitlab-to-the-software-catalog.adoc[leveloffset=+1]

assemblies/assembly-authenticating-with-rhbk.adoc renamed to assemblies/assembly-enable-authentication-with-rhbk.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
:_mod-docs-content-type: ASSEMBLY
22

3-
[id="assembly-authenticating-with-rhbk"]
4-
= Authenticating with {rhbk-brand-name} ({rhbk})
3+
[id="enable-authentication-with-rhbk"]
4+
= Enable authentication with {rhbk-brand-name} ({rhbk})
55

66

77
include::modules/authentication/proc-enabling-user-authentication-with-rhbk-with-optional-steps.adoc[leveloffset=+1]

‎assemblies/assembly-enable-authentication.adoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:optional-steps: enable
3+
4+
[id='enable-authentication']
5+
= Enable authentication in {product}
6+
7+
include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1]
8+
9+
10+
include::assembly-enable-or-disable-authentication-with-the-guest-user.adoc[leveloffset=+1]
11+
12+
13+
include::assembly-enable-authentication-with-rhbk.adoc[leveloffset=+1]
14+
15+
16+
include::assembly-enable-authentication-with-github.adoc[leveloffset=+1]
17+
18+
19+
include::assembly-enable-authentication-with-azure.adoc[leveloffset=+1]
20+
21+
22+
include::assembly-enable-service-to-service-authentication.adoc[leveloffset=+1]
23+
24+
25+
include::modules/authentication/proc-enable-auto-logout-for-inactive-users.adoc[leveloffset=+1]
26+
27+
28+
include::assembly-authentication-troubleshooting.adoc[leveloffset=+1]
29+

‎assemblies/assembly-enable-or-disable-authentication-with-the-guest-user.adoc‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
[id="enable-or-disable-authentication-with-the-guest-user_{context}"]
4+
= Enable or disable authentication with the Guest user
5+
6+
For trial or non-production environments, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features.
7+
8+
For production environments, disable guest access to ensure secure authentication and authorization.
9+
10+
include::modules/authentication/proc-enable-the-guest-login-on-the-login-page.adoc[leveloffset=+1]
11+
12+
13+
include::modules/authentication/proc-disable-the-guest-login-on-the-login-page.adoc[leveloffset=+1]
14+

assemblies/assembly-enabling-service-to-service-authentication.adoc renamed to assemblies/assembly-enable-service-to-service-authentication.adoc

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
:_mod-docs-content-type: assembly
22
:previous-context: {context}
3-
:context: enabling-service-to-service-authentication
4-
[id="enabling-service-to-service-authentication"]
5-
= Enabling service-to-service authentication
3+
:context: enable-service-to-service-authentication
4+
[id="enable-service-to-service-authentication"]
5+
= Enable service-to-service authentication
66

77
To secure communication between services and verify identities without manual intervention, you can configure service-to-service authentication.
88
{product} can use this mechanism for plugin-to-plugin communication, and for external service to plugin communication.
9-
{product-short} supports the following service-to-service authentication methods:
9+
{product-short} supports the following service-to-service authentication methods:
1010

1111
* Static tokens
1212
* JSON Web Key Sets (JWKS)
1313
1414
[IMPORTANT]
1515
----
16-
The availability of service-to-service authentication might vary for REST APIs.
16+
The availability of service-to-service authentication might vary for REST APIs.
1717
Each plugin defines the restrictions on this feature.
1818
Consult your specific plugin's documentation for detailed limitations.
1919

‎assemblies/assembly-enabling-authentication.adoc‎

Lines changed: 0 additions & 29 deletions
This file was deleted.

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="creating-a-custom-transformer-to-provision-users-from-azure-to-the-software-catalog"]
4+
= Creating a custom transformer to provision users from Azure to the software catalog
5+
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 Azure backend.
8+
9+
.Prerequisites
10+
* You have xref:enabling-user-authentication-with-azure-with-optional-steps[enabled provisioning users from Azure to the software catalog].
11+
12+
.Procedure
13+
. Create a new backend module:
14+
+
15+
[source,shell]
16+
----
17+
$ yarn new
18+
? What type of module would you like to create? backend-plugin-module
19+
? Enter the ID if the plugin [required]? catalog
20+
? Enter the ID of the module [required]? msgraph-transformer
21+
----
22+
+
23+
The command creates a plugin named: `catalog-backend-module-msgraph-transformer`.
24+
25+
. Install required packages:
26+
+
27+
[source,shell]
28+
----
29+
$ yarn --cwd plugins/catalog-backend-module-msgraph-transformer add @backstage/plugin-catalog-backend-module-msgraph
30+
----
31+
32+
. (Optional) Install recommended packages for UserEntity or GroupEntity type checking:
33+
+
34+
[source,shell]
35+
----
36+
$ yarn --cwd plugins/catalog-backend-module-msgraph-transformer add @backstage/catalog-model
37+
----
38+
39+
. Refer to the sample plugins and implement `plugins/catalog-backend-module-msgraph-transformer/src/module.ts`.
40+
41+
. Package and export the plugin as a Dynamic Plugin, and embed the required package for the custom transformer.
42+
+
43+
[source,shell]
44+
----
45+
$ npx @red-hat-developer-hub/cli@latest plugin export \
46+
--embed-package @backstage/plugin-catalog-backend-module-msgraph
47+
----
48+
49+
[IMPORTANT]
50+
====
51+
Verify that the installed plugin version is compatible with the Backstage version
52+
53+
See plugin marketplace for the version to import.
54+
====
55+
56+
57+
.Verification
58+
59+
* {product-short} imports the users and groups each time when started.
60+
Check the console logs to verify the synchronization result.
61+
+
62+
Successful synchronization example:
63+
+
64+
[source,json]
65+
----
66+
FIXME
67+
----
68+
69+
* After the first import is complete, go to the *Catalog* page and select **User** to view the list of users.
70+
71+
* When you select a user, you see the information imported from GitHub.
72+
73+
* You can select a group, view the list, and access or review the information imported from GitHub.
74+
75+
* You can log in with a GitHub account.

0 commit comments

Comments
 (0)