Gazelle User Management

Readme

This repository contains User Management modules for Gazelle.

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

NameDescriptionValue Example

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_USER

Postgres database user for TM

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_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: indus@kereval.com

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.
```

Last updated