OTRS can act as an identity issuer so that an approved AI-channel service provider (for example a chat integration embedded in the external interface) can recognize a logged-in customer user without requiring a second login.
When a customer user is authenticated in the external interface, OTRS can mint a dedicated, short-lived, cryptographically signed identity token for that user. The service provider verifies the token against a public key that OTRS publishes, and thereby trusts which customer user is asking. This is a one-way trust hand-off only: the identity token proves who is asking, it is never accepted back by OTRS’s own APIs, and it plays no part in the actual work the service provider performs on the customer user’s behalf (ticket handling, FAQ search, and so on go through a separately configured and separately secured connection).
Megjegyzés
This feature only applies when OTRS itself handles customer user login. If the system is configured to use Keycloak for authentication (see Személyazonosság- és hozzáférés-kezelés), tokens are issued by Keycloak instead and the configuration on this page has no effect. That does not mean there is nothing to do: enabling the integration under Keycloak still requires its own setup (forwarding the Keycloak-issued token to the service provider, and registering the provider as a client/audience in Keycloak), which is not covered here.
Generating a Key Pair
The identity issuer signs tokens with an RSA private key. Generate one (2048 bit or larger) on a trusted machine, for example with OpenSSL:
openssl genrsa -out identity-issuer-private.pem 2048
Keep the resulting file confidential. The matching public key is derived automatically and does not need to be generated or stored separately.
Enabling the Identity Issuer
To activate the identity issuer, copy the following configuration snippet from Kernel/Config/Defaults.pm and paste it to Kernel/Config.pm. Uncomment the lines and add the proper values for the keys.
# -------------------------------------------------- #
# Identity Issuer #
# -------------------------------------------------- #
$Self->{'IdentityToken::Enabled'} = 1;
$Self->{'IdentityToken::PrivateKeyPEM'} = '-----BEGIN PRIVATE KEY-----...';
$Self->{'IdentityToken::Issuer'} = 'https://my-otrs-host.example.com';
$Self->{'IdentityToken::Audience'} = ['my-approved-provider'];
# $Self->{'IdentityToken::TTL'} = 60; # seconds, optional
Alternatively, environment variables can be used for the same purpose. The following environment variables provide identical configuration possibilities as the Kernel/Config.pm snippet above. If yes is displayed in the last column, the setting is mandatory to enable the feature, regardless of whether it is set via Kernel/Config.pm or the environment variable.
|
Environment Variable |
Leírás |
Alapértelmezett érték |
Kötelező |
|---|---|---|---|
|
|
Master switch for the identity issuer |
off |
igen |
|
|
RSA private key (PEM) used to sign tokens |
N/A |
igen |
|
|
Value of the token’s issuer claim, typically |
N/A |
igen |
|
|
One or more identifiers agreed with the |
N/A |
igen |
|
|
Token lifetime in seconds |
60 |
nem |
|
|
Previous public key (PEM), only used while |
N/A |
nem |
After setting the configuration, restart OTRS for the change to take effect.
Fontos
The audience value in OTRS_IDENTITYTOKEN_AUDIENCE must be agreed with the service provider beforehand and must not be a value already used elsewhere in the system (for example agent or customer). Do not hardcode or guess a provider’s expected value; confirm it with the provider directly.
Security Considerations
-
The private key is configuration, not data: it must only ever be set through
Kernel/Config.pmor an environment variable (which, in a container deployment, should come from a secret store). It is never written to the database, and it should never be shared with the service provider — only the derived public key is published. -
Tokens are deliberately short-lived (
OTRS_IDENTITYTOKEN_TTL, default 60 seconds) and are rejected by every OTRS API. A copy of a token intercepted in transit cannot be replayed against OTRS itself, and it expires quickly even against the service provider. -
Enabling this feature does not expose any customer data beyond what is already visible to a logged-in customer user (their own login identifier). It only adds a way for OTRS to vouch for that identifier to a third party the administrator has explicitly configured.
Rotating the Key
The signing key can be replaced without any downtime or service interruption, because OTRS can publish two public keys at once — the current one and the previous one — while only ever signing new tokens with the current one.
-
Before generating a new private key, derive and keep the public key that matches the current
OTRS_IDENTITYTOKEN_PRIVATEKEYPEM:openssl rsa -in identity-issuer-private.pem -pubout -out identity-issuer-previous-public.pem
-
Generate a new private key as described above.
-
Set
OTRS_IDENTITYTOKEN_PRIVATEKEYPEMto the new private key, andOTRS_IDENTITYTOKEN_PREVIOUSPUBLICKEYPEMto the public key saved in step 1. -
Restart OTRS.
While both values are set, OTRS signs new tokens with the new key, but still publishes the previous public key so that any token issued moments before the restart (still within its short lifetime) continues to verify successfully. Once the previous key’s tokens can no longer be outstanding — comfortably longer than OTRS_IDENTITYTOKEN_TTL — remove OTRS_IDENTITYTOKEN_PREVIOUSPUBLICKEYPEM and restart again.
Allowing the Provider’s Origin
If the service provider’s integration loads scripts or opens network connections from the browser (for example a chat widget embedded in the external interface), its host must also be added to the WebApp::Server::AdditionalOrigins setting, otherwise the browser’s content security policy will block it. See the external interface script settings for where the provider’s own snippet is configured.
