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:
Temporary Auth link
-
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.
SAML
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.
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.
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.
Requirements
In order to enable the authentication strategies available in Carbonio, the following requirements need to be satisfied.
Note
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
ontrue
and2fa_policy
to 1
Note
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 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 example.com, accessible at SP_URL.
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.
sp.entityid
-
https://SP_URL/zx/auth/samlMetadata?domain=example.com
sp.assertion_consumer_service.url
-
https://SP_URL/zx/auth/saml
sp.nameidformat
-
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
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 https://my-saml-provider.org/simplesaml/saml/idp/metadata.php, you can import the configuration using the command:
# carbonio auth saml import example.com URL https://my-saml-provider.org/simplesaml/saml/idp/metadata.php
Note
The URL supplied by the SAML IDP for an unsecured connection may be slight different from the previous one, like in our example.
# carbonio auth saml import example.com 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. 4 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
# carbonio auth saml get example.com 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
{
"sp.entityid":"https://SP_URL/zx/auth/samlMetadata?domain=example.com",
"sp.assertion_consumer_service.url":"https://SP_URL/zx/auth/saml",
"sp.nameidformat":"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
"sp.assertion_consumer_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
"sp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
"sp.single_logout_service.url":"https://SP_URL/?loginOp=logout",
"sp.x509cert":"aabbcc",
"idp.entityid":"https://IDP-URL/simplesamlphp/saml2/idp/metadata.php",
"idp.x509cert":"xxyyzz",
"idp.single_sign_on_service.url":"https://IDP-URL/simplesamlphp/saml2/idp/SSOService.php",
"idp.single_sign_on_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
"idp.single_logout_service.binding":"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
"organization.name":"ACME, INC.",
"organization.displayname":"Example",
"organization.url":"https://www.example.com/",
"security.requested_authncontextcomparison":"exact",
"security.requested_authncontext":"urn:oasis:names:tc:SAML:2.0:ac:classes:urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
"security.signature_algorithm":"http://www.w3.org/2000/09/xmldsig#rsa sha1",
"security.want_nameid_encrypted":"false",
"security.want_assertions_encrypted":"false",
"security.want_assertions_signed":"false","debug":"true",
"security.want_messages_signed":"false",
"security.authnrequest_signed":"false",
"security.want_xml_validation":"true",
"security.logoutrequest_signed":"false"
"security.logoutresponse_signed":"false",
}
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:
# carbonio auth saml import example.com /tmp/saml.json
Hint
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.
Note
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 https://mycompany.okta.com/app/test/app_id/slo/saml.
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.
1{
2 "sp.entityid":"https://SP_URL/zx/auth/samlMetadata?domain=example.com",
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":"https://mycompany.okta.com/app/test/app_id/slo/saml",
8 "sp.x509cert":"aabbcc",
9 "sp.privatekey":"ddeeff",
10
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",
16
17 "organization.name":"ACME, INC.",
18 "organization.displayname":"Example",
19 "organization.url":"https://www.example.com/",
20
21 "security.requested_authncontextcomparison":"exact",
22 "security.requested_authncontext":"urn:oasis:names:tc:SAML:2.0:ac:classes:urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
23 "security.signature_algorithm":"http://www.w3.org/2000/09/xmldsig#rsa sha1",
24 "security.want_nameid_encrypted":"false",
25 "security.want_assertions_encrypted":"false",
26 "security.want_assertions_signed":"false","debug":"true",
27 "security.want_messages_signed":"false",
28 "security.authnrequest_signed":"false",
29 "security.want_xml_validation":"true",
30 "security.logoutrequest_signed":"true"
31 "security.logoutresponse_signed":"true",
32 "security.authnrequest_signed":"true",
33}
Temporary Auth Link
A typical user-management task that an administrator needs to carry out is to allow the first access to the company’s infrastructure to a new colleague or employee.
When 2FA is enabled on the mailstore, a new user can not login immediately, therefore the solution is to provide a temporary link (auth link) that allows the user to access and configure 2FA.
Administrators can generate a auth link easily from the Administration GUI:
In the user’s General Information section, in box called Temporary link, click the Create a temporary link button
A URL link will be shown in an overlay window and can be copied by clicking on the accompanying button
The link can then be sent to the new user
The user must access the mailbox within 12 hours before the link expires
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.