Backport 615

assemblies/assembly-authenticating-with-rhsso.adoc

@@ -9,3 +9,5 @@ To authenticate users with Red Hat Single Sign-On (RHSSO):
 include::modules/authentication/proc-enabling-authentication-with-rhsso.adoc[leveloffset=+1]
 
 include::modules/authentication/proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc[leveloffset=+1]
+
+include::modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhsso-to-the-software-catalog.adoc[leveloffset=+1]

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

@@ -0,0 +1,92 @@
+[id="provisioning-users-from-rhsso-to-the-software-catalog"]
+= Creating a custom transformer to provision users from Red Hat Single-Sign On (RHSSO) to the software catalog
+
+To customize how RHSSO 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.
+
+.Prerequisites
+* You have xref:provisioning-users-from-rhsso-to-the-software-catalog[enabled provisioning users from Red Hat Single-Sign On (RHSSO) to the software catalog].
+
+.Procedure
+. Create a new backend module with the `yarn new` command.
+
+. Add your custom user and group transformers to the `keycloakTransformerExtensionPoint`.
+
++
+The following is an example of how the backend module can be defined:
++
+.`plugins/__<module-name>__/src/module.ts`
+[source,javascript]
+----
+import {
+  GroupTransformer,
+  keycloakTransformerExtensionPoint,
+  UserTransformer,
+} from '@janus-idp/backstage-plugin-keycloak-backend';
+
+const customGroupTransformer: GroupTransformer = async (
+  entity, // entity output from default parser
+  realm, // Keycloak realm name
+  groups, // Keycloak group representation
+) => {
+  /* apply transformations */
+  return entity;
+};
+const customUserTransformer: UserTransformer = async (
+  entity, // entity output from default parser
+  user, // Keycloak user representation
+  realm, // Keycloak realm name
+  groups, // Keycloak group representation
+) => {
+  /* apply transformations */
+  return entity;
+};
+
+export const keycloakBackendModuleTransformer = createBackendModule({
+  pluginId: 'catalog',
+  moduleId: 'keycloak-transformer',
+  register(reg) {
+    reg.registerInit({
+      deps: {
+        keycloak: keycloakTransformerExtensionPoint,
+      },
+      async init({ keycloak }) {
+        keycloak.setUserTransformer(customUserTransformer);
+        keycloak.setGroupTransformer(customGroupTransformer);
+        /* highlight-add-end */
+      },
+    });
+  },
+});
+----
++
+[IMPORTANT]
+====
+The module's `pluginId` must be set to `catalog` to match the `pluginId` of the `keycloak-backend`; otherwise, the module fails to initialize.
+====
+
+. Install this new backend module into your {product-short} backend.
++
+[source,javascript]
+----
+backend.add(import(backstage-plugin-catalog-backend-module-keycloak-transformer))
+----
+
+.Verification
+
+* {product-short} imports the users and groups each time when started.
+Check the console logs to verify that the synchronization is completed.
++
+.Successful synchronization example:
+[source,json]
+----
+{"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"}
+{"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"}
+----
+
+* After the first import is complete, navigate to the *Catalog* page and select **User** to view the list of users.
+
+* When you select a user, you see the information imported from RHSSO.
+
+* You can select a group, view the list, and access or review the information imported from RHSSO.
+
+* You can log in with an RHSSO account.