Identitäts- und Zugangsmanagement

Keycloak-Einrichtung

OTRS verwendet eine Lösung mit zwei Realms, einen Realm für Agenten und einen für Kundenbenutzer.

Wenn Keycloak betriebsbereit ist:

1. Erstellen Sie den Agenten-Realm otrs-agents.

2. Gehen Sie zu Realm settings, wählen Sie General und aktivieren Sie Unmanaged Attributes.

3. Wählen Sie unter Realm settings die Registerkarte User profile:

   • wählen Sie Benutzername, scrollen Sie dann nach unten zum Abschnitt Validierungen und löschen Sie den Validator up-username-not-idn-homograph

   • Wählen Sie lastName, scrollen Sie dann nach unten zum Abschnitt Validierungen und löschen Sie den Validator person-name-prohibited-characters

   • wählen Sie firstName, scrollen Sie dann nach unten zum Abschnitt Validierungen und löschen Sie den Validierer person-name-prohibited-characters

4. Wählen Sie den Client Realm-Management `` aus der *Clients-Liste * und erstellen Sie dann auf der Registerkarte *Rollen* die Rolle ``view-system.

5. Erstellen Sie den Client otrs-app. Dies wird der Client sein, der vom OTRS-Agenten-Frontend verwendet wird.

6. Wählen Sie den Client aus der Liste der Clients, scrollen Sie dann auf der Registerkarte Einstellungen nach unten zum Abschnitt Funktionskonfiguration und aktivieren Sie das Kontrollkästchen Standardfluss in Authentifizierungsfluss.

7. Erstellen Sie den Client otrs-api. Dieser Client wird für die Benutzerverwaltung benötigt.

8. Wählen Sie den Client in der Liste Clients aus. Blättern Sie auf der Registerkarte Einstellungen nach unten zum Abschnitt Capability config. Aktivieren Sie unter Authentication flow die Client-Authentifizierung, aktivieren Sie die Kontrollkästchen Standard Flow und Service accounts roles.

9. Fügen Sie dann auf der Registerkarte Servicekontenrollen mit der Schaltfläche Rolle zuweisen die folgenden Rollen hinzu:

   - realm-management: manage-clients
   - realm-management: manage-users
   - realm-management: query-users
   - realm-management: view-clients
   - realm-management: view-system
   - realm-management: view-users
   

10. Erstellen Sie den Kundenbenutzer-Realm otrs-customer-users.

11. Konfigurieren Sie ihn genau so wie den Agenten-Realm.

OTRS-Einrichtung für Keycloak

Um Keycloak für Agenten zu aktivieren, müssen Sie den folgenden Konfigurationsausschnitt aus Kernel/Config/Defaults.pm kopieren und in Kernel/Config.pm einfügen. Dekommentieren Sie die Zeilen und fügen Sie die richtigen Werte für die Schlüssel hinzu.

# -------------------------------------------------- #
# OIDC/Keycloak authentication of Agents             #
# -------------------------------------------------- #
$Self->{'AuthModule'}                              = 'Kernel::System::Auth::OIDC';
$Self->{'AuthModule::OIDC::Authority'}             = 'https://keycloak-host:8024';
# In Kubernetes environment, we need a different Authority URL, to comunicate directly to the Keycloak.
# $Self->{'AuthModule::OIDC::BackendAuthority'}           = 'https://keycloak-host:8024';
$Self->{'AuthModule::OIDC::Realm'}                        = 'otrs-agents';
$Self->{'AuthModule::OIDC::ClientID'}                     = 'otrs-app';
$Self->{'AuthModule::OIDC::PostLogoutRedirectURL'}        = 'http://localhost:3001';
$Self->{'Agent::AccessTokenStorageModule'}                = 'Kernel::System::AccessToken::Storage::OIDC';
$Self->{'Keycloak::API::Credentials::User::ClientID'}     = 'otrs-api';
$Self->{'Keycloak::API::Credentials::User::ClientSecret'} = 'secret';
# };
# Set to 1 to enable remote session checking, instead of using local checking
# $Self->{'AuthModule::OIDC::Token::EnableRemoteCheck'} = 1;
# Define role name which user must have in order to be able to login on Agent interface.
# $Self->{'AuthModule::OIDC::AgentRole'} = 'Agent'; # optional

# --------------------------------------------------------- #
# authentication sync settings - OpenID Connect             #
# (enable agent data sync. after successful authentication) #
# --------------------------------------------------------- #

# This is an example configuration for an OIDC auth sync. backend.
$Self->{'AuthSyncModule'} = 'Kernel::System::Auth::Sync::OIDC';

# Map if agent should be created/synced from access token to DB after successful login.
#  OTRS-User-FieldName => Access token key
$Self->{'AuthSyncModule::OIDC::UserSyncMap'} = {
    # DB -> Header
    UserFirstname => 'given_name',
    UserLastname  => 'family_name',
    UserEmail     => 'email',
};

# Sync roles based on access token values (must be an array reference of role names).
# - DisableUserRolesSync: set to 1 to disable role sync.
# $Self->{'AuthSyncModule::OIDC::DisableUserRolesSync'} = 1;

Alternativ können für denselben Zweck auch Umgebungsvariablen verwendet werden. Die folgenden Umgebungsvariablen bieten die gleichen Konfigurationsmöglichkeiten wie das Kernel/Config.pm Code Snippet. Wenn ja in der letzten Spalte angezeigt wird, ist die Umgebungsvariable obligatorisch, wenn Keycloak aktiviert ist.

Um Keycloak für Kundenbenutzer zu aktivieren, müssen Sie den folgenden Konfigurationsausschnitt von Kernel/Config/Defaults.pm kopieren und in Kernel/Config.pm einfügen. Dekommentieren Sie die Zeilen und fügen Sie die richtigen Werte für die Schlüssel hinzu.

# --------------------------------------------------- #
# OIDC/Keycloak authentication of CustomerUsers       #
# --------------------------------------------------- #
$Self->{'Customer::AuthModule'}                              = 'Kernel::System::CustomerAuth::OIDC';
$Self->{'Customer::AuthModule::OIDC::Authority'}             = 'https://keycloak-host:8024';
# In Kubernetes environment, we need to use different Authority URL, to comunicate directly to the Keycloak.
# $Self->{'Customer::AuthModule::OIDC::BackendAuthority'}         = 'https://keycloak-host:8024';
$Self->{'Customer::AuthModule::OIDC::Realm'}                      = 'otrs-customer-users';
$Self->{'Customer::AuthModule::OIDC::ClientID'}                   = 'otrs-app';
$Self->{'Customer::AuthModule::OIDC::PostLogoutRedirectURL'}      = 'http://localhost:3001';
$Self->{'Customer::AccessTokenStorageModule'}                     = 'Kernel::System::AccessToken::Storage::OIDC';
$Self->{'Keycloak::API::Credentials::CustomerUser::ClientID'}     = 'otrs-api';
$Self->{'Keycloak::API::Credentials::CustomerUser::ClientSecret'} = 'secret';
# Set to 1 to enable remote session checking, instead of using local checking
# $Self->{'Customer::AuthModule::OIDC::Token::EnableRemoteCheck'} = 1;
# Define role name which user must have in order to be able to login on External interface.
# $Self->{'Customer::AuthModule::OIDC::CustomerUserRole'} = 'Customer User'; # optional

$Self->{CustomerUser} = {
    Name   => 'OIDC Backend',
    Module => 'Kernel::System::CustomerUser::OIDC',
    # customer unique id
    CustomerKey => 'username',
    CustomerID => 'email',
    CustomerUserListFields => ['firstName', 'lastName', 'email'],
    CustomerUserSearchFields => ['id', 'username', 'email'],
    CustomerUserSearchListLimit => 250,
    CustomerUserPostMasterSearchFields => ['customerid'],
    CustomerUserNameFields => ['firstName', 'lastName'],
    # Configures the character for joining customer user name parts. Join single space if it is not defined.
    CustomerUserNameFieldsJoin => ' ',
    # show customer user and customer tickets in the external interface
    CustomerUserExcludePrimaryCustomerID => 0,
    # cache time to live in sec. - cache any Keycloak queries
    CacheTTL => 0,
    # Consider this source read only.
    ReadOnly => 1,
    Map      => [
        [ 'UserTitle',      Translatable('Title or salutation'), 'title',     1, 0, 'var', '', 1, undef, undef ],
        [ 'UserFirstname',  Translatable('Firstname'),           'firstName', 1, 1, 'var', '', 1, undef, undef ],
        [ 'UserLastname',   Translatable('Lastname'),            'lastName',  1, 1, 'var', '', 1, undef, undef ],
        [ 'UserLogin',      Translatable('Username'),            'username',  1, 1, 'var', '', 1, undef, undef ],
        [ 'UserEmail',      Translatable('Email'),               'email',     1, 1, 'var', '', 1, undef, undef ],
        # Important: customerid attribute MUST BE DEFINED in the Keycloak.
        [ 'UserCustomerID', Translatable('CustomerID'),          'customerid',0, 1, 'var', '', 1, undef, undef ],
        #[ 'UserCustomerIDs',Translatable('CustomerIDs'),'second_customer_ids',1, 0, 'var', '', 1, undef, undef ],
        [ 'UserPhone',      Translatable('Phone'),               'phone',     1, 0, 'var', '', 1, undef, undef ],
        [ 'UserFax',        Translatable('Fax'),                 'fax',       1, 0, 'var', '', 1, undef, undef ],
        [ 'UserMobile',     Translatable('Mobile'),              'mobile',    1, 0, 'var', '', 1, undef, undef ],
        [ 'UserStreet',     Translatable('Street'),              'street',    1, 0, 'var', '', 1, undef, undef ],
        [ 'UserZip',        Translatable('Zip'),                 'zip',       1, 0, 'var', '', 1, undef, undef ],
        [ 'UserCity',       Translatable('City'),                'city',      1, 0, 'var', '', 1, undef, undef ],
        [ 'UserCountry',    Translatable('Country'),             'country',   1, 0, 'var', '', 1, undef, undef ],
        [ 'UserComment',    Translatable('Comment'),             'comment',   1, 0, 'var', '', 1, undef, undef ],
        [ 'ValidID',        Translatable('Valid'),               'enabled',   0, 0, 'int', '', 1, undef, undef ],
        # this is needed, if "SMIME::FetchFromCustomer" is active
        # [ 'UserSMIMECertificate','SMIMECertificate','userSMIMECertificate', 0, 1, 'var', '', 1, undef, undef ],
        # Dynamic field example
        # [ 'DynamicField_Name_X', undef,              'Name_X', 0, 0, 'dynamic_field', undef, 0, undef, undef ],
    ],
};

Alternativ können für denselben Zweck auch Umgebungsvariablen verwendet werden. Die folgenden Umgebungsvariablen bieten die gleichen Konfigurationsmöglichkeiten wie das Kernel/Config.pm Code Snippet. Wenn ja in der letzten Spalte angezeigt wird, ist die Umgebungsvariable obligatorisch, wenn Keycloak aktiviert ist.

Nach der Einrichtung von Keycloak und OTRS:

1. Erstellen Sie den Benutzer root@localhost im Agenten-Realm.

2. Erstellen Sie die erforderlichen Rollen im Mandanten otrs-app und weisen Sie sie den Benutzern zu.

Verbindung zwischen LDAP und Keycloak einrichten

1. Loggen Sie sich als Administrator in Keycloak ein und wählen Sie den gewünschten Realm.

2. Wählen Sie auf der linken Seite User Federation und klicken Sie auf Add LDAP provider.

3. Unter Allgemeine Optionen:

   • UI Display Name – Setzen Sie einen beliebigen Namen, der als Deskriptor dient (z.B. Corporate LDAP oder OTRS Directory).

   • Vendor – Wählen Sie Other für Standard-OpenLDAP-Server oder Active Directory bei Verwendung von Microsoft AD.

4. Unter Verbindungs- und Authentifizierungseinstellungen:

   • Verbindungs-URL – ldaps://ldap.example.com:636 (verwenden Sie ldap:// mit Port 389 wenn TLS nicht verfügbar ist)

   • Andere Konfiguration als Standard belassen.

   • Klicken Sie auf Verbindung testen und vergewissern Sie sich, dass das Ergebnis grün ist.

   • Bindungsart – Wählen Sie simple.

   • Bind DN – DN des Verwaltungs- oder Dienstbenutzers, zum Beispiel: uid=ldap-admin,ou=system,dc=example,dc=com

   • Bind Credentials – Passwort für den Bind-DN-Benutzer, zum Beispiel: secret123

   • Klicken Sie auf ** Authentifizierung testen ** und stellen Sie sicher, dass das Ergebnis grün ist.

   Bemerkung

   Ersetzen Sie alle Beispielwerte (ldap.example.com, uid=ldap-admin, secret123) durch die tatsächliche Konfiguration Ihres LDAP-Servers.

   Tipp

   Wenn Sie LDAPS mit einem selbstsignierten Zertifikat verwenden, stellen Sie sicher, dass Sie einen Java Truststore konfigurieren und diesen in den Startparametern von Keycloak referenzieren: -Djavax.net.ssl.trustStore=/opt/keycloak/conf/truststore.jks und -Djavax.net.ssl.trustStorePassword=<password>. Alternativ können Sie „Use Truststore SPI → Only for LDAPS connection“ in der Keycloak-Benutzeroberfläche aktivieren.

   Tipp

   Um die Leistung in großen Umgebungen zu verbessern, aktivieren Sie Connection Pooling.

5. Unter LDAP-Suche und -Aktualisierung:

   • Bearbeitungsmodus – READ_ONLY (empfohlen, wenn LDAP die Hauptquelle der Wahrheit ist)

   • Benutzer DN – ou=users,dc=example,dc=com

   • Benutzername LDAP-Attribut – uid (oder sAMAccountName für Active Directory)

   • RDN LDAP-Attribut – uid

   • UUID LDAP-Attribut – entryUUID (oder objectGUID für Active Directory)

   • Benutzerobjekt-Klassen – inetOrgPerson,organizationalPerson,person,posixAccount

   • Andere Konfiguration als Standard belassen.

   Tipp

   Standardmäßig wird empfohlen, Edit Mode auf READ_ONLY zu setzen, da LDAP typischerweise als die einzige Quelle der Wahrheit angesehen wird und von Keycloak nicht verändert werden sollte.

   Für bestimmte Anwendungsfälle – wie z.B. OTRS-Systemmigration – kann es jedoch notwendig sein, Edit Mode vorübergehend auf WRITABLE umzuschalten, damit Keycloak die Benutzer mit OTRS synchronisieren kann.

   In solchen Fällen:

   • Setzen Sie Edit Mode auf WRITABLE bevor den Synchronisationsprozess startet.

   • Sobald die Synchronisierung abgeschlossen ist, setzen Sie Edit Mode zurück auf READ_ONLY, um die Integrität der LDAP-Daten zu schützen.

   Wichtig

   Lassen Sie WRITABLE aktiviert nur für die Dauer der erforderlichen Synchronisation. Wenn Sie diese Option dauerhaft aktiviert lassen, kann Keycloak LDAP-Benutzerdaten ändern, was zu unbeabsichtigten Attributänderungen oder Konflikten mit externen Systemen führen kann.

   Tipp

   Wenn Sie mehr als 1000 Benutzer haben, aktivieren Sie Pagination, um Keycloak zu erlauben, alle Einträge ohne server-auferlegte Grenzen abzurufen. Dies verhindert partielle Synchronisationsergebnisse in größeren Verzeichnissen, insbesondere in Active Directory-Umgebungen, wo die Standardgröße auf 1000 Einträge begrenzt ist.

6. Synchronisationseinstellungen:

   • Gehen Sie zu User Federation → Settings → Action → Sync all users.

   • Rufen Sie die Liste Users auf. Da die Benutzer möglicherweise nicht automatisch angezeigt werden, geben Sie * in das Suchfeld ein.

   • Vergewissern Sie sich, dass alle Benutzer im Realm aufgelistet und sichtbar sind.

   Tipp

   Um die Daten automatisch zu synchronisieren, konfigurieren Sie eine periodische Synchronisierung: – Periodic Full Sync: alle 24 Stunden (86400 Sekunden) – Periodic Changed Users Sync: alle 1 Stunde (3600 Sekunden)

   Bemerkung

   Stellen Sie sicher, dass Import Users aktiviert ist. Dadurch kann Keycloak LDAP-Benutzer in seine interne Datenbank zur Authentifizierung und Rollenzuordnung importieren.

7. Attribut-Mapping (Mappers):

   Wenn ein neuer LDAP-Provider erstellt wird, versucht Keycloak automatisch Mappings zwischen LDAP-Attributen und Keycloak-Benutzerattributen zu erkennen und zu erstellen.

   • Zu den Standardzuordnungen gehören in der Regel: – firstName → givenName – lastName → sn – email → mail – username → uid (oder sAMAccountName für Active Directory) – uuid → entryUUID (oder objectGUID für AD)

   Bemerkung

   In den meisten Umgebungen werden diese Zuordnungen automatisch erstellt, wenn der LDAP-Anbieter hinzugefügt wird. Sie können jedoch auch manuell unter User Federation → [Ihr LDAP-Anbieter] → Mappers überprüft und angepasst werden.

   Tipp

   • Wenn die Felder email oder name nach der Synchronisierung leer sind, überprüfen Sie, ob ihre LDAP-Attribute in diesem Abschnitt korrekt zugeordnet sind.

   • Für Active Directory stellen Sie sicher, dass objectGUID auf das User ID Attribut in Keycloak abgebildet wird, um eine konsistente Benutzeridentität zu gewährleisten.

   • Wenn Gruppen oder Rollen in LDAP verwaltet werden, können Sie einen zusätzlichen Mapper vom Typ group-ldap-mapper oder role-ldap-mapper hinzufügen, um sie automatisch mit Keycloak zu synchronisieren.

   Wichtig

   Falsche oder fehlende Mapper können zu Anmeldefehlern oder doppelten Benutzern nach der Synchronisierung führen. Überprüfen Sie immer, ob alle kritischen Attribute (Benutzername, E-Mail, UUID) korrekt zugeordnet sind, bevor Sie die automatische Synchronisierung aktivieren.

Migrieren der Systemauthentifizierung zu Keycloak

1. Stellen Sie sicher, dass Keycloak korrekt eingerichtet ist. Siehe Abschnitt Keycloak Setup oben.

2. Synchronisieren Sie die Agentenrollen, indem Sie die folgenden Skripte in OTRS ausführen:

   bin/otrs.Console.pl Admin::IAM::SyncRoles \
   --realm otrs-agents \
   --client-id otrs-app \
   --backend-authority {Keycloak host} \
   --api-credentials-client-id otrs-api \
   --api-credentials-client-secret {secret}
   

3. Synchronisieren Sie die Agenten, indem Sie die folgenden Skripte in OTRS ausführen:

   bin/otrs.Console.pl Admin::IAM::SyncUsers \
   --realm otrs-agents \
   --client-id otrs-app \
   --backend-authority {Keycloak host} \
   --api-credentials-client-id otrs-api \
   --api-credentials-client-secret {secret}
   

4. Synchronisieren Sie die Kundenbenutzer, indem Sie die folgenden Skripte in OTRS ausführen:

   bin/otrs.Console.pl Admin::IAM::SyncCustomerUsers \
   --realm otrs-customer-users \
   --client-id otrs-app \
   --backend-authority {Keycloak host} \
   --api-credentials-client-id otrs-api \
   --api-credentials-client-secret {secret}
   

5. Richten Sie OTRS ein. Siehe Abschnitt OTRS-Einrichtung für Keycloak oben.

Einrichtungs- und Wartungsthemen

OTRS muss jederzeit über das Netzwerk auf Keycloak zugreifen können. Eine gute Verbingung mit niedriger Latenz wird empfohlen.

So überprüfen Sie die Verbindung:

curl -v -L http://my.keycloak.host:8024.

Für den gleichen Zweck können Sie einen Konsolenbefehl verwenden:

bin/otrs.Console.pl Maint::IAM::Check

Löschen Sie keine Benutzer in Keycloak. Stattdessen sollten Sie sie auf deaktivieren wenn sie nicht mehr benötigt werden. OTRS speichert Referenzen zu Benutzern. Aus diesem Grund sollten sie nicht gelöscht werden, sondern nur auf deaktiviert gesetzt werden.

Wenn OTRS Keycloak für die Authentifizierung verwendet, muss jeder Agent seine Organisator-Elemente vom Typ Kundenbenutzer überprüfen. Beachten Sie, dass alte Organisator-Elemente höchstwahrscheinlich nicht funktionieren, da die Platzhaltersuche (*) in Keycloak nicht unterstützt wird. Es wird empfohlen, diese zu löschen und erneut neue Organisator-Elemente mit verfügbaren und unterstützten Filtern zu erstellen.

Kunden-Benutzer-Attribute

Beim Übertragen oder Anlegen von Kundenbenutzern in Keycloak sollten die folgenden Attribute beachtet werden. Einige Attribute sind obligatorisch.

• firstName (erforderlich)

• lastName (erforderlich)

• username (erforderlich)

• email (erforderlich)

• customerid (erforderlich, muss genau dem Wert in OTRS entsprechen)

• enabled (erforderlich)

• title

• phone

• comment

• fax

• mobile

• street

• zip

• city

• country

Um die Attribute des Kundenbenutzers in Keycloak zu konfigurieren, öffnen Sie die Einstellungen des Kundenbenutzerbereichs und dann das Benutzerprofil.

Daten-Synchronisation

Kundenbenutzer

Wenn Keycloak verwendet wird, ist es nicht möglich, Kundenbenutzer direkt in OTRS zu erstellen, und es gibt keine Synchronisierung von Kundenbenutzern von Keycloak zu OTRS. Kundenbenutzer sollten in Keycloak erstellt und aktualisiert werden, aber sie werden nicht in OTRS erstellt oder aktualisiert.

Agenten

Wenn Keycloak verwendet wird, ist es nicht möglich, Agenten direkt in OTRS zu erstellen. Die Synchronisierung der Agenten von Keycloak zu OTRS erfolgt bei erfolgreicher Agentenanmeldung. Die oben genannte Konfigurationseinstellung AuthSyncModule steuert, wie der Agentensynchronisierungsprozess abläuft.

Der Synchronisierungsprozess umfasst grundlegende Attribute des Agenten wie beispielsweise Name, Adresse und Telefon. Der Synchronisierungsprozess umfasst Agentenrollenzuordnungen wie z. B. Benutzer und Administrator. Der Synchronisierungsprozess deckt keine Gruppen ab.

Agentenrollen

Wenn sich ein Agent anmeldet, liest OTRS Agentenrollenzuordnungen aus dem entsprechenden, von Keycloak bereitgestellten Zugriffstoken. Der Zugriffstoken enthält ein spezielles Feld für solche Daten und kann von OTRS gelesen werden.

In Keycloak definierte Rollennamen müssen genau mit den in OTRS definierten Rollennamen übereinstimmen.

Die Konfigurationseinstellung „ DisableUserRolesSync„ kann auf 1 gesetzt werden, um diese Funktion zu deaktivieren. Um Rollen in Keycloak ohne Synchronisierung zu erstellen, sollten Sie den gewünschten Client aus dem Menü Clients auswählen. Dort können Sie im Tab Rollen Rollen anlegen und diese bei Bedarf den Keycloak-Benutzern zuweisen.

Client-Geheimnis

Um die Einstellung ClientSecret zu erhalten, sollten Sie auf Ihre Keycloak-Benutzeroberfläche zugreifen, den gewünschten Client aus dem Menü Clients auswählen und Client-Authentifizierung in der Registerkarte Einstellungen aktivieren. Danach können Sie zum Tab Anmeldeinformationen navigieren. Der Wert, den Sie benötigen, befindet sich im Textfeld Kundengeheimnis.