Carbonio's Authorship

Carbonio Auth is a Carbonio component that impacts the process of accessing a Carbonio instance beginning with the Login Page, including the access mode. The access mask varies depending on the authentication backends specified, allowing the user to give their credentials via any of the backends. This is reflected in the Carbonio Auth for users as well.

Carbonio Auth allows you to handle all of Carbonio’s Authentication Strategies (user/pwd, SAML, 2FA, MobilePwd, QrCode) and Service Authorizations.

This section is broken into three major sections, which are ordered as follows. Immediately below is a description of all supported authentication methods; the next two sections are dedicated to administration tasks, which require privileged access and are mostly performed via the CLI, and everyday tasks, which can be performed by both administrators and users via the Web GUI.

Methods of Authentication Supported

Carbonio Auth is compatible with the following backends:

Temporary Authorization Link
Credential management through self-service
Mobile password management
Application password
Integration of SAML
2FA (using an OTP token) authentication
CLI Credential Management

Self Service Credentials Management

SAML

Two Factor Authentication

Self Service Credentials Management

SAML

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 Administrators

This section is for administrators and the tasks they may perform to administer and maintain Carbonio Auth. Administrators may discover the prerequisites for the various authentication methods, installation instructions, and credential management here.

Requirements

The following prerequisites must be met in order to activate the authentication schemes offered in Carbonio.

Note

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

QR Code Requirements

2FA Requirements

SAML Requirements

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

Note

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

SAML Requirements

SAML configuration

Configuring SAML To link a SAML application with Carbonio, you must setup the SAML IDP (IDentity Provider) using the SAML SP data. In our example situation, we wish to add SAML authentication to the domain example.com, which can be accessed through the SP_URL.

Automatically Import SAML Configuration

The SAML IDP gives a URL where you may obtain the configuration; if this URL is https://my-saml-provider.org/simplesaml/saml/idp/metadata.php, you can import the configuration with the command:

zextras$ 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.

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

You are now finished! On the login screen, you can see the LOGIN SAML SAML button.

You will be sent to the SAML IDP login page after clicking it.

Manually Import SAML Configuration

If you need to manually change the SAML settings, follow this four-step process. To summarise, you must export the default SAML settings, edit them, and then save and import them again.

Step 1. Export the default SAML settings

In order to export the default SAML setting, use

zextras$ 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:

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 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.

Set up SAML Logout

Some SAML IDP providers demand that the logout procedure be signed as well. If you have previously setup SAML, you may use the same steps mentioned in the previous section: export the configuration, edit it, and then import it again.

By altering the configuration file saml.json, we can add signed logout to the settings used in the previous section.

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

To begin, set up the SAML IDP logout service URL (line 7, sp.single_logout_service.url). Because we are using Okta as an example SAML IDP provider, the URL will be something like https://mycompany.okta.com/app/test/app_id/slo/saml.

Then, configure the service provider’s certificate, sp.x509cert (line 8), which should be there previously.

You should be finished at this point, and you may import the changed configuration file.

However, if the SAMP IDP requires that the requests be signed, or if you need to sign the requests for security reasons, please do these further steps.

Make a fresh X509 certificate and enrol it in the SAML IDP. To create one using openssl, execute a command identical to the one below. openssl
```
# openssl req -x509 -sha256 -nodes -days 365  \
-newkey rsa:2048 -keyout privateKey.key -out certificate.crt
```
Add the certificate as sp.x509cert and the private key as sp.privatekey to the configuration file (lines 8 and 9).
Set security by enabling signature creation.line 30: set logoutrequest_signed to true
By configuring security, you may also enable the signature for the login request.line 32: set authn request_signed to to true

saml.json file with signed logout and request

{
 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.signature_algorithm":"http://www.w3.org/2000/09/xmldsig#rsa 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",
32}

Using SAML, you may gain access to a service.

Once SAML authentication has been correctly established on both the SP and IDP sides, multiple modalities can be used to access a Carbonio resource:

Log in to the IDP site and navigate to the resource you wish to use.
Navigate to the service’s web page and click the SAML LOGIN button, which is located near the login and password boxes.
Note
The label on the button might slight differ, depending on IPD and configuration.
Use the direct URL to the service’s SAML authentication. For example, if you have a Carbonio installation (the Service) at mail.example.com and are already connected to the IDP, you may access the mailbox by using the URL https://mail.example.com/zx/auth/startSamlWorkflow?redirectUrl=https://mail.example.com/carbonio/mails.
Hint
By replacing the URL after the redirectUrl it is possible to allow direct access to other Carbonio components, for example: https://mail.example.com/zx/auth/startSamlWorkflow?redirectUrl=https://mail.example.com/carbonio/files will open the Carbonio Files component.

Configure SAML on Azure as an example

We configure SAML on an Azure portal (the Identity Provider, IDP) to give SSO access to a Carbonio installation (the Service Provider, SP) in this section. This approach necessitates first configuring the Azure portal with a few settings from the Carbonio installation, and then configuring Carbonio to utilise the Azure portal as the 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.

Value	Option
Identifier (Entity ID)	`https://carbonio-hostname/zx/auth/samlMetadata?domain=carbonio-domain`
Reply URL	`https://carbonio-hostname/zx/auth/saml/?domain=carbonio-domain`
Sign on URL	You can leave this empty
Relay State	`https://carbonio-hostname/`
Logout URL	`https://carbonio-hostname/zx/auth/logout`

Next, in Attributes & Claims, configure

Value	Option
Unique User Identifier	`user.mail`

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.

Note

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

The options to configure are these four:

idp.entityid using Azure_AD_ID

zextras$ carbonio admin saml update example.com \
idp.entityid Azure_AD_ID

idp.x509cert using the path to the uploaded SAML_cert

zextras$ carbonio admin saml update example.com \
idp.x509cert SAML_cert

idp.single_sign_on_service.url using Azure_login_URL

zextras$ carbonio admin saml update example.com \
idp.single_sign_on_service.url Azure_login_URL

idp.single_logout_service.url using Azure_logout_URL

zextras$ carbonio admin saml update example.com \
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

Temporary Auth Link

A common user-management activity that an administrator must perform is granting a new colleague or employee the initial access to the company’s infrastructure.

Because a new user cannot login instantly when 2FA is set on the mailstore, the answer is to issue a temporary link (auth link) that allows the user to access and configure 2FA.

Administrators may easily produce an authentication link using the Administration GUI:

Click the Create a temporary link button in the user’s General Information section, in the box labelled Temporary link.
An overlay window will appear with a URL link that may be copied by clicking on the accompanying button.
The link may then be forwarded to the new user.
Before the link expires, the user must access the inbox within 12 hours.

Corner Cases of 2FA

2FA is a common approach for allowing users to securely login to an infrastructure using a temporary token (often in the form of a QR code) in addition to the regular user/password combination.

However, there are a few situations in which 2FA cannot be used: Consider a domain or mailstore with 2FA enabled, but an application that wants or has to utilise the SMTP service: the application would not operate since SMTP does not support 2FA.

To avoid situations like these, which may include any service or protocol that does not allow 2FA (such as the previously mentioned SMTP or SOAP), an Administrator can provide proper credentials that can be used by the application to operate successfully on Carbonio.

Management of Credentials

A credential is anything that permits access to one of Carbonio’s services or modules.

Carbonio Auth’s Credential Management solution enables the creation of unique passwords for various services such as EAS devices, Mobile Applications (such as Carbonio Chats and Carbonio Files), and IMAP/SMTP.

It is also feasible to share access to a service with other coworkers, team members, or even third-party individuals by simply generating a new authentication mechanism (e.g., a QR code for mobile access) for the service and not sharing the password. When the access for these people is no longer required, just delete the authentication methods to withdraw the access.

This also implies, as an added benefit, that users may pick who can use the same services they use, enabling a high degree of granularity at the user level.

The remainder of this section demonstrates a few typical and significant actions that an administrator can perform, followed by a few examples.

Warning

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 Provided

Custom passwords may be created or updated using Zextras Auth for the following services:

EAS	Mobile Password
WebUI	Zextras Auth Login Page
WebAdminUI	Admin Console
MobileApp	Zextras Mobile Apps
Dav	Zextras LDAP Address Book
SMTP	SMTP Authentication
IMAP	IMAP Authentication
POP3	POP3 Authentication

Administrators can mix these services to create a variety of simple to complicated situations, such as:

Only WebAccess should be enabled.
allow IMAP in the absence of SMTP
Only allow IMAP/SMTP for managed clients (pre-setup without a user).
Create SMTP passwords that are not enabled for Web/Soap/Imap access in order to be utilised for automation or other 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 john@example.com [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 john@example.com

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 john@example.com [param VALUE[,VALUE]]

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

Credential Fr2jM updated

        values
                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 john@example.com password_id

Hint

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

Examples

In this part, we will provide a few instances.

Make a password and a label for user john@example.com, who will be able to access service EAS (mobile password).
```
zextras$ carbonio auth credential add john@example.com password 'easpass' label "Smartphone" service eas
Credential correctly added

list
   generated 0
   created 1620892109473
   label Smartphone
   id aKcLK
   services EAS
   hash 6Fs6knbW1+fJmWMB1nKoCgLFPy+IGsuZGtmkW0NzV4A=
   enabled true
   algorithm SHA256
text_data
   auth_method password
   password easpass
   user john@example.com
```
- generated – if the credential was generated at random or not, 0 indicates true and 1 means false
- created – the time of creation
- label – a label that can be used to recall the purpose or user of the credentials.
- id – the unique ID required to alter or update the credentials. To avoid confusion, it is referred to as password_id in the instructions.
- services – services to which access is granted
- hash – the credential that has been hashed
- enabled – whether or not the credential may be used.
- algorithm – the hashing algorithm that is employed
- password – the password that was issued or created at random. As previously stated, the administrator can only view a user’s password on this instance.

Make a password for jane@example.com that will only be used for Web Access (both ClassicUI and Zextras Login Page).

zextras$ carbonio auth credential add jane@example.com password \
'SecretPassword!' label "Web access" service WebUI

Make a password for alice@example.com that will only be used for IMAP and POP3 downloads (no SMTP).

zextras$ carbonio auth credential add alice@example.com password \
'LocalClient' service imap,pop3

Make a password for bob@example.com/SMTP_Service_Credential to allow SMTP for an external client.

zextras$ carbonio auth credential add bob@example.com password \
'SMTP_Service_Credential' service smtp

An crucial argument is qrcode, which is used to generate a new qrcode, for usage by mobile devices if QR code support is enabled. When used with the --json option, it will also display the QR code’s content. Here’s an example:
```
zextras$ carbonio auth credential add charles@example.com password \
'SMTP_Service_Credential' qrcode true service smtp
```

Carbonio’s Authorship

Zextras Carbonio 23.6.0

INSTALL

CARBONIO INSTALLATION

Security

ADMIN BY GUI

ADMIN BY CLI

Administration Tasks

Carbonio Backup

Backup and Restore Stratergies

Advanced Backup Methods

Carbonio Mobile

Carbonio Storages

VideoServer Carbonio

Customisations

Carbonio Mesh

USE

The Carbonio User Manuals

APPs for Mobile

DEVELOP

Carbonio Community Edition

RELEASE

INSTALL

Carbonio CE Installation

Web Interface Access

Security

ADMIN BY GUI

Domains

Suite for Zimbra