Access to the MailArchiva web console and its features can be restricted to authorized users only. The following types of authentication mechanisms are supported:
Basic – Users are authenticated using credentials stored in a configuration file
Active Directory – Users are authenticated using their Windows credentials
LDAP – Users are authenticated against users on a directory server such as OpenLDAP
Imail - Users are authenticated against iMail mail server
TOTP Two-Factor Authentication - Add an additional layer of security by requiring users to authenticate using a one-time-password (OTP)
In all modes, if authentication is successful, a role is assigned to the authenticated user. The user’s role determines what the user can and cannot do within the application. A user’s role can also restrict which emails the user can see. For instance, users assigned the User role can be assigned permission to see their own emails only. Refer to Roles for further details on how to define role permissions in MailArchiva.
Master Password
Before selecting an authentication method, it is prudent to specify the master password in the Logins section. The master password is essentially the “root” password for the system. It serves as a convenient back door in the event the system is unable to authenticate with Active Directory or LDAP servers. To login as the master user, use the username “admin” and your chosen master password. The master user has access to all the privileges in the system.
Note: If you forget the master password, edit the file server.conf located in:
In the Basic Authentication mode, the server authenticates users from credentials stored in an XML configuration file. The users.conf configuration file is located in mailarchivaserver webappsMailArchivaWEB-INFconf from the root of your MailArchiva installation directory. You can either add users directly using the MailArchiva server console configuration screen or by editing the server.conf directly. The users.conf file, as illustrated below, contains a list of users, each of which has a username, role and a password. The users listed in users.conf will login using their username and any of the domains in the Domains section appended to it.
Once a user is authenticated, the user will be assigned the specified role.
When Basic authentication mode is enabled, users are able to change their own passwords in the Preferences section.
Note On Aliases
In the case of Basic Authentication, the use of email aliases is not currently supported (only LDAP & AD authentication).
That being said, the following workaround is possible:
1) Enter markw and specify radeon.com,radeon.co.uk, radeon.us in the Domains section. This will show all emails corresponding with markw across all domains.
2) Create a role for each user and specify the alternate email addresses in the view filter. e.g. anyaddress:(%email% OR markweston)
Note: Starting with MailArchiva V10, Kerberos is now used in place of NTLM v2 for Active Directory authentication.
In Active Directory (AD) authentication mode, the server uses Kerberos and LDAP protocols to authenticate users residing in Active Directory. The login procedure is a five-step process:
MailArchiva validates the login credentials against Active Directory using Kerberos.
MailArchiva searches for the login user in Active Directory using the login name.
MailArchiva retrieves the user’s LDAP attributes (including email addresses).
MailArchiva assigns a role to the user based on the defined role assignments.
MailArchiva extracts the user’s email addresses from the mail LDAP attribute for use in search filtering.
Field
Description
Example
FQDN of this server
Fully qualified domain name of the MailArchiva server
mailarchiva.business.local
Base DN
Distinguished name of the base location in AD where users are located
CN=Users, DC=business, DC=local
Default realm
Kerberos realm name (usually the AD domain in uppercase)
The mail attribute where the user’s email addresses are obtained
proxyAddresses
Email Value
Regular expression used to extract email addresses
SMTP:(.*)
Primary Mail Attribute
The mail attribute where the user’s primary email address must be obtained
mail
Primary Email Value
Regular expression used to extract the primary email address
(.*)
Bind Attribute
Attribute used to search for the user in LDAP
sAMAccountName
UPN Attribute
The User Principal Name (UPN) attribute
userPrincipalName
UPN Value
Regular expression used to extract the UPN value
(.*)
1. Create a Service Account
Kerberos authentication requires that a service account is created in Active Directory. This account will be used by MailArchiva to query LDAP and authenticate users.
In Active Directory Users and Computers (ADUC), create a new user (for example, mailarchiva).
Set a strong password and mark Password never expires.
2. Configure MailArchiva
Open the MailArchiva console, click Configuration → Login.
Fill in the fields as described in the Field Descriptions table above, namely: Default realm, FQDN of this server, Base DN, Service account login, Service account password and Active Directory address.
3. Assign Roles
During console authentication, after a user is identified, MailArchiva retrieves the user’s LDAP attributes from Active Directory and evaluates them against each configured role assignment. If an attribute’s value matches the assignment’s match criterion, the role is granted.
Open Configuration → Logins → New Role Assignment.
Select a role.
Choose an LDAP attribute.
Enter a match criterion (exact string or regular expression).
Use Lookup to fetch a sample user’s attributes and values to assist with choosing the correct pair.
Use a regex to target a subtree (for example, everyone in Engineering).
4. Test Login
Perform a test login with a domain user.
Confirm that Kerberos authentication and role assignments work as expected.
For multiple domains, configure MailArchiva to connect to the Global Catalog server on port 3268 and leave Base DN empty.
Extra Notes
In addition to the AD properties editable in the GUI, additional advanced LDAP properties can be set directly by editing the MailArchiva server.conf file using a text editor such as Wordpad or Vi.
Field
Description
Server.conf Example
Alternate Email Address
Secondary location where the user's emails can be found. MailArchiva will retrieve the user's email addresses from both the mail attribute and the alternate email address.
The regular expression pattern used to extract the email address. If you wish to take as is, use (.*). If you email addresses are in the format SMTP:joe@blog.com, then you will specify SMTP:(.*). Note position of brackets.
When LDAP authentication is enabled, MailArchiva authenticates to a directory service such as OpenLDAP using pure password-based credentials.
The following process occurs during LDAP console login:
MailArchiva authenticates with the directory using a service account DN and a password.
MailArchiva searches for the user, starting from the Base DN, by matching the supplied username with the Bind Attribute (normally, UID)
MailArchiva retrieves the DN of the located user
MailArchiva uses the retrieved user DN and user password to login into the directory.
Once logged in, MailArchiva looks for a matching role and retrieves the user’s email address from the Email Attribute field (usually, email or mail).
Since directory structures tend to be unique across different organizations, care must be taken to ensure that the base DN, service account login DN, bind attribute and email attribute is correct for the target directory. For example, some companies use “mail” as the location where user email addresses are stored, while others use “email”.To determine the structure of a directory, it may be useful to connect to it using the Linux command line utility ldapsearch or one of the many LDAP browsers available. Once the correct LDAP settings have been entered, it is necessary to create one or more role assignments for the purpose of assigning MailArchiva roles to the users residing in the directory.
Field
Description
Example
LDAP Server Address
Fully qualified domain name of LDAP server
openldap.company.com:389
Base DN
The distinguished name of the location in AD where MailArchiva should start searching for end-user entries.
Cn=Users, dc=Company, dc=Com
Service Account Login
DN The distinguished name of an admin user in LDAP
cn=Administrator,cn=Users,
dc=company, dc=com
Service Account Password
The service account password
Mail Attribute
The mail attribute where the user’s email addresses are obtained mail
mail
Mail Value
The regular expression used to extract the user’s email address from the mail attribute
(.*)
Bind Attribute
The field in LDAP that contains the username or login name of the user.
uid
Note: Should your LDAP be configured for anonymous LDAP bind, empty out the Service Account Login and Service Account Password fields.
In addition to the above properties, additional advanced LDAP properties can be set directly by editing the MailArchiva server.conf file using a text editor such as Wordpad or Vi.
Field
Description
Server.conf Example
Alternate Email Address
Secondary location where the user's emails can be found. MailArchiva will retrieve the user's email addresses from both the mail attribute and the alternate email address.
ldap3.alternateemailaddress.attribute=emai
Alternate Email Address Value
The regular expression pattern used to extract the email address. If you wish to take as is, use (.*). If you email addresses are in the format SMTP:joe@blog.com, then you would specify SMTP:(.*). Note position of brackets.
MailArchiva has the capability to securely authenticate users residing in Office 365 (using the OpenID Connect (OIDC) protocol built on OAuth 2.0). To enable login using Office 365 credentials, choose Azure as the console login method in Configuration->Logins. Using this login method, there is no need to define individual users in MailArchiva, since users are authenticated against user credentials residing in Microsoft Azure Active Directory (i.e. Office 365).
During Microsoft Azure login, users are redirected to Microsoft Office 365 for authentication, and then after successful login, redirected back to MailArchiva, and a logon session established. As user credentials are inputted into the common Microsoft login website, at no point in the process does MailArchiva have the opportunity to intercept the user's Office 365 credentials. As an added advantage, MailArchiva built-in roles (e.g. administrator, audit, user) and custom roles, can be assigned according to the user groups (e.g. Administrators) and attributes (e.g. userPrincipalName) defined in Microsoft Azure Active Directory.
For example, in the Azure console login settings in Configuration->Logins, a role mapping can be defined that maps the MailArchiva administrator role to all users belonging to the Microsoft Office 365 Administrator Group. The mapping has the effect that Office 365 users belonging to the Office 365 Administrator Group are automatically assigned the MailArchiva Administrator role during login to MailArchiva. Thus, there is no need to create a separate role mapping for each individual user. Rather, the role mapping can be done at a group level.
When a MailArchiva Cloud instance is first setup, authentication to Microsoft Office 365 is preconfigured and automatically enabled. By default, the Office 365 user who created the MailArchiva instance, is automatically assigned the Administrator role in MailArchiva. Additional role assignments can be defined as per the following:
Click the New Role Assignment button
Select the desired MailArchiva role to map (.e.g. Administrator)
Click Lookup button. A Lookup Window appears.
Enter the administrators email address/UPN. Click Lookup.
Choose an appropriate attribute (e.g. Administrator Group) to map.
Click Save to save the mapping.
Perform a Test Authentication to verify that the correct role is assigned to a target user or group of users.
In addition to the MailArchiva Cloud, it is possible to integrate Azure authentication for MailArchiva On-Premise. Refer to Office Setup for instructions on how to achieve this.
OpenID Connect is a protocol for authenticating against federated login services such as provided by Google Apps or Office 365. Using OpenID Connect, it is possible to authenticate users using their Google Apps or Office 365 credentials.
The following process occurs during Google console login:
An unauthenticated user accesses the MailArchiva console
MailArchiva redirects to an outside federated login page provided by an authentication provider (i.e. such as Google Apps or Office 365)
If not already logged in, the user logs in to the provider's federated login service.
(note: for security purposes, MailArchiva never actually receives these credentials)
If login is successful, MailArchiva receives a token from the federated login provider and verifies it to ensure authenticity.
MailArchiva receives and retrieves user properties such as email addresses, etc.
A matching role is assigned to the user based on the defined role mapping.
client secret (provided by federated login provider)
XXXXXX
Authentication Callback URL
After successful login, URL where the authentication provider must redirect to process the token
http://localhost:8090/authorize.do
Scopes
Specifies what access privileges are being requested
openid,profile,email
Once the user is authenticated, the user needs to be assigned a role in MailArchiva. This is achieved by creating a Role Assignment. Each Role Assignment maps an OpenID user field (such as user_login) to a role in MailArchiva. Refer to the Google Apps OpenID Connect example below for further instructions.
In the sidebar on the left, expand APIs & Services -> Credentials.
In Create Credentials drop down, click OAuth Client ID (if you haven't done so prior)
In the Create Client ID dialog, select Web application as the Application Type
Enter the Application Name in the Consent Dialog (e.g. MailArchiva). Click Save.
In Authorized JavaScript origins, enter MailArchiva's access URL. For example, enter the equivalent of "http://mailarchiva.company.com:8090" (adjust to suit your domain name). If you do not have an external domain for the MailArchiva server, add the domain to your local hosts file (e.g. /etc/hosts) as a temporary measure.
In Authorized redirect URIs, enter "http://mailarchiva.company.com:8090/authorize.do" (adjust to suit your domain name)
Click Create. Take note of the Client ID and Client Secret
From inside MailArchiva:
Visit Configuration->Logins
Select the OpenID Connect authentication method
In Issuer URL enter "https://accounts.google.com"
Enter the Client ID and Client Secret from the Client ID created earlier
Enter a matching authentication callback URL. For example, "http://localhost:8090/authorize.do" or "https://mailarchiva.company.com/authorize.do" (adjust to suit your domain name)
In the Scopes field, enter "openid,profile,email"
Leave "Auto discover connection settings" checked
To assign a role to a specific logged-in user, enter:
Click "New Role Assignment" button
Select the Administrator Role
In Attribute, enter user_login
In the value field, enter the primary email address of a test user. For instance administrator@company.com
Logout the MailArchiva console, by clicking the username at the top right. Click Logout. Visit http://localhost:8090. MailArchiva should immediately redirect to the Google Apps login page. After logging in, it should redirect to MailArchiva with the logged in user.
Note: If there is a misconfiguration in the login service, it is always possible to log back into the MailArchiva console as admin by accessing the URL http://localhost:8090/signonform.do directly.
To assign users to a group in Google Apps:
Follow the steps to setup Google Archiving & Sync (i.e. create a new Google Client Connection).
To view available groups associated with a user, click the Lookup button beside the Attribute field
Enter the user's primary email address (user@company.com) in the Lookup Dialog
Select the desired group to map, and the assignment will be completed. Click Save to save changes.
SAML Authentication
MailArchiva has the ability to authenticate against federated login services supporting the SAML protocol. For instance, one can use a federated login service such as OneLogin to provide single-sign-on access to the MailArchiva web console.
The following process occurs during Google console login:
An unauthenticated user accesses the MailArchiva console
MailArchiva redirects to an outside federated login page provided by an authentication provider (i.e. such as OneLogin)
If not already logged in, the user logs in to the provider's federated login service.
(note: for security purposes, MailArchiva never actually receives these credentials)
If login is successful, MailArchiva receives a token from the federated login provider and verifies it to ensure authenticity.
MailArchiva receives and retrieves user properties such as email addresses, etc.
A matching role is assigned to the user based on the defined role mappings.
Field
Description
Example
SSL Login URL
federated login provider's login URL. Also known as the Idp SSO target URL
After successful login, URL where the authentication provider must redirect to process the token
http://localhost:8090/authorize.do
Issuer
federated login provider's issuer URL
https://app.onelogin.com/saml/metadata/436692
Certificate
X.509 certificate obtained from the federated login provider
Certificate must first be imported from Configuration->Certificates
Scopes
Specifies what access privileges are being requested
openid,profile,email
Bind Attribute
The name of an attribute that can be used to bind to a user
User.FirstName
Email Attribute
The name of an attribute containing the user's email addresses
User.email
Email Value
A regular expression for matching the user attribute. In most cases, this does not need to be changed.
(.*)
Once the user is authenticated, the user will need to be assigned a role in MailArchiva. This is achieved by mapping a SAML user field (such as User.email or User.MemberOf) to a role in MailArchiva. Refer to the OneLogin example below for further instruction.
OneLogin provides federated single signon services. With SAML authentication enabled, it is possible for users to login to the MailArchiva console using their OneLogin credentials.
Search for ‘SAML Test Connector’ and select the first result from the search results.
The SAML Test Connector properties will open
In the Display Name field, enter MailArchiva, click Save.
Select the Configuration Tab
In Audience, Recipient and ACS URL fields, enter the equivalent of "http://localhost:8090/authorize.do"
In the ACS URL Validator field, enter the equivalent of "^http://localhost:8090/authorize.do/$"
Note: The ACS URL and ACS URL Validator fields will need to be adjusted to match the specific URL used to access your MailArchiva system. Assuming your MailArchiva server is assigned an external domain name, such as mailarchiva.company.com, the ACS URL would be "https://mailarchiva.company.com/authorize.do", while the ACS Validator URL would be "^https://malarchiva.company.com/authorize.do/$"
Select the SSO Tab
Select an existing X.509 certificate if one is available. If not, one can be created in Settings (top menu) -> Security -> SAML.
Take note of the Issuer URL and SAML 2.0 Endpoint (HTTP) urls
Save the settings
To obtain a certificate, click Settings (top menu) -> Security -> SAML.
If no certificate is available, Click New to create a new one. Select a name for the certificate. And Save.
Download the resultant X.509 certificate PEM file
Open the SAML Test Connector again, ensure the newly created X.509 certificate is selected. Save.
From inside the MailArchiva Console:
Click Configuration->Certificates
Click Import CA Certificate
Select the PEM file downloaded earlier
Enter a storage alias of your choosing (for example, "saml")
Visit Configuration->Logins
Select the SAML authentication method
In the Issuer URL field, enter the Issuer URL obtained the Test SAML Connector properties (e.g. https://app.onelogin.com/saml/metadata/436692)
In the SSO Login URL field, enter the SAML 2.0 Endpoint (HTTP) obtained the Test SAML Connector properties (e.g. https://app.onelogin.com/trust/saml2/http-post/sso/436692)
In the Assertion Consumer Service (ACS) URL enter the equivalent of "http://localhost:8090/authorize.do"
In the Certificate field, select the alias of the certificate imported earlier
In the Bind Attribute field, enter "User.FirstName"
In the Email Attribute field, enter "User.email"
Leave the Emal Value as "(.*)"
To assign a role to a specific logged in user, enter:
Click "New Role Assignment" button
Select the Administrator Role
In the Attribute field, enter "User.email".
In the Contains field, enter the email address of a Onelogin user (e.g. user@company.com).
Click Save to Save the Configuration.
Logout the MailArchiva console, by clicking the username at the top right. Click Logout. Visit http://localhost:8090. MailArchiva should immediately redirect to the OneLogin login page. After logging in, it should redirect to MailArchiva with the logged in user.
Note: If there is a misconfiguration in the login service, it is always possible to log back into the MailArchiva console as admin by accessing the URL http://localhost:8090/signonform.do directly.
Note: It is possible to assign roles using any number of SAML fields. Common fields include:
SAML Test Connector Fields
Value
E-mail (Attribute)
User.email
Email (SAML NameID)
User.email
First Name (Attribute)
User.FirstName
Last Name (Attribute)
User.LastName
Member of (Groups) (Attribute)
User.MemberOf
IMAP/POP Login
In architectures where an authentication server is not available, it may be useful to authenticate users against either an IMAP or POP server.
The following process occurs during IMAP/POP authentication:
An unauthenticated user accesses the MailArchiva console
User enters their IMAP/POP credentials
Server authenticates the entered credentials against an IMAP/POP server
A matching role is assigned to the user based on the defined role mappings (see how to define a role mapping further below)
The assigned email addresses of the user is concatenation of username + domains defined in Configuration->Domains
Security Note: When defining an IMAP/POP connection, ensure that TLS is configured and enabled on the connection.
In Configuration->Logins, select IMAP/POP authentication method
Select the IMAP/POP client connection created above
Click the New Role Assignment button to create a mapping between a role in MailArchiva and an IMAP or POP username.
Note: Regular expression matches are supported. Thus, to assign all users to the Users role, enter ".*" in the matches value field.
Save
TOTP Two Factor (2FA) Authentication
The two-factor authentication (2FA) feature offers an additional layer of security by requiring users to authenticate using a one-time-password (OTP) in addition to their regular password-based credential. 2FA is supported by way of the RFC 6238 Time-based One-Time Password (TOTP) algorithm. With 2FA enabled, in addition to authenticating with a password, users are required to input a one-time-password (OTP) generated by a TOTP mobile authenticator app such as Google Authenticator. To enable 2FA, login to the MailArchiva console as admin, open Configuration->Logins, and check "Add extra layer of security..".
After 2FA is enabled, all users will be prompted at next login to register the MailArchiva application on a TOTP mobile phone app such Google Authenticator. Each user registers MailArchiva on their TOTP mobile app by scanning a QR-code (see image to right) using their mobile phone. Thereafter, after logging in, each user will be prompted to input the OTP displayed on the TOTP app for authentication purposes. During login, a user may also opt to trust the device for 30 days, in which case, they will not be prompted for 2FA for another 30 days provided they are logging in using the same browser on the same machine.
If a user is unable to authenticate for any reason, their 2FA registration must be reset by an administrator. To reset a user's 2FA registration, login to MailArchiva using the admin account, go to Configuration->Logins, click the "Reset user" button. Enter the user's User Principal Name (UPN) or username in the popup dialog and click the "Reset user" button. Provided the reset is successful, on next login, the user will be prompted to re-register the MailArchiva application again on their TOTP mobile phone app. If resetting a user for the second time, if the user had not logged in and registered for TOTP authentication yet, a message will popup stating "Reset failed as user's two-step auth was already reset". It is simply stating there was no need to reset, as the user was not registered yet.
