Introduction

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

This page shows how to get started with a Docker image for the midPoint component of the InCommon Trusted Access Platform.

Anchor
prerequisites prerequisites

Prerequisites

In order to set up and run this container and associated demonstrations, you need a Linux machine with a reasonably recent Docker and docker-compose installation. The most advanced demo/grouper optionally uses an LDAP browser, e.g. Apache Directory Studio that itself requires Java.

This container and demos were tested on Ubuntu 18.04.1 LTS with

• Docker 18.06.1-ce,
• docker-compose 1.17.1 (and 1.22.0),
• libxml2-utils package (in order to have xmllint command available),
• Apache Directory Studio 2.0.0.v20170904-M13 with OpenJDK 8.

The LDAP browser is really optional. It is used only to check that LDAP objects are created correctly. You can safely proceed without it.

It seems that the usual way of installation via e.g. apt-get does not always guarantee sufficiently recent versions of Docker and docker-compose. To have the latest stable versions you can use procedures described here:

• https://docs.docker.com/install/linux/docker-ce/ubuntu/#install-docker-ce
• https://docs.docker.com/compose/install/

Also, make sure appropriate ports are available on the host machine. They are listed in the documentation to individual demonstrations; usually they are 8443 and 3306, sometimes 389, 443, or 5432. The demo/grouper needs even more free ports, please see the description.

Getting started (simple demo)

The image cannot be "run" by itself as it requires a midPoint repository - i.e. an SQL database - to execute. So the easiest way to start dockerized midPoint is to use one of the provided demonstrations. The most logical choice for just getting started with midPoint is demo/simple.TODO this does not work yet

$ git clone https://github.internet2.edu/TIERDocker/midPoint_container.git
$ cd midPoint_container/midpointdemo/simple
$ docker-compose up --no-build

Building

...

own images

The above commands download TAP midpoint image from Internet2's enterprise github. Alternatively, you can build this image yourself. Here is how:

$ git clone https://github.internet2.edu/TIERDocker/midPoint_container.git
$ cd midPoint_container/midpoint
$ ./build.sh
$ cd .demo/download-midpointsimple
$ docker-compose up --build

(Note the build.sh has a -n switch that skips downloading the midPoint distribution archive, saving some time during repeated builds.)

After starting

After docker-compose up command successfully finishes you should see something like this on the console:

midpoint-_server_1  | midpoint;midpoint.log;demo;3.9-SNAPSHOT;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;3.9-SNAPSHOT;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:

...

. If you are using midPoint 4.8.1 or greater please check the documentation on how to set an initial password. 

Beyond the simple demo

Besides the midPoint image itself, and the simple demo discussed above, the project contains demonstrations that integrate midPoint with selected other components

Configuring the container (general information)

The lowest level of configuration of the midPoint container is during its inclusion into a Docker composition. There is the full set of environment properties and other configurable items (e.g. Docker secrets and configs) available.

During the composition some of the environment properties can be made accessible from the outside. This depends strictly on the compositor. The demonstrations here show some of the options.

How to set environment variables after composition is done

After the composition is done, you can set the environment variables like this

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

...

Docker volumes

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

...

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="34.0.91" MP_MEM="4096m"
$ docker-compose up

...

$ env ENV="test" USERTOKEN="34.0.91" MP_MEM="4096m" docker-compose up

How to set Docker secrets and configs

Secrets The way of accessing secrets and configs is specific to the composition. In our demonstrations these 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

...

container 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:

...

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.

...

For automatic schema creation and upgrade options please see Schema creation and updating section in midPoint documentation.

Note that in order to connect to the database you have to provide the password. For security reasons, we use the indirect way through file access. So, typically you provide the following Docker secret:

Of course, you can provide the password file in any other way, assuming you correctly set REPO_PASSWORD_FILE environment variable.

Logging

Logging is configured by setting the following environment variables:

According to the specification, semicolons and spaces in these fields are eliminated. We decided to replace them by underscores.

Authentication

This midPoint dockerization supports two authentication mechanisms.

Authentication configuration is done using the following environment variables.

TODO describe/support the use of SSO_HEADER variable

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

Note that besides these variables you have to provide the following files. They are necessary for the Shibboleth service provider module.

And the following Docker secrets are to be provided:

Other

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

Other files that are necessary for this midPoint container to function Other configs/secrets are:

...

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:

Start Shibboleth containers

$ cd demo/shibboleth
$ docker-compose up

Start midPoint containers

$ cd midpoint
$ env AUTHENTICATION=shibboleth docker-compose up

Try to login

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.

Image Removed

These values are checked against LDAP directory. Then the uid of administrator is passed to midPoint as authenticated user's login name.

...

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:

1. PostgreSQL can be started as part of the midPoint composition.
2. 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:

1. The first service declaration (posgresql) creates a container hosting the new repository.
2. 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, 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.)

And the following Docker secrets are to be provided:

...

...

...

...

Guiding requirements for this project: TIER Docker Container Specification

After successful start of midPoint you can login and check that the database is really an Oracle one.

...