X4 Produktdokumentation
X4 Produktdokumentation
Breadcrumbs

OIDC Configuration

Authentication via OpenID Connect is controlled centrally via two configuration files:

  • authentication_config.xml: Contains the OIDC-specific settings for communicating with the identity provider.

  • tokenhandler_config.xml: Determines which authentication configuration applies for which resources (e.g., paths, services, Web Apps).

These configuration files must be stored in the configurations folder of the X4 Server and must be maintained by administrators during initial configuration or changes to the authentication system.

Configuration files

authentication_config.xml – configuration of the identity provider

This file specifies which OIDC configurations are available in X4 BPMS and which of them should be used by default.

Contents of the file 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AuthenticationConfiguration>
	<OIDCConfigs>
		<X4OidcConfig>
			<Name>X4Default</Name>
			<UseAsDefaultConfig>true</UseAsDefaultConfig>
			<ReturnChallengeOnFailedAuth>true</ReturnChallengeOnFailedAuth>
			<OIDCProviderConfig>
				<EnableBasicAuth>true</EnableBasicAuth>
				<Credentials>
					<entry>
						<key>secret</key>
						<value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
						xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">60304a13-8fa6-4899-94a2-0c10562768ec</value>
					</entry>
				</Credentials>
				<Realm>X4Realm</Realm>
				<AuthServerUrl>http://localhost:8085/auth</AuthServerUrl>
				<ClientId>X4</ClientId>   
			</OIDCProviderConfig>
		</X4OidcConfig>
	</OIDCConfigs>
</AuthenticationConfiguration>


Element

Possible values

Description

OIDCConfigs

List of <X4OidcConfig/>

Contains a list of different X4 OIDC configurations. Each configuration is referenced by the name in the <Name> element.

Name

String

Unique name of the configuration, for example X4Default. Used for referencing.

UseAsDefaultConfig

true/false

Specifies whether this is the default configuration for authentication requests.

ReturnChallengeOnFailedAuth

true/false

Specifies whether to return a user login prompt if authentication fails.

OidcProviderConfig


Contains the IdP-specific part.

EnableBasicAuth

true/false

Enables Basic Auth (only useful with Keycloak and corresponding setup).

Credentials


Contains the secrets for the identity provider.

Realm

String

Specifies which realm to use for the identity provider.

AuthServerUrl

URL

Base URL of the identity provider.

This usually only works with Keycloak. If another IdP is used, <ProviderUrl> must be used instead.

ClientId

String

ID of the client to be used to retrieve a token.

PublicClient

true/false

Must be set to false for Basic Auth to work with Kecyloak.

Advanced options for the <X4OidcConfig> element:

For finer control of access control, X4 BPMS can read roles and groups directly from the identity provider's access token. This is done via the optional XML element <TokenContent> within a <X4OidcConfig> block in the authentication_config.xml file.

Example configuration:

XML
<TokenContent>
  <RolesClaim>roles</RolesClaim>
  <GroupsClaim>groups</GroupsClaim>
</TokenContent>

With this configuration, X4 searches for the user roles in all claims of the access token that match the name roles. If there are multiple claims with the same name, all claims are read out and their contents are entered into the user's groups.

Example token with embedded roles:

JSON
{
  "exp": 1747664459,
  "iat": 1747664159,
  "iss": "http://localhost:8085/auth/realms/X4Realm",
  "aud": ["X4Bearer", "account"],
  "sub": "1b367493-2a5a-4edc-b858-f2ce71e1b625",
  "realm_access": {
    "roles": [
      "x4_dev_access",
      "x4_admin_access",
      "default-roles-x4realm"
    ]
  }
}

In this example, the roles are located under the realm_access.roles path. Accordingly, the value in the <RolesClaim> must be set to roles so that X4 can extract these roles and use them for authorization checks.

tokenhandler_config.xml – control of the authentication filters

This file links OIDC configurations to specific paths within X4, such as Web Apps or REST services.

Contents of the file

XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TokenHandlerConfiguration>
    <TokenHandlerConfigs>
        <oidcTokenHandlerConfigList>
            <ConfigName>oidc-token-handler</ConfigName>
            <OidcBaseConfigName>X4Default</OidcBaseConfigName>
         </oidcTokenHandlerConfigList>
    </TokenHandlerConfigs>
    <TokenHandlerFilters>
        <Filter>
            <Claims/>
            <RequestPaths>
                <requestPath>/X4/WebApp/*</requestPath>
                <requestPath>/X4/rest/webapp/*</requestPath>      
				<requestPath>/X4/services/rest/openapi.json</requestPath>
				<requestPath>/X4/X4Api/*</requestPath>
            </RequestPaths>
            <ConfigName>oidc-token-handler</ConfigName>
        </Filter>
    </TokenHandlerFilters>
</TokenHandlerConfiguration>


Element

Possible values

Description

TokenHandlerConfigs

List of <oidcTokenHandlerConfigList/>

Contains a list of different token handler configurations.

ConfigName

String

Unique name of the token handler. Used in the <TokenHandlerFilters> element.

OidcBaseConfigName

String

Reference to a <X4OidcConfig> entry in the authentication_config.xml file. Specifies that a token handler should use the referenced configuration to perform the authentication process.

TokenHandlerFilters

List of filters

Wrapper for different types of filters to determine which requests a particular token handler configuration should be active for.

Filter

Filter structure

A filter is a collection of various <RequestPath> elements that specify which URL paths the token handler filter should be active for.

RequestPaths

List of <requestPath> elements

Contains specific request paths. Placeholders can be used at the end and beginning of the path. If a placeholder is not used, the path must match completely.

ConfigName

String

References a specific token handler configuration by name. If any of the request path filters match, the specific token handler configuration is used.

Use in Web Apps and .wsinc

In .wac files (for Web Apps) and .wsinc files (HTTP starters), you can now specify an Auth Config Name to specifically use one of the defined OIDC configurations. This allows Web Apps or endpoints to be specifically backed up with different identity providers without affecting global configuration.

Note:

The Realm, Client ID , and Client Secret fields are obsolete and should no longer be used.