Flexible Authentication Configuration

Last modified 09 Jul 2026 13:39 UTC
Flexible authentication feature
This page describes configuration of Flexible authentication midPoint feature. Please see the feature page for more details.
Table of Contents

This page describes how to configure flexible authentication in midPoint. It covers the configuration of authentication modules and sequences, as well as examples of default and emergency login sequences.

Introduction

Configuration of flexible authentication is complex. Before reading this page, make sure you are familiar with basic concepts.

How users authenticate to midPoint is defined in the security policy. MidPoint comes with a predefined security policy (see 015-security-policy.xml within the initial objects). In the system configuration, it is referred to in the globalSecurityPolicyRef attribute.

If you want to configure flexible authentication, either update the default security policy (UID = 00000000-0000-0000-0000-000000000120), or create a new security policy and change the reference in the system configuration.

The security policy has the following main parts:

  • Name - Defines the policy name.

  • Credentials configuration - This defines the maximum number of attempts for login with password, references the password policy, defines password requirements, etc.

  • Authentication configuration - Defines the actual authentication in two distinct sections:

    • Modules - Defines a particular authentication method. Each module has an identifier that is referenced by a sequence in which it is used.

    • Sequences - Defines where the particular authentication method is used.

Test your configuration prior deploying.
In case of an incorrect loginForm module configuration or in case of its absence, there will be no possibility to login via the standard login form again. In that case, the user should have another way to restore the midPoint environment.
The emergency urlSuffix configuration can help in such case. See example of sequence for administrator login.

Module configuration

Authentication modules identify the protocol used for the actual authentication. By default, midPoint uses the httpBasic module for authentication in the GUI through username and password.

MidPoint supports multiple authentication modules.

Each module has its own specific configuration, however, the following elements are common for all modules:

Name Description Required Type Default

identifier

Unique identifier of the authentication module. Short identifier. It is supposed to give some idea about nature of the module to system administrator. But it is not supposed to be used as a user-friendly label for the module. The name is also used in the url, so it should not contain special characters.

true

String

description

Free form description of the module (administrator comment).

false

String

focusType

Type of logged object that this authentication module applies to. E.g UserType, RoleType, OrgType, …​

false

UserType

See the configuration details for individual modules.

Authentication sequence

Authentication sequence flow can be illustrated by following scenarios

Scenario 1

MidPoint receives an HTTP request with the URL http://localhost:8080/midpoint/actuator/metrics.

It extracts the suffix 'actuator' from the URL and determines the channel. This channel is then used to search for the default authentication sequence associated with that channel. Once found, midPoint initializes the authentication sequence and, upon successful authentication, sends a request to the actuator service.

Scenario 2

In the second scenario, midPoint receives an HTTP request with the URL http://localhost:8080/midpoint/auth/emergency/users.

Here, it extracts the 'auth' suffix from the URL, which signifies the use of a specific authentication sequence. MidPoint then proceeds to search for the appropriate authentication sequence based on the next part of the URL, which, in this case, is 'emergency'. After successfully authenticating, midPoint sends a request to the service defined in the sequence configuration. For example, if it is a GUI, the request would be redirected to the users page in the GUI.

Sequence Configuration

Sequence contains following attributes:

Name Description Required Type

name

Unique name of the authentication sequence. This name is fact a short identifier. It is supposed to give some idea about purpose of the sequence to system administrator. But it is not supposed to be used as a user-friendly label. Sequence name must be unique.

name attribute is DEPRECATED, use identifier instead.

true

String

identifier

Unique identifier of the authentication sequence. Short identifier. It is supposed to give some idea about purpose of the sequence to system administrator. But it is not supposed to be used as a user-friendly label. Sequence name must be unique.

true

String

description

Free form description of the sequence (administrator comment).

false

String

channel

Specifies the channel for the authentication sequence. This defines where a particular authentication method is used. You can define multiple sequences per channel, but only one sequence per channel can be the default sequence. The following channels are supported:
user - Handles how users authenticate in GUI.
rest - Defines the authentication process for the midPoint REST API, and it is also used in midPoint Studio.
actuator - Used mainly as a health check for midPoint instances, particularly when midPoint runs in a container or a pod.

false

AuthenticationSequenceChannelType

requireAssignmentTarget

Required assignment target. This authentication sequence is applicable only to users that have an active assignment with this target (and relation). If the sequence is attempted on a user that does not have this assignment then the authentication will fail.

false

ObjectReferenceType

nodeGroup

Required node group. This authentication sequence is applicable only to node group that have active assignment with this archetype.

false

ObjectReferenceType

module

Specification of authentication module in the sequence.

true

AuthenticationSequenceModuleType

focusBehaviorUpdate

Option for updating focus authentication behaviour attributes.

false

FocusBehaviorUpdateType

AuthenticationSequenceChannelType

Channel specification for authentication sequence. It specifies whether this sequence is usable for a specific channel (user/GUI, REST, etc.) AuthenticationSequenceChannelType contains following attributes:

Name Description Required Type

channelId

Name (URI) of the channel, i.e, one of the following:
http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user
http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest
http://midpoint.evolveum.com/xml/ns/public/common/channels-3#actuator

true

String

description

Free form description (administrator comment).

false

String

default

Specifies whether this sequence is the default sequence for a specified channel. As there can be multiple authentication sequences per channel, only one needs to be set as the default (true).
The default sequence will be chosen in case that a specific sequence was not requested, e.g., by using a URL suffix. If this element is not present and only a single sequence is defined for a channel, then such sequence is considered to be the default.
If more than one sequence is specified then none of them is considered to be default. In that case this element must be used explicitly.

false

boolean

urlSuffix

URL suffix defines the ending of the URL where the module is accessible. For example, if httpBasic is used in the user channel, and the urlSuffix is set to basic, the full URL will be <midPoint-base-URL>/midpoint/auth/basic.

true

String

FocusBehaviorUpdateType

We can enable/disable updating of focus authentication behavior (such as information about last login time) during every login, or we can use option for updating behaviour only when login failed and during success login after failed login. Default value is 'enabled'. Possible values are:

Value Description

enabled

Behaviour attributes will be updated every login.

disabled

Authentication behaviour attributes will not be updated during login.

failureOnly

Authentication behaviour attributes will be updated when login failed and when login will be success, but previous login was failed and midPoint needs to update attributes as is number of login fails and lockout state.

AuthenticationSequenceModuleType

Specification of authentication module in the sequence. The authentication modules are evaluated in sequence (or in parallel if possible). At least one authentication module must succeed for authentication to be successful. If there are required or requisite modules in the sequence then all of them must succeed for the sequence to be successful.

There is hard-coded behavior for modules which defines if the module itself is strong enough for authentication to succeed. FocusIdentification, Hint and AttributeVerification module are three specific modules, which are marked as not enough when exist on their own. Even when the sequence consist of other modules (sufficient) which were evaluated as failed and only those three (combination or one of them) succeed, the result of the authentication is failure.
Example of default sequence
<sequence>
    <identifier>admin-gui-default</identifier>
    <description>
        Default GUI authentication sequence.
        We want to try company SSO, federation and internal. In that order.
        Just one of then need to be successful to let user in.
    </description>
    <channel>
        <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user</channelId>
        <default>true</default>
        <urlSuffix>default</urlSuffix>
    </channel>
    <nodeGroup oid="05b6933a-b7fc-4543-b8fa-fd8b278ff9ee" relation="org:default" type="c:ArchetypeType"/>
    <module>
        <identifier>mySamlSso</identifier>
        <order>30</order>
        <necessity>sufficient</necessity>
    </module>
    <module>
        <identifier>internalLoginForm</identifier>
        <order>20</order>
        <necessity>sufficient</necessity>
    </module>
</sequence>
Example of sequence for administrator login

This configuration allows emergency backup access via url /emergency. It accepts only users with role superuser.

Example of URL: https://localhost/midpoint/auth/emergency .

<sequence>
    <identifier>admin-gui-emergency</identifier>
    <description>
        Special GUI authentication sequence that is using just the internal user password.
        It is used only in emergency. It allows to skip SAML authentication cycles, e.g. in case
        that the SAML authentication is redirecting the browser incorrectly.
    </description>
    <channel>
        <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user</channelId>
        <default>false</default>
        <urlSuffix>emergency</urlSuffix>
    </channel>
    <requireAssignmentTarget oid="00000000-0000-0000-0000-000000000004" relation="org:default" type="c:RoleType">
    <!-- Superuser -->
    </requireAssignmentTarget>
    <module>
        <identifier>loginForm</identifier>
        <order>1</order>
        <necessity>sufficient</necessity>
    </module>
</sequence>
Example of the default GUI sequence with configured login form

This configuration allows to configure label, description and external link for login form.

        <sequence id="3">
            <identifier>admin-gui-default</identifier>
            <displayName>Default gui sequence</displayName>
            <channel>
                <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user</channelId>
                <default>true</default>
                <urlSuffix>gui-default</urlSuffix>
            </channel>
            <module>
                <identifier>loginForm</identifier>
                <order>1</order>
                <necessity>sufficient</necessity>
                <display>
                    <label>
                        <orig>Login to your account</orig>
                        <translation>
                            <key>PageLogin.loginToYourAccount</key>
                        </translation>
                    </label>
                    <help>
                        <orig>Please enter account details to start the session</orig>
                        <translation>
                            <key>PageLogin.enterAccountDetails</key>
                        </translation>
                    </help>
                </display>
                <action>
                    <display>
                        <label>
                            <orig>Live demo documentation</orig>
                        </label>
                    </display>
                    <target>
                        <targetUrl>https://docs.evolveum.com</targetUrl>
                    </target>
                </action>
            </module>
        </sequence>

Midpoint GUI authentication form

In order to utilize the Midpoint GUI, it is necessary to configure an authentication sequence for the loginForm module.

If no authentication is configured in the security policy or if no sequence is defined in the configured authentication, midPoint will default to using the standard (built-in) login form for user GUI authentication. However, if there is at least one sequence configured that is not related to loginForm in the authentication configuration, it is imperative to explicitly specify a sequence for the loginForm module in the authentication configuration. This is essential to ensure the proper functioning of the Midpoint GUI.

To view the default configuration for the loginForm sequence, please refer to the security policy found in the Midpoint initial objects (015-security-policy.xml).

Ignored path Configuration

Tag <authentication> contains tag <ignoredLocalPath>, which defines path without authentication. For example:

<authentication>
    <ignoredLocalPath>/actuator</ignoredLocalPath>
    <ignoredLocalPath>/actuator/health</ignoredLocalPath>
    .
    .
    .
</authentication>

Complete Configuration Examples

You can find example on security-policy-flexible-authentication.

See Also

Compliance

This feature is related to the following compliance frameworks:

Was this page helpful?
YES NO
Thanks for your feedback