This is a work in progress. It is synchronized with the master
branch of TIER/midPoint_container GitHub project.
Introduction
Here we describe Docker image for midPoint that is to be used within the TIER IdM environment.
The image 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 this image 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.
Building your own image
This is the preferred option until midPoint dockerization is finished and a stable image is uploaded to the Docker Hub.
$ git clone https://github.internet2.edu/TIER/midPoint_container.git $ cd midPoint_container/midpoint $ ./build.sh $ docker-compose up --build
Using existing images
This is faster but currently carries the risk of using obsolete images.
$ git clone https://github.internet2.edu/TIER/midPoint_container.git $ cd midPoint_container/midpoint $ docker-compose up --no-build
After build
After docker-compose up
command successfully finishes you should see something like this on the console:
midpoint-server_1 | midpoint;midpoint.log;demo;;2018-09-20 16:25:22,191 [] [main] INFO (org.springframework.boot.web.embedded.tomcat.TomcatWebServer): Tomcat started on port(s): 8080 (http) 9090 (http) with context path '/midpoint' midpoint-server_1 | midpoint;midpoint.log;demo;;2018-09-20 16:25:22,209 [] [main] INFO (com.evolveum.midpoint.web.boot.MidPointSpringApplication): Started MidPointSpringApplication in 60.512 seconds (JVM running for 61.688)
Now 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 the MariaDB database created from the TIER MariaDB image. |
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. See Alternative repository demonstration section below for more information.
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 from the outside.)
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 (internal) | Volume name (externally visible) | Description | Used by container |
---|---|---|---|
midpoint_home | midpoint_midpoint_home | The midPoint home directory. Contains schema extensions, logs, custom libraries, custom ConnId connectors, and so on. | midpoint-server |
midpoint_data | midpoint_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
Or like this:
$ env 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.
Configuring specific midPoint features
In this section we describe how to configure and use specific features of this midPoint dockerization.
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 |
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: MySQL: PostgreSQL: SQL Server: Oracle: |
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, 5432, 1433, 1521 for MariaDB/MySQL, PostgreSQL, SQL Server and Oracle, respectively |
REPO_DATABASE | Specific database to connect to. Used to construct the URL. | registry |
REPO_USER | User under which the connection to the database is made. | registry_user |
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. This is ensured using Shibboleth SP (service provider) module for Apache httpd configured as reverse proxy for midPoint. |
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 |
SSO_HEADER | Shibboleth attribute to be used as a login identifier. It is matched against name property of the user when logging in. When changing it, do not forget to change your Shibboleth IdP configuration as well as midPoint's shibboleth2.xml configuration file. | uid |
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 |
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 |
| 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
In order to quickly verify the Shibboleth integration feature of the standard midPoint container we have provided a sample Shibboleth composition in demo/shibboleth
directory. It contains a Shibboleth IdP container (idp
) and an LDAP directory container (directory
). They are to be started independently on midPoint.
Here we show how:
Starting Shibboleth containers
$ cd demo/shibboleth $ docker-compose up
Starting midPoint containers
$ cd midpoint $ env AUTHENTICATION=shibboleth docker-compose up
Logging in
Use https://localhost:8443/midpoint URL as before. This time you will be redirected to Shibboleth login screen where you enter username of administrator
and a password of password
.
These values are checked against LDAP directory. Then the uid
of administrator
is passed to midPoint as authenticated user's login name.
Alternative repository demonstration
In order to quickly verify the ability to configure alternative repository location we have provided a sample PostgreSQL container in demo/postgresql
directory. There are two ways how to invoke it:
- PostgreSQL can be started as part of the midPoint composition.
- PostgreSQL can be started independently of the midPoint composition.
Starting PostgreSQL as part of the midPoint composition
$ cd midpoint $ docker-compose -f docker-compose.yml -f ../demo/postgresql/midpoint-additions.yml up midpoint-server postgresql
The midpoint-additions.yml
composition file looks like this:
services: postgresql: build: ../demo/postgresql/postgresql/ environment: - POSTGRES_PASSWORD=password expose: - 5432 ports: - 5432:5432 networks: - back volumes: - postgresql_data:/var/lib/postgresql/data midpoint-server: environment: - REPO_DATABASE_TYPE=postgresql - REPO_HOST=postgresql - REPO_DATABASE=midpoint - REPO_USER=midpoint volumes: postgresql_data:
Notes:
- The first service declaration (
posgresql
) creates a container hosting the new repository. - The second service declaration (
midpoint-server
) adds a couple of environment variables needed to tell midPoint how to access the new repository.
You can safely ignore console messages like this:
postgresql_1 | ERROR: could not serialize access due to read/write dependencies among transactions postgresql_1 | DETAIL: Reason code: Canceled on identification as a pivot, during write. postgresql_1 | HINT: The transaction might succeed if retried.
This is a part of standard midPoint conflict resolution process. The mentioned transactions are really retried and they succeed eventually.
Starting PostgreSQL independently of the midPoint composition
$ cd demo/postgresql $ docker-compose up
and
$ cd midpoint $ docker-compose -f docker-compose.yml -f ../demo/postgresql/midpoint-additions-for-standalone-run.yml up midpoint-server
Here the additional compose file looks like this:
services: midpoint-server: environment: - REPO_DATABASE_TYPE=postgresql - REPO_HOST=postgresql - REPO_DATABASE=midpoint - REPO_USER=midpoint networks: - postgresql_net networks: postgresql_net: external: true
We need this file mainly to allow midpoint-server
container to directly communicate with the postgresql
host (via postgresql_net
network). Setting of the environment variables could be done also from the command line, as will be seen in the following example.
Note that the PostgreSQL database will be different from the database created in the first case. The first one resides in midpoint_postgresql_data
volume, this one in postgresql_data
volume.
Using an externally provided repository
Here we show how to use externally provided repository. We have chosen Oracle as an example; mainly because it requires adding custom drivers to midPoint.
The custom drivers reside in lib
subdirectory of midPoint home directory. The home directory is available as a Docker volume with a default name of midpoint_midpoint_home
(assuming midPoint was started at least once - so please if you have not started it, do it at least once with a standard configuration before trying this). After downloading the Oracle driver you can copy it into the appropriate place using e.g. for following command:
$ sudo cp ~/Downloads/ojdbc7.jar /var/lib/docker/volumes/midpoint_midpoint_home/_data/lib
Let us assume that our server is available on host 192.168.56.101
. We can then tell midPoint to connect to the Oracle database using the following command. (Do not forget to set the correct password in configs-and-secrets/midpoint/application/database_password.txt
as shown below.)
$ cd midpoint $ echo oracle > configs-and-secrets/midpoint/application/database_password.txt $ env REPO_DATABASE_TYPE=oracle REPO_HOST=192.168.56.101 REPO_USER=system docker-compose up midpoint-server
After successful start of midPoint you can login and check that the database is really an Oracle one.