{"id":23122772,"url":"https://github.com/folio-org/mod-users-keycloak","last_synced_at":"2026-04-17T09:01:49.807Z","repository":{"id":211890715,"uuid":"729035290","full_name":"folio-org/mod-users-keycloak","owner":"folio-org","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-15T11:57:07.000Z","size":588,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":8,"default_branch":"master","last_synced_at":"2026-04-15T13:41:01.297Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/folio-org.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-12-08T09:01:09.000Z","updated_at":"2026-04-15T11:57:10.000Z","dependencies_parsed_at":"2024-04-16T11:42:35.608Z","dependency_job_id":"ce4b8985-7d9e-43ba-82f6-da009e4efe89","html_url":"https://github.com/folio-org/mod-users-keycloak","commit_stats":null,"previous_names":["folio-org/mod-users-keycloak"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/folio-org/mod-users-keycloak","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-users-keycloak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-users-keycloak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-users-keycloak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-users-keycloak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/folio-org","download_url":"https://codeload.github.com/folio-org/mod-users-keycloak/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-users-keycloak/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31922399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T07:30:21.445Z","updated_at":"2026-04-17T09:01:49.798Z","avatar_url":"https://github.com/folio-org.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mod-users-keycloak\n\nCopyright (C) 2023-2023 The Open Library Foundation\n\nThis software is distributed under the terms of the Apache License,\nVersion 2.0. See the file \"[LICENSE](LICENSE)\" for more information.\n\n## Table of contents\n\n* [Introduction](#introduction)\n  * [ModuleDescriptor](#moduledescriptor)\n* [API documentation](#api-documentation)\n* [Environment Variables](#environment-variables)\n  * [Kafka environment variables](#kafka-environment-variables)\n  * [System User Environment Variables](#system-user-environment-variables)\n  * [Secure storage environment variables](#secure-storage-environment-variables)\n    * [AWS-SSM](#aws-ssm)\n    * [Vault](#vault)\n    * [Folio Secure Store Proxy (FSSP)](#folio-secure-store-proxy-fssp)\n  * [Keycloak environment variables](#keycloak-environment-variables)\n  * [mod-configuration properties](#mod-configuration-properties)\n* [Loading of client IDs/secrets](#loading-of-client-idssecrets)\n\n## Introduction\n\nBusiness logic \"join\" module to provide simple access to all user-centric data.\n\nThe module combines interfaces normally provided by `mod-users` and `mod-users-bl` Folio modules. Thus its output are\neither User model from mod-users or Composite User from mod-users-bl.\n\nThe module also operates with Keycloak to manage authentication information of users (`authUser`). Auth users created\nand updated in Keycloak on per-realm basis.\n\n### ModuleDescriptor\n\nSee the built `target/ModuleDescriptor.json` for the interfaces that this module\nrequires and provides, the permissions, and the additional module metadata.\n\n## API documentation\n\nAPI documentation can be generated with the following command:\n\n```shell\nmvn clean generate-sources\n```\n\nAfter that the documentation will be available in `target/docs/mod-users-keycloakindex.html`\n\n## Environment Variables\n\n| Name                             | Default value              | Required | Description                                                                                                                          |\n|:---------------------------------|:---------------------------|:--------:|:-------------------------------------------------------------------------------------------------------------------------------------|\n| DB_HOST                          | localhost                  |  false   | Postgres hostname                                                                                                                    |\n| DB_PORT                          | 5432                       |  false   | Postgres port                                                                                                                        |\n| DB_USERNAME                      | postgres                   |  false   | Postgres username                                                                                                                    |\n| DB_PASSWORD                      | postgres                   |  false   | Postgres username password                                                                                                           |\n| DB_DATABASE                      | postgres                   |  false   | Postgres database name                                                                                                               |\n| KC_URL                           | -                          |   true   | Keycloak URL used to perform HTTP requests by `KeycloakClient`.                                                                      |\n| KC_ADMIN_CLIENT_ID               | folio-backend-admin-client |   true   | Keycloak client id                                                                                                                   |\n| KC_ADMIN_GRANT_TYPE              | client_credentials         |  false   | Defines grant type for issuing Keycloak token                                                                                        |\n| KC_PASSWORD_RESET_CLIENT_ID      | password-reset-client      |  false   | Keycloak password reset client                                                                                                       |\n| KC_ADMIN_TOKEN_TTL               | 60s                        |  false   | ttl value for Keycloak token to persist in cache                                                                                     |\n| KC_CONFIG_TTL                    | 3600s                      |  false   | Client credentials expiration timeout                                                                                                |\n| KC_LOGIN_CLIENT_SUFFIX           | -login-application         |  false   | Suffix of a Keycloak client who owns the authorization resources. It is used as `audience` for keycloak when evaluating permissions. |\n| MIGRATION_BATCH_SIZE             | 20                         |  false   | Batch size for user migration. Max value is 50                                                                                       |\n| IDP_MIGRATION_BATCH_SIZE         | 20                         |  false   | Batch size for user identity provider (IDP) linking migration. Max value is 50                                                       |\n| DEFAULT_PASSWORDS_ON_MIGRATION   | false                      |  false   | If specified to true migrated user’s password being set to their username otherwise migrated users not having any credentials set    |\n| INCLUDE_ONLY_VISIBLE_PERMISSIONS | false                      |  false   | Defines if onlyVisible (UI permissions/permission-set names) will be returned using `_self` endpoint                                 |\n| SINGLE_TENANT_UX                 | false                      |  false   | Defines if the module is running in single tenant UX mode                                                                            |\n| IDENTITY_PROVIDER_SUFFIX         | -keycloak-oidc             |  false   | Suffix of a Keycloak OIDC identity provider who will perform federated authentication requests. Used if SINGLE_TENANT_UX is enabled  |\n| OKAPI_URL                        | http://sidecar:8081        |  false   | Okapi url                                                                                                                            |\n\n### Kafka environment variables\n\n| Name                                | Default value                                                             | Required | Description                                                                                                                                                |\n|:------------------------------------|:--------------------------------------------------------------------------|:--------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------|\n| KAFKA_HOST                          | kafka                                                                     |  false   | Kafka broker hostname                                                                                                                                      |\n| KAFKA_PORT                          | 9092                                                                      |  false   | Kafka broker port                                                                                                                                          |\n| KAFKA_SECURITY_PROTOCOL             | PLAINTEXT                                                                 |  false   | Kafka security protocol used to communicate with brokers (SSL or PLAINTEXT)                                                                                |\n| KAFKA_SSL_KEYSTORE_LOCATION         | -                                                                         |  false   | The location of the Kafka key store file. This is optional for client and can be used for two-way authentication for client.                               |\n| KAFKA_SSL_KEYSTORE_PASSWORD         | -                                                                         |  false   | The store password for the Kafka key store file. This is optional for client and only needed if 'ssl.keystore.location' is configured.                     |\n| KAFKA_SSL_TRUSTSTORE_LOCATION       | -                                                                         |  false   | The location of the Kafka trust store file.                                                                                                                |\n| KAFKA_SSL_TRUSTSTORE_PASSWORD       | -                                                                         |  false   | The password for the Kafka trust store file. If a password is not set, trust store file configured will still be used, but integrity checking is disabled. |\n| KAFKA_SYS_USER_TOPIC_RETRY_DELAY    | 1s                                                                        |  false   | `system-user` topic retry delay if tenant is not initialized                                                                                               |\n| KAFKA_SYS_USER_TOPIC_RETRY_ATTEMPTS | 9223372036854775807                                                       |  false   | `system-user` topic retry attempts if tenant is not initialized (default value is Long.MAX_VALUE ~= infinite amount of retries)                            |\n| KAFKA_SYS_USER_TOPIC_PATTERN        | `(${application.environment}\\.)(.*\\.)mgr-tenant-entitlements.system-user` |  false   | Topic pattern for `system-user` topic filled by mgr-tenants-entitlement                                                                                    |\n| KAFKA_SYS_USER_ROLE_RETRY_ATTEMPTS  | 60                                                                        |  false   | Number of retry attempts to upsert loadable roles and assign it to (module) system user                                                                    |\n| KAFKA_SYS_USER_ROLE_RETRY_DELAY     | 5s                                                                        |  false   | Duration between retry attempts (with time unit suffix) to upsert loadable roles and assign it to (module) system user                                     |\n\n### System User Environment Variables\n\n| Name                          | Default value                    | Required | Description                                                            |\n|:------------------------------|:---------------------------------|:--------:|:-----------------------------------------------------------------------|\n| SYSTEM_USER_USERNAME_TEMPLATE | {tenantId}-system-user           |  false   | System user username template, used to generate system user `username` |\n| SYSTEM_USER_EMAIL_TEMPLATE    | {tenantId}-system-user@folio.org |  false   | System user email template, used to generate system user `email`.      |\n| SYSTEM_USER_ROLE              | System                           |  false   | System user role name. It will be assigned on tenant initialization    |\n| SYSTEM_USER_PASSWORD_LENGTH   | 32                               |  false   | Batch size for user migration. Max value is 50                         |\n| SYSTEM_USER_RETRY_COUNT       | 10                               |  false   | Number of retry attempts to create a system user                       |\n| SYSTEM_USER_RETRY_DELAY       | 250                              |  false   | Amount of milliseconds between retry attempts                          |\n\n### Secure storage environment variables\n\n| Name                | Default value | Description                                                                                                                                                    |\n|:--------------------|:--------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| SECURE_STORE_ENV    | folio         | First segment of the secure store key, for example `prod` or `test`. Defaults to `folio`. In Ramsons and Sunflower defaults to ENV with fall-back `folio`.     |\n\n#### AWS-SSM\n\nRequired when `SECRET_STORE_TYPE=AWS_SSM`\n\n| Name                                          | Default value | Description                                                                                                                                                    |\n|:----------------------------------------------|:--------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| SECRET_STORE_AWS_SSM_REGION                   | -             | The AWS region to pass to the AWS SSM Client Builder. If not set, the AWS Default Region Provider Chain is used to determine which region to use.              |\n| SECRET_STORE_AWS_SSM_USE_IAM                  | true          | If true, will rely on the current IAM role for authorization instead of explicitly providing AWS credentials (access_key/secret_key)                           |\n| SECRET_STORE_AWS_SSM_ECS_CREDENTIALS_ENDPOINT | -             | The HTTP endpoint to use for retrieving AWS credentials. This is ignored if useIAM is true                                                                     |\n| SECRET_STORE_AWS_SSM_ECS_CREDENTIALS_PATH     | -             | The path component of the credentials endpoint URI. This value is appended to the credentials endpoint to form the URI from which credentials can be obtained. |\n\n#### Vault\n\nRequired when `SECRET_STORE_STORE_TYPE=VAULT`\n\n| Name                                    | Default value | Description                                                                         |\n|:----------------------------------------|:--------------|:------------------------------------------------------------------------------------|\n| SECRET_STORE_VAULT_TOKEN                | -             | token for accessing vault, may be a root token                                      |\n| SECRET_STORE_VAULT_ADDRESS              | -             | the address of your vault                                                           |\n| SECRET_STORE_VAULT_ENABLE_SSL           | false         | whether or not to use SSL                                                           |\n| SECRET_STORE_VAULT_PEM_FILE_PATH        | -             | the path to an X.509 certificate in unencrypted PEM format, using UTF-8 encoding    |\n| SECRET_STORE_VAULT_KEYSTORE_PASSWORD    | -             | the password used to access the JKS keystore (optional)                             |\n| SECRET_STORE_VAULT_KEYSTORE_FILE_PATH   | -             | the path to a JKS keystore file containing a client cert and private key            |\n| SECRET_STORE_VAULT_TRUSTSTORE_FILE_PATH | -             | the path to a JKS truststore file containing Vault server certs that can be trusted |\n\n#### Folio Secure Store Proxy (FSSP)\n\nRequired when `SECRET_STORE_TYPE=FSSP`\n\n| Name                                   | Default value         | Description                                          |\n|:---------------------------------------|:----------------------|:-----------------------------------------------------|\n| SECRET_STORE_FSSP_ADDRESS              | -                     | The address (URL) of the FSSP service.               |\n| SECRET_STORE_FSSP_SECRET_PATH          | secure-store/entries  | The path in FSSP where secrets are stored/retrieved. |\n| SECRET_STORE_FSSP_ENABLE_SSL           | false                 | Whether to use SSL when connecting to FSSP.          |\n| SECRET_STORE_FSSP_TRUSTSTORE_PATH      | -                     | Path to the truststore file for SSL connections.     |\n| SECRET_STORE_FSSP_TRUSTSTORE_FILE_TYPE | -                     | The type of the truststore file (e.g., JKS, PKCS12). |\n| SECRET_STORE_FSSP_TRUSTSTORE_PASSWORD  | -                     | The password for the truststore file.                |\n\n### Keycloak environment variables\n\nKeycloak all configuration properties: https://www.keycloak.org/server/all-config\n\n| Name                              | Description                                                                                                                                                                |\n|:----------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| KC_HOSTNAME                       | Keycloak hostname, will be added to returned endpoints, for example for openid-configuration                                                                               |\n| KC_ADMIN                          | Initial admin username                                                                                                                                                     |\n| KC_ADMIN_PASSWORD                 | Initial admin password                                                                                                                                                     |\n| KC_DB                             | Database type                                                                                                                                                              |\n| KC_DB_URL_DATABASE                | Sets the database name of the default JDBC URL of the chosen vendor. If the DB_URL option is set, this option is ignored.                                                  |\n| KC_DB_URL_HOST                    | Sets the hostname of the default JDBC URL of the chosen vendor. If the DB_URL option is set, this option is ignored.                                                       |\n| KC_DB_URL_PORT                    | Sets the port of the default JDBC URL of the chosen vendor. If the DB_URL option is set, this option is ignored.                                                           |\n| KC_DB_USERNAME                    | Database Username                                                                                                                                                          |\n| KC_DB_PASSWORD                    | Database Password                                                                                                                                                          |\n| KC_PROXY                          | The proxy address forwarding mode if the server is behind a reverse proxy. Possible values are: edge, reencrypt, passthrough. https://www.keycloak.org/server/reverseproxy |\n| KC_HOSTNAME_STRICT                | Disables dynamically resolving the hostname from request headers. Should always be set to true in production, unless proxy verifies the Host header.                       |\n| KC_HOSTNAME_PORT                  | The port used by the proxy when exposing the hostname. Set this option if the proxy uses a port other than the default HTTP and HTTPS ports. Defaults to -1.               |\n| KC_CLIENT_TLS_ENABLED             | Enables TLS for keycloak clients.                                                                                                                                          |\n| KC_CLIENT_TLS_TRUSTSTORE_PATH     | Truststore file path for keycloak clients.                                                                                                                                 |\n| KC_CLIENT_TLS_TRUSTSTORE_PASSWORD | Truststore password for keycloak clients.                                                                                                                                  |\n| KC_CLIENT_TLS_TRUSTSTORE_TYPE     | Truststore file type for keycloak clients.                                                                                                                                 |\n\n### mod-configuration properties\n\nConfiguration properties must be created for a module: `USERSBL`\n\nRequest example:\n\n```HTTP\nPOST /configurations/entries HTTP/1.1\nHost: \u003cgateway\u003e\nx-okapi-tenant: \u003ctenant_name\u003e\nx-okapi-token: \u003cauth-token\u003e\n\n{\n  \"module\": \"USERSBL\",\n  \"configName\": \"validation_rules\",\n  \"code\": \"FOLIO_HOST\",\n  \"description\": \"Host value for password reset\",\n  \"default\": true,\n  \"enabled\": true,\n  \"value\": \"https://ui-host:3000\"\n}\n```\n\n\u003e **_NOTE:_** Fields `code` and `value` are mandatory, if any of them are not specified - default value will be used.\n\n| Name                                        |     Default value     | Description                                                                                                                                       |\n|:--------------------------------------------|:---------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------|\n| FOLIO_HOST                                  | http://localhost:3000 | Folio host used to generate password reset link                                                                                                   |\n| RESET_PASSWORD_UI_PATH                      |    /reset-password    | UI path, added to the folio host, took value firstly from `mod-configuration`, then from application property `reset-password.ui-path.default`    |\n| RESET_PASSWORD_LINK_EXPIRATION_TIME         |          24           | A duration value when the reset password token will be expired                                                                                    |\n| RESET_PASSWORD_LINK_EXPIRATION_UNIT_OF_TIME |         hours         | A duration unit when the reset password token will be expired                                                                                     |\n| PUT_RESET_TOKEN_IN_QUERY_PARAMS             |         false         | Defines if reset token will be included in the path (if value is not set or set as `false`) or as a query parameter (if value is set to a `true`) |\n\n## Loading of client IDs/secrets\n\nThe module pulls client_secret for client_id from AWS Parameter store, Vault or other reliable secret storages when they\nare required for login. The credentials are cached for 3600s.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-users-keycloak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffolio-org%2Fmod-users-keycloak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-users-keycloak/lists"}