Frequently Asked Questions

Table of Contents

MidPoint Project

What is midPoint?

Midpoint is a comprehensive identity management and identity governance system. It is basically a complex integration tool that can replicate and transform user records between numerous user databases, management of the records, reporting, auditing and so on. It allows very complex transformation and replication rules including support for advanced RBAC, data mappings, organizational structure management and identity governance. Its internal mechanisms are based on state-of-the art concepts that are still not yet widely used in the field of Identity Management.

For those that are interested in long reading there is book about midPoint.

Please see Enterprise Identity Management for a generic introduction to the Identity Management (IDM) concepts. Please see the Unique Features for a short description of features that make midPoint unique.

Is there an Enterprise Edition of midPoint?

No, there is no such thing.

MidPoint is an open source project. Every line of midPoint code is published under the terms of open source licenses. Every bit of functionality is available to anyone. We are open source, not open core. We are not holding back anything from the community.

However, midPoint is also a professional software. MidPoint developers in Evolveum work full-time on midPoint as their daily jobs. Evolveum is offering midPoint subscriptions, training and professional services to fund midPoint development.

ConnId is an open-source project that aims to develop a reusable identity connector framework and a basic set of connectors. It has started as an Identity Connector Framework project by Sun Microsystems to be used as part of Sun IDM. However, the open-source project was de facto stopped after the acquisition of Sun Microsystems by Oracle. The ConnId framework is open source continuation of that project.

ConnId is currently developed by several independent parties and Evolveum is one of the major contributors. ConnId is currently used as the primary connector framework for midPoint.

OpenICF is (or rather was) a similar framework based on Sun Identity Connector Framework. It was maintained by ForgeRock. MidPoint has been using OpenICF in the past. Due to various reasons the midPoint project has completely migrated to ConnId. Evolveum is no longer contributing to OpenICF or any OpenICF connector. OpenICF and ConnId used to be compatible, however OpenICF changes make them non-compatible. Therefore, OpenICF connectors are not officially supported in midPoint any more. The OpenICF connectors can still be used in midPoint, but a (relatively simple) source code change need to be done to port the connectors to ConnId framework.

Please see Identity Connectors section for the details.

How does midPoint relate to Sun IDM (Oracle Waveset)?

MidPoint is somehow influenced by the Sun Identity Manager (Sun IDM, currently Oracle Waveset) design and features, and midPoint somehow follows similar approach to provisioning that was introduced by Sun IDM. Therefore engineers that are used to work with Sun IDM will find some parts of midPoint quite familiar. However, even though Sun IDM was a good product it was far from perfect. There were severe architectural issues in Sun IDM and we are well aware of them. MidPoint has a different implementation architecture and the development team tries very hard not to repeat the mistakes of Waveset and Sun IDM development teams.

MidPoint was designed from ground up on a green field and it does not contain or is not related to any part from SunIDM, except for ConnId framework (see above).

How does midPoint relate to ForgeRock IDM (OpenIDM, wren:IDM)?

MidPoint and OpenIDM share a part of common past (see midPoint History). Yet these two products are currently almost entirely separate. Their architecture, principle, development model and also approach to IDM is vastly different.

Despite a common history, the source code bases were separated very early and both products were significantly changed since. There is no source code overlap between midPoint and ForgeRock IDM (or OpenIDM, or wren:IDM) that we are aware of.

How does midPoint relate to Apache Syncope

Apache Syncope is a completely separate open source project that evolved in parallel to midPoint. There is no technological overlap between midPoint and Syncope, except for the ConnId framework (see above). Syncope and midPoint are de facto competing products. However, we are both part of larger open source community and therefore we like to cooperate as much as we can.

Architecture and Features

What are the basic technological foundations of midPoint?

MidPoint is implemented in a form of stand-alone Java web application. The basic application framework is based on Spring. MidPoint administration user interface is based on Apache Wicket. MidPoint is using the usual set of open-source infrastructure libraries (e.g. SLF4J, logback, Apache commons, etc.). MidPoint user interface is based on Apache Wicket framework.

What do I need to run midPoint?

MidPoint is a Java application, therefore you will need a java runtime to run it. You will need Java Runtime Environment (JRE) or Java Development Kit (JDK). Java distributions based on OpenJDK are recommended. MidPoint is distributed as a stand-alone self-contained application, therefore it brings all the other components that it needs to run, including Tomcat web container.

What user interface midPoint provides?

MidPoint provides a graphical administration and user interface (GUI) in a form of rich web application. It is an integral part of midPoint application as a primary midPoint administration tool. Although the GUI is part of midPoint, the GUI layer is clearly separated from the back-end layer using well-defined interfaces. Therefore it is possible to adapt or even replace the GUI if needed. There is a RESTful service that can be used to build completely custom user interfaces.

What services midPoint provides?

MidPoint provides a RESTful service for the vital provisioning functions. This service can be used to modify and control vast majority of midPoint functions.

What connectors and resource types midPoint supports?

MidPoint is using ConnId connector framework. Therefore it can work with any connector that is compliant with the ConnId framework. Available connectors support the usual IDM cases such as Active Directory, LDAP, CSV files, relational databases, etc. Please see the Identity Connectors page for a list of currently available connectors.

Can midPoint synchronize passwords from Active Directory or LDAP?

The backward password synchronization channel is quite difficult to utilize. Both AD and LDAP store passwords in a hashed form. Therefore, it is not directly possible to get the clear value by just reading the userPassword attribute. Additionally, the hashes are not compatible. Therefore midPoint needs a clear value to transform one to the other.

The only practical way that we have found is to use agents. That means a piece of code that will get between setting the password and hashing it on AD/LDAP side and sends the cleartext password to midpoint. This is clearly not the best idea from a security point of view. However, if you require password sync then we do not know about any other way.

The approach that we usually recommend it to avoid this kind of password synchronization altogether. It has considerable security, consistency and operational issues (e.g. how to handle password notifications that arrive before the account creation event is synchronized? What to do with passwords that comply with source password policy but do not comply with target password policy? etc …​)

The recommended approach is to use midPoint as a point of central password management. Users should change and manage their passwords in midPoint. The password can then be easily replicated to any other system (resource). MidPoint can also enforce consistent password policies, make sure the passwords are same (or different) on several resources (in the future) and so on.

See Initial Password Management Discussion page for more detailed discussion of the topic.

Does midPoint supports Single Sign-On (SSO)?

Yes and no.

MidPoint is identity management system, not access management system. Therefore midPoint is neither authentication server nor a SSO server. There are numerous possibilities how to implement these services by using an existing software, ranging from simple LDAP server to a sophisticated flexible access management suites. MidPoint has no ambition to reinvent the wheel of access management therefore it does not contain access management services. A comprehensive explanation of IDM solution components can be found on Enterprise Identity Management page.

However, midPoint can integrate with access management software on two levels:

  • MidPoint can manage the user database of access management system by provisioning to it. This is very common integration scenario.

  • MidPoint can be a SSO client under some circumstances. For example, it can be SSO client for Active Directory system by correctly configuring midPoint spring security settings (may currently require some customization). Alternatively midPoint is just a web application therefore it can be integrated to a web-SSO system as an ordinary web application. See Flexible Authentication for more details.

Does midPoint support OAuth2, OpenID Connect, SAML and similar protocols?

No. And yes. OAuth2, OpenID Connect, SAML and similar protocols are protocols from the access management and identity federation world. MidPoint is identity management system, not access management system. Therefore, midPoint is neither identity provider, authentication server nor a SSO server. That means that midPoint does not implement "server side" of OAuth2, OpenID Connector or SAML protocols. Such implementation is responsibility of access management systems. There are plenty such systems to choose from and midPoint can easily integrate with most of them. So, midPoint can support those protocols indirectly in a larger identity and access management (IAM) solution.

However, when it comes to "client side" implementation that a slightly is a different story. It makes sense for midPoint to support OAuth2, OpenID Connect and SAML on those services in a role of service provider (relying party). MidPoint supports some of the protocols for midPoint user interface and RESTful services. However, there are still some limitations. Please see Flexible Authentication for more details.

Does midPoint have a dedicated end-user interface (GUI)?

We do not have a special-purpose simplified end-user GUI. At least not yet. The end-user user interface is integrated into midPoint administration interface and we have good reasons for this approach (see below). Despite that, we are working on plans to eventually develop a dedicated end-user interface.

We do not have dedicated end-user interface yet, because:

  • The end-user interface usually has a lot of forms and styles. It is customized for almost every non-trivial deployment. E.g. some customers want a standard portlet others want proprietary portlet, yet others want to integrate it in their current core information system, etc. We have found out that it may in fact be easier to develop the end-user GUI for each deployment than to create and maintain a customizable code.

  • MidPoint is open-source project so any deployer can take the current GUI, strip it down to the very minimum, customize it or even write its own code. MidPoint follows a strict architectural approach of separating presentation logic and business logic. The GUI is using IDM Model Interface to execute all the IDM-related "business" and integration logic. Therefore, none of it needs to be re-implemented in a custom GUI. This interface is also available as a RESTful service which is suitable for supporting a custom end-user GUI.

There are also good reasons that our current end-user interface is integrated with administration interface. The minimal end-user GUI has a very limited features. E.g. it is usually not possible to fully interact in workflows or delegated administration using a minimal end-user GUI. Significant percentage of users usually require at least some portions of the administration GUI (delegated administrators, approvers, auditors, etc.) It means that a real value of a separate simple end-user GUI is quite limited for this type of users. Therefore we have chosen in implement end-user interface as an integral part of midPoint administration interface. And this approach worked well for many years.

However, we also see a value in a dedicated end-user interface. The plans are currently being considered and evaluated.

What are the experimental features?

Experimental features are not intended for production use. Such features are not finished. They are not stable. The implementation may contain bugs, the configuration may change at any moment without any warning and it may not work at all. Use experimental features at your own risk. This feature is not covered by midPoint support.

Please see Experimental Functionality page for the details.

I need midPoint to support feature X. What should I do?

Please see I Need New Feature.

Setup and Customization

Why does midPoint execute outbound mappings during import from resource?

Import from resource mechanism imports the accounts from a resource and creates midPoint users. Inbound mappings are usually used to populate the users with values. However, if there are also outbound mappings from the user to other (or even the same) accounts, these mappings will be executed as well.

MidPoint tries to execute all the mappings and all the synchronization logic anytime it can. Immediately. This may be quite a different philosophy as compared to other IDM systems but there is a strong reasoning to do so:

  • Executing all the applicable mappings as soon as possible gives almost-realtime character to the synchronization. Propagating changes as soon as they are detected lowers risk of consistency problems.

  • All the synchronization logic needs to be executed sooner or later otherwise consistency can be broken. Many other IDM systems postpone the execution of parts of synchronization logic to a later time, to a different task, etc. This may be more efficient from a performance point of view, and it forms a cleaner event-oriented architecture. However, it has a severe practical drawback. Cause-and-effect trail is practically lost. If there is a problem in a synchronization logic that was postponed it is almost impossible to figure out the original cause. Such systems are very difficult to maintain. MidPoint tries to avoid this by executing everything as soon as it can. Therefore, the configuration problems are evident when all the data are fresh and still available. Executing all the mappings together maintains a cause-and-effect trail. This significantly improves diagnostics and troubleshooting of the configuration and customizations.

This is a generic mechanism that applies not only to import but to all flavours of synchronization and provisioning in midPoint.

Such "execute everything immediately" approach is ideal for a sustained operation of the system. However, it may be slightly inconvenient during initial imports and migration. Therefore there are few tips how to work around it:

  • Import the data first, create outbound mappings after the data are imported.

  • Application of mappings can be constrained to a specific channel. Import has its own channel therefore some mappings may be constrained only to be executed during import.

  • Spend more time setting up the outbound mappings correctly. Use import not just to get the data inside midPoint but also to test that the outbound mappings work well. This requires more time during initial import but the time will pay off after the deployment.

Does midPoint support generic objects?

Of course it does. But most likely, you would not like to use them. MidPoint has something that is much better than generic objects: Archetypes.

See Generic Objects and Archetypes pages for the details.

Installation, Deployment and Operation

Is Tomcat deployment still supported?

TL;DR: Yes, but it is deprecated. Please use stand-alone deployment instead.

For the details please see Is Tomcat deployment still supported?

I found in log warning midpoint.home is not set

This warning is displayed during the starting of midPoint. It can be ignored unless you want to use a custom directory for your embedded repository or custom connectors. Please refer to the Directory for Custom Components (midpoint.home) section.

Missing sn attribute on LDAP

The following error may be encountered while using LDAP connector:

Couldn't add object. Reason: Schema violation during processing shadow: account: null (OID:null): Schema violation: javax.naming.directory.SchemaViolationException([LDAP: error code 65 - Entry uid=aa,ou=people,dc=example,dc=com violates the Directory Server schema configuration because it is missing attribute sn which is required by objectclass person])

The immediate cause of that error is a missing sn attribute. The sn attribute is mandatory in the usual LDAP inetOrgPerson objectclass. Therefore, attempt to create and account without this attribute fails. The missing sn attribute is most likely caused by no value in user’s familyName property which is usually the source of the sn attribute mapping.

The simples solution is to either make sure the familyName property is always filled. Alternatively, a more sophisticated mapping may be created for the sn attribute, e.g. taking value from the fullName property if the familyName is not filled in.

Connectors are not detected upon midPoint start

If you start midPoint and your connectors are not detected and therefore Connector objects not created in repository, check your config.xml file located in midPoint.home directory. The following parameters should be set:

config.xml
<icf>
  <scanClasspath>true</scanClasspath>
  <scanDirectory>${midpoint.home}/icf-connectors</scanDirectory>
</icf>

The scanClasspath=true parameter will detect the connectors bundled with midPoint, while the scanDirectory parameter defines the directory where custom connectors can be detected.

What are midPoint availability requirements?

It depends mostly on your requirements. How long you can live without ability to change passwords and assign/unassign roles? That’s perhaps the only midPoint function that is sensitive to availability.

All other midPoint functions are resilient, and they can recover even from long outages (days) without any loss in data. E.g. it is not an important difference if synchronization or reconciliation tasks will process the data a second after the change or few minutes later. MidPoint can also easily recover from changes done manually on the target systems. Therefore, even if midPoint is down there is still option to disable the accounts manually (e.g. during security incident), to manually create testing accounts and so on. If midPoint is configured correctly then it will re-establish the consistency after it recovers from the failure.

Therefore, the availability parameters depend on your requirements. Typical downtime requirements allow for 99.9% availability (which is approx. 8 hours per year) or even less. Practical cases suggest that even if the system is down more than an hour each month then there is no real impact on any essential services.

What does Subresult …​ of operation …​ is still UNKNOWN during cleanup mean?

Simply speaking this is midPoint error handling bug.

MidPoint is using OperationResult data structure to compile a complex result of most midPoint operations. Consistency of this data structure depends on a very strict error handling inside midPoint. We pay a huge amount of attention to good error handling, but some errors slip our attention from time to time. These are usually programming ("runtime") errors such as null pointer exception. If such exception happens, and it is not properly handled then the corresponding slot of OperationResult data structure will be left with an UNKNOWN status. This is detected at a later stage of result processing and the Subresult is still UNKNOWN error is issued.

Therefore, this message does not describe a bug directly. It in fact describes that there is an error handling problem in midPoint. The root cause of the issue is also included, it is provided as an inner exception. However, the Subresult is still UNKNOWN error tells midPoint developers much more than just the root cause. It tells us that we also need to fix our error handling code.

If you are encountering this error you have most likely found midPoint bug. Please see I Have Found a Bug page for more details.

Can I use newer version of XYZ with midPoint?

Resources And Connectors

LDAP and Active Directory FAQs

Please see:

What are ConnId result handlers?

Annoying little things that usually get in the way when working with a resource.

See What are ConnId result handlers? for more details.

Integration

I want to invoke midPoint operations from my application.

There are several Interfaces that you can use. Namely:

  • RESTful service: REST API

  • Local Java API: IDM Model Interface

  • SOAP-based web service interface was present in midPoint up to midPoint 4.1. It is not available any more.

All the interfaces provide services that are roughly equivalent. Almost all midPoint features are available by using these interfaces. We are using the local Java API ourselves (as given by midPoint architecture), so almost all features that you can see in midPoint GUI is available in all of these interfaces.

I want to use RESTful service. Where do I start?

I want to use the SOAP-based web service interface. Where do I start?

Don’t. SOAP interface was removed in midPoint 4.2. Please use RESTful service instead.

Support

Where can I get support?

Evolveum provides support in a form of midPoint subscriptions, which is a paid service. Our software is free, but our services are not. There is no free service provided by Evolveum to support midPoint.

However, there is a community communication channel that can be used to discuss midPoint-related topics, in a form of public mailing lists. This is community service, which means it is provided to the community by community. It is not provided by Evolveum. Evolveum only maintains the means of communication (mailing lists) and occasionally participates in the service. There are absolutely no guarantees regarding any communication in midPoint community.

I have found a bug in midPoint. I want it fixed.

Please see I Have Found a Bug.

Why is my bug not fixed yet? I have reported it weeks ago!

How do I get midPoint subscription?

You can get midPoint subscription from Evolveum. It is simple: just contact us. The details about the subscription programs are also available at support page of Evolveum website.

Does support cover my heavily-customized midPoint deployment?

The answer is usually "yes", but there are some considerations. In short, midPoint customizations do not automatically invalidate the support. Customized midPoint deployment are still be covered by the support, however we cannot promise to fix all your issues.

By "customization" we mean changes of midPoint at a source code level. Extending midPoint user interface using Maven overlay project, creating a custom GUI tab using Apache Wicket, implementing a custom service in midPoint or heavily modifying midPoint look and feel by changing the styleseets are examples of midPoint customizations. On the other hand, using the usual midPoint configuration and expressions are not considered to be customizations (for the purpose of this text).

The basic rules is that we will fix your issue if we are able to reproduce it in uncustomized midPoint instance. Therefore, if your issues is not caused by your customizations, it is covered by the support. If your instance is heavily-customized, you will need to provide a lot of details in your bug report and you will need to be prepared to invest a lot of time to cooperate with Evolveum team to reproduce the issue. This is likely to mean that you will also need to wait longer for your fix. There is also a chance, that the issue will be resolved as "cannot reproduce" and we will not be able to fix it. It is perhaps quite undestandable that there is no practical way how to reliably fix an issue that we cannot reproduce.

You can help us if you set up an uncustomized midPoint instance in your development or test environment and try to reproduce the issue there. This is very likely to dramatically speed up the fixing process.

Of course, we will not diagnose or fix the code of your customization. That is your own responsibility. Our responsibility is to fix midPoint code.

When it comes to customizations, there is a gray zone between issues caused by product and issues caused by customizations. We cannot promise that we will fix all your issues. But we fully acknowledge that IDM solutions often need to be customized, and that was also one of the aspects where open source nature of midPoint is a strength. Therefore, we will not turn you down when you report an issue in customized midPoint deployment. However, you have to be aware of the limitations.

Of course, this is still limited by the usual support rules. E.g. we will not fix bugs in experimental functionality that you depend on in your customization.