Readme

This repository contains User Management modules for Gazelle.

• Gazelle User Management

  • Requirements

  • Build artifacts

  • Testing

  • Configuration

    • Environment variables

  • Applications deployment (for dev)

    • Deploy with Maven

      • Check the logs

      • Stop the services

    • Deploy with Compose

      • Requirements

  • How to configure the gazelle realm

  • Configuration to integrate a CAS Client

  • License

Requirements

• JDK 17+/Maven 3.8.2+

• Docker 20.10.14+

• Docker-compose 2.16.0+

• PostgreSQL 10+ with authorized prepared transactions

Build artifacts

It is possible to generate the artifacts with maven.

This command will directly build the docker image of the project :

• rg.fr-par.scw.cloud/gazelle-snapshot/app/gazelle-keycloak:${project.version}

• rg.fr-par.scw.cloud/gazelle-snapshot/app/gazelle-quarkus:${project.version}

mvn clean package

Testing

It is possible to run different types of test in this application :

• Unit tests that are run with the following command, the jacoco results can be found in module_path/target/site/jacoco/

mvn clean test

• Integration tests that can be run with the following command

mvn verify

• Mutation tests that can be run with the following command, the results can be found in module_path/target/pit-reports/

  In keycloak-provider module, the mutation tests are skipped.

mvn test-compile org.pitest:pitest-maven:mutationCoverage

Be careful of tests that need environment variables, they will more than likely not work, so you will need to exclude them from pitest. To do that add the following in the pom.xml of the module, in the configuration section of the pitest plugin, where the classes to exclude are in :

<excludedClasses>
  <param>path.of.the.class.to.excludes</param>  
  <param>path.of.the.classes.to.exclude.*</param>
</excludedClasses>
<excludedTestClasses>
  <param>path.of.the.test.class.to.excludes</param>
  <param>path.of.the.test.classes.to.exclude.*</param>
</excludedTestClasses>

Configuration

Environment variables

Name	Description	Value Example
DB_KC_JDBC_URL	JDBC URL for Keycloak database	jdbc:postgresql://localhost:5432/keycloak [OPTIONAL]
DB_KC_USER	Postgres database user for Keycloak	gazelle
DB_KC_PASSWORD	Postgres database password for Keycloak
DB_KC_HOST	Postgres database hostname for Keycloak	localhost
DB_KC_PORT	Postgres database port for Keycloak	5432
DB_KC_NAME	Postgres database name for Keycloak	keycloak
DB_GUM_JDBC_URL	JDBC URL for GUM database	jdbc:postgresql://localhost:5432/gum [OPTIONAL]
DB_GUM_USER	Postgres database user for GUM	gazelle
DB_GUM_PASSWORD	Postgres database password for GUM
DB_GUM_HOST	Postgres database hostname for GUM	localhost
DB_GUM_PORT	Postgres database port for GUM	5432
DB_GUM_NAME	Postgres database name for GUM	gum
DB_TM_JDBC_URL	JDBC URL for TM database	jdbc:postgresql://localhost:5432/gazelle [OPTIONAL]
DB_TM_USER	Postgres database user for TM	gazelle
DB_TM_PASSWORD	Postgres database password for TM
DB_TM_HOST	Postgres database hostname for TM	localhost
DB_TM_PORT	Postgres database port for TM	5432
DB_TM_NAME	Postgres database name for TM	gazelle
DEBUG	Enable keycloak remote debug mode	false
DEBUG_PORT	Set keycloak debug port	*:18787
DEV_MODE	Start keycloak in dev mode	false
GZL_EXTERNAL_PROVIDER_JAR_URLS	The list of urls of external jars to be retrieve	http://localhost/file1.jar,http://localhost/file1.jar
GZL_SSO_DEFAULT_LOCALE	The default language used for user interface, only works when migrating	en
GZL_TM_URL	Gazelle-tm url	http://localhost:8080/gazelle
GZL_SSO_LOGO_URL	The url of the customer logo displayed on the login page	http://localhost:8080/gazelle/mylogo.png
GZL_USER_MANAGEMENT_FRONT_URL	The url of the user management front application	http://localhost:3000/gum-ui
GZL_TERMS_OF_SERVICE_URL	Terms of service url	http://localhost:3000/tos
GZL_SSO_ADMIN_EMAIL	The email of the user with manage-client role	Default: [e-mail]
GZL_SSO_ADMIN_USER	The username of the user with manage-client role	gazelle-clients-admin
GZL_SSO_ADMIN_PASSWORD	The password of the user with manage-client role	password
GZL_SSO_URL	The URL of the SSO server.	http://localhost:28080
GZL_SSO_REALM	The realm to use	gazelle
KC_HTTP_PORT	The HTTP port used by the Keycloak instance	28080
KC_HTTP_PATH	The HTTP path used by the Keycloak instance (used behind reverse proxy)	/auth
KC_HTTP_RELATIVE_PATH	The relative HTTP path (used behind reverse proxy)	/auth
KC_HOSTNAME_URL	The hostname url used by the Keycloak instance (used behind reverse proxy)	https://production/auth
KC_HOSTNAME_PATH	The hostname path used by the Keycloak instance (used behind reverse proxy)	/auth
KC_PROXY	The proxy mode used by the Keycloak instance	edge
KC_SPI_CONNECTIONS_HTTP_CLIENT_DEFAULT_SOCKET_TIMEOUT_MILLIS	Setup Socket inactivity timeout to any outside http request.	10000
KEYCLOAK_ADMIN_USER	The username of the Keycloak admin	admin
KEYCLOAK_ADMIN_PASSWORD	The password of the Keycloak admin	password
ROOT_TEST_BED_URL	Test bed root url	http://localhost
SMTP_SSL_ENABLED	Enable SSL for SMTP	false
SMTP_FROM_DOMAIN	Configure from domain (default equals to FQDN variable)	localhost
SMTP_MOCK_ENABLED	Enable mock SMTP server	false
SMTP_USERNAME	SMTP username for authentication
SMTP_PASSWORD	SMTP password for authentication
SMTP_PORT	SMTP server port	25
SMTP_HOST	SMTP server hostname	localhost
JWT_VERIFY_PUBLIC_KEY_LOCATION	The location of the public key used to verify the JWT token	${GZL_SSO_URL}/realms/gazelle/protocol/openid-connect/certs
JWT_VERIFY_ISSUER	The issuer of the JWT token	${GZL_SSO_URL}/realms/gazelle

See the official documentation of Keycloak for more information about the environment variables.

Applications deployment (for dev)

Deploy with Maven

The first possibility is to deploy GUM with maven-docker-plugin. This process is useful for integrations tests.

mvn -f gazelle-keycloak/keycloak-provider/pom.xml docker:start

Keycloak should be available by default at http://localhost:28080/.

The list of applications that will be deployed :

• gazelle-database (https://gitlab.inria.fr/gazelle/private/industrialization/docker/gazelle-database)

• gazelle-user-management-keycloak (The keycloak instance)

• gazelle-user-management-quarkus (The GUM backend)

• Mailhog for testing mails (https://github.com/mailhog/MailHog)

Check the logs

docker logs -f user-management/user-management

ℹ️ Tips: you can add the flag -Ddocker.follow to your command to automatically follow the logs.

Stop the services

mvn -f gazelle-keycloak/keycloak-provider/pom.xml docker:stop

Deploy with Compose

For end-to-end testing you can use the docker-compose to deploy the applications that you need.

Requirements

• Data for gazelle-tm

• Environment files (.env)

1) Start the database

docker compose up -d gazelle-database

2) Import data [First deployment only]

psql -h localhost -U gazelle -d postgres -c "CREATE DATABASE gazelle;"
psql -h 127.0.0.1 -U gazelle gazelle < ./gazelle-tm-dev-database.sql

3) Configure realm [Optional]

Copy your realm to /opt/keycloak/data/import/ (create folders if necessary) if additional realms are required.

sudo cp ./realm-gazelle.json /opt/keycloak/data/import/

4) Start GUM

docker-compose up -d gazelle-user-management-keycloak gazelle-user-management-quarkus

How to configure the gazelle realm

To understand better how the gazelle realm works and how to configure it, see Keycloak administrator manual.

Configuration to integrate a CAS Client

In CAS file .properties of your client application:

casServerUrlPrefix="http://localhost:28080/realms/gazelle/protocol/cas"
casServerLoginUrl="http://localhost:28080/realms/gazelle/protocol/cas/login"
casLogoutUrl="http://localhost:28080/realms/gazelle/protocol/cas/logout"
service|serverName=${your.app.service|server.name}

License

```
Copyright [xxxx]-[xxxx] IHE International

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```