Authentication#

This section guides you in the configuration of an authentication mechanism from CLI. To see which are the available alternatives, check Section Authentication Methods, where you can also find references to the corresponding Carbonio Admin Panel procedures to configure authentication mechanisms and enforce them with 2FA or SAML.

Local LDAP#

The default authentication method is local LDAP. This method does not require any specific configuration other than the installation of the Mesh and Directory Role according to the procedure described in the documentation.

External LDAP#

To illustrate how an external LDAP source works in Carbonio, we build on the following scenario.

Scenario

This scenario defines a few values that are used for the connection to an external LDAP server. Adapt them according to your needs!

  • Define on Carbonio the domain authentication.example.com

  • On an external LDAP server, located at 172.24.0.155, a domain called ldapexternal.local exists

    Note

    This external source can also be another Carbonio.

  • On the external LDAP server a dedicated admin user exists, that will be used for the LDAP connection (for example service.ldap@ldapexternal.local with password astrongpwd)

  • The LDAP class that stores the users and their password is called uid

Our goal is to have the authentication.example.com domain users authenticate with the passwords of the domain accounts ldapexternal.local defined on the external ldap server

On Carbonio, set up the authentication.example.com domain for authentication on the external LDAP using the command below. Remember to change the values in the scenario with the actual values of your infrastructure!

zextras$ carbonio prov md authentication.example.com \
zimbraAuthLdapSearchBase "ou=people,dc=ldapexternal,dc=local" \
zimbraAuthLdapSearchBindDn \
"uid=service.ldap,ou=people,dc=ldapexternal,dc=local" \
zimbraAuthLdapSearchBindPassword "astrongpwd" \
zimbraAuthLdapSearchFilter "uid=%u" zimbraAuthLdapURL \
"ldap://172.24.0.10:389"

Create three test accounts on the external LDAP domain with username and password:

user1@ldapexternal.local password1
user2@ldapexternal.local password2
user3@ldapexternal.local password3

Finally, we also create 3 accounts on Carbonio

zextras$ carbonio prov ca user1@authentication.example.com ""
zextras$ carbonio prov ca user2@authentication.example.com ""
zextras$ carbonio prov ca user3@authentication.example.com ""

Warning

Do not provide any passwords in these commands!

If all the steps have been performed correctly, any of the three accounts can login to Carbonio using the passwords defined on the respective users of the external LDAP server.

See also

You can carry out the same procedure from the Carbonio Admin Panel, please refer to Admin Panel’s Section External LDAP.

External Active Directory#

To illustrate how an Active Directory source works in Carbonio, we build on the following scenario.

Scenario

This scenario defines a few values that are used for the connection to an external AD server. Adapt them according to your needs!

  • Define on Carbonio the domain ad-auth.example.com

  • On an external AD server, located at 172.24.0.100 a domain called external_ad.com exists

    Note

    This external source can also be another Carbonio.

  • On the external AD server a dedicated user exists, that will be used for the AD connection (for example service.ad@external_ad.com with password very_strong_pass!)

Our goal is to have the ad-auth.example.com domain users authenticate with the passwords of the domain accounts external_ad.com defined on the external ldap server

On Carbonio, set up the ad-auth.example.com domain for authentication on the external LDAP using the command below. Remember to change the values in the scenario with the actual values of your infrastructure!

zextras$ carbonio prov md ad-auth.example.com zimbraAuthLdapSearchBase DC=external_ad,DC=com
zextras$ carbonio prov md ad-auth.example.com zimbraAuthLdapSearchFilter '(|(userprincipalname=%u@external_ad.com)(samaccountname=%u))'
zextras$ carbonio prov md ad-auth.example.com zimbraAuthLdapURL ldap://172.24.0.100:3268
zextras$ carbonio prov md ad-auth.example.com zimbraAuthLdapSearchBindDn service.ad@external_ad.com
zextras$ carbonio prov md ad-auth.example.com zimbraAuthLdapSearchBindPassword 'very_strong_pass!'

Create three test accounts on the external AD domain with username and password:

user1@external_ad.com password1
user2@external_ad.com password2
user3@external_ad.com password3

Finally, we also create 3 accounts on Carbonio

zextras$ carbonio prov ca user1@authentication.example.com ""
zextras$ carbonio prov ca user2@authentication.example.com ""
zextras$ carbonio prov ca user3@authentication.example.com ""

Warning

Do not provide any passwords in these commands!

If all the steps have been performed correctly, any of the three accounts can login to Carbonio using the passwords defined on the respective users of the external AD server.

See also

You can carry out the same procedure from the Carbonio Admin Panel, please refer to Section External AD.

Automatic User Provisioning with AD#

The purpose of this section is to set up Carbonio to poll an existing external LDAP or AD server, collect the existing users from there and create account with the same username on Carbonio. Once the feature has been configured, every user that exists on the LDAP or AD will be able to login directly to Carbonio.

Scenario#

The scenario we present here consists of an Active Directory Server with the following configuration.

  • Network IP address is 128.24.0.50.

  • The users that will be able to login to Carbonio belong to the test247 group.

  • The test247 group belongs to the zextraslab.ad domain.

  • There is an administrative user with credentials

    • AdminBindDn: CN=Auto Provisioning,CN=Users,DC=zextraslab,DC=ad

    • BindPassword: a_very_stron_pass!

Moreover, for the set up, we need also the following configuration option.

  • BindDn: autoprovisioning@zextraslab.ad

  • A domain on which to bind in the form of SearchBase: DC=zextraslab, DC=ad

  • A correct search filter: CN=test247,CN=Users,DC=zextraslab,DC=ad. By using this filter, all user in AD’s grou

Additionally, on Carbonio we will use domain test.auth for the purpose of authenticating users and we will set a time interval of 1 minute, called provisioning polling interval, used to synchronise users in Carbonio and in the external AD.

Procedure#

To configure auto provisioning, follow the procedure in this section; to complete it successfully, remember that all the commands below must be run as the zextras user on a Node featuring the Mailstore & Provisioning Role.

Hint

Make sure that all relevant information are enclosed in quotes, to prevent any issue with non-escaped characters.

We start by defining the domain used for authentication.

zextras$ carbonio prov cd test.auth

Now, configure the AD auto provisioning.

zextras$ carbonio prov md test.auth zimbraAutoProvAccountNameMap samAccountName
zextras$ carbonio prov md test.auth zimbraAutoProvAttrMap description=description
zextras$ carbonio prov md test.auth zimbraAutoProvAttrMap displayName=displayName
zextras$ carbonio prov md test.auth zimbraAutoProvAttrMap givenName=givenName
zextras$ carbonio prov md test.auth zimbraAutoProvAttrMap cn=cn
zextras$ carbonio prov md test.auth zimbraAutoProvAttrMap sn=sn
zextras$ carbonio prov md test.auth zimbraAutoProvAuthMech LDAP
zextras$ carbonio prov md test.auth zimbraAutoProvBatchSize 4000

Configure the AD server from which to fetch the usersm using the data provided in the Scenario above.

zextras$ carbonio prov md test.auth zimbraAutoProvLdapAdminBindDn \
"CN=Auto Provisioning,CN=Users,DC=zextraslab,DC=ad"
zextras$ carbonio prov md test.auth zimbraAutoProvLdapAdminBindPassword 'a_very_stron_pass!'
zextras$ carbonio prov md test.auth zimbraAutoProvLdapBindDn auto provisioning@zextraslab.ad
zextras$ carbonio prov md test.auth zimbraAutoProvLdapSearchBase DC=zextraslab,DC=ad

Define the correct search filter, so all accounts in the group test247 will be fetched.

zextras$ carbonio prov md test.auth zimbraAutoProvLdapSearchFilter \
"(memberOf=CN=test247,CN=Users,DC=zextraslab,DC=ad)"

Enter the IP address or hostname of the ad server.

zextras$ carbonio prov md test.auth zimbraAutoProvLdapURL \
ldap://128.24.0.50:3268

Set the operation mode to EAGER.

zextras$ carbonio prov md test.auth zimbraAutoProvMode EAGER

Finally, set the provisioning polling interval to 1 minute for domain test.auth.

zextras$ carbonio prov ms $(zmhostname) \
zimbraAutoProvPollingInterval "1m" +zimbraAutoProvScheduledDomains \
 "test.auth"

At this point, configuration of auto provisioning is complete. You should be able to find in the /opt/zextras/log/mailbox.log file messages that show activities relates to auto provisioning, for example:

2024-06-26 15:59:13,386 INFO  [AutoProvision] [] autoprov - Auto provisioning accounts on domain test.auth
2024-06-26 15:59:13,406 INFO  [AutoProvision] [] autoprov - 3 external LDAP entries returned as search result
2024-06-26 15:59:13,406 INFO  [AutoProvision] [] autoprov - auto creating account in EAGER mode: john@test.auth, dn="CN=paolo rossi,CN=Users,DC=zextraslab,DC=ad"
2024-06-26 15:59:13,637 INFO  [AutoProvision] [] autoprov - auto provisioned account: john@test.auth
2024-06-26 15:59:13,637 INFO  [AutoProvision] [] autoprov - auto creating account in EAGER mode: jane@test.auth, dn="CN=test01,CN=Users,DC=zextraslab,DC=ad"
2024-06-26 15:59:13,639 INFO  [AutoProvision] [] autoprov - auto provisioned account: jane@test.auth
2024-06-26 15:59:13,639 INFO  [AutoProvision] [] autoprov - auto creating account in EAGER mode: alice@test.auth, dn="CN=mario,CN=Users,DC=zextraslab,DC=ad"
2024-06-26 15:59:13,641 INFO  [AutoProvision] [] autoprov - auto provisioned account: alice@test.auth
2024-06-26 15:59:13,641 INFO  [AutoProvision] [] autoprov - Auto Provisioning has finished for now, setting last polled timestamp: 20240626155913.404Z
2024-06-26 15:59:13,642 INFO  [AutoProvision] [] autoprov - Sleeping for 1000 milliseconds

If you see messages similar to these, which show that accounts are fetched from the AD server, then provisioning was successfully configured and you can proceed with the last point: configure Authentication using an External Active Directory.

Troubleshooting#

In case you do not see any account being fetched, please double check that all the data you supplied is correct, especially credentials of AD’s administrative user, IP or hostname, and ports.