OTRS supports authentication via any OpenID Connect compatible identity provider (e.g. Keycloak, Auth0, Azure AD, Okta, etc.). This tutorial explains the setup, configuration and maintenance guidelines for using an OIDC provider as central authentication with OTRS.
When OTRS is configured to use an OIDC provider, and an agent or a customer user tries to access the OTRS login page, the browser will be automatically redirected to the OIDC provider where authentication actually happens. If authentication is successful, the browser is redirected to OTRS where normal usage takes place.
Agent OIDC Configuration
To enable OpenID Connect authentication for agents, configure the following settings in a custom Perl configuration file under Kernel/Config/Files/ (e.g. ZZZ_OIDC.pm) or directly in Kernel/Config.pm:
$Self->{AuthModule} = 'Kernel::System::Auth::OIDC';
$Self->{'Agent::AccessTokenStorageModule'} = 'Kernel::System::AccessToken::Storage::OIDC';
$Self->{'AuthModule::OIDC::Authority'} = 'https://oidc.example.com/issuer';
$Self->{'AuthModule::OIDC::ClientID'} = 'otrs-agent-client';
$Self->{'AuthModule::OIDC::Engine'} = 'Standard';
$Self->{'AuthModule::OIDC::PostLogoutRedirectURL'} = 'https://otrs.example.com/agent';
$Self->{'AuthSyncModule'} = 'Kernel::System::Auth::Sync::OIDC';
$Self->{'AuthSyncModule::OIDC::UserSyncMap'} = {
UserFirstname => 'given_name',
UserLastname => 'family_name',
UserEmail => 'email',
};
# Optional settings:
# $Self->{'AuthModule::OIDC::AgentRole'} = 'Agent';
# $Self->{'AuthModule::OIDC::AccountSecurityPageURL'} = 'https://oidc.example.com/account/security';
# $Self->{'AuthModule::OIDC::ClaimsSource'} = 'access_token'; # or 'id_token' for Casdoor
# $Self->{'AuthModule::OIDC::BackendAuthority'} = 'https://oidc-internal.example.com/issuer';
# $Self->{'AuthModule::OIDC::Token::RolesPath'} = 'resource_access::<client-id>::roles';
# $Self->{'AuthModule::OIDC::UsersAdminPageURL'} = 'https://oidc.example.com/admin/users';
The required parameters:
|
Setting |
Description |
Required |
|---|---|---|
|
|
Must be set to |
yes |
|
|
Must be set to |
yes |
|
|
OIDC issuer URL (provider base URL). |
yes |
|
|
OIDC client ID registered in the provider. |
yes |
|
|
OIDC engine to use. Set to |
yes |
|
|
URL to redirect agents after successful logout. |
no |
|
|
Must be set to |
yes |
|
|
Maps OIDC claims to OTRS user fields. |
yes |
Optional Agent OIDC Configuration
The following optional settings can be added to fine-tune the OIDC integration:
|
Setting |
Description |
Required |
Default |
|---|---|---|---|
|
|
Role name the user must have in the IdP to access |
no |
(none) |
|
|
External URL for users to manage authentication |
no |
(none) |
|
|
Token containing the claims: |
no |
|
|
|
Alternative Authority URL for backend-to-backend |
no |
(uses |
|
|
Path to the roles array in the token using |
no |
|
|
|
External URL for user management in the IdP |
no |
(none) |
Agent OIDC Environment Variables
All agent OIDC settings can also be configured via environment variables.
The following table maps environment variables to their Perl configuration equivalents:
|
Environment Variable |
Perl Setting |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note
Environment variables take precedence over Perl configuration file settings.
Customer User OIDC Configuration
To enable OpenID Connect authentication for customer users, configure the following settings in a custom Perl configuration file under Kernel/Config/Files/ (e.g. ZZZ_OIDC.pm) or directly in Kernel/Config.pm:
$Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::OIDC';
$Self->{'Customer::AccessTokenStorageModule'} = 'Kernel::System::AccessToken::Storage::OIDC';
$Self->{'Customer::AuthModule::OIDC::Authority'} = 'https://oidc.example.com/issuer';
$Self->{'Customer::AuthModule::OIDC::ClientID'} = 'otrs-customer-client';
$Self->{'Customer::AuthModule::OIDC::PostLogoutRedirectURL'} = 'https://otrs.example.com/customer';
The required parameters:
|
Setting |
Description |
Required |
|---|---|---|
|
|
Must be set to |
yes |
|
|
Must be set to |
yes |
|
|
OIDC issuer URL (provider base URL). |
yes |
|
|
OIDC client ID registered in the provider. |
yes |
|
|
URL to redirect customer users after successful |
no |
Optional Customer User OIDC Configuration
The following optional settings can be added to fine-tune the OIDC integration for customer users:
# Optional settings:
# $Self->{'Customer::AuthModule::OIDC::CustomerUserRole'} = 'Customer User';
# $Self->{'Customer::AuthModule::OIDC::BackendAuthority'} = 'https://oidc-internal.example.com/issuer';
# $Self->{'Customer::AuthModule::OIDC::AccountSecurityPageURL'} = 'https://oidc.example.com/account/security';
# $Self->{'Customer::AuthModule::OIDC::ClaimsSource'} = 'access_token'; # or 'id_token' for Casdoor
# $Self->{'Customer::AuthModule::OIDC::Token::RolesPath'} = 'resource_access::<client-id>::roles';
# $Self->{'Customer::AuthModule::OIDC::UsersAdminPageURL'} = 'https://oidc.example.com/admin/users';
|
Setting |
Description |
Required |
Default |
|---|---|---|---|
|
|
Role name the user must have in the IdP to access |
no |
(none) |
|
|
Alternative Authority URL for backend-to-backend |
no |
(uses |
|
|
External URL for users to manage authentication |
no |
(none) |
|
|
Token containing the claims: |
no |
|
|
|
Path to the roles array in the token using |
no |
|
|
|
External URL for user management in the IdP |
no |
(none) |
Customer User OIDC Environment Variables
All customer user OIDC settings can also be configured via environment variables.
The following table maps environment variables to their Perl configuration equivalents:
|
Environment Variable |
Perl Setting |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note
Environment variables take precedence over Perl configuration file settings.
Note
For ClaimsSource, use id_token with providers like Casdoor that
include roles/claims in the ID token rather than the access token.
Note
For Token::RolesPath, use :: to traverse nested structures.
The default resource_access::<client-id>::roles expects you to replace
<client-id> with your actual OIDC client ID (e.g.
resource_access::otrs-agent-client::roles).
Example for Keycloak (client roles): resource_access::<client-id>::roles
Note
The Authority URL must point to the OIDC provider’s issuer endpoint
(the base URL from which .well-known/openid-configuration is reachable).
Ensure the provider has a valid OIDC client configured with the matching
ClientID and appropriate redirect URIs.
Important
These settings cannot be configured via SysConfig. They must be set in
a custom Perl configuration file under Kernel/Config/Files/,
directly in Kernel/Config.pm, or via environment variables.
