Skip to content
OTOBO Community Guide

OpenID Connect in OTOBO – SSO for Agents & Customers

In this guide: Centralize authentication via an external Identity Provider for agents and customer portal users.

Related: OAuth2 email · Customer users · SSO Kerberos · Get support

OTOBO OpenID Connect login configuration With OpenID Connect (OIDC), both agents and customer users can be authenticated conveniently and securely in the OTOBO ticket system. User management is handled centrally via an external Identity Provider (IdP) such as Azure AD or Keycloak.

Prerequisites

Section titled “Prerequisites”
  • OTOBO 11 or higher
  • OpenID Connect-compatible Identity Provider (Azure AD, Keycloak, Auth0, etc.)
  • Access to the Kernel/Config.pm file

Configuring Agent Login with OpenID Connect

Section titled “Configuring Agent Login with OpenID Connect”

The integration for agents is performed in the Kernel/Config.pm.

Example Configuration

Section titled “Example Configuration”
$Self->{AuthModule} = 'Kernel::System::Auth::OpenIDConnect';


$Self->{'AuthModule::OpenIDConnect::Config'}{ClientSettings} = {
    ClientID     => 'YOUR-AGENT-CLIENT-ID',
    ClientSecret => 'YOUR-AGENT-CLIENT-SECRET',
    RedirectURI  => 'https://your-domain.de/otobo/index.pl?Action=Login',
};


$Self->{'AuthModule::OpenIDConnect::Config'}{ProviderSettings} = {
    OpenIDConfiguration => 'https://your-provider.de/.well-known/openid-configuration',
    TTL                 => 1800,
};


$Self->{'AuthModule::OpenIDConnect::AuthRequest'}->{ResponseType}    = ['code'];
$Self->{'AuthModule::OpenIDConnect::AuthRequest'}->{AdditionalScope} = [qw/profile email/];


$Self->{'AuthModule::OpenIDConnect::UID'} = 'email';


$Self->{'AuthModule::OpenIDConnect::UserMap'} = {
    email       => 'UserEmail',
    given_name  => 'UserFirstname',
    family_name => 'UserLastname',
};


# Optional mapping of groups/roles
$Self->{'AuthModule::OpenIDConnect::RoleMap'} = {
    groups => {
        admins  => 'admin',
        support => 'support',
    },
};


# Debugging (temporary)
$Self->{'AuthModule::OpenIDConnect::Debug'}->{'LogIDToken'} = 1;

Configuring Customer User Login with OpenID Connect

Section titled “Configuring Customer User Login with OpenID Connect”

Customer users can also be authenticated via OpenID Connect.

Example Configuration for Customer Users

Section titled “Example Configuration for Customer Users”
$Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::OpenIDConnect';


$Self->{'Customer::AuthModule::OpenIDConnect::Config'}{ClientSettings} = {
    ClientID     => 'YOUR-CUSTOMER-CLIENT-ID',
    ClientSecret => 'YOUR-CUSTOMER-CLIENT-SECRET',
    RedirectURI  => 'https://your-domain.de/otobo/customer.pl?Action=Login',
};


$Self->{'Customer::AuthModule::OpenIDConnect::Config'}{ProviderSettings} = {
    OpenIDConfiguration => 'https://your-provider.de/.well-known/openid-configuration',
    TTL                 => 1800,
};


$Self->{'Customer::AuthModule::OpenIDConnect::AuthRequest'}->{ResponseType}    = ['code'];
$Self->{'Customer::AuthModule::OpenIDConnect::AuthRequest'}->{AdditionalScope} = [qw/profile email/];


$Self->{'Customer::AuthModule::OpenIDConnect::UID'} = 'email';


$Self->{'Customer::AuthModule::OpenIDConnect::UserMap'} = {
    email       => 'UserEmail',
    given_name  => 'UserFirstname',
    family_name => 'UserLastname',
};


# Automatic customer user creation
$Self->{'Customer::AuthModule::OpenIDConnect::AutoCreateUser'} = 1;


# Optional debugging
$Self->{'Customer::AuthModule::OpenIDConnect::Debug'}->{'LogIDToken'} = 1;

Optimally Configuring Azure AD (Example)

Section titled “Optimally Configuring Azure AD (Example)”

  1. Register a new app in Azure Active Directory

  2. Add permissions for “openid”, “profile”, and “email”

  3. Set Redirect URIs:

    • Agents: https://your-domain.de/otobo/index.pl?Action=Login
    • Customers: https://your-domain.de/otobo/customer.pl?Action=Login

  4. Configure claims (given_name, family_name) under “Token Configuration”

Testing the Login

Section titled “Testing the Login”

After configuration and restarting the web server, agents and customer users can be conveniently authenticated via your external IdP. New users are automatically created in OTOBO, provided this is configured.

Advantages of OIDC Integration in OTOBO

Section titled “Advantages of OIDC Integration in OTOBO”
  • Central and secure authentication
  • Unified identity management
  • Automatic user creation
  • Reduced administrative effort

FAQ: OpenID Connect in OTOBO

Section titled “FAQ: OpenID Connect in OTOBO”

From which version does OTOBO support OpenID Connect?

Section titled “From which version does OTOBO support OpenID Connect?”

OpenID Connect is supported natively from OTOBO 11 onward — for both agents and customer users.

Does OIDC work with Azure AD / Microsoft Entra ID, Keycloak, and Auth0?

Section titled “Does OIDC work with Azure AD / Microsoft Entra ID, Keycloak, and Auth0?”

Yes. Any standards-compliant OpenID Connect provider can be connected. You only need the OpenIDConfiguration URL (.well-known/openid-configuration), a client ID, and a client secret.

Are new users created automatically?

Section titled “Are new users created automatically?”

For customer users, yes — provided AutoCreateUser is enabled. You control how claims (email, given_name, family_name) map to OTOBO fields via UserMap.

Can I authenticate agents and customers with different providers?

Section titled “Can I authenticate agents and customers with different providers?”

Yes. Agent login (AuthModule) and customer-user login (Customer::AuthModule) are configured separately and can point to different providers and client IDs.

Section titled “Further Links”

Frequently asked questions

What are the prerequisites and minimum OTOBO version required for OpenID Connect integration?

To successfully implement OpenID Connect (OIDC) for authentication in OTOBO, you must ensure a few key prerequisites are met. First, your OTOBO instance needs to be version 11 or higher. This version introduced native support for OIDC, allowing both agents and customer users to leverage this secure authentication method. Second, you require an OpenID Connect-compatible Identity Provider (IdP). Popular choices include Azure AD (Microsoft Entra ID), Keycloak, or Auth0, but any standards-compliant IdP will work. Finally, you must have access to the Kernel/Config.pm file on your OTOBO server, as this is where all the necessary configuration for both agent and customer OIDC integration is performed. Meeting these requirements ensures a smooth setup process for centralizing your user authentication.

Quellen

How do I configure OpenID Connect for OTOBO agents?

Configuring OpenID Connect for OTOBO agents involves modifying the Kernel/Config.pm file to specify the authentication module and its settings. You'll set $Self->{AuthModule} to 'Kernel::System::Auth::OpenIDConnect'. Within the $Self->{'AuthModule::OpenIDConnect::Config'}{ClientSettings} block, you must define your ClientID, ClientSecret, and the RedirectURI (typically https://your-domain.de/otobo/index.pl?Action=Login). The $Self->{'AuthModule::OpenIDConnect::Config'}{ProviderSettings} section requires the OpenIDConfiguration URL of your IdP (e.g., https://your-provider.de/.well-known/openid-configuration) and an optional TTL for metadata caching. Additionally, you'll configure $Self->{'AuthModule::OpenIDConnect::AuthRequest'} for ResponseType (usually ['code']) and AdditionalScope (e.g., [qw/profile email/]). Crucially, define $Self->{'AuthModule::OpenIDConnect::UID'} (e.g., 'email') and $Self->{'AuthModule::OpenIDConnect::UserMap'} to map IdP claims like email, given_name, and family_name to OTOBO's UserEmail, UserFirstname, and UserLastname fields, respectively. An optional RoleMap can also be used for group-based access.

Quellen

How is OpenID Connect configured for OTOBO customer users, and does it support automatic user creation?

OpenID Connect for OTOBO customer users is configured similarly to agents, but with distinct settings in Kernel/Config.pm. You'll use $Self->{'Customer::AuthModule'} set to 'Kernel::System::CustomerAuth::OpenIDConnect'. The ClientSettings will include a ClientID, ClientSecret, and RedirectURI specific to the customer portal (e.g., https://your-domain.de/otobo/customer.pl?Action=Login). ProviderSettings will again point to your IdP's OpenIDConfiguration URL. Just like with agents, AuthRequest defines ResponseType and AdditionalScope, and UID specifies the unique identifier (e.g., 'email'). A key feature for customer users is the support for automatic user creation. By setting $Self->{'Customer::AuthModule::OpenIDConnect::AutoCreateUser'} = 1;, OTOBO will automatically create new customer user accounts upon their first successful login via OIDC. The $Self->{'Customer::AuthModule::OpenIDConnect::UserMap'} ensures that attributes like email, given_name, and family_name from the IdP are correctly mapped to the corresponding OTOBO customer user fields.

Quellen

Which identity providers (IdPs) are compatible with OTOBO's OpenID Connect integration, and what information is needed from them?

OTOBO's OpenID Connect integration is designed to be highly flexible and compatible with any standards-compliant OpenID Connect provider. This includes widely used IdPs such as Azure AD (Microsoft Entra ID), Keycloak, and Auth0, among others. The core principle is that if an IdP adheres to the OpenID Connect specification, it can be integrated with OTOBO. To establish the connection, you primarily need three pieces of information from your chosen IdP:

  1. The OpenIDConfiguration URL: This is typically an endpoint ending in /.well-known/openid-configuration, which provides OTOBO with all the necessary metadata about the IdP's OIDC capabilities.
  2. A Client ID: This unique identifier is assigned to your OTOBO application when you register it with the IdP.
  3. A Client Secret: This confidential key is used by OTOBO to authenticate itself to the IdP securely.
    It's important to note that OTOBO allows you to configure agent login and customer user login with different providers and client IDs, offering great flexibility for diverse organizational structures.

Quellen

What are the key steps for optimally configuring Azure AD (Microsoft Entra ID) for OTOBO's OpenID Connect?

When configuring Azure AD (now known as Microsoft Entra ID) for OTOBO's OpenID Connect, there are four crucial steps to ensure optimal integration:

  1. Register a new application in your Azure Active Directory tenant. This creates the necessary application identity for OTOBO within Azure AD.
  2. Add API permissions for the standard OpenID Connect scopes: openid, profile, and email. These permissions allow OTOBO to request basic user information and the ID token from Azure AD.
  3. Set the Redirect URIs for your registered application. It's vital to specify two distinct URIs:
    • For Agents: https://your-domain.de/otobo/index.pl?Action=Login
    • For Customers: https://your-domain.de/otobo/customer.pl?Action=Login
      These URIs tell Azure AD where to redirect the user after successful authentication.
  4. Configure claims under "Token Configuration" to ensure that essential user attributes like given_name and family_name are included in the ID token. This allows OTOBO's UserMap to correctly populate agent and customer user profiles with first and last names.

Quellen

What are the main advantages of integrating OpenID Connect with OTOBO?

Integrating OpenID Connect (OIDC) with OTOBO offers several significant advantages that enhance security, streamline user management, and reduce administrative overhead. Firstly, it provides central and secure authentication, allowing OTOBO to leverage a single, trusted Identity Provider (IdP) for verifying user identities. This eliminates the need for managing separate credentials within OTOBO, reducing the risk of credential sprawl and improving overall security posture. Secondly, it enables unified identity management, as user accounts and attributes are managed centrally in the IdP, ensuring consistency across various applications. Thirdly, OIDC facilitates automatic user creation, particularly beneficial for customer users where new accounts can be provisioned instantly upon their first login, provided the AutoCreateUser setting is enabled. This feature significantly reduces administrative effort by automating the onboarding process for new users and simplifying ongoing user lifecycle management, allowing IT teams to focus on more critical tasks.

Quellen