Carbonio Auth#

Carbonio Auth is the Carbonio component that influences the process of accessing a Carbonio instance from the Login Page onwards, including the access modality. Depending on the authentication backends configured, the access mask changes, to allow user to provide their credentials using any of the backends. This also is reflected in the Carbonio Auth for users.

Carbonio Auth allows to manage all the Authentication Strategies (user/pwd, SAML, 2FA, MobilePwd, QrCode) and Service Authorizations supported by Carbonio.

This section is divided in three main parts and organised as follows. Immediately below, you can find the description of all supported authentication methods; the next two sections are dedicated to administration tasks, which require privileged access and are mostly carried out from the CLI, and everyday’s task, which can be carried out from the Web GUI by both administrators and users.

Supported Authentication Methods#

Carbonio Auth supports the following backends:

  • Self service credentials management

    • Mobile password management

    • Application password

  • SAML integration

  • 2FA Authentication (using OTP token)

  • Credential Management by CLI

Self Service Credentials Management

Self-service credential management allows every user to create new passwords and QR codes for third-parties—​for example team members, personal assistants—​accessing her/his email account and Carbonio Applications from mobile devices.

QR Codes in particular can be used to access Mobile Apps, currently Carbonio Chats and Carbonio Files.

More information and step by step guidelines can be found in Section Carbonio Auth for users.

Two Factor Authentication

Two Factor Authentication (usually spelled as 2FA) adds a security layer to the login phase, making unwanted accesses less likely to take place. In Carbonio, this additional layer is given by an One Time Password (OTP), which can be read as a QR code on mobile devices.

2FA applies only to those protocols or apps supporting it, for example HTTP and HTTPS but not to IMAP and SMTP, and can be configured at either device, IP, or IP range level, by means of the trusted_device or trusted_ip parameter. When an IP or IP range is trusted, 2FA will be successful for any login originating from there, while the trusted_device requires that the same browser or app be used, otherwise it will fail: if a 2FA login is carried out on Chrome, accessing the same page with Firefox will require a new login.

In order to use the OTP, a domain must be configured (see Section Requirements) by the site admin, while users can configure it from their Auth settings.


The Security Assertion Markup Language (SAML) is an XML-based open standard data format for exchanging authentication information. It enables web-based authentication and authorization scenarios including cross-domain Single Sign-On (SSO), which allows the use of the same credentials to access different applications.

SAML implementation in Carbonio relies on an external IDentity Provider (IDP), to which a user identifies; the IDP then passes authorization credentials to a service providers (SP). SAML authentication is the process of verifying the user’s identity and credentials. In Carbonio, SAML requires little configuration, because an administrator can generate the SAML configuration by importing SAML metadata from the ISP. Each domain can have a different SAML endpoint and both SDP and IDP SAML authentication is supported.

These are the key concepts of SAML authentication:

Service Provider

(SP) is the entity providing the service.

Identity Provider

(IdP) is the entity providing the identities.

SAML Request

is generated by the Service Provider to “request” an authentication.

SAML Response

is generated by the Identity Provider and contains the assertion of the authenticated user.

Moreover, the Assertion Consumer Service (ACS) endpoint is a location to which the SSO tokens are sent, according to partner requirements.

Directions on how to configure SAML and integrate other applications in Carbonio is described in Section Setting up SAML Configuration.

Carbonio Auth for Admins#

This section is dedicated to administrators and the activities they can carry out to manage and maintain Carbonio Auth. Here administrators can find the requirements for the various authentication methods, then the installation instructions and finally the credential management.


In order to enable the authentication strategies available in Carbonio, the following requirements need to be satisfied.


It is not necessary to enable all of them, simply configure the one you need in your infrastructure.

QR Code Requirements

The QR Code Application Password feature requires the following properties to be set at domain level in order to be functional:

  • zimbraPublicServiceHostname

  • zimbraPublicServicePort

  • zimbraPublicServiceProtocol

Should one or more of the properties be unset, a notification will be delivered to the Admin reporting the affected domains and their missing properties.

2FA Requirements

To enable 2FA it is necessary, for all services:

  • to define a trusted ip range

  • to set the ip_can_change on true and 2fa_policy to 1


2FA is not compatible with other mechanisms such as LDAP, AD, or kerberos5

SAML Requirements

There is no special requirement to enable SAML, besides having a SAML IDP Provider.

Setting up Policy Management for 2FA#

Carbonio Auth introduced the second factor as part of the service authentication strategy. At domain or at global level, each service can either:

  • be enabled or disabled for the 2FA

  • have its own Trusted Networks

When enabled, the connection can be established only if the source is trusted, which means that the connection originates either from a trusted network, manually configured by the admin for the service, or from a previously trusted IP or device, depending on the 2FA policy configured for the service.

If none of the above conditions holds, the service must ask for the OTP, used as the second factor. If the service does not support the second factor, or is not able to interact with the user for it, the authentication process fails. For example, IMAP is a service not supporting OTP and therefore 2FA can not be used with it. Otherwise, when the user provides a valid OTP, the current user’s device and IP are stored in the Trusted Device table

Moreover, depending on the service policy, the connection should be valid even if the IP has been trusted by another service.

2FA Policy Management is a rather advanced technique which avoids the use of OTP in all cases when an authentication request is received from a device that is already in the Trusted Networks or Trusted Devices tables.

To set up and manage 2FA Policies, several CLI commands are available.

Display policies

The command carbonio auth policy list returns the list of 2FA by domain, with option to filter specific services.


zextras$ carbonio auth policy list domain service EAS

Shows 2FA setting for domain and for service EAS.


zextras$ carbonio auth policy list global

Display for which services 2FA can be enabled. As a bonus, the output contains a lists of all supporter services, which fall in:

  • standard protocols or technologies (CLI, DAV, EAS, IMAP, POP3, and SMTP)

  • related to Carbonio components (MobileApp, WebAdminUI, WebUI).

Manage policies

The command carbonio auth policy set enables or disables a service and accepts the following three optional parameters:


This attribute allows the server to deny connection requests coming from an IP other than the one used during the authentication. As an example, suppose that authentication was successfully carried out from a device with IP and for any reason the IP of the device changes (e.g., a laptop moved to a different subnet). If ip_can_change is set to true, then the device is still authenticated and connections are allowed, otherwise, if ip_can_change is set to false, authentication is invalidated and no connection is allowed for the device until a new authentication.


It defines the Trusted Networks, a set of IP ranges configured for each service (like e.g., DAV, EAS, SMTP, and more). If a connection comes from an IP in the Trusted Networks, the authentication will not require the second factor validation, independently from the policy specified, but users will be authenticated with username and password.


This parameter determines how 2FA policies are enforced for each service and takes one of these three integer values:

  • 0 (no_2fa): 2FA authentication is disabled for the service

  • 1 (ip_2fa): Trust the IP from which the connection starts. All the subsequent logins from the same IP will not require the second factor.

  • 2 (device_2fa): Trust the device from which the connection starts. All the subsequent logins from the same device (that is, same browser or Mobile App) will not require the second factor.

These parameters are supported by all services.

Manage expiration time

Two commands help to check and define the expiration time of trusted devices.


Check the current policy for expiration time, i.e., for how long a device will be considered as trusted. The number of days is returned. The command acts at domain and global level.


zextras$ carbonio auth policy trustedDevice getExpiration domain

Show how many days is the expiration time for


zextras$ carbonio auth policy trustedDevice getExpiration global

Show how many days is the expiration time for the whole infrastructure.


Define the current policy for expiration time, i.e., for how long a device will be considered as trusted. The number of days is required. The command acts at domain and global level.


zextras$ carbonio auth policy trustedDevice setExpiration domain 20

Defines the expiration time for domain to 20 days.

Setting up SAML Configuration#

To integrate a SAML application into Carbonio, you need to configure the SAML IDP (IDentity Provider) using the SAML SP data. In our sample scenario, we want to add SAML authentication to our domain, accessible at SP_URL.

See also

The same tasks can be carried out from the Carbonio Admin Panel, please refer to Section SAML.

The SAML configuration is carried out at an IDP provider, then imported in Carbonio using a dedicated command.

The most important configuration options are the following. You should configure them on the SAML IDP side.







In order to validate against Carbonio, make sure that the Name of the attribute that is used as NameID is set to mailPrimaryAddress.

You can now integrate a SAML application in Carbonio in two ways, either automatic or manual. The following sections describe each method in detail.

Import SAML Configuration Automatically#

The SAML IDP provides a URL from which to download the configuration; assuming that this URL is, you can import the configuration using the command:

zextras$ carbonio auth saml import URL


The URL supplied by the SAML IDP for an unsecured connection may be slight different from the previous one, like in our example.

zextras$ carbonio auth saml import URL https://localidp.local.loc/app/xxxxxxxxxxxxxxx/sso/saml/metadata allow_unsecure true

You are now DONE! You can see the LOGIN SAML button on the login page.


Fig. 9 Login page with enabled SAML.#

By clicking it, you will be redirect to the SAML IDP login page.

Import SAML Configuration Manually#

If you need to manually edit the SAML configuration, you need to follow this 4-step procedure. In a nutshell, you need to export the default SAML settings, modify them, then save and import them back.

Step 1. Export the default SAML settings

In order to export the default SAML setting, use

zextras$ carbonio auth saml get export_to /tmp/saml.json
Step 2. Modify /tmp/saml.json

Open the resulting file /tmp/saml.json in any editor and modify the requested attributes:

  • entityid

  • assertion_consumer_service.url

  • nameidformat

Step 3. Check modified /tmp/saml.json

The /tmp/saml.json` file should look similar to this one:

Simple saml.json file


  "":"ACME, INC.",

  "security.signature_algorithm":" sha1",

Values appearing in the above code excerpt are taken from the example in the previous section. Certificates must be valid, they are omitted for clarity.

Step 4. Save the changes

The final step is to save the changes made to the file and import it into Carbonio using the command:

zextras$ carbonio auth saml import file /tmp/saml.json


It is also possible to view or edit single attributes by using the carbonio auth saml get and carbonio auth saml set command options.

Configure SAML Logout#

Some SAML IDP provider require that also the logout procedure be signed. In case you had already configured SAML, you can proceed in a similar fashion as described in the previous section: export the configuration, modify it, then import it again.

Here we show how to add signed logout to the configuration used in the previous section, by modifying the configuration file saml.json presented there.


We also report below the configuration file presented in the previous section, modified according to the procedure described below and with the lines interested by the changes highlighted. The line numbers are those

First, you need to configure the SAML IDP logout service URL (line 7, sp.single_logout_service.url). We use Okta as example SAML IDP provider, so the URL will be similar to

Then, configure also the service provider’s certificate, sp.x509cert (line 8), which however should be already present.

At this point, you should be done and you can import the modified configuration file.

However, in case the SAMP IDP requires that also the requests be signed, or in case to sign the requests for security reasons, please follow these additional steps.

  • Create a new X509 certificate and register it to the SAML IDP. You can use a command similar to the following one to create one with openssl

    # openssl req -x509 -sha256 -nodes -days 365  \
    -newkey rsa:2048 -keyout privateKey.key -out certificate.crt
  • Add to the configuration file the certificate as sp.x509cert and the private key as sp.privatekey (lines 8 and 9 respectively)

  • Enable the signature generation, that is, set security.logoutrequest_signed to true (line 30)

  • You can also optionally enable the signature for the login request, by setting security.authnrequest_signed to true (line 32)

saml.json file with signed logout and requests.
 2  "sp.entityid":"https://SP_URL/zx/auth/samlMetadata?",
 3  "sp.assertion_consumer_service.url":"https://SP_URL/zx/auth/saml",
 4  "sp.nameidformat":"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
 5  "sp.assertion_consumer_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
 6  "sp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
 7  "sp.single_logout_service.url":"",
 8  "sp.x509cert":"aabbcc",
 9  "sp.privatekey":"ddeeff",
11  "idp.entityid":"https://IDP-URL/simplesamlphp/saml2/idp/metadata.php",
12  "idp.x509cert":"xxyyzz",
13  "idp.single_sign_on_service.url":"https://IDP-URL/simplesamlphp/saml2/idp/SSOService.php",
14  "idp.single_sign_on_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
15  "idp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
17  "":"ACME, INC.",
18  "organization.displayname":"Example",
19  "organization.url":"",
21  "security.requested_authncontextcomparison":"exact",
22  "security.signature_algorithm":" sha1",
23  "security.want_nameid_encrypted":"false",
24  "security.want_assertions_encrypted":"false",
25  "security.want_assertions_signed":"false","debug":"true",
26  "security.want_messages_signed":"false",
27  "security.authnrequest_signed":"false",
28  "security.want_xml_validation":"true",
29  "security.logoutrequest_signed":"true"
30  "security.logoutresponse_signed":"true",
31  "security.authnrequest_signed":"true",

Access a Service Using SAML#

Once SAML authentication has been properly configured on both the SP and IDP sides, it is possible to access to a Carbonio resource using different modalities:

  1. Login to the IDP portal and click on the resource you want to access.

  2. Directly go to the service’s web page and click the SAML LOGIN button that appears near the username and password fields


    The label on the button might slight differ, depending on IPD and configuration.

  3. Use the direct link to the SAML authentication of the service. For example, given a Carbonio installation (the Service) located at, and provided you are already authenticated to the IDP, it is possible to access the mailbox by using the link


    By replacing the URL after the redirectUrl it is possible to allow direct access to other Carbonio components, for example: will open the Carbonio Files component.

Example: Configure SAML on Azure#

In this section we configure SAML on an Azure portal (the Identity Provider, IDP) to allow SSO access to a Carbonio installation (the Service Provider, SP). This procedure requires to configure first the Azure portal using a few values from Carbonio installation, then configure Carbonio to use the Azure portal as SAML provider.

Configure Azure Portal

On the Azure Portal you need to configure the following values on Basic SAML Configuration. From your Carbonio installation you need to know the carbonio-hostname and the carbonio-domain.



Identifier (Entity ID)


Reply URL


Sign on URL

You can leave this empty

Relay State


Logout URL


Next, in Attributes & Claims, configure



Unique User Identifier


As an optional step, you can upload an X.509 CSR Certificate in case you want to enable certificate signing.

The configuration on the Azure side is now complete. From here, you need the following data for Carbonio’s configuration.

  • Azure_AD_ID the identifier of the Azure AD

  • SAML_cert the certificate used for the connection between azure and Carbonio

  • Azure_login_URL the login URL of the Azure Portal

  • Azure_logout_URL the logout URL of the Azure Portal

Configure Carbonio

The configuration on the Carbonio side is currently possible from the CLI only. Therefore, copy the SAML_cert on the Carbonio installation, then log in to it as the zextras user. The SAML configuration is carried out by means of the carbonio admin saml update command.


to keep consistency with the rest of the documentation, we will use in the commands the value for the carbonio-domain in the commands listed below.

The options to configure are these four:

  1. idp.entityid using Azure_AD_ID

    zextras$ carbonio admin saml update \
    idp.entityid Azure_AD_ID
  2. idp.x509cert using the path to the uploaded SAML_cert

    zextras$ carbonio admin saml update \
    idp.x509cert SAML_cert
  3. idp.single_sign_on_service.url using Azure_login_URL

    zextras$ carbonio admin saml update \
    idp.single_sign_on_service.url Azure_login_URL
  4. idp.single_logout_service.url using Azure_logout_URL

    zextras$ carbonio admin saml update \
    idp.single_logout_service.url Azure_logout_URL

As an optional step to enable certificate signing, you need the private key that refers to the X.509 certificate and configure the following variables, similarly to what has been done above.

  • sp.x509cert is the path to SAML_cert

  • sp.privatekey is the private key you have generated with sp.x509cert

  • security.logoutresponse_signed , security.logoutrequest_signed, and security.authnrequest_signed must all be set to true

Corner Cases of 2FA#

2FA is a popular mechanism to allow users a secure login to an infrastructure, based on a temporary token (usually in the form of a QR code) besides the usual user/password combination.

There are however a few cases in which 2FA can not be used: consider for example a domain or mailstore on which 2FA is enabled, but there is an application that wants or needs to use the SMTP service: since SMTP does not support 2FA, the application would not work.

To avoid situation like this, which may involve any service or protocol not supporting 2FA (like, e.g., the above mentioned SMTP or SOAP), on Carbonio, an Administrator can create suitable credentials that can be used by the application to operate correctly.

Credential Management#

Within Carbonio, a credential is something that allows access to one of its services or modules.

Carbonio Auth’s Credential Management system allows to create dedicated passwords to access different services such as EAS devices, Mobile Applications (e.g., Carbonio Chats and Carbonio Files), or IMAP/SMTP.

It is also possible to share the access to a service with other colleagues, team members, or even third-party persons by simply creating a new authentication means (e.g., a QR code for mobile access) for the service, without the need to share the password. Once the access for these persons is not needed anymore, it suffices to delete the authentication means to revoke the access.

This also implies, as an additional advantage, that users are able to decide who can have access to the same services they use, providing a high level of granularity also at user level.

In the remainder of this section, we show a few common and relevant tasks that an administrator can carry out, followed by a couple of examples.


While Administrators can set the password of any user account on the command line when they create the credentials, In no other circumstances they have access to the password, not even for changing it.

Services Supported#

Zextras Auth allows to create or update custom passwords for the following services:


Mobile Password


Zextras Auth Login Page


Admin Console


Zextras Mobile Apps


Zextras LDAP Address Book


SMTP Authentication


IMAP Authentication


POP3 Authentication

Administrators can combine these services to set up multiple basic to complex scenarios, including:

  • enable only WebAccess

  • enable IMAP without SMTP

  • enable IMAP/SMTP only for managed client (pre-setup without the user)

  • create SMTP password that are not enabled for Web/Soap/Imap access, to be used for automation or external services

Add New Credential

New credentials for each of the active authentication services can be added using the carbonio auth credential add command:

zextras$ carbonio auth credential add [param VALUE[,VALUE]]
List Existing Credential

System Administrators can view an extended list of all credentials active on an account by using the carbonio auth credential list command:

zextras$ carbonio auth credential list

This command gives no access to the user’s passwords: they are never shown.

The output of this command can be quite long, because it shows all the credentials configured for an account, including a number of additional information.

Edit a Credential

While usually the credential itself cannot be edited, the System Administrator can update its label and properties, including the services for which it is valid, by using the carbonio auth credential update command:

zextras$ carbonio auth credential update [param VALUE[,VALUE]]

The successful credential update will be displayed as output of the previous command, reporting all credential’s properties:

Credential Fr2jM updated

                generated           0
                created             Wed 05 May 2021 at 17:53:38
                label               New Label
                id                  aKcLK
                services            EAS
                hash                +Crk6YcPL7IapCg6xfT6oXWP977uTeZdJTVQDQZd+Io=
                enabled             true
                algorithm           SHA256
Delete a Credential

Credentials can be delete, once at a time using the carbonio auth credential delete command:

zextras$ carbonio auth credential delete password_id


The password_id is shown as id in the carbonio auth credential list command.


In this section we present a few examples

  1. create a password and a label for user who can access service EAS (mobile password).

    zextras$ carbonio auth credential add password 'easpass' label "Smartphone" service eas
    Credential correctly added
       generated 0
       created 1620892109473
       label Smartphone
       id aKcLK
       services EAS
       hash 6Fs6knbW1+fJmWMB1nKoCgLFPy+IGsuZGtmkW0NzV4A=
       enabled true
       algorithm SHA256
       auth_method password
       password easpass
    • generated - whether the credential was randomly generated or not, 0 true and 1 means false

    • created - the creation timestamp

    • label - the label, useful to remember the purpose or user of the credentials

    • id - the unique ID, which is mandatory to edit or update the credentials. It is called password_id in the commands, to prevent misunderstandings.

    • services - the services for which access is allowed

    • hash - the hashed credential itself

    • enabled - whether the credential can be actually used or not

    • algorithm - the hashing algorithm used

    • password - the password assigned or randomly generated. As mentioned, this is the only occasion that the administrator can see a user’s password

  2. Create a password for, that can be used only for Web Access (Zextras Login Page)

    zextras$ carbonio auth credential add password \
    'SecretPassword!' label "Web access" service WebUI
  3. Create a password for that can be used only for IMAP and POP3 download (no SMTP)

    zextras$ carbonio auth credential add password \
    'LocalClient' service imap,pop3
  4. Create a password for can be used to enable SMTP for an external client

    zextras$ carbonio auth credential add password \
    'SMTP_Service_Credential' service smtp
  5. An important parameter is qrcode, to create a new QR code to be used by mobile devices, provided QR code support has been enabled. Used together with the --json switch, it will show the QR code’s payload as well. An example is:

    zextras$ carbonio auth credential add password \
    'SMTP_Service_Credential' qrcode true service smtp