diff --git a/plugins/keycloak-backend/README.md b/plugins/keycloak-backend/README.md index 5b6ea04c3c..161a988932 100644 --- a/plugins/keycloak-backend/README.md +++ b/plugins/keycloak-backend/README.md @@ -30,6 +30,7 @@ yarn workspace backend add @janus-idp/backstage-plugin-keycloak-backend providers: keycloakOrg: default: + # Remove the `/auth` if using keycloak 17+ baseUrl: https:///auth loginRealm: ${KEYCLOAK_REALM} realm: ${KEYCLOAK_REALM} @@ -219,6 +220,7 @@ yarn workspace backend add @janus-idp/backstage-plugin-keycloak-backend providers: keycloakOrg: default: + # Remove the `/auth` if using keycloak 17+ baseUrl: https:///auth loginRealm: ${KEYCLOAK_REALM} realm: ${KEYCLOAK_REALM} @@ -243,9 +245,9 @@ yarn workspace backend add @janus-idp/backstage-plugin-keycloak-backend backend.start(); ``` -1. Optional: provide a transformer function for user/group to mutate the entity before their ingestion into catalog. Create a new backend module with the `yarn new` command to use the `keycloakTransformerExtensionPoint`. +1. Optional: To configure custom transformer function for user/group to mutate the entity generated by the keycloak-backend. Create a new backend module with the `yarn new` command and add your custom user and group transformers to the `keycloakTransformerExtensionPoint`. Then install this new backend module into your backstage backend. Below is an example of how the backend module can be defined: - ```ts + ```ts title="plugins//src/module.ts" /* highlight-add-start */ import { GroupTransformer, @@ -253,14 +255,15 @@ yarn workspace backend add @janus-idp/backstage-plugin-keycloak-backend UserTransformer, } from '@janus-idp/backstage-plugin-keycloak-backend'; - /* highlight-add-end */ - - /* highlight-add-start */ - const groupTransformer: GroupTransformer = async (entity, realm, groups) => { + const customGroupTransformer: GroupTransformer = async ( + entity, + realm, + groups, + ) => { /* apply transformations */ return entity; }; - const userTransformer: UserTransformer = async ( + const customUserTransformer: UserTransformer = async ( entity, user, realm, @@ -273,7 +276,7 @@ yarn workspace backend add @janus-idp/backstage-plugin-keycloak-backend export const keycloakBackendModuleTransformer = createBackendModule({ pluginId: 'catalog', - moduleId: 'transformer', + moduleId: 'keycloak-transformer', register(reg) { reg.registerInit({ deps: { @@ -283,8 +286,8 @@ yarn workspace backend add @janus-idp/backstage-plugin-keycloak-backend }, /* highlight-add-start */ async init({ keycloak }) { - keycloak.setUserTransformer(userTransformer); - keycloak.setGroupTransformer(groupTransformer); + keycloak.setUserTransformer(customUserTransformer); + keycloak.setGroupTransformer(customGroupTransformer); /* highlight-add-end */ }, }); @@ -294,27 +297,27 @@ yarn workspace backend add @janus-idp/backstage-plugin-keycloak-backend *** - **NOTE** + **IMPORTANT** - The `pluginId` must be the ID of an existing plugin (e.g. `catalog`) due to a limitation with extending a module on top of another module. Otherwise the newly created backend module will not be initialized. + The `pluginId` for the module **MUST** be set to `catalog` to match the `pluginId` of the `keycloak-backend` or else the module will fail to initialize. ---- + *** Communication between Backstage and Keycloak is enabled by using the Keycloak API. Username/password or client credentials are supported authentication methods. The following table describes the parameters that you can configure to enable the plugin under `catalog.providers.keycloakOrg.` object in the `app-config.yaml` file: -| Name | Description | Default Value | Required | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------- | -| `baseUrl` | Location of the Keycloak server, such as `https://localhost:8443/auth`. Note that the newer versions of Keycloak omit the `/auth` context path. | "" | Yes | -| `realm` | Realm to synchronize | `master` | No | -| `loginRealm` | Realm used to authenticate | `master` | No | -| `username` | Username to authenticate | "" | Yes if using password based authentication | -| `password` | Password to authenticate | "" | Yes if using password based authentication | -| `clientId` | Client ID to authenticate | "" | Yes if using client credentials based authentication | -| `clientSecret` | Client Secret to authenticate | "" | Yes if using client credentials based authentication | -| `userQuerySize` | Number of users to query at a time | `100` | No | -| `groupQuerySize` | Number of groups to query at a time | `100` | No | +| Name | Description | Default Value | Required | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------- | ---------------------------------------------------- | +| `baseUrl` | Location of the Keycloak server, such as `https://localhost:8443/auth`. Note that Keycloak 17+ omits the `/auth` context path. | "" | Yes | +| `realm` | Realm to synchronize | `master` | No | +| `loginRealm` | Realm used to authenticate | `master` | No | +| `username` | Username to authenticate | "" | Yes if using password based authentication | +| `password` | Password to authenticate | "" | Yes if using password based authentication | +| `clientId` | Client ID to authenticate | "" | Yes if using client credentials based authentication | +| `clientSecret` | Client Secret to authenticate | "" | Yes if using client credentials based authentication | +| `userQuerySize` | Number of users to query at a time | `100` | No | +| `groupQuerySize` | Number of groups to query at a time | `100` | No | When using client credentials, the access type must be set to `confidential` and service accounts must be enabled. You must also add the following roles from the `realm-management` client role: @@ -331,7 +334,7 @@ If you have self-signed or corporate certificate issues, you can set the followi --- **NOTE** -The solution of setting the environment variable is not recommended. +The solution of setting the `NODE_TLS_REJECT_UNAUTHORIZED` environment variable is not recommended. ---