The Guide is definitive. Reality is frequently inaccurate.
The Restaurant at the End of the Universe by Douglas Adams
This chapter provides instructions for installation and initial configuration of a midPoint system. Installation instructions provided in this chapter focus on small installations, suitable for evaluation, experiments, and development of midPoint configurations. Most of us are going to start with an environment like this. Deployment of midPoint in a production setting is an entirely different matter, suitable for its own chapter.
MidPoint will run on almost any machine. Mid-range laptop is fine for personal use of midPoint. MidPoint needs approximately 4GB of RAM, which is perhaps the only real limiting factor.
Theoretically, MidPoint is platform-independent, it can run on any environment where Java is running. However, devil is in the detail. Individual environments and operating systems have their peculiarities. Therefore, only some environments are supported by Evolveum.
Linux is an operating system of choice for production use of midPoint. However, midPoint will be happy in Windows or macOS environment on your laptop for non-production use. Some midPoint releases have production-grade support for Windows environment as well.
If you look for more formal system requirements definition, then you will find that in midPoint docs (see Additional Information chapter at the end of the book).
There are several ways to install and use midPoint.
-
Docker: MidPoint can be installed from docker images published on Docker Hub. Docker, being a container platform, simplifies installation to downloading and running the image. Even that is further simplified and automated with Docker Compose. This is ideal method for exploration, experiments, testing and demos. Docker Engine is needed to run the images, which can run on almost any computer. Evolveum provides convenient script to set up and manage midPoint environment for docker-based installation.
-
Kubernetes: MidPoint can be installed to Kubernetes platform. This is a fully cloud-native method to deploy midPoint. Kubernetes deployment is recommended for production use of midPoint. Kubernetes platform or cloud environment (AWS, Azure, Google cloud) is needed for this method. This installation method is not covered in this book.
-
Distribution package: MidPoint is distributed in a form of package, which is built from source code. The package contains binaries, scripts and other files to run midPoint. Java Runtime Environment (JRE) is needed to run the binaries, as well as knowledge of system administration techniques. This method is supported for production use of midPoint. It is recommended for people that prefer the traditional installation approach.
-
Source code: MidPoint is an open source software, complete source code is available. The source code can be built to obtain binary packages. Java Development Environment (JDK) is needed to build and run the binaries, as well as some knowledge of software development and system administration techniques. This approach is recommended for deep experimentation and special scenarios, and for people that need to build their own source code.
It is strongly recommended to start with the Docker method. The descriptions and examples in this book assume that Docker Compose installation is used.
Docker provides a popular method to distribute and run containerized software. Evolveum is building and publishing docker images for every midPoint version. In addition to that, Docker Compose definition file is provided for easier start. Docker Compose file describes how the necessary containers are assembled, creating a simple environment with all the necessary components.
MidPoint installation described in this chapter is a very basic one. It is ideal for initial exploration of midPoint, development of midPoint configurations, simple testing, demonstrations, exploration and similar purposes. It is a very convenient installation, and it provides all you need to get started.
Following steps are applicable to Linux and macOS environment. Windows users may use Docker Desktop running on Windows Subsystem for Linux (WSL). Please refer to Evolveum documentation regarding Docker Compose for more details.
|
Warning
|
Not for production use
MidPoint installation based on Docker Compose is not meant for production use.
|
You will need:
-
Docker Engine installed on your machine. It is available for Linux, Windows and macOS. Please follow Docker installation instructions. Make sure that Docker Compose is installed as well. Special packages are needed to support compose in some operating systems, e.g.
docker-compose-pluginordocker-compose-v2is necessary in Debian/Ubuntu Linux. -
MidPoint Docker Script (
midpoint-quickstart.sh) downloaded to your machine. The script takes care of initialization of Docker Compose environment for midPoint. The script can be downloaded from Evolveum download page. Detailed instructions about usage of the script can be found on Quickstart page in midPoint documentation.
Once the Docker is installed and the script is downloaded, there is still some preparation to do:
-
Create a new directory for the environment. Any directory would do.
mkdir midpoint-demoChoosing a relatively unique name for the directory would be a good idea, as Docker Compose is using name of the directory as a prefix for container names. Therefore
midpoint-demois better name thanmidpointordemo. -
Copy the script to the new directory:
cp Downloads/midpoint-quickstart.sh midpoint-demo/ -
Enter the newly-created directory:
cd midpoint-demo -
Initialize and start midPoint environment by running the
midpoint-quickstart.shscript:./midpoint-quickstart.sh upThe script needs to be executed from the dedicated directory created in the first step. When started, the script initializes the environments. It creates Docker Compose definition file (
docker-compose.yml) and midPoint home directory (midpoint-home), setting correct permissions for easy management. Then the script starts docker containers.
|
Note
|
Docker and sudo
The midpoint-quickstart.sh script may ask for your password, as it is using sudo to start Docker containers.
Using sudo is a recommended method to manage Docker containers in a secure way.
There are configurations that allow users to start the containers without sudo, yet these are not considered secure.
As midPoint is designed with security in mind and it is supposed to be secure by default, it uses the sudo method.
|
Once the environment is started, midPoint user interface can be accessed as a localhost service at port 8080.
+
You can start working with midPoint now.
Log in as administrator.
The script has generated a random initial password (remember: secure by default), which can be used to log in.
|
Note
|
Localhost only
The Docker exposes midPoint as HTTP service on localhost port 8080.
To make things simpler and quicker, this midPoint instance is not secured properly.
It is using HTTP instead of HTTPS.
However, this deployment is still reasonably secure, as it is exposed only on local network interface (localhost).
It is not accessible over network.
This is a very explicit decision to limit the exposure of new midPoint instance until it is properly secured.
|
In case that midPoint does not start, the problems are indicated in the logfile.
The logfile (midpoint.log) is located in midPoint home directory.
In our little Docker Compose environment, the logfile can be found at the following path:
midpoint-home/log/midpoint.log
If there is any problem, it is likely that detailed problem description can be found at the end of the log file. When desperate, please refer to the Troubleshooting chapter.
When not needed, the containers can be shut down:
./midpoint-quickstart.sh down
When shut down, midPoint keeps all the data and state in the repository. The data will be available when the container is started again.
In case that there is a need to purge all data and re-start on a clean playing field, persistent database data can be deleted by using the clean command passed to the script:
./midpoint-quickstart.sh clean
|
Tip
|
Behind the scenes
The script is using Docker Compose to do quite a lot of things behind the scenes.
First of all, the script creates midPoint home directory (midpoint-home), setting correct permissions for both the docker container and you can access it.
Then the script uses Docker Compose starts up midPoint repository, which is a PostgreSQL database instance.
The database is using a persistent volume to store its data, otherwise you would lose all your work on every re-start.
Then the database is initialized with proper configuration and database schema.
Finally, midPoint container is started and connected to the database.
The container generates a random administrator password, which is retrieved by the script and displayed to the user.
While it may look like a single "midPoint" instance to you, it is in fact several cooperating containers, all orchestrated by Docker Compose.
|
Standard Docker Compose definition for midPoint contains just the basic components: midPoint server and PostgreSQL database.
However, for the purposes of this book, we are going to need a little bit more - to have some fun with midPoint.
We are going to need an LDAP server, CSV files and some additional database tables to play the role of resources.
Of course, the stock docker compose definition can be extended to include all that.
However, the primary goal of this book is to learn midPoint.
Messing around with docker may be a distraction.
Therefore, there are already containers configured to run the environment suitable for trying examples provided in this book.
The containers are located in the docker directory in book samples (see Additional Information chapter for details).
There are two configurations, first one corresponds roughly to the beginning of chapter 5 (Synchronization), the other corresponds to end of chapter 10 (organizational structure).
There are README files in both directories, explaining the details.
The containers have convenient book-example.sh script, which can be used to set up, start and re-set container state.
This script is meant for Linux, as primary author of this book is a hopeless Linux enthusiast.
There are no Windows or macOS versions.
However, this is open source world, contributions are more than welcome.
If you want to have just a quick look at midPoint, there is on-line midPoint demo located at the following URL:
The demo has some basic configuration to demonstrate midPoint features. There are several resources configured for synchronization, role-based access control (RBAC) is set up, there is organizational structure, some policies, and many other things. Link to the demo documentation is provided at the login page.
|
Note
|
The demo is shared among all the users, therefore it may not be in a pristine state when you log in. The demo is re-set to the original state once a day. |
When local midPoint instance is started, use the following URL to access midPoint user interface:
Log in with the following credentials:
Username: administrator
Password: randomly generated at first start, displayed by the start script
|
Note
|
HTTP
Oh yes, the URL is really using insecure HTTP instead of HTTPS.
This is certainly not suitable for production use, as we have already mentioned several times.
However, it is reasonably safe for local, non-production use.
When using the provided docker configuration, midPoint service is available on localhost only, it is not accessible from the network.
This setup is reasonably secure for use on personal computers.
We did not want to complicate the matter by acquiring TLS certificates for HTTPS use.
However, you will need to do that for production use, in order to secure midPoint.
|
Now you are logged-in as the administrator.
This user has superuser privileges, therefore you can see everything, and you can do anything in the midPoint user interface.
MidPoint user interface is structured. It has the same layout and controls for all the user interface areas:
Primary tool for user interface interaction is the menu. MidPoint user interface is functionally divided into three parts, therefore there are also three parts of the menu:
-
Self-service user interface deals with the things that the user can do for oneself: displaying list of account, changing password, requesting a role and so on. This is relatively simple part of the user interface. It is often accessible to all the users.
-
Administration user interface deals with management of other users, roles, organizational structures and similar midPoint objects. This is a very comprehensive and considerably complex part of the user interface. Usually only privileged users have access to this part of the user interface. This part of user interface is often used to support delegated administration and role management therefore it is also meant for security officers, resource owners, role engineers and similar expert users.
-
Configuration user interface deals with configuration of midPoint system itself. It is used to customize midPoint behavior, set fundamental policies and rules that form the foundation of midPoint deployments. This part of user interface is usually used only by identity management engineers.
The menu can be hidden by clicking on the button at the top of the screen. The top bar also contains the title of the current user interface page and breadcrumbs. Breadcrumbs show where you currently are in the user interface and how you got there. The breadcrumbs can be used to "find your way home" and back to the previous page. The use of browser btn:[Back] button is not recommended. Please use the btn:[Back] buttons that are present in midPoint user interface, or use breadcrumbs.
MidPoint user interface is quite rich. Following list provides short description of the most important parts of the user interface.
-
Home page gives a brief status about users own accounts, requests, work items and so on. This is a page designed to be the first page that will be displayed to the end user after log in to midPoint.
-
Profile page allows users to see or edit their own profile.
-
Credentials page allows users to change their own credentials, such as password.
-
Request access page allows users to select the roles that they need, and then request assignment of the roles.
-
Dashboard pages shows a couple of dashboards designed to provide a lot of useful information at the first sight. The built-in system dashboard shows statistics about midPoint installation. Dashboards can be customized to suit needs of a particular deployment.
-
User pages list users in midPoint, allows to create and edit users.
-
Organizational structure pages show the organizational structure trees. Many parallel organizational structures can be managed here, such as tree-like functional organizational structure, flat project-oriented structure, role catalogs and so on.
-
Role pages allow to list and manage roles. Roles can be defined and maintained in this part of the user interface.
-
Service pages allow to list and define services, such as applications, devices, servers and so on.
-
Resource pages list and manage identity resources. New resource can be defined here, associated with the connector, tested, etc.
-
Cases pages list the things that the users have to do. Work items are created if user has to approve something or if there is some manual step in the process.
-
Certification pages deal with access certification (re-certification, attestation). Certification campaigns can be created and managed here.
-
Server task pages show the tasks that are running on midPoint servers. These may be scheduled synchronization tasks, import tasks, running user requests – everything that runs on the servers and cannot be executed immediately in a synchronous way.
-
Nodes page lists processing nodes in midPoint cluster.
-
Report pages allow defining and running reports. These pages typically deal with scheduled printable reports.
-
Simulation pages allow running simulated operations, predicting operation result without causing any damage.
-
Audit log viewer can be used to look at audit log, reviewing record of all past operations.
-
Configuration area contains many pages that manage midPoint configuration: system default configuration, repository objects, logging, bulk actions and so on.
-
Archetype pages define specific object types that can be used to customize behavior of midPoint objects.
-
Repository object pages for accessing objects in midPoint repository, used for low-level manipulation of midPoint configuration and data.
MidPoint user interface is using the same concepts and controls in all its parts. For example all the lists of all the objects (users, roles, …) look like this:
Each row represents one object: user, roles, service, task, etc. There is also a color-coded object icon. The search bar at the top can be used to look for a specific object or to filter the object view. Right side is reserved for action buttons. Buttons in the table header trigger actions that apply to all selected objects. Buttons in each row trigger actions that apply only to that individual object. The buttons in the bottom-left corner execute global actions, such as creating or importing new object, exporting objects and refreshing the view. Paging controls are in the bottom-right corner.
MidPoint has a unified color-code that makes the navigation easier. Users, roles and other object types have their specific color and icon. This indicates the object type, and it is used whenever possible: menu, information boxes, lists, box title accents and so on. The primary colors and icons are shown in the dashboard:
All user-related controls are red, all controls that deal with organizational structure are yellow. Roles are green. And so on. This color code is applied consistently through the midPoint user interface.
Similar color code applies to object icons when displayed in user lists. However, the color that is used there does not indicate object type, but rather an archetype. Archetypes are subtypes that are often used to distinguish similar objects. For example, archetypes can be used to sort users to employees, contractors, customers and so on. Look and behavior of "archetyped" objects is configurable. Default midPoint configuration contains just a couple of archetypes. Those archetypes apply red color to system users and roles.
|
Tip
|
All objects are equal in midPoint. MidPoint will handle users, roles, organizational units and services in the same way. The lists used to display these objects are the same, the pages that display object details are the same. All the objects have properties, they can be enabled/disabled in the same way, they are subject to authorizations in the same way and so on. It is a midPoint philosophy to design several powerful principles, and then apply them over and over again. |
When a user clicks on a name of any object in the object list then object details page appears. The detail pages for common midPoint objects, such as user or role, are very similar to each other. They have the same layout and controls. E.g. user details page looks like this:
The screen below the information area is divided into several panels. There is a summary panel at the top of the page. This is an information area which shows user photo (or icon) and provides some basic information such as user identifier and title. It also shows where the object belongs in the organizational structure. There is also a couple of "tags" that show interesting details about the object: whether the object is enabled, whether it has special privileges and so on.
Below the summary panel, there is a panel with operation controls. There are buttons to save the changes, go back to the previous page, controls to set operation options and so on.
The data are displayed in details panel. However, midPoint data structures are often quite complex. Displaying the data in their full complexity would make it very difficult to understand. Therefore, the data are divided into several parts, each containing a portion of the data. Navigation menu is displayed left to the main details panel. It allows easy navigation through data structures, each displaying a specialized panel with object details.
The first item is perhaps the most interesting one. It contains fields that show basic object properties: the attributes of the object. Properties are displayed, and they can be edited – depending on the authorizations of currently logged-in user. The other panels shows more complex information about the object. E.g. activation panel shows whether the object is enabled or disabled, it shows the activation dates and other activation details. The password panel provide password management functionality. And so on.
The view control buttons present in the details panel can be used to adjust the way the information is presented. These buttons control sorting of the fields, can toggle metadata display and there may be additional control buttons for more complex fields. MidPoint shows only some fields by default, to make the presentation easier to read. For example, most empty fields are not shown by default. There is a small btn:[Show empty fields] button under the fields than can be used to display empty fields.
The content of the details panel changes its form, adapting to the type of displayed information. Basic properties are shown as a series of editable fields. Content of some panels is similar to the menu:Basic[] panel, displaying a set of fields. Other panels provide lists of more complex data structures such as projections, assignments and personas.
MidPoint user interface often needs to present objects that are internally quite complex. It does not make sense to present all the details at once. These objects need to be presented in quite a compact form that can be expanded to show the details. This applies to list of user’s accounts, assignments, role inducements, etc. The objects are initially displayed as in a form of a simple list, displaying only the basic data:
The list above shows user’s projections. Those are usually accounts that are linked to user object. Click on account name shows account details:
Account details display is shown in place of user details. This may be slightly confusing. However, account details can be often complex, therefore all the available screen space is needed to display them. The btn:[Cancel] and btn:[Done] buttons at the bottom can be used to return to list of projections. Click on btn:[Done] button will not start the operation yet, it only changes the view. Therefore, do not confuse those buttons with btn:[Back] and btn:[Save] buttons located in the control panel.
|
Tip
|
Perceptive reader is certainly curious about the small red question mark in the corner of the account icon. This corner of the account icon is a place where a special marker would be displayed to indicated disabled accounts. There would be no such marker for enabled accounts. Such visual indicators are very helpful when managing identities of larger user bases. However, this is an LDAP account. There is no standard way to disable an account in LDAP world. Many LDAP servers implement their own proprietary mechanisms, and the OpenLDAP server that we are using has no such mechanism at all out-of-the-box. Hence the question mark, indicating that the activation status of the account is not known. |
Each panel provides the information in an editable way, provided that the user has adequate privileges to edit the information. When the data are edited, the changes can be confirmed by using the btn:[Save] button in the operations panel. Saving the changes is a universal way how to start almost any operation: change of user properties, assignment of roles, change of password, user disable, etc. When you make edits in any of the panels on the details page, then nothing really happens yet. MidPoint just remembers what you are editing. The operation is executed only when you click the btn:[Save] button. This is our method to execute several changes in one operation. It may require some time to get used to it. Just do not forget to click the btn:[Save] button when you are done editing.
Operation options are used to modify the behavior of the operation. These options may force execution of operations that fail to pass midPoint internal checks. There is an option to reconcile the data even if midPoint thinks that reconciliation is not needed. And so on. Checking or unchecking these options influences the way how midPoint executes the operation.
The principle of midPoint configuration is quite different from what would a typical system administrator expect. There are almost no configuration files in midPoint. MidPoint is storing the vast majority of its configuration in its configuration database. There are several reasons for this:
-
MidPoint configuration is complex. MidPoint configuration is not what a typical system administrator would think of like a "configuration". It contains numerous resource definitions that in turn contains mappings that in turn may contain scripts. There are roles, policies, templates, … and these objects are too complex to be expressed in simple configuration files.
-
MidPoint configuration is scalable. It is no exception that a midPoint deployment has thousands of role definitions or organizational units, tens of resource definitions and a significant number of templates and policies. All of that needs to be stored efficiently, for midPoint to handle deployments that manage millions of identities. The configuration also needs to be searchable. Managing thousands of roles in plain text files simply won’t work.
-
MidPoint configuration needs to be available. There are midPoint deployments with several nodes working together in a cluster. Configuration change done on one node has to be seen by other nodes. Simple configuration files would not work here.
Therefore, midPoint has a completely different approach to configuration. The configuration is stored in a form of well-defined structured objects in the midPoint database. We call that database midPoint repository.
Everything is an object in midPoint. Every piece of configuration is represented as a structured object and stored in midPoint repository. Object may look like this:
<role oid="8ebab0bc-7e7e-11e6-a7bc-57de1cd45ecc">
<name>Basic User</name>
<description>Basic user role. Almost all users have it.</description>
<requestable>true</requestable>
<inducement>
<targetRef oid="f92e67c2-7e7e-11e6-a306-7bf6aa2e8c61" type="RoleType"/>
</inducement>
</role>Every object has its identifier. We call that identifier OID, which stands for "object identifier" (it has nothing to do with LDAP or ASN.1 OIDs). OID is usually randomly-generated universally unique identifier (UUID). OID value has to be unique in a whole system. This identifier is persistent – it is assigned to the object, and it is never changed. OID is used for internal purposes, and it is almost never displayed to midPoint user.
Every object has a name. Name is human-readable, and it can change any time. The value of name is usually displayed to users. This is the values that ordinary users understand as an identifier.
Then there are other object properties - or rather items. Each type of midPoint object has a slightly different set of these items. That’s what we call schema. The items may be simple properties such as string, integer or boolean values. There may be complex structures, and references between objects. MidPoint data model is quite rich. It is in fact so rich that its description will take better part of this book, because description of the data model is also description of midPoint features.
You can see midPoint configuration objects in midPoint user interface by navigating to menu:Configuration[Repository Objects > All objects] and selecting object type. The following picture shows objects of type "Role":
The objects are stored in the midPoint repository in a native form which is hidden from midPoint users. However, the objects also have a human-readable representation. They can be represented in XML, JSON and YAML forms. All the objects can be imported into midPoint in any of those forms. They can be exported from midPoint in any of those forms. They can be edited directly in midPoint using embedded editor, in any of those forms. Just click on any object in the menu:Repository objects[] page:
The ability to export, import and edit objects in XML/JSON/YAML form is absolutely essential, because:
-
It is human-readable (or rather administrator-readable). The configuration can be created, edited and maintained in your favorite editor and then imported into midPoint. It can be reviewed. It can be copied and pasted. Especially that. No system administrator can live efficiently without an ability to copy and paste.
-
It is transferable. It can be exported from one system (e.g. development environment) and easily transferred to another system (e.g. testing environment). It can be easily backed-up and restored. It can be easily shared, e.g. in a form of configuration samples.
-
It is versionable. The exported configuration can be easily put under any ordinary version control system. This is essential for deployment projects and configuration management.
Therefore, the midPoint configuration has the best of both worlds. It is stored in repository, therefore it can be processed efficiently, it can be made available and so on. Yet, it also has a text form, therefore it can be easily managed.
The XML, JSON and YAML forms are considered to be equivalent. Objects can be written in any of these forms.
<role oid="8ebab0bc-7e7e-11e6-a7bc-57de1cd45ecc">
<name>Basic User</name>
<description>Basic user role. Almost all users have it.</description>
<requestable>true</requestable>
<inducement>
<targetRef oid="f92e67c2-7e7e-11e6-a306-7bf6aa2e8c61" type="RoleType"/>
</inducement>
</role>{
"role" : {
"oid" : "8ebab0bc-7e7e-11e6-a7bc-57de1cd45ecc",
"name" : "Basic User",
"description" : "Basic user role. Almost all users have it.",
"requestable" : true,
"inducement" : {
"targetRef" : {
"oid" : "f92e67c2-7e7e-11e6-a306-7bf6aa2e8c61",
"type" : "RoleType"
}
}
}
}role:
oid: "8ebab0bc-7e7e-11e6-a7bc-57de1cd45ecc"
name: "Basic User"
description: "Basic user role. Almost all users have it."
requestable: true
inducement:
- targetRef:
oid: "f92e67c2-7e7e-11e6-a306-7bf6aa2e8c61"
type: "RoleType"Most of the examples in this book are in XML notation. The XML form is almost always simplified for clarity: there are no namespace definitions, no namespace prefixes and so on. The complete files with all the details can be found in midPoint distribution package, midPoint source code or in other places. See Additional Information chapter for more details.
When it comes to maintenance of midPoint configuration, there are two practical methods.
First method is to maintain the configuration in midPoint: use midPoint wizards and user interface tools to create new objects and modify them. Export the objects in regular intervals to backed them up. This is an easy method to start with.
However, sooner or later you will probably figure out that you need the ability to copy and paste parts of the configuration, compare differences and review configuration history. You will need to share parts of the configuration with other team members. As we all know, no user interface is ever as efficient as an experienced engineer with a good text editor.
Then there is a second method: maintain the configuration in text form: XML, JSON or YAML. Import the configuration to midPoint as needed. The objects can be imported in midPoint user interface by going to menu:Configuration[Import object] page.
It is much easier to maintain a proper version control and a good teamwork using this method. It also seems to be more efficient once you get used to midPoint: pieces of configuration can be copied from samples, documentation or from other projects. This makes the work efficient. Although work with midPoint is "just" configuration, and there is usually almost no programming, this method of work is quite close to the methods that software developers use. We know that these methods work quite efficiently, as we are using them every day.
However, maintaining configuration in files and importing them individually using midPoint user interface may look a bit uncomfortable. However, there is a better way. There is MidPoint Studio, an integrated development environment (IDE) based on IntelliJ IDEA. MidPoint Studio allows you to maintain the configuration files in a form of a development project. You can edit the files with all the usual luxury of IDE, such as syntax highlight and autocompletion. Studio allows easy download and upload of changed configuration files to midPoint instance. As the IntelliJ platform has good integration for version control systems and other development tools, this seems like an ideal approach, especially for large and complex projects. If you plan to use midPoint professionally, MidPoint Studio is certainly worth trying.
MidPoint needs its own database to work. We call that database midPoint repository. The database is used to store the configuration, users, resource definitions, account links, audit trails and a lot of other things. Proper relational database is needed for midPoint repository, such as PostgreSQL database. Docker Compose deployment makes sure that PostgreSQL is available, properly set up, initialized with database schema and ready to be used as midPoint repository.
MidPoint {midpointversion} supports several database engines. However, only PostgreSQL database fully supports all midPoint features. Support for database engines other than PostgreSQL is currently deprecated. The future of generic repository support (as we call it) is uncertain. Choose PostgreSQL directory (a.k.a. _native repository) to get reliable support for all midPoint features.
|
Note
|
Embedded database
MidPoint had embedded database engine in the past, in a form of H2 database.
However, proper database engine is needed to support all midPoint features.
While the embedded H2 engine is still present in midPoint, it is not recommended to use it.
Many midPoint features will fail unless a proper database engine (PostgreSQL) engine is used.
|
While almost all of midPoint configuration is stored in the database, there are few things that cannot be stored there - such as connection parameters to the database itself.
For that purpose midPoint has a small configuration file called config.xml.
MidPoint also needs a place where to store other data that cannot be in the database, such as cryptographic keys, connector binaries and so on.
MidPoint needs a special directory on a filesystem for that purpose. We call it midPoint home directory. When a new midPoint instance starts for the first time, new midPoint home directory, populated with default configuration. Location of midPoint home directory slightly varies, it depends on your deployment method:
-
Docker-based installation: MidPoint home directory is named
midpoint-home. It is located in directory where themidpoint-quickstart.shscript was started, i.e. at the same level as thedocker-compose.ymldirectory. -
Package-based installation: MidPoint home directory is named
var. It is located in directory where midPoint distribution package was installed, i.e. at the same level as thebindirectory, where midPoint start scripts are located. Assuming that midPoint was installed in/opt/midpointdirectory then default midPoint home will be located in/opt/midpoint/vardirectory.If necessary, the location of midPoint home directory can be changed by using the
midpoint.homeJava system property. This is done by specifying-Dmidpoint.homein the JVM command-line. In case that the default midPoint start scripts are used,MIDPOINT_HOMEenvironment variable can be used to set the location of midPoint home directory.
MidPoint home directory contains several interesting items:
-
config.xmlcontains fundamental configuration, such as location and credentials of repository database. -
logdirectory contains midPoint log files,midpoint.logfile being the most important. -
connid-connectorsdirectory is a place where additional identity connectors may be deployed. Copying a connector into this directory automatically deploys it to midPoint. -
resourcesdirectory is used to store data for file-based resources, such as resources based on CSV connector. This directory is used in this book. The directory does not exist by default, and its name is not hardcoded anywhere in midPoint. It is just a convention to store file-based resources in this directory.
When midPoint starts for the first time, it starts with an empty database.
MidPoint populates the database with a minimal set of configuration objects.
We call them initial objects.
This set contains objects such as the Superuser role and user administrator.
These objects get imported automatically, because if they are not there, you will not be able to log into the new midPoint instance.
These objects are imported only if they are not already present in the database.
If you modify them later, midPoint will not overwrite them.
Logging is perhaps the most important mechanism to diagnose any issues with midPoint. Logging should be the thing that comes to your mind anytime you cast a puzzled look at midPoint user interface. We try to make midPoint user interface convenient to use, and we pay a lot of attention to good error reporting. However, there are always some practical limits what the user interface can do. The error that the user interface displays may be just a result of a long chain of causes and effects. Error messages in the user interface may not directly point to the primary cause. Perhaps there is no error at all, just midPoint does not do what it is supposed to do. That is the point where logging comes to the rescue.
MidPoint is using Java logging facilities to log its messages.
MidPoint log file name is midpoint.log, and it is stored in the log subdirectory in midPoint home directory (midpoint-home/log/midpoint.log for docker-based deployment, /opt/midpoint/var/log/midpoint.log for package-based deployment).
The default logging level is set up more-or-less to suit normal midPoint operation.
This means that the messages on level INFO and above are logged while the finer levels are not logged.
If you want to diagnose midPoint issues you will need to switch the logging levels to DEBUG, or in extreme cases even to TRACE.
The logging levels can be adjusted in midPoint user interface.
Navigate to menu:Configuration[System > Logging].
MidPoint is not a simple system. There are complex interactions, there is usually a lot of custom configuration, customizations, expressions and so on. Diagnostics of midPoint issues is no easy task. Therefore, there is a dedicated Troubleshooting chapter in this book. That chapter is your best friend when things do not go as expected.