OpenID Connect Authentication

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

AuthModule

Must be set to Kernel::System::Auth::OIDC
to enable OIDC authentication.

yes

Agent::AccessTokenStorageModule

Must be set to
Kernel::System::AccessToken::Storage::OIDC
to store tokens via OIDC backend.

yes

AuthModule::OIDC::Authority

OIDC issuer URL (provider base URL).
Example: https://oidc.example.com/issuer

yes

AuthModule::OIDC::ClientID

OIDC client ID registered in the provider.

yes

AuthModule::OIDC::Engine

OIDC engine to use. Set to Standard for
standard OIDC flow.

yes

AuthModule::OIDC::PostLogoutRedirectURL

URL to redirect agents after successful logout.

no

AuthSyncModule

Must be set to
Kernel::System::Auth::Sync::OIDC to create
and sync the agent in the OTRS database after
a successful login.

yes

AuthSyncModule::OIDC::UserSyncMap

Maps OIDC claims to OTRS user fields.
Example: UserFirstname → given_name,
UserLastname → family_name,
UserEmail → email.

yes

Optional Agent OIDC Configuration

The following optional settings can be added to fine-tune the OIDC integration:

Setting

Description

Required

Default

AuthModule::OIDC::AgentRole

Role name the user must have in the IdP to access
the OTRS agent interface.

no

(none)

AuthModule::OIDC::AccountSecurityPageURL

External URL for users to manage authentication
settings (password, 2FA, etc.).

no

(none)

AuthModule::OIDC::ClaimsSource

Token containing the claims: access_token or
id_token (e.g. Casdoor uses id_token).

no

access_token

AuthModule::OIDC::BackendAuthority

Alternative Authority URL for backend-to-backend
communication (e.g. Kubernetes internal network).
If not set, Authority is used.

no

(uses Authority)

AuthModule::OIDC::Token::RolesPath

Path to the roles array in the token using ::
as separator.

no

resource_access::<client-id>::roles

AuthModule::OIDC::UsersAdminPageURL

External URL for user management in the IdP
(admin console, user portal, etc.).

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

OTRS_AGENT_AUTH_MODULE

AuthModule

OTRS_AGENT_ACCESSTOKEN_STORAGE_MODULE

Agent::AccessTokenStorageModule

OTRS_OIDC_AGENT_AUTHORITY

AuthModule::OIDC::Authority

OTRS_OIDC_AGENT_BACKENDAUTHORITY

AuthModule::OIDC::BackendAuthority

OTRS_OIDC_AGENT_CLIENTID

AuthModule::OIDC::ClientID

OTRS_OIDC_AGENT_ENGINE

AuthModule::OIDC::Engine

OTRS_OIDC_AGENT_POSTLOGOUTREDIRECTURL

AuthModule::OIDC::PostLogoutRedirectURL

OTRS_OIDC_AGENT_ROLE

AuthModule::OIDC::AgentRole

OTRS_OIDC_AGENT_ACCOUNTSECURITYPAGEURL

AuthModule::OIDC::AccountSecurityPageURL

OTRS_OIDC_AGENT_CLAIMSSOURCE

AuthModule::OIDC::ClaimsSource

OTRS_OIDC_AGENT_TOKEN_ROLESPATH

AuthModule::OIDC::Token::RolesPath

OTRS_OIDC_AGENT_USERSADMINPAGEURL

AuthModule::OIDC::UsersAdminPageURL

OTRS_AGENT_AUTH_SYNC_MODULE

AuthSyncModule

OTRS_OIDC_AGENT_USERSYNCMAP_USERFIRSTNAME

AuthSyncModule::OIDC::UserSyncMap
(UserFirstname)

OTRS_OIDC_AGENT_USERSYNCMAP_USERLASTNAME

AuthSyncModule::OIDC::UserSyncMap
(UserLastname)

OTRS_OIDC_AGENT_USERSYNCMAP_USEREMAIL

AuthSyncModule::OIDC::UserSyncMap
(UserEmail)

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

Customer::AuthModule

Must be set to Kernel::System::CustomerAuth
::OIDC
to enable OIDC authentication.

yes

Customer::AccessTokenStorageModule

Must be set to
Kernel::System::AccessToken::Storage::OIDC
to store tokens via OIDC backend.

yes

Customer::AuthModule::OIDC::Authority

OIDC issuer URL (provider base URL).
Example: https://oidc.example.com/issuer

yes

Customer::AuthModule::OIDC::ClientID

OIDC client ID registered in the provider.

yes

Customer::AuthModule::OIDC::PostLogoutRedirectURL

URL to redirect customer users after successful
logout.

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

Customer::AuthModule::OIDC::CustomerUserRole

Role name the user must have in the IdP to access
the OTRS customer interface.

no

(none)

Customer::AuthModule::OIDC::BackendAuthority

Alternative Authority URL for backend-to-backend
communication (e.g. Kubernetes internal network).
If not set, Customer::AuthModule::OIDC::Authority
is used.

no

(uses Customer::AuthModule::OIDC::Authority)

Customer::AuthModule::OIDC::AccountSecurityPageURL

External URL for users to manage authentication
settings (password, 2FA, etc.).

no

(none)

Customer::AuthModule::OIDC::ClaimsSource

Token containing the claims: access_token or
id_token (e.g. Casdoor uses id_token).

no

access_token

Customer::AuthModule::OIDC::Token::RolesPath

Path to the roles array in the token using ::
as separator.

no

resource_access::<client-id>::roles

Customer::AuthModule::OIDC::UsersAdminPageURL

External URL for user management in the IdP
(admin console, user portal, etc.).

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

OTRS_CUSTOMER_USER_AUTH_MODULE

Customer::AuthModule

OTRS_CUSTOMER_USER_ACCESSTOKEN_STORAGE_MODULE

Customer::AccessTokenStorageModule

OTRS_OIDC_CUSTOMER_USER_AUTHORITY

Customer::AuthModule::OIDC::Authority

OTRS_OIDC_CUSTOMER_USER_CLIENTID

Customer::AuthModule::OIDC::ClientID

OTRS_OIDC_CUSTOMER_USER_ENGINE

Customer::AuthModule::OIDC::Engine

OTRS_OIDC_CUSTOMER_USER_POSTLOGOUTREDIRECTURL

Customer::AuthModule::OIDC::PostLogoutRedirectURL

OTRS_OIDC_CUSTOMER_USER_ROLE

Customer::AuthModule::OIDC::CustomerUserRole

OTRS_OIDC_CUSTOMER_USER_BACKENDAUTHORITY

Customer::AuthModule::OIDC::BackendAuthority

OTRS_OIDC_CUSTOMER_USER_ACCOUNTSECURITYPAGEURL

Customer::AuthModule::OIDC::AccountSecurityPageURL

OTRS_OIDC_CUSTOMER_USER_CLAIMSSOURCE

Customer::AuthModule::OIDC::ClaimsSource

OTRS_OIDC_CUSTOMER_USER_TOKEN_ROLESPATH

Customer::AuthModule::OIDC::Token::RolesPath

OTRS_OIDC_CUSTOMER_USER_USERSADMINPAGEURL

Customer::AuthModule::OIDC::UsersAdminPageURL

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.

Scroll to Top