MidPoint Quick Start Guide

Last modified 18 Nov 2024 02:48 +01:00
Table of Contents

This guide describes steps how to run midPoint, a comprehensive open source identity management and governance platform.

In order to have full feature set available, there are requirements to utilized midpoint native repository. To be able quickly and easily start the environment, the containers are the preferred way. There is a docker-compose file available for quick start. In case you have more complex environment, a focused part of the docs with specific information for your use case is available.

Quick start using Docker compose

For the docker compose, the docker environment is required. The requirement for this environment is the availability of the docker engine.

Docker documentation related to installation based on OS:

  • Linux - Docker engine
    The docker engine can directly be installed.

  • Windows - Docker Desktop
    Fot the windows, the docker engine is only available as a part of Docker Desktop application. Any install configuration of docker Desktop is suitable for our purpose. Feel free to follow the default setting during the installation process.

For working midPoint environment, more than just one application is needed. To be able to address this complexity we prepared a description file, which can be easily processed - docker compose file. This file contains the definition for all parts and also provides necessary settings. The benefit for the user is that it can be "simply run" and the isolated working environment is available for you. If you are curious about the content, check the documentation related to the installation using the containers.

The following commands are the same for all Linux and Windows.

  • Linux
    It can be directly run in the terminal.

  • Windows
    For the following command run the command line.

Download the docker compose file.

All objects based on the docker compose file will contain the name of directory as a prefix.

To download you can use curl command or preferred browser using the link to github.

Get available docker compose definition (@github)
curl -O https://raw.githubusercontent.com/Evolveum/midpoint-docker/master/docker-compose.yml

Once the file is available we can start the environment (we are still in terminal / command line).

start the environment in background
docker compose up -d

It will take some time to start. For few seconds the web GUI will not be available - it is expected. There is initiation in progress - starting, loading init object to empty repository, etc.

In case you want to stop the container, use the following command. .stop the environment

docker compose down

This command will stop the container but keep it defined - allocated the space. The data stay available for next run.

To reset environment (clean up the data) you can use the following command:

stop the midPoint environment and clean up the relevant data
docker compose down -v

Using -v parameter cause removing also the volumes. Volumes are the space where the data is stored out of the container - persistent storage over the container remove / re-create.

In other words also user data related to the container will be removed - e.g. content of the DB (repository).

As a summary here is table with the most often used command.

Table 1. Summary available commands with docker compose.
Command Result

docker compose up -d

Start the environment based on docker-compose file content

docker compose down

Stop the environment (the stored data is kept)

docker compose down -v

Stop the environment and clean up the relevant data

docker ps -a

List of currently used containers in the system.

In case you have installed Docker Desktop you have additionally also GUI available to start and stop the environment. There is no additional feature in comparison to command line usage.

The services from docker compose file are grouped. The name of group is the name of directory where the docker compose file is located.

After first docker compose up command the environment is available in the list. On the related row in the list there are buttons with allowed actions start/stop and remove.

dockerDesktop
Figure 1. Docker desktop with midPoint environment

MidPoint User Interface

MidPoint has a web administration user interface. This is a primary user interface to use and configure midPoint. By default, the user interface is accessible at port 8080:

http://localhost:8080/midpoint/

Logging In

Please log in to user interface as an administrator user.

Username

administrator

Password

Test5ecr3t

For the security reason there is not default password. With the first run there is initiated administrator user. If the required password is not set, a generated one is there.

The password Test5ecr3t is set by the configuration in provided docker compose file.

For more information see Administrator Initial Password doc page.

In the releases before 4.8.1 (up to 4.8) there were default Password 5ecr3t. In case you are running one of these version there is following default credentials.

Username

administrator

Password

5ecr3t

Take A Look Around

Administrator is an all-powerful user, therefore all the capabilities of midPoint are at your disposal. Feel free to take a look around. Some places of the user interface may be confusing, but you certainly find some familiar places as well.

  • Self service part of the interface is used to manage the identity and privileges of a user that is currently logged in.

  • Administration part of the user interface is used to manage user identities, roles, organizational structure and policies. This part is used for routine administration of the system. At this stage, this is perhaps the most interesting part of midPoint to explore.

  • Configuration part of the user interface is used to customize midPoint behavior, going deep into midPoint internals.

midpoint gui

Terminology

MidPoint is using terminology that is quite common in the identity management field, however it may be slightly confusing for people coming from other fields. Following list explain basic midPoint terms:

  • User means user record (profile) in midPoint database. This data record usually contains unified data, synchronized from source systems.

  • Resource is a remote system that is connected to midPoint. It may be a source system that feeds data to midPoint. Or it may be a target system, that is managed by midPoint.

  • Account is a data structure (user profile) that resides on resource (source or target system). MidPoint reads data from accounts, or manages the accounts.

  • Role gives privileges to users. Role may also specify which accounts on which resources a user should have.

Next Steps

MidPoint will not do much on its own. We need to connect midPoint to a source or target system (a resource) to see it shine. However, midPoint is a very powerful and comprehensive system, there are many things that can be set up, customized and adjusted when a new resource is connected to midPoint. The configuration may be somehow overwhelming for a new midPoint engineer.

It will take some time to get an understanding how midPoint works. However, any time invested in learning midPoint will be paid back many times over.

There are three great ways how to start learning about midPoint:

First Steps Methodology Webinar Video

  • Video tutorials on Evolveum YouTube channel. There is a series of tutorials that is based on the book. There are also other videos explaining various details of midPoint configuration and deployment.

  • MidPoint Book provides a general introduction to identity management, it explains how midPoint works, it provides examples, ideas and tips for midPoint configuration, deployment and use. This is the book to learn about midPoint. It is freely available for on-line reading and downloading.

  • Trainings organized by Evolveum. These are usually remote, instructor-lead trainings designed by midPoint authors.

There are also additional sources of information, that are usually suitable for engineers with some experience:

  • docs.evolveum.com: This entire site is dedicated to documentation. It is more than worth exploring the content.

  • MidPoint mailing lists are a great place to discuss midPoint.

  • Conference talks and workshop recordings are a good resource for people that like to sit back and listen.

Frequently Asked Questions

MidPoint won’t start

Q: MidPoint won’t start, I cannot access the 8080 port.

A: MidPoint is a substantial software system. It usually takes 1-2 minutes for midPoint to start up based on hardware. You can monitor the progress of midPoint startup by looking at midPoint logs.

Something went wrong …​

Q: Something went wrong, I have no idea what is going on.

A: The best start to midPoint diagnostics is to have a look at midPoint logs.

The log is visible on the console or the standard docker logging mechanism is used: docker logs midpoint_server.

My first resource won’t work

Q: My first resource won’t work, there are connection errors, I can see no data, nothing works.

A: Have a look at the error message. You can expand the error message to get more details about the problem. However, please keep in mind that connecting new system to midPoint may be tricky. There are nice systems that use standard protocols and provide good error messages. However, many systems are not very nice. They deviate from standards, require exotic configuration and return cryptic error messages. If the resource does not work on the first try, it is usually helpful to learn more about midPoint and its workings.

Something else

Please check out MidPoint FAQs.

Was this page helpful?
YES NO
Thanks for your feedback