Configuration - SSO

This page describes how to configure the authentication module of the Datachain solution, based on Keycloak. It is required when the solution is not connected to an external SSO.

Images can be configured via docker *.env files or environment variables.

This page describes the dc/keycloak image in version 9.0.18 (Keycloak 21.1), the current reference version.

SSO module - Image dc/keycloak

Image description

Description

Datachain authentication component. On first startup, it creates the dc-realm realm with the Datachain clients, roles and login theme. Data (users, groups, sessions) is stored in the keycloak PostgreSQL database.

Size

~620MB

Technical components

Keycloak 21.1 (Quarkus), started in edge proxy mode: TLS encryption is handled by the reverse proxy placed in front of the service. Adobis extensions: two OpenID Connect mappers for the user’s groups, and the datachain login theme.

User

keycloak (uid 1000, gid 0, group root)

Volumes

No volumes. Data is stored in the PostgreSQL database (see Data management, image dc/pg_keycloak or keycloak database of dc/dc_pg).

Logs

Module logs on the docker standard output

URLs

Port	URL	Purpose
8080	/auth	HTTP port of the service, under the `/auth` path: access to the Keycloak API by the other modules; user authentication interface; Keycloak administration console.
8080	/auth/health/ready	Health check: the image reports itself as healthy when this address answers `UP`. The check runs every 5 minutes, with an initial delay of 2 minutes.
8080	/auth/health, /auth/metrics	Monitoring (`KC_HEALTH_ENABLED` and `KC_METRICS_ENABLED`)
8443	-	HTTPS port exposed by the image, but with no certificate configured: TLS is handled upstream, by the reverse proxy.

Environment variables

For more information on native Keycloak configuration, see https://www.keycloak.org/server/all-config. The native variables (KC_*, KEYCLOAK_ADMIN*) keep their original meaning.

The passwords of the KC_DB_PASSWORD, KEYCLOAK_ADMIN_PASSWORD and DC_DEFAULT_ADMIN_PASSWORD variables can be provided through a docker secret, using the variable suffixed with _FILE that contains the file path. These are the only variables concerned: the general rule described in About environment variables does not apply to this image.

Database

Variable Default Description

Variable	Default	Description
KC_DB	postgres	Native Keycloak setting: database type. Do not modify.
KC_DB_URL_HOST	dc-pg-keycloak	DNS name of the PostgreSQL server. To be modified when using an external database.
KC_DB_URL_PORT	5432	PostgreSQL server port
KC_DB_URL_DATABASE	keycloak	Database name
KC_DB_USERNAME	postgres	Database user
KC_DB_PASSWORD	(image default value)	Password of the database user. To be modified, via this variable or `KC_DB_PASSWORD_FILE`.
KC_DB_PASSWORD_FILE	(empty)	Path of the file (docker secret) that contains the database password. If it exists, it replaces `KC_DB_PASSWORD`.

KC_DB

postgres

Native Keycloak setting: database type. Do not modify.

KC_DB_URL_HOST

dc-pg-keycloak

DNS name of the PostgreSQL server. To be modified when using an external database.

KC_DB_URL_PORT

5432

PostgreSQL server port

KC_DB_URL_DATABASE

keycloak

Database name

KC_DB_USERNAME

postgres

Database user

KC_DB_PASSWORD

(image default value)

Password of the database user. To be modified, via this variable or KC_DB_PASSWORD_FILE.

KC_DB_PASSWORD_FILE

(empty)

Path of the file (docker secret) that contains the database password. If it exists, it replaces KC_DB_PASSWORD.

Keycloak operation

Variable Default Description

Variable	Default	Description
KEYCLOAK_FRONTEND_URL	`http://localhost:8080/auth`	Public URL of Keycloak, including the `/auth` path, as used by browsers. It serves as the reference address (`hostname-url`) and as the token issuer. To be modified. Read at every startup.
KC_HEALTH_ENABLED	true	Enables the health check addresses
KC_METRICS_ENABLED	true	Enables the monitoring metrics
KC_FEATURES	token-exchange,admin-fine-grained-authz,scripts	Optional Keycloak features enabled: token exchange, fine-grained administration permissions and scripts

KEYCLOAK_FRONTEND_URL

http://localhost:8080/auth

Public URL of Keycloak, including the /auth path, as used by browsers. It serves as the reference address (hostname-url) and as the token issuer. To be modified. Read at every startup.

KC_HEALTH_ENABLED

true

Enables the health check addresses

KC_METRICS_ENABLED

true

Enables the monitoring metrics

KC_FEATURES

token-exchange,admin-fine-grained-authz,scripts

Optional Keycloak features enabled: token exchange, fine-grained administration permissions and scripts

Keycloak administrator

Administration account of the master realm, created by Keycloak on first startup.

Variable Default Description

Variable	Default	Description
KEYCLOAK_ADMIN	admin	Keycloak administrator login for the `master` realm
KEYCLOAK_ADMIN_PASSWORD	(image default value)	Password of this administrator. To be modified, via this variable or `KEYCLOAK_ADMIN_PASSWORD_FILE`.
KEYCLOAK_ADMIN_PASSWORD_FILE	(empty)	Path of the file (docker secret) that contains the password. If it exists, it replaces `KEYCLOAK_ADMIN_PASSWORD`.

KEYCLOAK_ADMIN

admin

Keycloak administrator login for the master realm

KEYCLOAK_ADMIN_PASSWORD

(image default value)

Password of this administrator. To be modified, via this variable or KEYCLOAK_ADMIN_PASSWORD_FILE.

KEYCLOAK_ADMIN_PASSWORD_FILE

(empty)

Path of the file (docker secret) that contains the password. If it exists, it replaces KEYCLOAK_ADMIN_PASSWORD.

Datachain realm

These variables are inserted into the dc-realm realm import file when the container starts. Keycloak only imports this file if the realm does not exist yet: they are therefore only taken into account on first startup. Afterwards, any change is made in the Keycloak administration console (clients, internationalization).

Variable Default Description

Variable	Default	Description
DATACHAIN_CLIENT_URL	`http://localhost:4200`	Public URL of Datachain. Populates the base address and the allowed redirect addresses (`<url>/`*) of the `dc_front` and `dc_core` clients. To be modified**.
DC_CONSOLE_CLIENT_URL	`http://localhost:4300`	Public URL of the Console. Populates the `dc_console` client. To be modified.
DC_MARKETPLACE_CLIENT_URL	`http://localhost:4400`	Public URL of the Marketplace. Populates the `dc_marketplace` client. To be modified.
INTERNALIZATION_ENABLED	true	Enables internationalization of the realm
INTERNALIZATION_LOCALES	`["fr","en"]`	Available languages (JSON format)
INTERNALIZATION_DEFAULT_LOCALE	fr	Default language

DATACHAIN_CLIENT_URL

http://localhost:4200

Public URL of Datachain. Populates the base address and the allowed redirect addresses (<url>/) of the dc_front and dc_core clients. *To be modified.

DC_CONSOLE_CLIENT_URL

http://localhost:4300

Public URL of the Console. Populates the dc_console client. To be modified.

DC_MARKETPLACE_CLIENT_URL

http://localhost:4400

Public URL of the Marketplace. Populates the dc_marketplace client. To be modified.

INTERNALIZATION_ENABLED

true

Enables internationalization of the realm

INTERNALIZATION_LOCALES

["fr","en"]

Available languages (JSON format)

INTERNALIZATION_DEFAULT_LOCALE

Default language

First Datachain administrator

These variables are only read by the image’s /create_default_admin_dc.sh script (see below).

Variable Default Description

Variable	Default	Description
DC_DEFAULT_ADMIN	admin	Login of the Datachain administrator created in the `dc-realm` realm
DC_DEFAULT_ADMIN_PASSWORD	(image default value)	Password of this administrator. To be modified, via this variable or `DC_DEFAULT_ADMIN_PASSWORD_FILE`.
DC_DEFAULT_ADMIN_PASSWORD_FILE	(empty)	Path of the file (docker secret) that contains the password. If it exists, it replaces `DC_DEFAULT_ADMIN_PASSWORD`.

DC_DEFAULT_ADMIN

admin

DC_DEFAULT_ADMIN_PASSWORD

(image default value)

Password of this administrator. To be modified, via this variable or DC_DEFAULT_ADMIN_PASSWORD_FILE.

DC_DEFAULT_ADMIN_PASSWORD_FILE

(empty)

Path of the file (docker secret) that contains the password. If it exists, it replaces DC_DEFAULT_ADMIN_PASSWORD.

The DC_DEFAULT_ADMIN_CREATE variable, present in the image, is not read by any script: it has no effect. The first Datachain administrator is not created automatically at startup.

Creating the first Datachain administrator

The imported realm contains no users. Once Keycloak has started, the image’s /create_default_admin_dc.sh script creates the Datachain administrator: it waits for Keycloak to be ready, then creates the DC_DEFAULT_ADMIN user in the dc-realm realm, assigns it its password and the realm-admin roles (realm-management client) as well as dc_admin, dc_user, dc_member and dc_project (dc_backend client). It uses the KEYCLOAK_ADMIN account of the master realm.

The script must be run only once, in the Keycloak container:

docker exec -i <keycloak container id> sh -c 'sh /create_default_admin_dc.sh'

The provided deployment examples (scripts/insert_first_admin.sh) run this command; see General principles.

Content of the imported realm

The dc-realm realm (display name DataChain) is created with the following characteristics:

login theme: datachain;
access token lifetime: 5 minutes; maximum SSO session idle time: 4 hours; maximum SSO session lifetime: 5 hours;
TLS required for external connections (sslRequired: external);
brute force attack protection: disabled;
SMTP server: an internal Adobis server is preconfigured. To be reconfigured in the Keycloak administration console (Realm settings, Email) so that Keycloak can send e-mails.

Realm clients:

Client Type Notes

Client	Type	Notes
dc_front	Public	Datachain web interface. Redirect allowed to `DATACHAIN_CLIENT_URL/` and to `https://oauth.powerbi.com/` (PowerBi connector).
dc_core	Confidential	Datachain Core module. Redirect allowed to `DATACHAIN_CLIENT_URL/*`.
dc_console	Confidential	Console module. Redirect allowed to `DC_CONSOLE_CLIENT_URL/*`.
dc_marketplace	Confidential	Marketplace module. Redirect allowed to `DC_MARKETPLACE_CLIENT_URL/*`.
dc_backend	Confidential, token access only (bearer-only)	Holds the Datachain roles: `dc_admin`, `dc_user`, `dc_member` and `dc_project`.
dc_backend_keycloak	Confidential, service account	Service account of the backend towards Keycloak.
dc_spark_backend	Confidential, service account	Service account of the Spark module.
dc_exposition	Public	Public client with direct access grants, without redirect address.

dc_front

Public

Datachain web interface. Redirect allowed to DATACHAIN_CLIENT_URL/ and to https://oauth.powerbi.com/ (PowerBi connector).

dc_core

Confidential

Datachain Core module. Redirect allowed to DATACHAIN_CLIENT_URL/*.

dc_console

Confidential

Console module. Redirect allowed to DC_CONSOLE_CLIENT_URL/*.

dc_marketplace

Confidential

Marketplace module. Redirect allowed to DC_MARKETPLACE_CLIENT_URL/*.

dc_backend

Confidential, token access only (bearer-only)

Holds the Datachain roles: dc_admin, dc_user, dc_member and dc_project.

dc_backend_keycloak

Confidential, service account

Service account of the backend towards Keycloak.

dc_spark_backend

Confidential, service account

Service account of the Spark module.

dc_exposition

Public

Public client with direct access grants, without redirect address.

The secrets of the confidential clients (dc_core, dc_console, dc_marketplace, dc_backend_keycloak, dc_spark_backend) are defined in the import file provided with the image: they are identical on all installations. They must be regenerated in the Keycloak administration console (client, Credentials tab), then copied into the configuration of the modules concerned: see the pages Datachain Core, Console and Marketplace.

Configuration file

Example of a keycloak.env file for a Docker Swarm deployment (values between angle brackets must be replaced):

# Public addresses
KEYCLOAK_FRONTEND_URL=https://<keycloak domain name>/auth
DATACHAIN_CLIENT_URL=https://<datachain domain name>
DC_CONSOLE_CLIENT_URL=https://<console domain name>
DC_MARKETPLACE_CLIENT_URL=https://<marketplace domain name>

# Database
KC_DB_URL_HOST=<postgresql host>
KC_DB_URL_DATABASE=keycloak
KC_DB_USERNAME=<user>
KC_DB_PASSWORD_FILE=/run/secrets/kc_db_password

# Administrators
KEYCLOAK_ADMIN=<keycloak administrator>
KEYCLOAK_ADMIN_PASSWORD_FILE=/run/secrets/kc_admin_password
DC_DEFAULT_ADMIN=<datachain administrator>
DC_DEFAULT_ADMIN_PASSWORD_FILE=/run/secrets/dc_admin_password

The service must be exposed by the reverse proxy under the /auth path to port 8080 (for example with Traefik, a rule such as Host(…) && PathPrefix(/auth`)`).

Dernière mise à jour le 2 novembre 2026 à 15:16