Flexible Authentication Configuration
Last modified 14 Mar 2024 12:46 +01: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
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

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

The following modules are supported in version 4.8: loginForm, httpBasic, httpHeader, saml2, oidc, mailNonce, smsNonce, securityQuestionsForm, httpSecQ, ldap, attributeVerification, focusIdentification, hint, other, archetypeSelection, correlation, duo.

Each module definition contains following common attributes:

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

2.1.1. Module loginForm

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

Example of loginForm module
<loginForm>
    <identifier>internalLoginForm</identifier>
    <description>Internal username/password authentication, default user password, login form</description>
</loginForm>

2.1.2. Module httpBasic

Definition of HTTP BASIC authentication module (RFC 7617).

Example of httpBasic module
<httpBasic>
    <identifier>internalHttpBasic</identifier>
    <description>Http basic username/password authentication, default user password</description>
</httpBasic>

2.1.3. Module httpSecQ

Definition of HTTP SecQ module. 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, but it is using security questions instead of password.

Example of httpBasic module
<httpSecQ>
    <identifier>httpSecurityQuestions</identifier>
</httpSecQ>

2.1.4. Module securityQuestionsForm

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

Example of securityQuestionsFrom module
<securityQuestionsForm>
    <identifier>securityQuestions</identifier>
</securityQuestionsForm>

2.1.5. Module mailNonce

From midPoint version 4.8, mailNonce module can’t be the first module in the sequence. Before mailNonce module, we need to use authentication module for identification of the user, for example focusIdentification.

Mail nonce authentication module. Module that sends randomly generated nonce in URL in mail message. This module contains next attribute:

Name Description Required Type

credentialName

Name of credential definition that should be used when validating password. This must point to a valid credential definition in the "credential" section of a security policy. If not specified then default password definition is used.

false

String
Example of mailNonce module
<mailNonce>
    <identifier>mailNonce</identifier>
    <credentialName>mailNonceCredential</credentialName>
</mailNonce>

2.1.6. Module archetypeSelection

Archetype selection module is used during Identity recovery flow. During this module processing the user can select an archetype which will be used in the following authentication modules in sequence.

Name Description Required Type

archetypeSelection

Contains the only multivalue element archetypeRef which is used to configure a list of the archetypes

false

ArchetypeSelectionType

allowUndefinedArchetype

If true, then the user can proceed authentication process without specifying a particular archetype.

If no, the particular archetype should be selected during Archetype selection module processing to proceed the authentication.

false

boolean
Example of archetypeSelection module
<archetypeSelection>
    <identifier>archetype-selection</identifier>
    <archetypeSelection>
        <archetypeRef oid="4b18a1eb-75ed-40f7-bed1-11cf2a6ef7ba"/>  <!-- Student archetype -->
        <archetypeRef oid="fd4fb0e1-0147-4431-a1c6-bc03ae5eacad"/>  <!-- Teacher archetype -->
    </archetypeSelection>
    <allowUndefinedArchetype>false</allowUndefinedArchetype>
</archetypeSelection>

2.1.7. Module correlation

Correlation module gives the possibility to find identity(es) (user object(s) for now) in midpoint using correlation mechanism within authentication process. This module is used during Identity recovery flow as the second authentication module.

The specified in the module correlators are processed one by one till the only identity is found by the correlators, or till the last correlator is proceeded. In case no identity is found after the last correlator, the list of candidates from the correlators results are considered to be a list of found identities.

Name Description Required Type

correlator

The definition of the correlator. Within this element correlatorIdentifier (should match 'name' attribute of the correlator set in object template) and order (the order during processing) are defined.

false

CorrelationModuleConfigurationType

options

Used to set some options for correlation module. For now contains the only candidateLimit element which restricts the maximum count of the found identities to the specified in this element number.

false

CorrelationModuleOptionsType
Example of correlation module
<correlation>
    <identifier>correlation</identifier>
    <correlator>
        <correlatorIdentifier>family-name-only</correlatorIdentifier>
        <order>1</order>
    </correlator>
    <correlator>
        <correlatorIdentifier>family-and-given-name</correlatorIdentifier>
        <order>2</order>
    </correlator>
    <options>
        <candidateLimit>10</candidateLimit>
    </options>
</correlation>

2.1.8. Module ldap

LDAP authentication module supports authentication via LDAP server. This module contains next attributes:

Name Description Required Type

host

Host of the LDAP server.

true

String

userDn

The user distinguished name.

true

String

userPassword

The password (credentials) to use for getting authenticated contexts.

true

String

dnPattern

The pattern which will be used to supply a DN for the user.

false

String

search

Search configuration which uses an Ldap filter to locate the user.

false

AuthenticationModuleLdapSearchType
2.1.8.1. AuthenticationModuleLdapSearchType
Name Description Required Type

pattern

The filter expression used in the user search. This is an LDAP search filter (as defined in 'RFC 2254') with optional arguments. Example: (uid={0})

true

String

namingAttr

Specifying explicit LDAP attribute that is retrieved from user’s LDAP account and contains value that matches midPoint’s username.

false

String

subtree

If true then searches the entire subtree as identified by context, if false (the default) then only searches the level identified by the context.

false

Boolean
Example of ldap module
<ldap>
    <identifier>ldapAuth</identifier>
    <host>ldap://localhost:389/dc=example,dc=com</host>
    <userDn>cn=admin,dc=example,dc=com</userDn>
    <userPassword>
        <t:clearValue>secret</t:clearValue>
    </userPassword>
    <dnPattern>uid={0},ou=people</dnPattern>
    <search>
        <pattern>(uid={0})</pattern>
        <namingAttr>uid</namingAttr>
        <subtree>true</subtree>
    </search>
</ldap>

2.1.9. Module httpHeader

Pseudo-authentication for pre-authenticated users. Based on HTTP header values. This module contains specific attributes:

Name Description Required Type

usernameHeader

Name of HTTP header that contains username.

true

String

logoutUrl

Url for redirect after logout. Default is '/'.

false

String
Example of httpHeader module
<httpHeader>AuthenticationModuleSaml2ProviderMetadataType
    <identifier>httpHeader</identifier>
    <logoutUrl>http://localhost:8081/Identity_provider/Logout</logoutUrl>
    <usernameHeader>uid</usernameHeader>
</httpHeader>

2.1.10. Module saml2

SAML2 authentication module supports authentication via Identity provider with SAML2. SAML2 module has a little complicated configuration. This module contains specific attribute:

Name Description Required Type

serviceProvider

Basic configuration of SP.

true

AuthenticationModuleSaml2ServiceProviderType
2.1.10.1. AuthenticationModuleSaml2ServiceProviderType

AuthenticationModuleSaml2ServiceProviderType contains following configuration attributes:

Name Description Required Type Default Unused from 4.4

entityId

Unique identifier of the service provider.

true

String

alias

Unique alias used to identify the selected local service provider based on used URL.

false

String

aliasForPath

Alias used for AssertionConsumerServiceURL.

false

String

defaultSigningAlgorithm

Default signing algorithm. Possible values are RSA_SHA1, RSA_SHA256, RSA_SHA512 and RSA_RIPEMD160.

false

enum

RSA_SHA256

signRequests

Flag indicating whether this service signs authentication requests.

false

boolean

false

keys

Key used by service provider.

false

AuthenticationModuleSaml2KeyType

identityProvider

Possible identity providers for this service provider.

true

AuthenticationModuleSaml2ProviderType
2.1.10.2. AuthenticationModuleSaml2KeyType

AuthenticationModuleSaml2KeyType contains following configuration attributes:

Name Description Required Type

activeSimpleKey

Base key used for signing and dencryption. You can use only one from active keys, or can be both null.

true

ModuleSaml2SimpleKeyType

activeKeyStoreKey

Base key used for signing and dencryption. You can use only one from active keys, or can be both null.

true

ModuleSaml2KeyStoreKeyType

standBySimpleKey

Other keys.

true

ModuleSaml2SimpleKeyType

standByKeyStoreKey

Other keys.

true

ModuleSaml2KeyStoreKeyType
2.1.10.3. ModuleSaml2SimpleKeyType

ModuleSaml2SimpleKeyType contains following attributes:

Name Description Required Type

privateKey

Private key.

true

ProtectedStringType

passphrase

Password.

true

ProtectedStringType

certificate

Certificate of key.

true

ProtectedStringType

type

Type of key. Possible values are SIGNING, UNSPECIFIED and DECRYPTION.

false

enum
Example of ModuleSaml2SimpleKeyType
<activeSimpleKey>
    <name>sp-signing-key</name>
    <privateKey>
        <t:clearValue>"primary key"</t:clearValue>
    </privateKey>
    <passphrase>
        <t:clearValue>"password"</t:clearValue>
    </passphrase>
    <certificate>
        <t:clearValue>"certificate"</t:clearValue>
    </certificate>
</activeSimpleKey>
2.1.10.4. ModuleSaml2KeyStoreKeyType

ModuleSaml2KeyStoreKeyType contains following attributes:

Name Description Required Type

keyStorePath

Path to KeyStore.

true

String

keyStorePassword

Password of KeyStore.

true

ProtectedStringType

keyAlias

Alias of private key in KeyStore.

true

ProtectedStringType

keyPassword

Password of private key with alias ‘keyAlias’ in KeyStore.

true

ProtectedStringType

type

Type of key. Possible values are SIGNING, UNSPECIFIED and DECRYPTION.

false

enum
Example of ModuleSaml2KeyStoreKeyType
<activeKeyStoreKey>
    <keyStorePath>/home/lskublik/keyStore</keyStorePath>
    <keyStorePassword>
        <t:clearValue>"password of keyStore"</t:clearValue>
    </keyStorePassword>
    <keyAlias>sp-signing-key-1</keyAlias>
    <keyPassword>
        <t:clearValue>"password of private key"</t:clearValue>
    </keyPassword>
</activeKeyStoreKey>
2.1.10.5. AuthenticationModuleSaml2ProviderType

AuthenticationModuleSaml2ProviderType represents one Identity Providers. AuthenticationModuleSaml2ProviderType contains following attributes:

Name Description Required Type Default

entityId

Unique identifier of the service provider.

true

String

metadata

Metadata of Identity provider.

true

AuthenticationModuleSaml2MetadataType

linkText

User friendly name of provider.

false

String

authenticationRequestBinding

SAML2 binding used for authentication request.

true

String

verificationKeys

false

ProtectedStringType

nameOfUsernameAttribute

Name of attribute in response, which value define name of user in Midpoint. For example 'uid'.

true

String
2.1.10.6. AuthenticationModuleSaml2ProviderMetadataType

AuthenticationModuleSaml2ProviderMetadataType represents metadata of provider. You can choose from one definition for metadata: metadataUrl, xml and pathToFile.

Name Description

metadataUrl

URL, which show metadata.

xml

Xml of metadata encrypted by base64.

pathToFile

Path to xml file, which contains metadata.
Example of saml2 module
<saml2>
    <identifier>mySamlSso</identifier>
    <description>My internal enterprise SAML-based SSO system.</description>
    <serviceProvider>
        <entityId>sp_midpoint</entityId>
        <signRequests>true</signRequests>
        <keys>
            .
            .
            .
        </keys>
        <identityProvider>
            <entityId>https://idptestbed/idp/shibboleth</entityId>
            <metadata>
                <xml>PD94bWwgdmVyc2lvbj0iMS4wI...</xml>
            </metadata>
            <linkText>Shibboleth</linkText>
            <authenticationRequestBinding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST</authenticationRequestBinding>
            <nameOfUsernameAttribute>uid</nameOfUsernameAttribute>
        </identityProvider>
    </serviceProvider>
</saml2>
2.1.10.7. Generation of service provider metadata

Midpoint can generate metadata of SP. You can get it via link http://<midpointHost>/midpoint/auth/<authenticationSequenceUrlSuffix>/<saml2ModuleName>/metadata/<registrationId>;. RegistrationId is 'aliasForPath', when is provided, or 'alias', when is provided, or 'entityId' of SP.

Generation of metadata works only if your sequence use only saml2 authentication module or saml2 authentication module is first in chain of your sequence. When you want to use a chain and saml2 module won’t be first authentication module, we recommend to create sequence only with saml module, generate metadata and then add other modules.

If Midpoint is located behind a reverse proxy it may be useful to set the publicHttpUrlPattern setting to the right value in order for the SAML endpoints (in the SP Metadata and in the SAMLRequest) to reflect the right URLs (see below)

Example of public URL configuration
<systemConfiguration>
    .
    .
    .
    <infrastructure>
        <publicHttpUrlPattern>https://public.url.local/midpoint</publicHttpUrlPattern>
    </infrastructure>
    .
    .
    .
</systemConfiguration>
2.1.10.8. Migration Saml2 authentication module from 4.3

Dependency for support of saml2 authentication module was changed to Spring Security saml2-service-provider.

  • Functionality of a new module is equivalent to the functionality of old saml2 module, however some configuration properties are not available in the new module. Such properties were tagged as deprecated in schema of saml2 authentication module.

  • Attribute 'provider' has to be changed to 'identityProvider' in 'serviceProvider'.

  • When keys of 'type' ENCRYPTION are used, they need to be removed. Service provider will obtain them from metadata for identity provider.

2.1.11. Module oidc

Since 4.5
This functionality is available since version 4.5.

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

OIDC Authentication module contains two different types of configuration:

  1. GUI with channel http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user, that was defined by attribute client,

  2. REST with channel http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest, that was defined by attribute resourceServer.

2.1.11.1. Configuration for GUI

Configuration for GUI is provided via attribute client, that is type OidcClientAuthenticationModuleType. Client supports only grand type Authorization code. We need to configure client properties for client authentication and configuration of OpenID provider for provide identity for identification of midpoint focus.

Client contains following attributes:

Name Description Required Type

registrationId

Unique identifier of the client. RegistrationId is used in url path, so it has to contain only correct symbols.

true

String

clientId

OAuth 2.0 Client Identifier valid at the Authorization Server.

true

String

clientSecret

OAuth 2.0 Client Secret valid at the Authorization Server.

false

ProtectedStringType

clientAuthenticationMethod

Define client authentication method. Possible values is clientSecretBasic, clientSecretPost, clientSecretJwt and privateKeyJwt.

false

OidcClientAuthenticationMethodType

clientSigningAlgorithm

Required node group. Identifier of algorithm for digitally sign or create a MAC of the content. (RFC7518 section-3.1)

false

String

scope

OpenID Connect Clients use scope values as defined in 3.3 of OAuth 2.0 [RFC6749] to specify what access privileges are being requested for Access Tokens. Scope contains 'openid', so we don’t need set it. Scope is multivalue attribute, so please set every value of scope to separate tags.

false

String

clientName

Human friendly name of client.

false

String

nameOfUsernameAttribute

Name of attribute in response, which value define name of user in Midpoint. Default value is 'sub'.

false

String

openIdProvider

OpenID Provider.

false

OidcOpenIdProviderType

simpleProofKey

Key used for sign with privateKeyJwt. Choice simpleProofKey or keyStoreProofKey.

false

AbstractSimpleKeyType

keyStoreProofKey

Key from key store used for sign with privateKeyJwt. Choice simpleProofKey or keyStoreProofKey.

false

AbstractKeyStoreKeyType

AbstractSimpleKeyType contains following attributes:

Name Description Required Type

privateKey

Private key.

true

ProtectedStringType

passphrase

Password.

true

ProtectedStringType

certificate

Certificate of key.

true

ProtectedStringType

AbstractKeyStoreKeyType contains following attributes:

Name Description Required Type

keyStorePath

Path to KeyStore.

true

String

keyStorePassword

Password of KeyStore.

true

ProtectedStringType

keyAlias

Alias of private key in KeyStore.

true

ProtectedStringType

keyPassword

Password of private key with alias ‘keyAlias’ in KeyStore.

true

ProtectedStringType

OidcOpenIdProviderType

Definition for OpenID Provider. Possible attributes are:

Name Description Required Type

issuerUri

Issuer identifier uri for the OpenID Connect provider.

true

String

authorizationUri

Uri for the authorization endpoint.

false

String

tokenUri

Uri for the token endpoint.

false

String

userInfoUri

Uri for user info endpoint.

false

String

endSessionUri

Uri for logout endpoint.

false

String

jwkSetUri

Uri for JSON web key set endpoint. Available from midPoint 4.8.

false

String

Required attribute is only issuerUri, because midPoint gets configuration for all other URIs from 'issuerUri'/.well-known/openid-configuration. MidPoint can write error to log file that some from optional configuration URIs is null and required. This error we can see when 'issuerUri'/.well-known/openid-configuration is unavailable.

Examples

The following example shows a simple client secret based authentication against Keycloak.

What is needed to make it work:

  1. Installed Keycloak e.g. from the Docker image. In the following we assume it’s running on http://192.168.4.100:8080/

  2. Created client midpoint (in Keycloak), with client authentication turned on and our midPoint URL (e.g., http://localhost:8080/midpoint/*) set as "Valid redirect URI".

  3. A sample user (e.g. jack) created in Keycloak, with a password set.

  4. The same user created in midPoint, with no password, but some roles (e.g. End user) allowing them to log in.

Example of client configuration with client authentication using client secret
<securityPolicy>
    <authentication>
        <modules>
            ...
            <loginForm> (1)
                <identifier>loginForm</identifier>
            </loginForm>
            ...
            <oidc> (2)
                <identifier>gui-oidc</identifier>
                <client>
                    <registrationId>oidc-registration</registrationId> (3)
                    <clientId>midpoint</clientId> (4)
                    <clientSecret>
                        <t:clearValue>RwdBxRhOggkDCr321SzyGwkEVvRHd7g1</t:clearValue> (5)
                    </clientSecret>
                    <clientAuthenticationMethod>clientSecretBasic</clientAuthenticationMethod>
                    <nameOfUsernameAttribute>preferred_username</nameOfUsernameAttribute>
                    <openIdProvider>
                        <issuerUri>http://192.168.4.100:8080/realms/master</issuerUri> (6)
                    </openIdProvider>
                </client>
            </oidc>
            ...
        </modules>
        ...
        <sequence> (2)
            <identifier>gui-oidc</identifier>
            <channel>
                <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user</channelId>
                <default>true</default>
                <urlSuffix>gui-oidc</urlSuffix>
            </channel>
            <module>
                <identifier>gui-oidc</identifier>
            </module>
        </sequence>
        ...
        <sequence> (1)
            <identifier>gui-login-form</identifier>
            <channel>
                <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user</channelId>
                <urlSuffix>gui-login-form</urlSuffix>
            </channel>
            <module>
                <identifier>loginForm</identifier>
            </module>
        </sequence>
        ...
    </authentication>
</securityPolicy>
1 To allow logging in for users that have no accounts in Keycloak (e.g., default midPoint administrator). Not strictly necessary.
2 OpenID Connect login for ordinary users.
3 Technical information that may be basically anything legal for inclusion into URI.
4 ID of the client as registered in Keycloak.
5 Secret of the client as generated by Keycloak (or provided manually).
6 URL at which Keycloak runs.

Administrator logs in at http://localhost:8080/midpoint/auth/gui-login-form. Ordinary users log in at http://localhost:8080/midpoint (the default authentication).

More advanced example

The following is a more advanced example using JWT-based authentication method.

Example of client configuration with client authentication for client signed JWT
<securityPolicy>
    <authentication>
        ...
        <modules>
            <oidc>
                <identifier>oidcKeycloak</identifier>
                <client>
                    <registrationId>keycloak</registrationId>
                    <clientId>account</clientId>
                    <clientSecret>
                        <clearValue>'client_secret'</clearValue>
                    </clientSecret>
                    <clientAuthenticationMethod>privateKeyJwt</clientAuthenticationMethod>
                    <nameOfUsernameAttribute>preferred_username</nameOfUsernameAttribute>
                    <openIdProvider>
                        <issuerUri>https://keycloak.lab.evolveum.com/auth/realms/test</issuerUri>
                    </openIdProvider>
                    <keyStoreProofKey>
                        <keyStorePath>/home/user/keystore.jks</keyStorePath>
                        <keyStorePassword>
                            <clearValue>password</clearValue>
                        </keyStorePassword>
                        <keyAlias>account</keyAlias>
                        <keyPassword>
                            <clearValue>password</clearValue>
                        </keyPassword>
                    </keyStoreProofKey>
                    <scope>profile</scope>
                    <scope>user</scope>
                </client>
            </oidc>
        </modules>
        <sequence>
            <identifier>admin-gui-default</identifier>
            <channel>
                <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user</channelId>
                <default>true</default>
                <urlSuffix>defaultGui</urlSuffix>
            </channel>
            <module>
                <identifier>oidcKeycloak</identifier>
                <order>10</order>
                <necessity>sufficient</necessity>
            </module>
        </sequence>
        ...
    </authentication>
</securityPolicy>
Since version 4.8, the flow for identifying a user logged in via the GUI has been changed. MidPoint uses the claim value with the name from the nameOfUsernameAttribute. The claim is primarily obtained from the ID token. When a claim is missing in the ID token, midPoint looks for it in the access token. Finally, if the claim is missing in the access token, midPoint uses the user info endpoint to retrieve the claim. Only the last step applies to Midpoint 4.7

If Midpoint is located behind a reverse proxy it may be useful to set the publicHttpUrlPattern setting to the right value in order for the OIDC Redirect URI to point to a valid public URL (see below).

Example of public URL configuration
<systemConfiguration>
    .
    .
    .
    <infrastructure>
        <publicHttpUrlPattern>https://public.url.local/midpoint</publicHttpUrlPattern>
    </infrastructure>
    .
    .
    .
</systemConfiguration>
2.1.11.2. Configuration for REST

Configuration for REST is provided via attribute resourceServer, that is type OidcResourceServerAuthenticationModuleType. When we want to use OIDC module for REST, midPoint works as resource server. REST request has to contain WWW-Authentication header with syntax Authorization: Bearer {token}.

Resource server contains following attributes:

Name Description Required Type Note

jwt

Define that resource server expect token in format JWT.

false

JwtOidcResourceServerType

Since midPoint 4.8.

opaqueToken

Define that resource server expect opaque token, which have to be verified by user info endpoint.

false

OpaqueTokenOidcResourceServerType

Since midPoint 4.8.

realm

Realm which midPoint use for WWW-Authentication header.

false

String

Deprecated since midPoint 4.8. Use attribute in token definition instead.
Planned removal in midPoint 4.9.

issuerUri

Issuer identifier URI for the OpenID Connect provider.

false

String

Deprecated since midPoint 4.8. Use attribute in token definition instead.
Planned removal in midPoint 4.9.

jwkSetUri

URI for the JSON Web Key (JWK) Set endpoint.

false

String

Deprecated since midPoint 4.8. Use attribute in token definition instead.
Planned removal in midPoint 4.9.

nameOfUsernameClaim

Name of claim in JWT, which value define name of user in midPoint.

false

String

Deprecated since midPoint 4.8. Use attribute in token definition instead.
Planned removal in midPoint 4.9.

singleSymmetricKey

Trusting a Single Asymmetric Key.

false

ProtectedStringType

Deprecated since midPoint 4.8. Use attribute in token definition instead.
Planned removal in midPoint 4.9.

trustedAlgorithm

Trusted Algorithms. (RFC7518 section-3.1).

false

String

Deprecated since midPoint 4.8. Use attribute in token definition instead.
Planned removal in midPoint 4.9.

trustingAsymmetricCertificate

Certificate of trusting a single asymmetric RSA public key.

false

ProtectedStringType

Deprecated since midPoint 4.8. Use attribute in token definition instead.
Planned removal in midPoint 4.9.

keyStoreTrustingAsymmetricKey

Key store with trusting a single asymmetric RSA public key.

false

AbstractKeyStoreKeyType

Deprecated since midPoint 4.8. Use attribute in token definition instead.
Planned removal in midPoint 4.9.
Until version 4.8 midPoint needs a JWT to authenticate and identify the midpoint. The configuration attributes used are directly in the OidcResourceServerAuthenticationModuleType.

Since version 4.8, midPoint supports two token formats, JWT (JwtOidcResourceServerType) and opaque token (OpaqueTokenOidcResourceServerType).

JWT format

When we choose the configuration for jwt(JwtOidcResourceServerType) midPoint obtains a claim, with the name from the nameOfUsernameClaim attribute, from the jwt that is contained in the request.

We have four choices for verification JWT, using issuerUri, JWKSetUri, singleSymmetricKey or using public key, by trustingAsymmetricCertificate or keyStoreTrustingAsymmetricKey.

JwtOidcResourceServerType contains following attributes:

Name Description Required Type

realm

Realm which Midpoint use for WWW-Authentication header.

false

String

issuerUri

Issuer identifier URI for the OpenID Connect provider.

false

String

jwkSetUri

URI for the JSON Web Key (JWK) Set endpoint.

false

String

nameOfUsernameClaim

Name of claim in JWT, which value define name of user in midPoint.

String

singleSymmetricKey

Trusting a Single Asymmetric Key.

false

ProtectedStringType

trustedAlgorithm

Trusted Algorithms. (RFC7518 section-3.1).

false

String

trustingAsymmetricCertificate

Certificate of trusting a single asymmetric RSA public key.

false

ProtectedStringType

keyStoreTrustingAsymmetricKey
Opaque token format

When we select the configuration for the opaqueToken(OpaqueTokenOidcResourceServerType) midPoint, we get the claim with the name from the nameOfUsernameClaim attribute from the user info endpoint.

OpaqueTokenOidcResourceServerType contains following attributes:

Name Description Required Type

realm

Realm which Midpoint use for WWW-Authentication header.

false

String

issuerUri

Issuer identifier URI for the OpenID Connect provider.

false

String

nameOfUsernameClaim

Name of claim in JWT, which value define name of user in midPoint.

String

userInfoUri
Example of Resource server configuration with issuerUri.
<securityPolicy>
    <authentication>
        ...
        <modules>
            <oidc>
                <identifier>oidcResourceServer</identifier>
                <resourceServer>
                    <jwt(or opaqueToken)>
                        <issuerUri>https://keycloak.lab.evolveum.com/auth/realms/test</issuerUri>
                        <nameOfUsernameClaim>preferred_username</nameOfUsernameClaim>
                    </jwt(or opaqueToken)>
                </resourceServer>
            </oidc>
        </modules>
        <sequence>
            <identifier>rest</identifier>
            <channel>
                <channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest</channelId>
                <default>true</default>
                <urlSuffix>rest-default</urlSuffix>
            </channel>
            <module>
                <identifier>oidcResourceServer</identifier>
                <order>10</order>
                <necessity>sufficient</necessity>
            </module>
        </sequence>
        ...
    </authentication>
</securityPolicy>

2.1.12. Module focusIdentification

Focus identification authentication module. Module that according to the specified attributes tries to find a user in midPoint. If only focusIdentification module is defined, authentication won’t succeed. This module is marked as not sufficient to live on its own.

Name Description Required Type

item

Structure defining how the user should be looked for.

true

ModuleItemConfigurationType

ModuleItemConfigurationType consists of the following attributes:

Name Description Required Type

path

The path to the focus attribute according to which the focus should be found.

true

ItemPathType

matchingRule

Matching rule which should be used for this item while filtering or comparing

false

QName
Example of focusIdentification module
<focusIdentification>
    <identifier>focusId</identifier>
    <item>
        <path>name</path>
        <matchingRule>polyStringNorm</matchingRule>
    </item>
</focusIdentification>

2.1.13. Module hint

Hint authentication module. Special module which was implemented to be able to use it during resetting password. The aim of the module is to provide the password hint (if defined) to the user. This module is marked as not sufficient to live on its own.

This module has no other configuration options.

Example of hint module
<hint>
    <identifier>hintAuth</identifier>
</hint>

2.1.14. Module attributeVerification

Attribute verification authentication module. Module which can be used as additional to any of the previous authentication modules. The aim of the module is to check defined focus items if they match. The focus must be identified for this module to be used. This module is marked as not sufficient to live on its own.

Name Description Required Type

item

Structure defining which items to check if they match.

true

ModuleItemConfigurationType

ModuleItemConfigurationType consists of the following attributes:

Name Description Required Type

path

The path to the focus attribute which should be checked if matches.

true

ItemPathType

matchingRule

Matching rule which should be used for this item while filtering or comparing the attribute values.

false

QName
Example of attributeVerification module
<attributeVerification>
    <identifier>attributeVerification</identifier>
    <item>
        <path>extension/employeeCardID</path>
    </item>
</attributeVerification>

2.1.15. Module duo

Module is used for 2FA authentication. Module use duo server for authentication via hardware key of mobile, tablet and so on. We can’t use it as only one authentication module. We need some primary authentication module for example saml, loginForm, etc.

Configuration of duo module contains next configuration properties, that you can read from duo server.

Name Description Required Type

clientId

This value is the client id provided by Duo in the admin panel.

true

string

clientSecret

This value is the client secret provided by Duo in the admin panel.

true

ProtectedStringType

apiHostname

This value is the api host provided by Duo in the admin panel.

true

string

CACerts

List of CA Certificates to use. You need add your cert when it misses in default certs.

false

string

pathForDuoUsername

The path to the user attribute which should be sent to duo server as username of authenticated user. Default path is for name attribute.

false

ItemPathType
Example of duo module
<duo>
    <identifier>duo2FA</identifier>
    <clientId>your_client_ID</clientId>
    <clientSecret>
        <clearValue>your_client_secret</clearValue>
    </clientSecret>
    <apiHostname>your_api_hostname</apiHostname>
</duo>

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

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

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

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

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

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