Személyazonosság- és hozzáférés-kezelés

Keycloak Setup

OTRS uses two-realm solution, one realm for agents and one for customer users.

Ha a Keycloak telepítve van és fut:

1. Hozza létre az otrs-agents ügyintézői tartományt.

2. Menjen a Tartomány beállításai menüpontra, válassza az Általános lapot, és engedélyezze a Kezeletlen attribútumok lehetőséget.

3. Still in Realm settings, select User profile tab:

   • select username, then scroll down to Validations section and delete the validator up-username-not-idn-homograph

   • select lastName, then scroll down to Validations section and delete the validator person-name-prohibited-characters

   • select firstName, then scroll down to Validations section and delete the validator person-name-prohibited-characters

4. Select the client realm-management from the Clients list, then in Roles tab create the role view-system.

5. Hozza létre az otrs-app ügyfélalkalmazást. Ez lesz az OTRS ügyintézői előtétprogramja által használt ügyfélalkalmazás.

6. Válassza ki az ügyfélalkalmazást az Ügyfelek listájából, majd a Beállítások lapon görgessen le a Képességkonfiguráció szakaszhoz, és jelölje be a Szabványos folyam jelölőnégyzetet a Hitelesítési folyam részen.

7. Create the client otrs-api. This client is needed for user management operations.

8. Select the client from the Clients list. In the Settings tab, scroll down to the Capability config section. Under Authentication flow, enable Client authentication, select the Standard Flow and Service accounts roles checkboxes.

9. Then in Service accounts roles tab add the following roles with Assign role button:

   - 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. Hozza létre az otrs-customer-users ügyfél-felhasználói tartományt.

11. Állítsa be pontosan ugyanúgy, mint az ügyintézők tartományát.

OTRS Setup for Keycloak

A Keycloak ügyintézőkhöz való aktiválásához át kell másolnia a következő beállítási kódrészletet a Kernel/Config/Defaults.pm fájlból, és be kell illesztenie a Kernel/Config.pm fájlba. Törölje a megjegyzésjelet a sorok elől, és adja hozzá a megfelelő értékeket a kulcsokhoz.

# -------------------------------------------------- #
# 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;

Alternatív megoldásként környezeti változók is használhatók ugyanerre a célra. A következő környezeti változók ugyanolyan beállítási lehetőségeket kínálnak, mintha a Kernel/Config.pm fájlban lévő kódrészletet használná. Ha az utolsó oszlopban igen jelenik meg, akkor a környezeti változó kötelező, ha a Keycloak engedélyezve van.

A Keycloak ügyfél-felhasználókhoz való aktiválásához át kell másolnia a következő beállítási kódrészletet a Kernel/Config/Defaults.pm fájlból, és be kell illesztenie a Kernel/Config.pm fájlba. Törölje a megjegyzésjelet a sorok elől, és adja hozzá a megfelelő értékeket a kulcsokhoz.

# --------------------------------------------------- #
# 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 ],
    ],
};

Alternatív megoldásként környezeti változók is használhatók ugyanerre a célra. A következő környezeti változók ugyanolyan beállítási lehetőségeket kínálnak, mintha a Kernel/Config.pm fájlban lévő kódrészletet használná. Ha az utolsó oszlopban igen jelenik meg, akkor a környezeti változó kötelező, ha a Keycloak engedélyezve van.

After the setup of Keycloak and OTRS:

1. Hozza létre a root@localhost felhasználót az ügyintézők tartományában.

2. Hozza létre a szükséges szerepeket az otrs-app ügyfélalkalmazásban, és rendelje hozzá a felhasználókhoz.

Set Up connection between LDAP and Keycloak

1. Login as admin in Keycloak and select the desired realm.

2. On the left side, select User Federation and click Add LDAP provider.

3. Under General options:

   • UI Display Name – Set any name, serves as a descriptor (e.g. Corporate LDAP or OTRS Directory).

   • Vendor – Select Other for standard OpenLDAP servers or Active Directory if using Microsoft AD.

4. Under Connection and Authentication Settings:

   • Connection URL – ldaps://ldap.example.com:636
     (use ldap:// with port 389 if TLS is not available)

   • Leave other configuration as default.

   • Click Test Connection and ensure the result is green.

   • Bind Type – Select simple.

   • Bind DN – DN of the administrative or service user, for example:
     uid=ldap-admin,ou=system,dc=example,dc=com

   • Bind Credentials – Password for the Bind DN user, for example:
     secret123

   • Click Test Authentication and ensure the result is green.

   Megjegyzés

   Replace all example values (ldap.example.com, uid=ldap-admin, secret123)
   with the actual configuration of your LDAP server.

   Javaslat

   If you are using LDAPS with a self-signed certificate, make sure to configure a
   Java truststore and reference it in the Keycloak startup parameters using:
   -Djavax.net.ssl.trustStore=/opt/keycloak/conf/truststore.jks
   and -Djavax.net.ssl.trustStorePassword=<password>.
   Alternatively, enable „Use Truststore SPI → Only for LDAPS connection”
   in the Keycloak UI.

   Javaslat

   To improve performance in large environments, enable Connection Pooling.

5. Under LDAP Searching and Updating:

   • Edit Mode – READ_ONLY (recommended when LDAP is the main source of truth)

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

   • Username LDAP Attribute – uid (or sAMAccountName for Active Directory)

   • RDN LDAP Attribute – uid

   • UUID LDAP Attribute – entryUUID (or objectGUID for Active Directory)

   • User Object Classes – inetOrgPerson,organizationalPerson,person,posixAccount

   • Leave other configuration as default.

   Javaslat

   By default, it is recommended to keep Edit Mode set to READ_ONLY since
   LDAP is typically considered the single source of truth and should not be
   modified by Keycloak.

   However, for certain use cases — such as OTRS system migration — it may
   be necessary to temporarily switch Edit Mode to WRITABLE to allow
   Keycloak to synchronize users with OTRS.

   In such cases:

   • Set Edit Mode to WRITABLE before running the synchronization process.

   • Once synchronization is completed, revert Edit Mode
     back to READ_ONLY to protect LDAP data integrity.

   Fontos

   Keep WRITABLE enabled only for the duration of the required synchronization.
   Leaving it permanently active may allow Keycloak to modify LDAP user data,
   which can lead to unintended attribute changes or conflicts with external systems.

   Javaslat

   If you have more than 1000 users, enable Pagination to allow Keycloak to
   retrieve all entries without server-imposed limits.
   This prevents partial synchronization results in larger directories,
   especially with Active Directory environments where the default size limit is 1000 entries.

6. Synchronization settings:

   • Go to User Federation → Settings → Action → Sync all users.

   • Go to the Users list. Since it may not show users automatically, type * in the search box.

   • Verify that all users are listed and visible in the realm.

   Javaslat

   To keep data in sync automatically, configure periodic synchronization:
   – Periodic Full Sync: every 24 hours (86400 seconds)
   – Periodic Changed Users Sync: every 1 hour (3600 seconds)

   Megjegyzés

   Make sure that Import Users is enabled. This allows Keycloak to import
   LDAP users into its internal database for authentication and role mapping.

7. Attribute mapping (Mappers):

   When a new LDAP provider is created, Keycloak attempts to automatically detect
   and create mappings between LDAP attributes and Keycloak user attributes.

   • Default mappings usually include:
     – firstName → givenName
     – lastName → sn
     – email → mail
     – username → uid (or sAMAccountName for Active Directory)
     – uuid → entryUUID (or objectGUID for AD)

   Megjegyzés

   In most environments, these mappings are created automatically when the LDAP
   provider is added. However, they can also be reviewed and customized manually
   under User Federation → [Your LDAP Provider] → Mappers.

   Javaslat

   • If the email or name fields are empty after synchronization,
     verify that their LDAP attributes are correctly mapped in this section.

   • For Active Directory, make sure objectGUID is mapped to the
     User ID attribute in Keycloak to ensure consistent user identity.

   • If groups or roles are managed in LDAP, you can add an additional mapper
     of type group-ldap-mapper or role-ldap-mapper to synchronize them
     into Keycloak automatically.

   Fontos

   Incorrect or missing mappers can cause login failures or duplicate users after
   synchronization. Always verify that all critical attributes (username, email,
   UUID) are mapped correctly before enabling automatic sync.

Rendszer-hitelesítés költöztetése Keycloakra

1. Make sure that Keycloak is set up correctly. See section Keycloak Setup above.

2. Szinkronizálja az ügyintézői szerepeket az OTRS-ben lévő következő parancsfájlok futtatásával:

   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. Szinkronizálja az ügyintézőket az OTRS-ben lévő következő parancsfájlok futtatásával:

   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. Szinkronizálja az ügyfél-felhasználókat az OTRS-ben lévő következő parancsfájlok futtatásával:

   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. Set up OTRS. See section OTRS Setup for Keycloak above.

Beállítási és karbantartási témák

Az OTRS-nek bármikor el kell tudni érnie a Keycloakot a hálózaton keresztül. Ajánlott egy jó, alacsony késleltetésű kapcsolat.

Az összekapcsolhatóság ellenőrzéséhez:

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

Használhat egy konzolparancsot is ugyanerre a célra:

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

Ne töröljön felhasználókat a Keycloakban. Ehelyett állítsa őket letiltva állapotra, ha már nincs rájuk szükség. Az OTRS megőrzi a felhasználókra vonatkozó hivatkozásokat. Ezért nem szabad őket törölni, csak letiltott állapotra állítani.

Ha az OTRS Keycloakot használ a hitelesítéshez, akkor minden ügyintézőnek ellenőriznie kell az ügyfél-felhasználó típusú szervezőelemeiket. Ne feledje, hogy a régi szervezőelemek valószínűleg nem fognak működni, mert a helyettesítő karakteres (*) keresés nem támogatott a Keycloakban. Azt javasoljuk, hogy törölje azokat, és hozzon létre új szervezőelemeket az elérhető és támogatott szűrőkkel.

Ügyfél-felhasználói attribútumok

Ha ügyfél-felhasználókat költöztet át vagy hoz létre a Keycloakban, akkor a következő attribútumokat kell figyelembe vennie. Néhány attribútum kötelező.

• firstName (kötelező)

• lastName (kötelező)

• username (kötelező)

• email (kötelező)

• customerid (kötelező, pontosan meg kell egyeznie az OTRS-ben lévő értékkel)

• enabled (kötelező)

• title

• phone

• comment

• fax

• mobile

• street

• zip

• city

• country

A Keycloakban az ügyfél-felhasználói attribútumok beállításához nyissa meg az ügyfél-felhasználói tartomány beállításait, majd a felhasználói profilt.

Adatszinkronizálás

Ügyfél-felhasználók

Keycloak használata esetén nem lehetséges ügyfél-felhasználókat közvetlenül az OTRS-ben létrehozni, és az ügyfél-felhasználók Keycloakból OTRS-be történő szinkronizálása sem lehetséges. Az ügyfél-felhasználókat a Keycloakban kell létrehozni és frissíteni, de nem kerülnek létrehozásra vagy frissítésre az OTRS-ben.

Ügyintézők

Keycloak használata esetén nem lehetséges az ügyintézőket közvetlenül az OTRS-ben létrehozni. Az ügyintézők szinkronizálása a Keycloakból az OTRS-be az ügyintéző sikeres bejelentkezése után történik. A fent említett AuthSyncModule konfigurációs beállítás vezérli, hogy az ügyintézők szinkronizálása hogyan történjen.

A szinkronizációs folyamat kiterjed az ügyintéző alapvető tulajdonságaira, például a névre, címre és telefonszámra. A szinkronizációs folyamat kiterjed az ügyintéző szerepeinek leképezésére is, például hogy felhasználó vagy adminisztrátor. A szinkronizációs folyamat nem terjed ki a csoportokra.

Ügyintézői szerepek

Ha egy ügyintéző bejelentkezik, az OTRS kiolvassa az ügyintézői szerepeinek leképezését a megfelelő, Keycloak által biztosított hozzáférési tokenből. A hozzáférési token tartalmaz egy különleges mezőt az ilyen adatok számára, és ezt az OTRS ki tudja olvasni.

A Keycloakban meghatározott szerepneveknek pontosan meg kell egyezniük az OTRS-ben meghatározott szerepnevekkel.

A DisableUserRolesSync konfigurációs beállítás 1 értékre állítható a funkció letiltásához. Ahhoz, hogy szinkronizálás nélkül hozzon létre szerepeket a Keycloakban, válassza ki a kívánt ügyfelet az Ügyfelek menüből. Ott létrehozhat szerepeket a Szerepek lapon, és igény szerint hozzárendelheti azokat a Keycloak felhasználókhoz.

Ügyféltitok

A ClientSecret beállítás megszerzéséhez lépjen be a Keycloak adminisztrációs felületére, válassza ki a kívánt ügyfelet az Ügyfelek menüből, majd aktiválja az Ügyfél-hitelesítés lehetőséget a Beállítások lapon. Ezután navigáljon a Hitelesítési adatok lapra. A szükséges érték az Ügyféltitok szövegmezőben található.