This is a work in progress.

Here we describe Docker images for midPoint that are to be used within the TIER IdM environment.

The images can be found in the TIER/midPoint_container GitHub project in the midpoint directory. (Besides that, the project contains a demonstration of the use of these containers in a wider environment consisting of Grouper, Shibboleth, LDAP directory, RabbitMQ messaging, and sample source and target systems.)

Getting started

The easiest way how to start dockerized midPoint is to use provided docker-compose.yml file. There are the following two options.

Using existing images

TODO this does not work yet

$ git clone https://github.internet2.edu/TIER/midPoint_container.git
$ cd midPoint_container/midpoint
$ docker-compose up --no-build

Building your own images

$ git clone https://github.internet2.edu/TIER/midPoint_container.git
$ cd midPoint_container/midpoint
$ ./download-midpoint
$ docker-compose up --build

After docker-compose up command finishes you can log into midPoint using https://localhost:8443/midpoint URL, with an user of administrator and a password of 5ecr3t. For Shibboleth authentication demonstration, please visit Shibboleth authentication demonstration section below.

Containers

The default composition contains two containers:

Container name	Description
`midpoint-server`	This is a container providing midPoint functionality. It contains standalone Tomcat running midPoint application, reverse Apache proxy (providing Shibboleth authentication, if needed), and TIER Beacon.
`midpoint-data`	This container hosts midPoint repository. It contains MariaDB database pre-configured to be used with midPoint.

You can either use these two containers together, or you can replace midpoint-data with your own Docker container, or even external repository implementation - either on-premises or in cloud.

Communication

By default, containers publish the following TCP ports. (Port mapped to localhost denotes the mapping of container port to the host port, where it can be reached.)

Container	Port number	Port mapped to localhost	Description
`midpoint-server`	443	8443	HTTPS port to be used to connect to midPoint application.
	80	-	HTTP port to be used to connect to midPoint application.
	9090	-	Tomcat AJP port used for Apache httpd ↔ Tomcat communication.
`midpoint-data`	3306	3306	Port used to connect to the default MariaDB repository.

Docker volumes

The following volumes are created to persist data and other relevant files.

Volume name	Description	Used by container
`midpoint_home`	The midPoint home directory. Contains schema extensions, logs, custom libraries, custom ConnId connectors, and so on.	`midpoint-server`
`midpoint_data`	Volume hosting MariaDB database used by midPoint.	`midpoint-data`

Configuring the containers

These containers are configured by the following means.

Environment variables

Some parameters are configured by setting environment variables. For example:

$ export ENV="test" USERTOKEN="3.9" MEM="4096m"
$ docker-compose up

Docker secrets and configs

Secrets and configs are stored in the configs-and-secrets directory. They are provided to midPoint containers in appropriate ways. (Currently, secrets are passed as Docker secrets, configs are mounted as volumes. This might be changed in the future.) For detailed information on individual items please see the following sections.

Logging

Logging is configured by setting the following environment variables:

Environment variable	Meaning	Default value
`ENV`	environment (e.g. prod, dev, test)	`demo`
`USERTOKEN`	arbitrary user-supplied token	current midPoint version, e.g. `3.9-SNAPSHOT`

According to the specification, semicolons and spaces in these fields are eliminated (replaced by underscores).

Repository

Repository configuration is done via the following environment variables.

Environment variable	Meaning	Default value
`REPO_DATABASE_TYPE`	Type of the database. Supported values are `mariadb`, `mysql`, `postgresql`, `sqlserver`, `oracle`. It is possible to use `H2` as well but H2 is inappropriate for production use.	`mariadb`
`REPO_JDBC_URL`	URL of the database.	MariaDB: `jdbc:mariadb://$REPO_HOST:$REPO_PORT/$REPO_DATABASE?characterEncoding=utf8` MySQL: `jdbc:mysql://$REPO_HOST:$REPO_PORT/$REPO_DATABASE?characterEncoding=utf8` PostgreSQL: `jdbc:postgresql://$REPO_HOST:$REPO_PORT/$REPO_DATABASE` SQL Server: `jdbc:sqlserver://$REPO_HOST:$REPO_PORT;database=$REPO_DATABASE` Oracle: `jdbc:oracle:thin:@$REPO_HOST:$REPO_PORT/xe`
`REPO_HOST`	Host of the database. Used to construct the URL.	`midpoint-data`
`REPO_PORT`	Port of the database. Used to construct the URL.	`3306`
`REPO_DATABASE`	Specific database to connect to. Used to construct the URL.	`midpoint`
`REPO_USER`	User under which the connection to the database is made.	`root`
`REPO_PASSWORD_FILE`	File (e.g. holding a docker secret) that contains the password for the db connection.	`/run/secrets/m_database_password.txt`

Besides that, the following Docker secrets are used:

Secret	Meaning	Location
`m_database_password.txt`	The default location of the password used to connect to the database	`configs-and-secrets/midpoint/application/database_password.txt`

Authentication

This midPoint dockerization supports two authentication mechanisms.

Mechanism	Description
`internal`	Users are authenticated against midPoint repository. Login name to be used is the `name` property of the user, and the password is `credentials/password/value` property.
`shibboleth`	Users are authenticated against Shibboleth IdP. (TODO)

Authentication configuration is done using the following environment variables.

Environment variable	Meaning	Default value
`AUTHENTICATION`	Authentication mechanism to use	`internal`
`LOGOUT_URL`	URL to be used for logout (for Shibboleth authentication)	`https://localhost:8443/Shibboleth.sso/Logout`

Besides variables, the following secrets and configs are used for Shibboleth-based authentication.

Item	Kind	Meaning	Location
`idp-metadata.xml`	config	Metadata related to Shibboleth identity provider	`configs-and-secrets/midpoint/shibboleth/idp-metadata.xml`
`shibboleth2.xml`	config	Service provider configuration	`configs-and-secrets/midpoint/shibboleth/shibboleth2.xml`
`m_sp-cert.pem`	config	Service provider certificate	`configs-and-secrets/midpoint/shibboleth/sp-cert.pem`
`m_sp-key.pem`	secret	Service provider private key	`configs-and-secrets/midpoint/shibboleth/sp-key.pem`

Other

Other aspects can be configured using the following variables and Docker secrets or configs.

Environment variable	Meaning	Default value
`MEM`	The limit for Java help memory (`-Xmx` setting)	2048M
`KEYSTORE_PASSWORD_FILE`	File (e.g. holding a docker secret) that contains the password for the midPoint keystore	`/run/secrets/m_keystore_password.txt`

Other configs/secrets are:

Item	Kind	Meaning	Location
`m_keystore_password.txt`	secret	Java keystore password used by midPoint e.g. to encrypt sensitive information stored in the repository.	`configs-and-secrets/midpoint/application/keystore_password.txt`
`m_host-key.pem`	secret	Private key for Apache HTTPS	`configs-and-secrets/midpoint/httpd/host-key.pem`
`host-cert.pem`	config	Certificate for Apache HTTPS	`configs-and-secrets/midpoint/httpd/host-cert.pem`

Shibboleth authentication demonstration

TODO

Alternative repository demonstration