Skip to content

Commit

Permalink
docs(keycloak-backend): update keycloak documentation (janus-idp#1832)
Browse files Browse the repository at this point in the history 
* docs(keycloak-backend): update keycloak documentation

Signed-off-by: Frank Kong <frkong@redhat.com>

* docs(keycloak-backend): add disclaimer to remove /auth for newer versions of keycloak

Signed-off-by: Frank Kong <frkong@redhat.com>

---------

Signed-off-by: Frank Kong <frkong@redhat.com>
  • Loading branch information
@Zaperex
Zaperex authored Jun 26, 2024
1 parent 6e598ef commit e7c59f5
Showing 1 changed file with 28 additions and 25 deletions.
53 changes: 28 additions & 25 deletions plugins/keycloak-backend/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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://<keycloak_host>/auth
loginRealm: ${KEYCLOAK_REALM}
realm: ${KEYCLOAK_REALM}
Expand Down Expand Up @@ -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://<keycloak_host>/auth
loginRealm: ${KEYCLOAK_REALM}
realm: ${KEYCLOAK_REALM}
Expand All @@ -243,24 +245,25 @@ 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/<module-name>/src/module.ts"
/* highlight-add-start */
import {
GroupTransformer,
keycloakTransformerExtensionPoint,
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,
Expand All @@ -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: {
Expand All @@ -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 */
},
});
Expand All @@ -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.<ENVIRONMENT_NAME>` 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:

Expand All @@ -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.

---

Expand Down

0 comments on commit e7c59f5

Please sign in to comment.