Skip to end of metadata
Go to start of metadata

Introduction

This HOWTO describes an installation and configuration of midPoint in Ubuntu Linux environment. MidPoint will run in Apache Tomcat web container. Apache web server will be placed in front of it as a reverse proxy. MidPoint repository will be maintained in PostgreSQL database running on the same host.

Note: all commands specified in this tutorial should be run as root. Therefore either prefix them with sudo or execute sudo -s at the beginning of installation session.

Install Java JDK

We recommend using the OpenJDK 8 that is distributed with Ububtu (16.04 LTS):

If you prefer Sun JDK or if there is no OpenJDK 8 in your distribution then download Sun JDK from oracle.com and install it. Just make sure it is JDK version 8.

Java 8 only

MidPoint 3.5 is supported only on Java 8 platforms. MidPoint supported both Java 7 and Java 8 for several years. The support for Java 7 was deprecated in midPoint 3.4.1 and it was removed in midPoint 3.5. It is finally the time to abandon obsolete technology and to move on.

Installing JCE Extension

The JCE Unlimited Strength extension provides a full-strength cryptography for Java. It is usually good idea to install it if it is legal under your jurisdiction. The files can be downloaded from oracle.com. Look for Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. Choose version appropriate for your JDK version.

Unzip the archive and copy the two jar files to /opt/java/jre/lib/security. It may be a good idea to back up the original files before doing this.

Install Apache Tomcat

Download tomcat 8 binary installation package from Apache website.

Unpack the tomcat to /opt. This creates /opt/apache-tomcat-8.5.4 or similar directory. Make a symlink for easier management:

Create tomcat user (remember to make sure /usr/sbin/nologin is an allowed shell in /etc/shells file - otherwise the init.d script will fail):

Change ownership of the installed files:

Create init.d script for tomcat:

/etc/init.d/tomcat

Add execution permissions to tomcat script:

 

We don't want tomcat to be accessible directly from the network. Therefore let's configure it to listen only on localhost address. Edit the /opt/apache-tomcat/conf/server.xml file and add address attribute to each <Connector> definition. Like this:

/opt/apache-tomcat/conf/server.xml

Install and Configure Apache

Install Apache ubuntu package:

Enable rewrite, proxy and proxy_http modules:

Configure the proxy to tomcat in appropriate apache site definition:

/etc/apache2/sites-available/default

If midPoint is the only (or the main) application on this host then you might also want to configure a redirect:

/etc/apache2/sites-available/default

Reload apache configuration:

Install PostgreSQL

Install PostgreSQL ubuntu package:

Create user in the database (remember the password):

Create a database:

Select appropriate SQL schema script for your midPoint version (Download script from Raw tab):

Execute the script to create database schema (tables, indexes, etc.):

(The "WARNING:  there is no transaction in progress" is OK)

The database is now ready.

Deploy and Set Up midPoint

Stop tomcat (if it is running):

Download or build midpoint.war. Place it into /opt/apache-tomcat/webapps directory.

Create midPoint home directory. This directory contains midpoint startup configuration, keystore, connector code and similar things. According to UNIX conventions the best place is perhaps /var/opt directory but use whatever place suits your installation. Also make sure it can be accessed by tomcat:

Edit tomcat startup file /opt/apache-tomcat/bin/catalina.sh to tweak its parameters. We need this to let midpoint know where is the location of its home directory and also to modify the default Java memory settings. Place this line somewhere near the beginning of the file:

/opt/apache-tomcat/bin/catalina.sh

Start tomcat now:

Tomcat should pick up the WAR file and deploy the application. This may take a minute or so. The /opt/apache-tomcat/webapps/midpoint directory should appear. You can follow the deployment process by tailing /opt/apache-tomcat/logs/catalina.out. You can watch pre process of midpoint startup and initialization by tailing /opt/apache-tomcat/logs/idm.log (this happens after the deployment). After midpoint starts the directory /var/opt/midpoint should be populated with several files and subdirectories.

Midpoint starts with a default settings. This means that it is using an embedded H2 database for storing files. We want to change this to PostgreSQL. The setting is in the midpoint home directory (/var/opt/midpoint) in config.xml file. This file is read during midpoint start. Therefore let's first stop tomcat together with deployed midpoint:

Edit the config.xml file midpoint home directory (/var/opt/midpoint). Change the <repository> section to refer to the PostgreSQL database created above. Do not forget to substitute the real password for midpoint PostgreSQL user in the <jdbcPassword> element.

/var/opt/midpoint/config.xml

Note that JDBC driver for PostgreSQL is already bundled in midPoint, there is no need to install it explicitly.

MidPoint initialized its embedded database repository during the first start. This is no longer needed and it may be deleted to free some space and avoid confusion. The databases are in  *.h2.db files:

Now it is the time to start tomcat and midPoint:

Optional Post-Installation Steps

Change Encryption Key

Encryption is used in midPoint to protect sensitive parts of the database such as passwords. The encryption key is not stored in the database (that would be really meaningless). It is stored in standard Java JCE keystore that is located in midPoint home directory by default. First start of midPoint generates and encryption key for you. But it generates a short encryption key that is suitable both for use by export-limited and full-strength cryptography modules. Therefore is full-strength JCE extension was installed it is recommended to change the encryption key to a full-strength key. It can be achieved by keytool utility.

First stop tomcat:

Generate new key with a keytool command:

That command will create a new 256-bit AES key with alias strong. Now reconfigure midPoint to use the new key. Edit the config.xml file to change encryption key alias. Also make sure a strong algorithm is specified:

/var/opt/midpoint/config.xml

Start tomcat again:

See Encryption and Keys and Keystore Configuration pages for more information.

Enjoy

MidPoint is now up and running. You can access the administration gui at:

Username

administrator

Password

5ecr3t

For more information how to customize and run midPoint please see:

External links

  • No labels