Navigation Tree

Module oidc

Last modified 09 Jul 2026 13:52 UTC

Since 4.5

This functionality is available since version 4.5.

This page describes how to configure the OIDC authentication module in midPoint for integrating with an OpenID Connect identity provider.

The OIDC Authentication module contains two different types of configuration:

GUI with the http://midpoint.evolveum.com/xml/ns/public/common/channels-3#user channel defined by the client attribute,
REST with http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest channel defined by the resourceServer attribute.

The OIDC module (Open ID Connect) relies considerably on HTTPS. Therefore, in production environments, you need to add the relevant protocols to the midPoint trust store, i.e., to the <midpoint-home>/keystore.jceks file. This may not be needed in local testing and experimental deployments.

Configuration for GUI

Configuration for GUI is provided via the client attribute that is of the OidcClientAuthenticationModuleType type. Client supports only the grand type Authorization code. You need to configure client properties for client authentication and configuration of the OpenID provider so that midPoint can obtain user identity and map it to a focus.

Client contains the following attributes:

Name Description Required Type

Name	Description	Required	Type
`registrationId`	Unique identifier of the client. `RegistrationId` is used in the 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`	Defines the client authentication method. Valid values are `clientSecretBasic`, `clientSecretPost`, `clientSecretJwt`, `privateKeyJwt` and `none`. Note that the values used for midPoint configuration follow the camel case convention, not the snake case convention typically used by OIDC providers.	false	OidcClientAuthenticationMethodType
`clientSigningAlgorithm`	Required node group. Defines the algorithm used for signatures in JWT tokens, etc. MidPoint uses this to authenticate to the OIDC provider. (See RFC7518 section-3.1.)	false	String
`idTokenSigningAlgorithm`	JDefinition of the algorithm used by the OIDC provider to authenticate to midPoint. If not set, it is assumed to be equal to `clientSigningAlgorithm`. (See RFC7518 section-3.1.)	false	String
`scope`	OpenID Connect Clients use scope values as defined in 3.3 of OAuth 2.0 RFC6749 that specify what access privileges are being requested for Access Tokens. Scope is a multivalue attribute and every value needs to be set in a separate tag. The 'openid' value is included by default. Other frequently used values are `profile`, `openid`, `email`, `hr`, etc. These are typically used to request additional claims about the user, such as their name, email address, or other profile information that may be necessary to identify the user in midPoint when username is not available.	false	String
`clientName`	Human friendly name of the client.	false	String
`nameOfUsernameAttribute`	Definition of the attribute by which the OIDC provider refers to the subject of the authentication process. If it is supposed to be the name of the user in midPoint, it should be set to `preferred_username`. Note that the values of `preferred_username` should correspond to the values of the `name` attribute in midPoint. Default value is 'sub'.	false	String
`openIdProvider`	Definition of URIs and endpoints of the OIDC provider. See `OidcOpenIdProviderType` for more details.	false	OidcOpenIdProviderType
`simpleProofKey`	Key used for signing with `privateKeyJwt`. Choose between `simpleProofKey` and `keyStoreProofKey`.	false	AbstractSimpleKeyType
`keyStoreProofKey`	Key from key store used for signing with `privateKeyJwt`. Choose between `simpleProofKey` and `keyStoreProofKey`.	false	AbstractKeyStoreKeyType
`usePkce`	Use Proof Key for Code Exchange for added security. (RFC7636)	false	Boolean

registrationId

Unique identifier of the client. RegistrationId is used in the 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

Defines the client authentication method. Valid values are clientSecretBasic, clientSecretPost, clientSecretJwt, privateKeyJwt and none. Note that the values used for midPoint configuration follow the camel case convention, not the snake case convention typically used by OIDC providers.

false

OidcClientAuthenticationMethodType

clientSigningAlgorithm

Required node group. Defines the algorithm used for signatures in JWT tokens, etc. MidPoint uses this to authenticate to the OIDC provider. (See RFC7518 section-3.1.)

false

String

idTokenSigningAlgorithm

JDefinition of the algorithm used by the OIDC provider to authenticate to midPoint. If not set, it is assumed to be equal to clientSigningAlgorithm. (See RFC7518 section-3.1.)

false

String

scope

OpenID Connect Clients use scope values as defined in 3.3 of OAuth 2.0 RFC6749 that specify what access privileges are being requested for Access Tokens. Scope is a multivalue attribute and every value needs to be set in a separate tag. The 'openid' value is included by default. Other frequently used values are profile, openid, email, hr, etc. These are typically used to request additional claims about the user, such as their name, email address, or other profile information that may be necessary to identify the user in midPoint when username is not available.

false

String

clientName

Human friendly name of the client.

false

String

nameOfUsernameAttribute

Definition of the attribute by which the OIDC provider refers to the subject of the authentication process. If it is supposed to be the name of the user in midPoint, it should be set to preferred_username. Note that the values of preferred_username should correspond to the values of the name attribute in midPoint. Default value is 'sub'.

false

String

openIdProvider

Definition of URIs and endpoints of the OIDC provider. See OidcOpenIdProviderType for more details.

false

OidcOpenIdProviderType

simpleProofKey

Key used for signing with privateKeyJwt. Choose between simpleProofKey and keyStoreProofKey.

false

AbstractSimpleKeyType

keyStoreProofKey

Key from key store used for signing with privateKeyJwt. Choose between simpleProofKey and keyStoreProofKey.

false

AbstractKeyStoreKeyType

usePkce

Use Proof Key for Code Exchange for added security. (RFC7636)

false

Boolean

AbstractSimpleKeyType

AbstractSimpleKeyType contains the following attributes:

Name Description Required Type

Name	Description	Required	Type
`privateKey`	Private key.	true	ProtectedStringType
`passphrase`	Password.	true	ProtectedStringType
`certificate`	Certificate of key.	true	ProtectedStringType

privateKey

Private key.

true

ProtectedStringType

passphrase

Password.

true

ProtectedStringType

certificate

Certificate of key.

true

ProtectedStringType

AbstractKeyStoreKeyType

AbstractKeyStoreKeyType contains the following attributes:

Name Description Required Type

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

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

To configure the provider correctly, ensure all of the OIDC provider endpoints share the same base URL (issuerURI) and comply with the OIDC protocol. You can verify this by inspecting the JSON file at <issuerURI>/.well-known/openid-configuration/. If all of the exposed URIs are compliant, i.e., they share the same base URL and use the default URL suffixes, you will only need to explicitly configure the issuerURI. Otherwise, you will need to explicitly specify all the attributes listed below.

The available OpenID provider attributes are:

Name Description Required Type

Name	Description	Required	Type
`issuerUri`	Issuer identifier URI for the OpenID Connect provider, i.e., `issuer`. This URI is accessed via the user’s browser.	true	String
`authorizationUri`	URI for the authorization endpoint, i.e., `authorization_endpoint`. This URI is accessed via the user’s browser.	false	String
`tokenUri`	URI for the token endpoint, i.e., `token_endpoint`. This URI is accessed internally by midPoint.	false	String
`userInfoUri`	URI for the user info endpoint, i.e., `clientinfo_endpoint`. This URI is accessed internally by midPoint.	false	String
`endSessionUri`	URI for the logout endpoint, i.e., `end_session_endpoint`. This URI is accessed via the user’s browser.	false	String
`jwkSetUri`	URI for the JSON web key set endpoint, i.e., `jwks_uri`. Available since midPoint 4.8. This URI is accessed internally by midPoint.	false	String

issuerUri

Issuer identifier URI for the OpenID Connect provider, i.e., issuer. This URI is accessed via the user’s browser.

true

String

authorizationUri

URI for the authorization endpoint, i.e., authorization_endpoint. This URI is accessed via the user’s browser.

false

String

tokenUri

URI for the token endpoint, i.e., token_endpoint. This URI is accessed internally by midPoint.

false

String

userInfoUri

URI for the user info endpoint, i.e., clientinfo_endpoint. This URI is accessed internally by midPoint.

false

String

endSessionUri

URI for the logout endpoint, i.e., end_session_endpoint. This URI is accessed via the user’s browser.

false

String

jwkSetUri

URI for the JSON web key set endpoint, i.e., jwks_uri. Available since midPoint 4.8. This URI is accessed internally by midPoint.

false

String

If your OpenID provider uses the HTTPS protocol, don’t forget to add certification to Midpoint’s keystore.

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:

Installed Keycloak e.g. from the Docker image. In the following we assume it’s running on http://192.168.4.100:8080/
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".
A sample user (e.g. jack) created in Keycloak, with a password set.
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>

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

If your OpenID server uses the HTTPS protocol, don’t forget to add certification to Midpoint’s keystore.

Resource server contains following attributes:

Name Description Required Type Note

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.

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