datavirtuality/dv-auth-mgmt repository overview

⁠CData Virtuality Authentication Management Component

⁠How to use this image

⁠Database configuration

The CData Virtuality Authentication Management Component application requires an external database server to be connected for normal work. The database server connection details along with credentials and other settings can be passed to the service using environment variables:

• KC_DB - the type of the database server connected. Possible values and servers are:
  • mariadb - MariaDB server,
  • mysql - MySQL Database server,
  • mssql - Microsoft SQL Server,
  • oracle - Oracle Database,
  • postgres - PostgreSQL server.
• KC_DB_URL_DATABASE - the database name to use for the service.
• KC_DB_SCHEMA - the database schema to be used.
• KC_DB_URL_HOST - the hostname of the default JDBC URL of the chosen vendor.
• KC_DB_URL_PORT - the port of the default JDBC URL of the chosen vendor.
• KC_DB_USERNAME - the username of the database user.
• KC_DB_PASSWORD - the password of the database user.

The above variables are minimal required to attach a database for the Authentication Management Component; there are a few more that allow to set connection details:

• KC_DB_POOL_INITIAL_SIZE - the initial size of the connection pool.
• KC_DB_POOL_MAX_SIZE - the maximum size of the connection pool.
• KC_DB_POOL_MIN_SIZE - the minimal size of the connection pool.

⁠HTTP configuration

⁠Base HTTP parameters

Additionally, the service requires a few settings to be set for HTTP protocol depending on how exactly Authentication Management Component will be set and how exactly it will be accessed.

First, if the service is supposed to run behind a balancer or reverse proxy, then the plain HTTP should be explicitly enabled:

• KC_HTTP_ENABLED - this enables HTTP.

It may also make sense to explicitly set the port which the HTTP server will be listening:

• KC_HTTP_PORT - default value is 8080.

Also, the service has to be informed which type of headers will bring the proxy information:

• KC_PROXY_HEADERS - possible values are:
  • forwarded
  • xforwarded

Additionally, if your reverse proxy overwrites the Host header, then dynamically resolving the hostname should be enabled:

• KC_HOSTNAME_STRICT - should be set to true to enable resolving, false otherwise. If disabled, the hostname must be explicitly set.

If, on the other hand, the service is supposed to be accessed directly, then the HTTP connection must be secured with TLS/SSL. In this case, the HTTPS port has to be set:

• KC_HTTPS_PORT - default value is 8443.

⁠SSL/TLS parameters

Besides the above, an SSL certificate has to be provided to secure the connection. Here are the variables that sets the certificates:

• KC_HTTPS_CERTIFICATE_FILE - the file path to a server certificate or certificate chain in PEM format.
• KC_HTTPS_CERTIFICATE_KEY_FILE - the file path to a private key in PEM format.

The certificates files must be present in the container by either attaching a volume that contains those files or building a new image on top of this base image embedding those files into the image.

In addition to the above, the hostname must also be configured:

• KC_HOSTNAME - set the hostname that the service will be accessed with.

⁠Default administrator account

• On the first container start against a new, empty database, a default administrator user is created.
• Username: admin
• Password: admin
• Sign in to the Admin Console at http://<hostname>:<port>/
• This account is created only on the first startup per database; subsequent runs use the administrator stored in the database.

Note: At first login CData Virtuality Authentication Management Component shows a pop-up: "Temporary admin user account. Ensure it is replaced with a permanent admin user account as soon as possible." Follow this procedure:

1. Log in as admin.
2. Create a permanent user and set a non-temporary password.
3. Grant admin privileges: Users → your user → Role mapping → Assign role → Filter by realm roles → assign admin.
4. Log out and log back in as the new user to verify admin access.
5. Remove or disable the default admin user.

⁠Docker example

Here is an example of a docker run command that starts a CData Virtuality Authentication Management Component container with a PostgreSQL database attached, a volume with certificates mounted, and HTTPS communication:

docker run --name cdv-auth-service \
-p 8443:8443 \
-v <host filesystem path>:/opt/ssl \
-e KC_HOSTNAME=<hostname> \
-e KC_HTTPS_PORT=9443 \
-e KC_HTTPS_CERTIFICATE_FILE=/opt/ssl/cert.pem \
-e KC_HTTPS_CERTIFICATE_KEY_FILE=/opt/ssl/key.pem \
-e KC_DB=postgres \
-e KC_DB_SCHEMA=<schema> \
-e KC_DB_URL_HOST=<server host> \
-e KC_DB_URL_PORT=5432 \
-e KC_DB_USERNAME=<username> \
-e KC_DB_PASSWORD=<password> \
datavirtuality/dv-auth-mgmt:26.1.4