Flexible Authentication Configuration

Last modified 07 May 2024 07:18 +02:00

Flexible authentication feature

This page describes configuration of Flexible authentication midPoint feature. Please see the feature page for more details.

Since 4.4

This functionality is available since version 4.4. The functionality was further improved in versions 4.5, 4.7, 4.8.

Table of Contents

1. Basic concepts
2. Basic configuration
- 2.1. Module configuration
- 2.2. Sequence Configuration
3. Necessity Configuration
4. Ignored path Configuration
5. Logout
6. Complete Configuration Examples
7. Limitations
8. See Also

Test your configuration prior deploying.

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

1. Basic concepts

To better understand the configuration of flexible authentication, it is essential to familiarize ourselves with a few key terms.

1.1. Authentication module

Authentication modules are the basic building blocks of flexible authentication. The easiest example of authentication module is the classic login form, found on many websites. An example is the classic login form found on many websites, which typically includes fields for a username or email and a password. This login form represents just one authentication module. There are others like LDAP, HTTP basic authentication, or Identity Provider server authentication, each with its own configuration settings.

1.2. Authentication sequence and channel

An authentication sequence consists of a chain of authentication modules, each with its specific order and configuration requirements within the sequence. These sequences are defined by channels.

A channel represents a portion of Midpoint for which a particular authentication sequence is applicable. For instance, a channel can be associated with the GUI or a REST service. Additionally, each channel includes a URL suffix, which further specifies when this authentication sequence should be used.

In essence, a channel determines which authentication sequence will be employed for an HTTP request.

Flexible authentication encompasses the following channels:

Request servlet suffix	Channel	Note
	http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user	Default one, represents GUI. No suffix specified.
/ws, /rest, /api	http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest
/actuator	http://midpoint.evolveum.com/xml/ns/public/common/channels-3#actuator
/resetPassword	http://midpoint.evolveum.com/xml/ns/public/common/channels-3#resetPassword
/registration	http://midpoint.evolveum.com/xml/ns/public/common/channels-3#selfRegistration
/invitation	http://midpoint.evolveum.com/xml/ns/public/common/channels-3#invitation
/identityRecovery	http://midpoint.evolveum.com/xml/ns/public/common/channels-3#identityRecovery

Request servlet suffix

Channel

Note

http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user

Default one, represents GUI. No suffix specified.

/ws, /rest, /api

http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest

/actuator

http://midpoint.evolveum.com/xml/ns/public/common/channels-3#actuator

/resetPassword

http://midpoint.evolveum.com/xml/ns/public/common/channels-3#resetPassword

/registration

http://midpoint.evolveum.com/xml/ns/public/common/channels-3#selfRegistration

/invitation

http://midpoint.evolveum.com/xml/ns/public/common/channels-3#invitation

/identityRecovery

http://midpoint.evolveum.com/xml/ns/public/common/channels-3#identityRecovery

Channels for rest and actuator default don’t create audit records about session creation or termination. You can turn it on via setting System Configuration → audit → eventRecording → recordSessionlessAccess.

1.3. Selecting the authentication sequence

We can illustrate the authentication sequence flow with two examples.

1.3.1. First example

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

It extracts the suffix 'actuator' from the URL and by it determines the channel (see table above). 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.

1.3.2. Second example

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.

2. Basic configuration

Flexible authentication is configured in Security Policy. Security policy can be defined on different levels. There is a global level, when the security policy is defined in System Configuration. Since midPoint 4.7 it is also possible to define security policies for organization unit and archetype. All security policies applicable for the user are merged together. The merging is performed after user identification, so after the first module which was able to find a user in the system.

Base tag is <authentication>. Configuration consists of modules and sequences. Element module is basic building block of the configuration. Each element has a configuration of a particular authentication module instance such as internal password-based authentication, SAML authentication and so on. Each module specified in the container must have unique identifier. Element sequence defines a sequence of authentication modules. The modules are invoked in order as they are specified in the sequence. The purpose of the sequence is to guide user through a complete authentication process.

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 there is no sequence 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).

2.1. Module configuration

Each module definition contains following common attributes:

Name Description Required Type Default

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

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

The following modules are supported:

Name	Description
loginForm	LoginForm module is used for interactive log-in of a user by using HTML forms.
httpBasic	Definition of HTTP BASIC authentication module (RFC 7617).
httpSecQ	The module is used for quasi-interactive log-in of a user by answering a set of security questions. The HTTP SecQ mechanism is similar to HTTP BASIC mechanism.
securityQuestionsForm	The module is used for interactive log-in of a user by answering a set of security questions.
mailNonce	Module that sends randomly generated nonce in URL in mail message.
archetypeSelection	During this module processing the user can select an archetype which will be used in the following authentication modules in sequence.
correlation	Correlation module gives the possibility to find identity(es) (user object(s) for now) in midpoint using correlation mechanism within authentication process.
ldap	LDAP authentication module supports authentication via LDAP server.
httpHeader	Pseudo-authentication for pre-authenticated users. Based on HTTP header values.
saml2	SAML2 authentication module supports authentication via Identity provider with SAML2.
oidc	OIDC authentication module supports authentication via Identity provider that supports OpenID connect.
focusIdentification	Module that according to the specified attributes tries to find a user in midPoint.
hint	The aim of the module is to provide the password hint (if defined) to the user.
attributeVerification	The aim of the module is to check defined focus items if they match.
duo	Module is used for 2FA authentication. Module use duo server for authentication via hardware key of mobile, tablet and so on.

Name

Description

loginForm

LoginForm module is used for interactive log-in of a user by using HTML forms.

httpBasic

Definition of HTTP BASIC authentication module (RFC 7617).

httpSecQ

The module is used for quasi-interactive log-in of a user by answering a set of security questions. The HTTP SecQ mechanism is similar to HTTP BASIC mechanism.

securityQuestionsForm

The module is used for interactive log-in of a user by answering a set of security questions.

mailNonce

Module that sends randomly generated nonce in URL in mail message.

archetypeSelection

During this module processing the user can select an archetype which will be used in the following authentication modules in sequence.

correlation

Correlation module gives the possibility to find identity(es) (user object(s) for now) in midpoint using correlation mechanism within authentication process.

ldap

LDAP authentication module supports authentication via LDAP server.

httpHeader

Pseudo-authentication for pre-authenticated users. Based on HTTP header values.

saml2

SAML2 authentication module supports authentication via Identity provider with SAML2.

oidc

OIDC authentication module supports authentication via Identity provider that supports OpenID connect.

focusIdentification

Module that according to the specified attributes tries to find a user in midPoint.

hint

The aim of the module is to provide the password hint (if defined) to the user.

attributeVerification

The aim of the module is to check defined focus items if they match.

duo

Module is used for 2FA authentication. Module use duo server for authentication via hardware key of mobile, tablet and so on.

2.2. Sequence Configuration

Sequence contains following attributes:

Name Description Required Type

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`	Specification of channel for authentication sequence.	false	AuthenticationSequenceChannelType
`requireAssignmentTarget`	Required assignment target. This authentication sequence is applicable only to users that have 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

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

Specification of channel for authentication sequence.

false

AuthenticationSequenceChannelType

requireAssignmentTarget

Required assignment target. This authentication sequence is applicable only to users that have 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

2.2.1. 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

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.

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.

2.2.2. 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

Name	Description	Required	Type
`channelId`	Name (URI) of the channel.	true	String
`description`	Free form description (administrator comment).	false	String
`default`	Specifies whether this sequence is the default sequence for a specified channel. The default sequence will be chosen in case that specific sequence was not requested, e.g. by using 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 that can be used to select this authentication sequence specifically.	true	String

channelId

Name (URI) of the channel.

true

String

description

Free form description (administrator comment).

false

String

default

Specifies whether this sequence is the default sequence for a specified channel.
The default sequence will be chosen in case that specific sequence was not requested, e.g. by using 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 that can be used to select this authentication sequence specifically.

true

String

2.2.3. 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. AuthenticationSequenceModuleType contains following attributes:

Name Description Required Type

Name	Description	Required	Type
`name`	Reference to the authentication module name. Value of this element must match name of existing authentication module. `name` attribute is DEPRECATED, use `identifier` instead.	true	String
`identifier`	Reference to the authentication module identifier. Value of this element must match the identifier of existing authentication module.	true	String
`description`	Free form description (administrator comment).	false	String
`order`	Ordering number for the module. The modules are sorted according to those numbers.	false	100
`necessity`	Necessity, i.e. the level of requirement, whether the module is mandatory or optional. We support only SUFFICIENT modules in 4.1. Since 4.7, supported necessity levels are SUFFICIENT, REQUIRED, REQUISITE, OPTIONAL	false	SUFFICIENT
`acceptEmpty`	Some modules might be automatically skipped if the concrete type of credentials is not defined. E.g. if there is no "hint" defined for the user, we can skip evaluation of the hint module. The same can apply for example for security questions. In case the module can be skipped, accept empty must be set to `true`. When such module exits and it is skipped, it is marked as CALLED_OFF in the sequence.	false	false

name

Reference to the authentication module name. Value of this element must match name of existing authentication module.

name attribute is DEPRECATED, use identifier instead.

true

String

identifier

Reference to the authentication module identifier. Value of this element must match the identifier of existing authentication module.

true

String

description

Free form description (administrator comment).

false

String

order

Ordering number for the module. The modules are sorted according to those numbers.

false

100

necessity

Necessity, i.e. the level of requirement, whether the module is mandatory or optional. We support only SUFFICIENT modules in 4.1.

Since 4.7, supported necessity levels are SUFFICIENT, REQUIRED, REQUISITE, OPTIONAL

false

SUFFICIENT

acceptEmpty

Some modules might be automatically skipped if the concrete type of credentials is not defined. E.g. if there is no "hint" defined for the user, we can skip evaluation of the hint module. The same can apply for example for security questions. In case the module can be skipped, accept empty must be set to true. When such module exits and it is skipped, it is marked as CALLED_OFF in the sequence.

false

There is one 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>

3. Necessity Configuration

Since 4.7

This functionality is available since version 4.7.

Each module defined in sequence can define its necessity. Following necessity levels are available:

SUFFICIENT - The module is sufficient for authentication to succeed. It is NOT required to succeed. If this module succeeds, the evaluation stops. The result is a success. Other modules are NOT evaluated. Except for the case when "required" module that was evaluated before has failed. If this module fails, the evaluation continues. Other modules are evaluated.
REQUIRED - The module is required. The module must succeed for the entire sequence to be successful. If this module succeeds, the evaluation continues. Other modules are evaluated. If this module fails, the evaluation continues. Other modules are evaluated. Final result of authentication sequence is a failure.
REQUISITE - The module is required. The module must succeed for the entire sequence to be successful. If this module succeeds, the evaluation continues. Other modules are evaluated. If this module fails, the evaluation stops with an error. Other modules are NOT evaluated. Final result of authentication sequence is a failure.
OPTIONAL - The module is optional. It is NOT required to succeed. Optional module does not really influence the result of the authentication. But it may be used to add some authentication attributes, it may be used to cross-authenticate is SSO realms and so on. If this module succeeds, the evaluation continues. If this module fails, the evaluation continues. The result of the sequence is a failure only if this is the only module in the sequence, and it fails.

The necessity levels might be combined. E.g. there might be a sequence consisting of three different modules each defined with different necessity level. The evaluation of the authentication is performed after each module. If SUFFICIENT module is found and its evaluation was successful, all previous modules are checked. In case, all previously REQUIRED and REQUISITE modules were successful, the authentication ends with the success. If any of them failed, authentication continues. All other modules defined in the sequence are evaluated and the result of the authentication is failure.

If evaluation for SUFFICIENT module failed, authentication continues according to the sequence defined. In case, there are REQUIRED modules and all of them are successful, despite the SUFFICIENT module failed, authentication is evaluated as successful. Only if the SUFFICIENT module is last and its evaluation failed, the whole authentication is evaluated as failed. Last SUFFICIENT module in the sequence MUST be successful for authentication to succeed.

If any of the REQUISITE modules failed, authentication stops and the result is failure.

4. Ignored path Configuration

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

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

5. Logout

Midpoint supports logout by removing session and data connected with session. Removing session is provided by request to logout by user or termination of session after timeout.

'httpHeader' and 'saml2' authentication modules support sending logout request to logout URL, but only for logout requested by user. For session timeout only its removing is supported.

6. Complete Configuration Examples

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

7. Limitations

Those are the limitations of current implementation of flexible authentication mechanisms.

Configuration schema for flexible authentication is designed to be mostly complete. However, not all configuration options are currently supported.
Social login functionality is not supported yet.
It is unlikely that midPoint could be used as a member of identity federation directly. Identity proxy or a similar technology may be needed.
Support for authentication module necessity is fully supported since 4.8.
Authentication modules for SOAP web services are not supported because SOAP is deprecated and it will be removed soon.
REST service supports HTTP basic authentication and OpenID Connect authentication.
Even though the authentication configuration often suggests that there may be more than one instances of credentials (password, nonce), midPoint currently supports only a single password, single nonce and a single set of security questions. Multiple credentials are not supported. The reason for mentioning credential names the configuration schema is to have ability to extend midPoint functionality in the future.

The implementation can be improved in the future. Please see Flexible Authentication Improvements for the details.

8. See Also

Was this page helpful?

YES NO

Thanks for your feedback