Logins

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
• Azure (Microsoft 365 (i.e. Office 365) - Login to Microsoft 365 
• OpenID Connect - Users are authenticated by a federated login service using the OpenID Connect protocol
  • Google Apps OpenID Connect - Setting up Google Apps authentication
• SAML - Users are authenticated by a federated login service using the SAML authentication protocol 
  • OneLogin - Setting up OneLogin federated authentication
• IMAP/POP - Login using IMAP/POP credentials
• 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

Basic Authentication

Once a user is authenticated, the user will be assigned the specified role.

The users.conf file contains the following:

Active Directory Authentication

1. MailArchiva authenticates with Active Directory users using a service computer account (you’ll see later how this computer account is created).
2. MailArchiva searches for the login user in Active Directory using the login name
3. MailArchiva binds (authenticates) with the login user using the supplied password.
4. MailArchiva assigns a role to the user based on the defined role assignments
5. MailArchiva extracts the user’s email addresses from the mail LDAP attribute for use in search filtering

In order to authenticate with Active Directory, MailArchiva requires that a new computer account is created in Active Directory and that a password to the account is set. While it is possible to create a new Computer using Active Directory Users And Computers, there is currently no way to set passwords on Computer accounts from the AD GUI. For this purpose, a VBS script called ADSetupWizard.vbs is included with the server distributable. The script, when executed with Domain Administrator privileges, will automatically create a Computer in Active Directory and set a password on the Computer account. It will also output the AD configuration settings that are appropriate for your setup.

The procedure for configuring Active Directory authentication is as follows:

2. Login to any computer nearby to (and including..) the MailArchiva server as a Domain Administrator. Copy the ADSetupWizard.vbs script from the above location to the local machine and run it.

3. Follow the Wizard instructions to create a new “service” computer account in Active Directory and set a password on the service account.

4. When the Wizard completes it, take note of the settings needed to define the AD settings in MailArchiva.

5. Open the MailArchiva console, click the Configuration menu at the top, thereafter select the Login menu on the left. Choose Active Directory authentication and enter the settings outputted by the AD Wizard.

6. Next, click the New Role Assignment button to create a mapping between a role in MailArchiva and an Active Directory attribute.
 

Note: If the ADSetupWizard.vbs script generates the error “AccessDenied 80070005”, it may be necessary to temporarily disable Windows UAC on the machine where the script is executed.  

Note: If you experience problems running the ADSetupWizard.vbs script, as an alternative, you can create a computer manually using Active Directory Users and Computers. Thereafter, run the SetComputerPassword.vbs script (located in the same location as ADSetupWizard script) to set the computer password.  

Note: Microsoft requires that the user assigned the impersonation rights should not also have administrator rights assigned.
When assigning roles to Active Directory users, it is necessary to select a role, select an LDAP attribute and enter a match criterion.

To complete the "attribute" and" "match" fields, it is useful to understand how roles are assigned to users during console authentication. A user in Active Directory has a set of LDAP attributes associated with it. These attributes are essentially properties of the user (e.g. account name, user group, etc.). During console authentication, once the user has been identified, all the users' LDAP attributes are retrieved from Active Directory and compared against the matching attribute values defined in each role assignment. If there is a match, the selected role is assigned to the user.The Lookup button is a convenience that allows you to "lookup" and select a sample attribute value pair from Active Directory for the purposes of defining the role assignment.

To assign a role to a Windows user, select “userPrincipalName” (UPN) as the LDAP attribute and enter the user’s UPN (e.g. user@company.local) in the matches field. To assign a role to all users within a user group, select “memberOf” in the attribute field and enter the distinguished name of the user group in Active Directory (e.g. “CN=Enterprise Admins, CN=Users, DC=company, DC=com”).

When specifying the "matches" field, it is useful to lookup the LDAP attribute name and values associated with a user. This is done by clicking the Lookup button and entering a user's username (e.g. admin@company.com) and a password. A list of possible attributes and their values will be shown. When clicking on an attribute value in the dialog, the LDAP "attribute" and "matches" field are automatically populated. 

To illustrate, a common requirement is to assign all normal AD users the built-in User Role. This task is accomplished as follows:

1. In Configuration->Logins, create a new role assignment
2. Select the User Role
3. Click the Lookup button
4. In the popup dialog, enter the credentials of an existing AD user
5. A list of LDAP attribute value pairs will appear.
6. Choose the LDAP attribute value pair that corresponds with "object class = user"
7. Click Save and perform a Test Login

Only If AD is running outside of the network, running MailArchiva: Ensure that DNS lookup is disabled.  In "Server IP" field, enter the IP address of AD server.

There is likely to be an error in your configuration if the Lookup dialog does not return any LDAP attribute values. Once all role assignments are configured, execute a Test Login to ensure that your Kereberos settings, LDAP settings and user roles have been configured correctly. If problems are encountered, please refer to Authentication Failed Steps.
 

If you are unable to get AD authentication working in your environment, it is possible to authenticate with AD using password-based LDAP authentication instead. To do this, select LDAP authentication, enter the mail attribute to be “proxyAddresses” and “SAMAccountName” to be the bind attribute. You will also need to clear out the default login name suffix in the Logins section. Refer to LDAP Authentication for more information.  

Multi-Domain Authentication Tip: if your organization has multiple domains, MailArchiva must be configured to connect to AD’s Global Catalog Server running on port 3268. To do this, change your Active Directory server FQDN to the equivalent of company.com:3268. Set the base DN to be empty.

LDAP Authentication

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.

Microsoft Azure Authentication (Office 365)

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:

1. Click the New Role Assignment button
2. Select the desired MailArchiva role to map (.e.g. Administrator)
3. Click Lookup button. A Lookup Window appears.
4. Enter the administrators email address/UPN. Click Lookup.
5. Choose an appropriate attribute (e.g. Administrator Group) to map.
6. Click Save to save the mapping. 
7. 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 Authentication

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.

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.

Google Apps OpenID Connect

From the Google Developers Console:

• Go to the Google Developers Console.
• Select a project, or create a new one.
• 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.

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.

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

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. 

From the OneLogin Administrator Dashboard:

• Login to the OneLogin Administrator Dashboard
• Navigate to Apps -> Add Apps in OneLogin
• 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/$"

• 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: It is possible to assign roles using any number of SAML fields. Common fields include: 

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

To enable IMAP/POP authentication:

• Define an IMAP/POP client 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.

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