Configure SAML backends for single sign-on (SSO)

Configure SAML backends for single sign-on (SSO)#

Single Sign-on means a user can login once and the credentials can be used by multiple applications. In Znuny, we offer SSO using:

Utilizing Kernel::System::Auth::HTTPBasicAuth as a backend, Znuny relies on the username exposed in the REMOTE_USER variable of the web server request. There are several authentication modules available like:

Utilizing Kernel::System::Auth::SAML as a backend, SAML 2.0 authentication can be used with an Identity Provider (IdP).

  • SAML 2.0

Here we discuss the settings available for SAML Authentication and Synchronization.

Configuration Defaults#

SAML authentication, if not done via an Apache module, can be directly configured in the Kernel/Config.pm. Customers and Agents can be authenticated in this fashion. The following links to the GitHub Repository, will allow you to copy the necessary configurations to your Kernel/Config.pm for adaptation. You should be familiar with SAML and it’s configuration on both sides, IdP and SP.

Tip

It is recommended to use a SAML tracer plugin for your browser when configuring SAML.

Agent Authentication#

Agent Authentication (Defaults.pm)

Customer Authentication#

Customer Authentication (Defaults.pm)

Agent Synchronization#

Agent Synchronization (Defaults.pm)

Note

Configuration option, descriptions and example data should be read from the file directly.

Description of Options#

Here is list of SAML-related configuration options available in Kernel/Config/Defaults.pm for:

  • AgentAuth (Agent Login)

  • CustomerAuth (Customer Login)

  • AuthSync (Agent Synchronization)

Note

All examples use backend index 1. Multiple backends can be configured by incrementing the numeric suffix.

Agent Authentication (AuthModule)#

Enable SAML Backend#

$Self->{'AuthModule1'} = 'Kernel::System::Auth::SAML';

Note

Enables SAML 2.0 authentication for agents.

Identity Provider (IdP) Metadata#

Metadata URL#
$Self->{'AuthModule::SAML::RequestMetaDataURL1'} = 'https://idp.example/metadata';

Note

URL to retrieve the IdP metadata XML.

Metadata XML (Alternative to URL)#
$Self->{'AuthModule::SAML::Request::MetaDataXML1'} = '<xml>...</xml>';

Note

Embed IdP metadata XML directly as a string.

SSL Options (only if Metadata URL is used)#
$Self->{'AuthModule::SAML::RequestMetaDataURLSSLOptions1'} = {
    SSL_ca_file     => '/etc/ssl/certs/ca.pem',
    SSL_ca_path     => '/etc/ssl/certs',
    verify_hostname => 1,
};

Note

Optional SSL/TLS settings for metadata retrieval.

Request Signing (Optional)#
$Self->{'AuthModule::SAML::RequestSignKey1'} = '/path/to/private.key';

Note

Private key used to sign the SAML authentication request.

Login Button Text#

$Self->{'AuthModule::SAML::RequestLoginButtonText1'} = 'Login via SAML';

Note

Custom text for the SAML login button. Translatable via the AdminTranslation. (see: Translating Terminology )

Service Provider (SP) Configuration#

Assertion Consumer Service (ACS) URL#
$Self->{'AuthModule::SAML::RequestAssertionConsumerURL1'}
    = 'https://yourhost/znuny/index.pl?Action=Login';

Note

Login callback endpoint for the IdP to send the SAML response. This URL should be create out of your system settings: $Self->{'AuthModule::SAML::RequestAssertionConsumerURL1'} = ( $Self->{HttpType} // '' ) . '://' . $Self->{FQDN} . '/' . $Self->{ScriptAlias} . 'index.pl?Action=Login';

Issuer#
$Self->{'AuthModule::SAML::Issuer1'} = 'https://your-znuny-instance/znuny/';

Note

Unique identifier for your Znuny instance, included in SAML requests. Often the URL of your Znuny instance.

Identity Provider Trust (Optional)#

IdP CA Certificate#
$Self->{'AuthModule::SAML::IdPCACert1'} = '/path/to/idp-ca.pem';

Note

Optional CA certificate of the Identity Provider.

Customer Authentication (Customer::AuthModule)#

Enable SAML Backend#

$Self->{'Customer::AuthModule1'} = 'Kernel::System::CustomerAuth::SAML';

Note

Enables SAML 2.0 authentication for customer users.

Identity Provider Metadata#

$Self->{'Customer::AuthModule::SAML::RequestMetaDataURL1'} = 'https://idp.example/metadata';

Or:

$Self->{'Customer::AuthModule::SAML::Request::MetaDataXML1'} = '<xml>...</xml>';

Note

Metadata Provisioning for Customer SAML Authentication.

SSL Options (Only if Metadata URL is used)#
$Self->{'Customer::AuthModule::SAML::RequestMetaDataURLSSLOptions1'} = {
    SSL_ca_file     => '/etc/ssl/certs/ca.pem',
    SSL_ca_path     => '/etc/ssl/certs',
    verify_hostname => 1,
};

Note

Optional SSL/TLS settings for metadata retrieval.

Request Signing#

$Self->{'Customer::AuthModule::SAML::RequestSignKey1'} = '/path/to/private.key';

Note

Private key used to sign the SAML authentication request.

Login Button Text#

$Self->{'Customer::AuthModule::SAML::RequestLoginButtonText1'} = 'Customer Login via SAML';

Note

Custom text for the SAML login button on the customer login page. Translatable via AdminTranslation. (see: Translating Terminology )

Service Provider Configuration#

Assertion Consumer URL#
$Self->{'Customer::AuthModule::SAML::RequestAssertionConsumerURL1'}
    = 'https://yourhost/otrs/customer.pl?Action=Login';

Note

Customer login callback endpoint. This URL should be create out of your system settings: $Self->{'AuthModule::SAML::RequestAssertionConsumerURL1'} = ( $Self->{HttpType} // '' ) . '://' . $Self->{FQDN} . '/' . $Self->{ScriptAlias} . 'customer.pl?Action=Login';

Issuer#
$Self->{'Customer::AuthModule::SAML::Issuer1'} = 'https://your-znuny-instance/znuny/';

Note

Unique identifier for your Znuny instance, included in SAML requests. Often the URL of your Znuny instance.

Identity Provider Trust#
$Self->{'Customer::AuthModule::SAML::IdPCACert1'} = '/path/to/idp-ca.pem';

Note

Optional CA certificate of the Identity Provider for customer authentication.

Synchronization (AuthSyncModule)#

Enable SAML Sync Backend#

$Self->{'AuthSyncModule1'} = 'Kernel::System::Auth::Sync::SAML';

Note

Synchronizes user data after successful SAML authentication.

Note

This module can be used in conjunction with Agent SAML authentication backends to sync user attributes, group memberships, and roles based on the SAML response.

User Attribute Mapping#

$Self->{'AuthSyncModule::SAML::UserSyncMap1'} = {
    UserFirstname => 'givenName',
    UserLastname  => 'sn',
    UserEmail     => 'mail',
};

The keys are the user (agent) attributes and the value the variables of the SAML response. first name, last name, and email are mandatory. Additional attribues can be configured too.

Note

Maps SAML response attributes to Znuny user fields.

Initial Group Assignment#

$Self->{'AuthSyncModule::SAML::UserSyncInitialGroups1'} = [
    'users',
];

Note

Groups assigned to newly created users.

Group Mapping via SAML Attribute#

Define Attribute Name

$Self->{'AuthSyncModule::SAML::UserSyncGroupsDefinition::Attribute1'} = 'MemberOf';

Define Mapping

$Self->{'AuthSyncModule::SAML::UserSyncGroupsDefinition1'} = {
    Support => {
        users => { rw => 1 },
    },
};

Note

Maps SAML attribute values to Znuny groups with permissions.

Attribute-Based Group Mapping (Alternative Structure)#

$Self->{'AuthSyncModule::SAML::UserSyncAttributeGroupsDefinition1'} = {
    MemberOf => {
        Admins => {
            admin => { rw => 1 },
        },
    },
};

Note

Maps SAML attribute values to Znuny groups with permissions.

Role Mapping via SAML Attribute#

Define Attribute Name#

$Self->{'AuthSyncModule::SAML::UserSyncRolesDefinition::Attribute1'} = 'Role';

Note

Name of the SAML attribute containing role information.

Define Mapping#

$Self->{'AuthSyncModule::SAML::UserSyncRolesDefinition1'} = {
    Operations => {
        ZnunyRole1 => 1,
        ZnunyRole2 => 0,
    },
};

Note

Maps SAML attribute values to Znuny roles.

Attribute-Based Role Mapping (Alternative Structure)#

$Self->{'AuthSyncModule::SAML::UserSyncAttributeRolesDefinition1'} = {
    Role => {
        Admin => {
            AdminRole => 1,
        },
    },
};

Note

Maps SAML attribute values to Znuny roles with permissions.