X4 Produktdokumentation
X4 Produktdokumentation
Breadcrumbs

OIDC-Konfiguration

Die Authentifizierung über OpenID Connect wird zentral über zwei Konfigurationsdateien gesteuert:

  • authentication_config.xml: Enthält die OIDC-spezifischen Einstellungen für die Kommunikation mit dem Identity Provider.

  • tokenhandler_config.xml: Bestimmt, für welche Ressourcen (z. B. Pfade, Services, Web Apps) welche Authentifizierungskonfiguration gilt.

Diese Konfigurationsdateien müssen im Ordner configurations des X4 Servers abgelegt werden und müssen von Administratoren bei der Erstkonfiguration oder bei Änderungen am Authentifizierungssystem gepflegt werden.

Konfigurationsdateien

authentication_config.xml – Konfiguration des Identity Providers

In dieser Datei wird festgelegt, welche OIDC-Konfigurationen X4 BPMS zur Verfügung stehen und welche davon standardmäßig verwendet werden sollen.

Inhalt der Datei 

<?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

Mögliche Werte

Beschreibung

OIDCConfigs

Liste mit <X4OidcConfig/>

Enthält eine Liste verschiedener X4-OIDC-Konfigurationen. Jede Konfiguration wird über den Namen im Element <Name> referenziert.

Name

String

Eindeutiger Name der Konfiguration, z. B. X4Default. Wird zur Referenzierung verwendet.

UseAsDefaultConfig

true/false

Gibt an, ob dies die Standardkonfiguration für Authentifizierungsanfragen ist.

ReturnChallengeOnFailedAuth

true/false

Gibt an, ob bei fehlgeschlagener Authentifizierung eine Aufforderung zum Login durch den Benutzer zurückgegeben werden soll.

OidcProviderConfig


Enthält den IdP-spezifischen Teil.

EnableBasicAuth

true/false

Aktiviert Basic Auth (nur sinnvoll bei Keycloak und entsprechendem Setup).

Credentials


Enthält die Secrets für den Identity Provider.

Realm

String

Gibt an, welcher Realm für den Identity Provider verwendet werden soll.

AuthServerUrl

URL

Basis-URL des Identity Providers.

Dies funktioniert in der Regel nur mit Keycloak. Wenn ein anderer IdP verwendet wird, muss stattdessen <ProviderUrl> verwendet werden.

ClientId

String

ID des Clients, der zum Abrufen eines Tokens verwendet werden soll.

PublicClient

true/false

Muss auf false gesetzt werden, damit Basic Auth mit Keycloak funktioniert.

Erweiterte Optionen für das Element <X4OidcConfig>:

Zur feineren Steuerung der Zugriffskontrolle kann X4 BPMS Rollen und Gruppen direkt aus dem Access Token des Identity Providers auslesen. Dies erfolgt über das optionale XML-Element <TokenContent> innerhalb eines <X4OidcConfig>-Blocks in der Datei authentication_config.xml.

Beispielkonfiguration:

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

Mit dieser Konfiguration sucht X4 in allen Claims des Access Tokens, die dem Namen roles entsprechen, nach den Benutzerrollen. Wenn mehrere Claims mit dem gleichen Namen vorhanden sind, werden alle Claims ausgelesen und deren Inhalte in die Gruppen des Nutzers eingetragen.

Beispiel-Token mit eingebetteten Rollen:

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 diesem Beispiel befinden sich die Rollen unter dem Pfad realm_access.roles. Entsprechend muss der Wert im <RolesClaim> auf roles gesetzt werden, damit X4 diese Rollen extrahieren und für Autorisierungsprüfungen verwenden kann.

tokenhandler_config.xml – Steuerung der Authentifizierungsfilter

Diese Datei verknüpft OIDC-Konfigurationen mit bestimmten Pfaden innerhalb von X4, z. B. für Web Apps oder REST-Services.

Inhalt der Datei

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

Mögliche Werte

Beschreibung

TokenHandlerConfigs

Liste mit <oidcTokenHandlerConfigList/>

Enthält eine Liste verschiedener Token-Handler-Konfigurationen.

ConfigName

String

Eindeutiger Name des Token-Handlers. Wird im Element <TokenHandlerFilters> verwendet.

OidcBaseConfigName

String

Referenz auf einen <X4OidcConfig>-Eintrag in der Datei authentication_config.xml. Gibt an, dass ein Token-Handler die referenzierte Konfiguration zum Ausführen des Authentifizierungsablaufs verwenden soll.

TokenHandlerFilters

Liste mit Filtern

Wrapper für verschiedene Arten von Filtern, um zu bestimmen, für welche Anfragen eine bestimmte Token-Handler-Konfiguration aktiv sein soll.

Filter

Filterstruktur

Ein Filter ist eine Sammlung von verschiedenen <RequestPath>-Elementen, die festlegen, für welche URL-Pfade der Token-Handler-Filter aktiv sein soll.

RequestPaths

Liste mit <requestPath>-Elementen

Enthält spezifische Anfragepfade. Am Ende und am Anfang des Pfades können Platzhalter verwendet werden. Wenn kein Platzhalter verwendet wird, muss der Pfad vollständig übereinstimmen.

ConfigName

String

Referenziert eine bestimmte Token-Handler-Configuration nach Namen. Wenn einer der Anfragepfadfilter übereinstimmt, wird die spezifische Token-Handler-Konfiguration verwendet.

Nutzung in Web Apps und .wsinc

In .wac-Dateien (für Web Apps) und .wsinc-Dateien (HTTP-Starter) kann jetzt ein Auth Config Name angegeben werden, um gezielt eine der definierten OIDC-Konfigurationen zu verwenden. So lassen sich Web Apps oder Endpunkte gezielt mit verschiedenen Identity Providern sichern, ohne die globale Konfiguration zu beeinflussen.

Hinweis:

Die Felder Realm, Client ID und Client Secret sind veraltet und sollten nicht mehr verwendet werden.