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 validates the login credentials against Active Directory using Kerberos.
2.     MailArchiva searches for the login user in Active Directory using the login name.
3.     MailArchiva retrieves the user’s LDAP attributes (including email addresses).
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 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.

1. Open Configuration → Logins → New Role Assignment.

2. Select a role.

3. Choose an LDAP attribute.

4. Enter a match criterion (exact string or regular expression).

5. Use Lookup to fetch a sample user’s attributes and values to assist with choosing the correct pair.

6. Save and perform a Test Login.

4. Test Login

• Perform a test login with a domain user.
• Confirm that Kerberos authentication and role assignments work as expected.

Extra Notes

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.