What exactly is Zextras Auth?
Zextras Auth is a Zextras Suite module that affects the process of accessing a Zextras instance beginning with the Login Page, including:
- The mode of access. The access mask varies depending on the authentication backends specified, allowing the user to give their credentials via any of the backends. This is also mirrored in the ZxAuth (Auth Zimlet) for users.
- Customisations. Define the appearance of the login page. A list of configurable things may be found in the special section Custom Login Page.
Zextras Auth allows you to handle all of Zextras’ Authentication Strategies (user/pwd, SAML, 2FA, MobilePwd, QrCode) and Service
This section is broken into three major sections, which are ordered as follows. Immediately below is a description of all supported authentication methods; the following 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. Finally, a reference list of all CLI commands is provided, with links to each command.
Methods of Authentication Supported
Zextras Auth is compatible with the following backends:
- Credential management through self-service
- Password management on mobile devices
- Application security code
- Personalised login page
- Integration of SAML
- OTP token authentication for two-factor authentication
- CLI Credential Management
Management of Self-Service Credentials
Self-service credential management enables each user to generate fresh passwords and QR codes for third-party users who access her/his email account and Zextras Applications via mobile devices, such as team members and personal assistants.
QR Codes, in particular, may be used to gain access to Zextras Apps, which are currently Team and Drive.
More details and step-by-step instructions may be found in Section ZxAuth for users (Auth Zimlet).
Personalised Login Page
All Zextras functionality is accessible upon login through the Zextras login page, which may be personalised in numerous ways, such as adding the company’s logo or other components of the company’s corporate identity.
This functionality is implemented through the CLI and so requires administrator rights; further information and recommendations may be found in the section Custom Login Page.
SAML (Security Assertion Markup Language) SAML (Security Assertion Markup Language) is an XML-based open standard data format for communicating authentication information. It supports web-based authentication and authorization situations like as cross-domain Single Sign-On (SSO), which allows users to use the same credentials to access several apps.
In Zextras, SAML implementation is based on an external IDentity Provider (IDP) that a user identifies with; the IDP then gives authorization credentials to a service provider (SP). The method of authenticating the user’s identity and credentials is known as SAML authentication. SAML requires less configuration in Zextras Suite since an administrator may construct the SAML configuration by importing SAML information from the ISP. Each domain can have its own SAML endpoint, and SDP and IDP SAML authentication are also supported.
The following are the fundamental elements of SAML authentication:
The entity that provides the service is known as the Service Provider (SP).
The entity that provides the identities is known as the Identity Provider (IdP).
The Service Provider generates a SAML Request to “request” authentication.
The Identity Provider generates the SAML Response, which contains the authorised user’s assertion.
Furthermore, the Assertion Consumer Service (ACS) endpoint is a site where SSO tokens are supplied based on partner needs.
Section Setting up SAML Configuration describes how to establish SAML and integrate other apps in Zextras Suite.
Two Factor Authentication (also known as 2FA) adds a security layer to the login step, making it less likely that unauthorised access will occur. This additional layer of Zextras is provided via a One Time Password (OTP), which may be read as a QR code on mobile devices.
When 2FA is enabled on a Zextras domain, an OTP is required to login; supplying merely the username and password will fail. Furthermore, for 2FA to operate effectively, the property zimbraAuthMech must be enabled on the domain.
2FA is only applicable to protocols or apps that enable it, such as HTTP and HTTPS, but not IMAP and SMTP, and may be configured at the device, IP, or IP range level using the trusted_device or trusted_ip parameters. When an IP or IP range is trusted, 2FA will work for any login that originates from that IP or IP range, however the trusted_device needs that the same browser or app be used, otherwise it will fail: if a 2FA login is performed on Chrome, viewing the same page with Firefox will require a new login.
To utilise the OTP, the site admin must setup a domain (see QR Code Requirements), while users can configure it using the Auth Zimlet.
ZxAuth for Administrators
This section is for administrators and the tasks they may perform to administer and maintain Zextras Auth. Administrators may discover the prerequisites for the various authentication methods, as well as installation instructions, on this page. Following that is credential management, with the opportunity to modify the login screen at the conclusion.
Requirements for QR Code Requirements
To be effective, the QR Code Application Password feature requires the following domain-level parameters to be set:
- zimbraPublicServiceHostname
- zimbraPublicServicePort
- zimbraPublicServiceProtocol
If one or more of the attributes are not set, an email will be sent to the administrator informing them of the affected domains and their missing properties.
2FA Prerequisites
To correctly install 2FA, the zimbraAuthMech property must be specified at the domain level:
To activate 2FA, you must also do the following:
- Using the command: ZimbraMailTrustedIp, enter the addresses of all mailboxes and MTAs.
- For all services, a trustworthy IP range must be specified.
- For all services, the ip_can_change property must be set to true, and 2fa_policy must be set to 1.
SAML Prerequisites
Before enabling SAML login, the Zextras Backend processing must be modified since the following header fields are required to assemble the entire URL request: X-Port and Protocol X.
The following files are impacted by this change:
- nginx.conf.web.http.default.template
- nginx.conf.web.http.template
- nginx.conf.web.https.default.template
- nginx.conf.web.https.template
The /zx/ code position should be modified in each of them.
Personalised Login Page
The Auth module allows you to personalise the Login Page as it appears to other users.
The login page may be customised at the domain level in terms of title, logo, background, and favicon.
Activating the Login Page
Set the zimbraWebClientLoginURL and zimbraWebClientLogoutURL configuration keys to allow the Login Page for a domain (example.com). You may accomplish so by entering the following two values into the GUI:
The same thing may be done using the CLI command below, which additionally configures the authentication mechanism (zimbraAuthMech):
Changing the Login Page
The loginPage Auth CLI command may be used to customise the Login Page.
Image File Sizes and Locations
For custom image files used by the Login Page, Zextras Auth provides two options: embedding external image files or hosting them locally. For the logo, background, and favicon, image files can be utilised.
A logo picture should be 320×80 pixels in size. Other sizes are possible, but the logo image may be stretched or scaled, resulting in poor quality. The aspect ratio of 4:1 should be maintained at all times.
While the optimal size for the background image is determined by the resolution of the client’s screen, it is strongly advised to avoid images smaller than the current standard monitor resolutions in order to avoid vertical or horizontal bars being displayed on screens with a higher resolution than the background image.
Title of the Login Page
The login page title may be changed by using the following commands:
- Using zxsuite auth loginPage setTitle global at the global level
- zxsuite auth loginPage setTitle domain at the domain level
Looking at the present setup
The zxsuite auth loginPage getConfig domain command may be used to see the current Login Page settings for a domain:
Configuring Policy Management for 2F
As part of the service authentication approach, Zextras Auth implemented the second factor. Each service, whether at the domain or global level, can either:
- be set to activate or disable 2FA
- possesses its own Trusted Networks
When enabled, the connection can be established only if the source is trusted, which means that the connection comes from a trusted network that the admin has manually configured for the service, or from a previously trusted IP or device, depending on the 2FA policy configured for the service.
If none of the following requirements are met, the service must request the OTP, which will be used as the second factor. The authentication procedure fails if the service does not support the second factor or is unable to interface with the user for it. For example, because IMAP does not allow OTP, 2FA cannot be utilised with it. Otherwise, when a valid OTP is provided by the user, the current user’s device and IP address are saved in the Trusted Device table.
Furthermore, based on the service policy, the connection should be legitimate even if the IP address has already been trusted by another service.
When an authentication request is received from a device that is already in the Trusted Networks or Trusted Devices tables, 2FA Policy Management prevents the usage of OTP in all situations.
Several CLI commands are provided to set up and administer 2FA Policies.
Creating the SAML Configuration
To link a SAML application with Zextras, setup the SAML IDP (IDentity Provider) with Zextras 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.
The SAML setup is completed at an IDP provider before being imported into Zextras Suite using a special command.
The following are the most significant setup choices. They should be configured 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
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress sp.nameidformat
Make sure that the Name of the property used as NameID is set to mailPrimaryAddress in order to validate against Zextras.
In Zextras, you can now integrate a SAML application in two ways: automatically or manually. Each strategy is described in depth in the sections that follow.
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:
You are now finished! On the login screen, you can see the LOGIN 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.
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.
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.
- 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 authnrequest_signed to true
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 Suite 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.
- Use the direct URL to the service’s SAML authentication. For example, if you have a Suite installation (the Service) at mail.example.com and are already connected to the IDP, you may access the mailbox by visiting https://mail.example.com/zx/auth/startSamlWorkflow?redirectUrl=https://mail.example.com/suite/mails.
Temporary Authorization Link
An administrator’s normal user-management role is to grant 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.
Users can utilise ZxAuth (Auth Zimlet).
Zextras Auth has a specific zimlet (see Figure 10) for managing all user-side credentials and functionality, such as account and EAS Mobile Passwords, Mobile App QR Codes, and Two Factor Authentication OTP.
Overview of Zextras Auth Zimlet
The Zextras Auth Zimlet may be found in the Zimbra Web Client’s “Zimlets” section. The Zextras Auth does not require any CLI access from the user.
The establishment of a new credential allows you to grant other people access to your account, including the Zextras Mobile Apps, without having to divulge your personal credentials.
The user can do the following with the zimlet:
- Change the current logged-in user’s password
- Add new credentials using the relevant pages, which may be accessed by selecting Exchange ActiveSync, Mobile Apps, or OTP Authentication.
- Examine the status and other details for any Exchange ActiveSync and Mobile Apps credentials that have been established. Entries in the list in each part indicate the label of the password, its status, the service it is valid for, and its creation date.
- Examine the status and other details for each One Time Password established. Each item includes a description, status, unsuccessful attempts, and the date it was created.
- Control 2FA access. Unless it has been enabled or deactivated at the COS, domain, or global level, each user can decide whether to enforce access via 2FA.
- Delete any credentials that have been generated
The remainder of this section provides an overview of the various options for creating new credentials as well as instructions for adding or deleting them.
Password Reset
To change your password, go to the Auth zimlet and choose Change Password. You must first enter your existing password, then enter it twice more.
Click the blue CHANGE PASSWORD button to save the new password.
EAS Create New Credentials
To generate a new EAS Password, open the Zextras Auth Zimlet and choose Exchange ActiveSync, then NEW AUTHENTICATION +.
In the Authentication description section, add an easy-to-remember identifier for the password.
The new Mobile Password will be presented when you click CREATE PASSWORD.
Finally, copy the password to the clipboard by clicking the COPY PASSWORD button.
To exit the Zextras Auth window, click DONE. The new Mobile Password is now available in the Zextras Auth Zimlet’s Active Passwords list.
Zextras Auth can speed up and manage Zextras Application logins, such as those for the Team Mobile App and Drive Mobile App.
This is accomplished by creating a QR Code that the user can then scan from the App’s login page to log in. The technique is pretty similar to the previous section’s description.
To generate a new QR Code for a Mobile Application, use the Zextras Auth Zimlet and navigate to Mobile Apps, then NEW AUTHENTICATION +.
In the Authentication description, insert an easy-to-remember identifier for the password.
When you click CREATE PASSWORD, the new QR code for the Mobile Application will appear. You may frame the code and provide access to the app using the Zextras mobile app.v
To exit the Zextras Auth window, click DONE. The new Mobile Application now has an item in the Zextras Auth Zimlet’s Active Passwords list.
Make a New Credential: OTP
To establish a new One Time Password access, open the Zextras Auth Zimlet and select OTP Authentication, then NEW OTP + to bring up a dialogue where you can add a unique label to identify the OTP.
You will be given the QR code as well as a list of PIN codes to use for authentication.
Then, to print the codes on paper or to a file, click the PRINT PIN CODES button. All of the codes are included in the printed page, as well as the username/e-mail address for whom they are valid and instructions on how to use them.
Finally, close the Zextras Auth window by clicking DONE. In the list, a new OTP entry will be displayed.
Remove Credentials
To delete a credential, choose it from the list of Active passwords or OTPs and click the DELETE x button: click YES to confirm the credential’s removal.
Management of Credentials
A credential is anything that grants access to one of Zextras Suite’s services or modules.
The Zextras Suite The Credential Management system in Auth enables the creation of unique passwords for various services such as Exchange ActiveSync devices, Mobile Applications (e.g., Team and Drive), and the Zimbra WebClient itself.
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 rest of this section demonstrates a few frequent and significant activities that an administrator can perform.
Services that are supported
Custom passwords may be created or updated using Zextras Auth for the following services:
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.
A few instances are provided in the next section.
Create new credentials
When creating credentials, administrators can specify the password for any user account using the command line. They do not have access to the password under any other circumstances, not even to change it.
The zxsuite auth credential add command may be used to create new credentials for each of the active authentication services:
This command’s default service is EAS (Exchange ActiveSync). A comma separated list of services can be added. Following are few samples, the first of which has a commented output.
- Create a password and a label for the user john@example.com who will be able to access service eas (mobile password).
- produced – 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.
- 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 is exclusively valid for Web Access (both ClassicUI and Zextras). Page of Login
- Make a password for alice@example.com that is only valid for IMAP and POP3 downloads (no SMTP).
- Make a password for bob@example.com/SMTP_Service_Password.An external client’s SMTP can be enabled using a credential.
An crucial argument is qrcode, which is used to generate a new QR code 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:
List your current credentials.
The zxsuite auth credential list command allows System Administrators to examine an expanded list of all credentials active on an account:
This command’s output can be fairly lengthy because it displays all of the credentials specified on an account, as well as a variety of extra information. Let’s look at an example and determine what information is relevant:
is the credentials’ id, which is unique and required to modify the credential (see following section).
the service(s) that the credential is valid for.
Creating a Credential
While the credential (password) itself cannot be changed, the System Administrator can use the zxsuite auth credential update command to alter its label and attributes, including the services for which it is valid:
Using the above example, we wish to update the label of credential id Fr2jM for user john@example.com. This may be accomplished by using:
As the result of the preceding operation, the successful credential update will be presented, reporting all credential properties:
doDeployAuthZimlet doRestartService doStartService doStopService credential add credential delete credential list credential update2FA service enforcement get account enforce2FA get cos enforce2FA configure account 2FA login set cos getServicesdomain login page getBackgroundImageglobal login page getBackgroundImagedomain login page getColorPaletteglobal login page getColorPalettegetConfig domain login pagegetConfig global login pagegetFavicon domain login pagegetFavicon global login pagegetLogo domain login pageglobal login page getLogogetSkinLogoAppBanner domain login pageglobal login page getSkinLogoAppBannergetSkinLogoURL domain login pageglobal login page getSkinLogoURLgetTitle domain login pagegetTitle global login pagesetBackgroundImage domain login pagesetBackgroundImage on page global authenticationPage layoutLogin to the ColorPalette domainglobal login page setColorPalettesetFavicon domain login pagesetFavicon global login pagesetLogo domain login pageglobal login page setLogosetSkinLogoAppBanner domain login pageglobal login page setSkinLogoAppBannersetSkinLogoURL domain login pageglobal login page setSkinLogoURLPage layoutlogin domain titlePage layoutglobal policy list domain policy list global policy set title Cli domain policy has been established. Cli worldwide policy has been established. Set Dav domain policy Set global Dav policy Set EAS domain policy The worldwide policy of the EAS has been established. Set IMAP domain policy Set of global Imap policies Set MobileApp domain policy Set global policies for mobile apps Setup of Pop3 domain policies Pop3 global policy framework Set Smtp Domain Policy Set global policy for Smtp WebAdminUI domain policy configuration WebAdminUI global policy configuration WebUI domain policy configuration Set of global policies for WebUI ZmWebUI domain policy configuration ZmWebUI trustedDevice global policy domain policy trustedDevice getExpiration setExpiration_domain policy trusted getExpiration global policy trustedDeviceglobal saml delete saml get saml import saml update saml validate token invalidate token list totp delete totp generate totp list trustedDevice remove from trustedDevices list
