OIDC client auth for REST

Last modified 12 Oct 2026 11:57 UTC
Table of Contents

This page describes how to configure midPoint to use an OIDC authentication provider for REST API authentication.

This configuration consists of the following parts, both of which take place in the Security Policy configuration:

Create an OIDC module

The OIDC module is configured as oidc in the modules section of the authentication configuration.

The elements of the oidc module configuration are described in the following table.

Name Description Required Type

identifier

Unique identifier among module elements.

This identifier will be used to reference this module.

true

String

resourceServer

Contains configuration of the OIDC resource server

false

Complex resourceServer type

focusType

Type of object this authentication module applies to, such as UserType or RoleType.

Default value is UserType.

false

QNames

name

Unique name of the authentication module

Deprecated, use identifier instead.

false

String

Configuration details of the individual elements listed in the table above are described in the following sections.

See an example module configuration below.

While resourceServer is not mandatory as per specification, in order to successfully configure OIDC REST authentication, it is necessary to use it.

Available fields in resourceServer section

While neither of jwt or opaqueToken is mandatory, at least one of them must be present. If both are present, the jwt configuration will be used.
Name Description Required Type

jwt

Defines that resource server expects token in JWT format.

false

Complex jwt type. Described in Token configuration 1

opaqueToken

Defines that resource server expects token in opaque format.

false

Complex opaqueToken type. Described in Token configuration 1
Deprecated fields in resourceServer section
Name Description Required Type

realm

Deprecated. This configuration now resides inside th token of your choosing.

false

String

issuerUri

Deprecated. This configuration now resides inside th token of your choosing.

false

String

jwkSetUri

Deprecated. This configuration now resides inside th token of your choosing.

false

String

nameOfUsernameClaim

Deprecated. This configuration now resides inside th token of your choosing.

false

String

singleSymmetricKey

Deprecated. This configuration now resides inside th token of your choosing.

false

String

trustedAlgorithm

Deprecated. This configuration now resides inside th token of your choosing.

false

String

trustingAsymmetricCertificate

Deprecated. This configuration now resides inside th token of your choosing.

false

String

keyStoreTrustingAsymmetricKey

Deprecated. This configuration now resides inside th token of your choosing.

false

String

Token configuration 1

This table contains methods to obtain public key. They are all mutually exclusive and evaluated in the order they are listed:

  1. trustingAsymmetricCertificate

  2. keyStoreTrustingAsymmetricKey

  3. singleSymmetricKey

  4. jwkSetUri

  5. issuerUri

In this table, the mandatory field is omitted, because all of the listed options are not mandatory.

Name Description JWT-relevant Opaque-relevant Type

realm

Realm name midPoint will use in WWW-Authenticate header.

true

true

String

issuerUri

URI for the OIDC authentication provider.

Relies on the <issuerUri>/.well-known/openid-configuration endpoint.

true

true

String

nameOfUsernameClaim

Name of the attribute, included in the token, referring to the subject of authentication, such as preferred_username.

Default value is sub.

true

true

String

jwkSetUri

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

true

false

String

singleSymmetricKey

OIDC provider’s public key

true

false

ProtectedStringType

trustedAlgorithm

It specifies the cryptographic algorithm used by the OIDC provider for digital signatures.

Potential values are RFC7518 §3.1 algorithms.

It is only valid in combination with the following: trustingAsymmetricCertificate, keyStoreTrustingAsymmetricKey, singleSymmetricKey, jwkSetUri.

true

false

String

trustingAsymmetricCertificate

Certificate of trust for a single asymmetric RSA public key.

true

false

ProtectedStringType

keyStoreTrustingAsymmetricKey

Complex type holding information about a a key and a keystore holding it.

true

false

Complex AbstractKeyStoreKeyType

userInfoUri

Uri for the user info endpoint of the OIDC authentication provider.

When not present, midPoint will rely on the information available on the OIDC discovery endpoint <openIdProvider / issuerUri>/.well-known/openid-configuration.

false

true

String

Token configuration 2

For better clarity, we’ll list token related fields in two tables. First table lists public key retrieval methods. Second table the miscellaneous fields.
Token validation methods

Fields in this table are all mutually exclusive and evaluated in the order they are listed:

Name Description JWT-relevant Opaque-relevant Type

trustingAsymmetricCertificate

Certificate of trust for a single asymmetric RSA public key.

true

false

ProtectedStringType

keyStoreTrustingAsymmetricKey

Complex type holding information about a a key and a keystore holding it.

true

false

Complex AbstractKeyStoreKeyType

singleSymmetricKey

OIDC provider’s public key

true

false

ProtectedStringType

jwkSetUri

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

true

false

String

issuerUri

URI for the OIDC authentication provider.

Relies on the <issuerUri>/.well-known/openid-configuration endpoint.

true

true

String
Miscellaneous fields
Name Description JWT-relevant Opaque-relevant Type

realm

Realm name midPoint will use in WWW-Authenticate header.

true

true

String

nameOfUsernameClaim

Name of the attribute, included in the token, referring to the subject of authentication, such as preferred_username.

Default value is sub.

true

true

String

trustedAlgorithm

It specifies the cryptographic algorithm used by the OIDC provider for digital signatures.

Potential values are RFC7518 §3.1 algorithms.

It is only valid in combination with the following: trustingAsymmetricCertificate, keyStoreTrustingAsymmetricKey, singleSymmetricKey, jwkSetUri.

true

false

String

userInfoUri

Uri for the user info endpoint of the OIDC authentication provider.

When not present, midPoint will rely on the information available on the OIDC discovery endpoint <openIdProvider / issuerUri>/.well-known/openid-configuration.

false

true

String

AbstractKeyStoreKeyType section

Name Description Required Type

keyStorePath

Path to the keystore file

true

String

keyStorePassword

Password for the keystore

true

ProtectedStringType

keyAlias

Alias of the private key in the keystore

true

ProtectedStringType

keyPassword

Password for the private key with the keyAlias in the keystore

true

ProtectedStringType

Example

This is a simple example of OIDC module configuration, using sample values.

<securityPolicy>
    <authentication>
        <modules>
            ...

            <!-- OIDC module for REST demo -->
            <oidc>
                <identifier>oidcResourceServer</identifier>
                <resourceServer>
                    <jwt> <!-- or opaqueToken -->
                        <issuerUri>https://keycloak.lab.evolveum.com/auth/realms/test</issuerUri>
                        <nameOfUsernameClaim>preferred_username</nameOfUsernameClaim>
                    </jwt>
                </resourceServer>
            </oidc>

            ...
        </modules>
    </authentication>
</securityPolicy>

Add a sequence referencing the OIDC module

An authentication sequence defines the authentication flow for a particular channel. It specifies which authentication modules are used and how they participate in the authentication process. To enable OIDC authentication for the GUI, configure a sequence for the GUI channel and reference the OIDC module in it.

The sequence has the following fields:

Name Description Required Type

identifier

Unique sequence identifier. Can be used to reference the sequence.

true

String

channel

Specification of the channel(s) this authentication sequence applies to (GUI, REST, etc.)

true

Complex channel type

module

Specification of an authentication module used in this sequence.

At least one module is required

true

Complex module type

name

A short identifier for administrator diagnostics. Not meant as a user-friendly label. Must be unique.

Deprecated, use identifier instead.

false

String

displayName

Display name of the sequence, shown for identifying the authentication sequence in the GUI.

false

String

description

Free form description (administrator comment).

false

String

requireAssignmentTarget

Required assignment target(s).

The authenticated user must hold all of the listed assignment targets. If not, the authentication sequence will fail.

For multiple targets, add this parameter multiple times, each time with a single value.

Example use case: emergency administrator access - can only work for administrator roles.

Example value: <requireAssignmentTarget oid="00000000-0000-0000-0000-000000000004" relation="org:default" type="c:RoleType"/>

false

ObjectReferenceType

nodeGroup

Required node group(s)

The authenticated user must carry one of the listed node groups (archetypes). If none applies, the authentication sequence will fail.

For multiple targets, add this parameter multiple times, each time with a single value.

Example use case: Only managers can log in to the GUI, but not regular users.

Example value: <nodeGroup oid="05b6933a-b7fc-4543-b8fa-fd8b278ff9ee" relation="org:default" type="c:ArchetypeType"/>

false

ObjectReferenceType

focusBehaviorUpdate

Controls updating of focus authentication behaviour attributes (e.g. failed login count, lockout state)

Possible values:

enabled - update focus authentication behaviour attributes on every login

disabled - never update focus authentication behaviour attributes

failureOnly - update focus authentication behaviour attributes only on failure

Default value is enabled.

false

String

While you can have multiple REST sequences configured, e.g., Basic Authentication and OIDC, you can only use one OIDC sequence configuration at any given time. If your configuration contains multiple OIDC sequence definitions, midPoint will consider the first one and skip the others.

See an example sequence below.

Available fields in channel section

Name Description Required Type

channelId

Name (URI) of the channel this configuration applies to.

The value for OIDC REST sequence is: http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest

true

String

description

Free form description (administrator comment).

false

String

default

Specifies whether this sequence is the default one for the given channel.

It is used, when no specific sequence is requested (e.g. via URL suffix).

It is recommended to keep one default sequence for each channel in use.

false

Boolean

urlSuffix

URL suffix used to select this authentication sequence specifically.

Must not contain a slash (/).

true

String

Available fields in module section

Name Description Required Type

identifier

Unique module identifier. Used to reference the module by module / identifier.

true

String

name

Reference to the authentication module name.

Value must match the name of an existing authentication module.

Deprecated, use identifier instead.

false

String

description

Free form description (administrator comment).

false

String

order

Ordering number for the module within the sequence.

Modules are sorted by order value

Modules sharing the same order may be evaluated in parallel where the authentication mechanism allows it.

Default value is 100.

false

Integer

necessity

Level of requirement for this module.

Possible values are: sufficient, required, requisite, or optional.

Default value is: sufficient.

false

String

Example

This is a simple example of OIDC module configuration, using sample values.

<securityPolicy>
    <authentication>
        ...

        <!-- Sequence referencing the OIDC REST module demo -->
        <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>
Was this page helpful?
YES NO
Thanks for your feedback