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
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:
C:ProgramDataMailArchivaROOTconf (Windows)
Remove the security.login.master.password and security.login.master.username fields.
Basic Authentication
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.
The users.conf file contains the following:
<User username="admin" role="administrator" password="123"/>
<User username="user" role="user" password="abc"/>
<User username="auditor" role="auditor" password="xyz"/>
</Users>
When Basic authentication mode is enabled, users are able to change their own passwords in the Preferences section.
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:
Active Directory Authentication
- 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.
Gotcha's
- In the default realm, do not enter the FQDN of the domain controller (i.e. not DC1.CONTSO.COM!). It must be the domain. (i.e. CONTSO.COM)
- Base DN is usually equivalent to "OU=Users, DC=Contoso, DC=com", but depending on AD server configuration, your users may be located in a different DN.
- The service account login must be located as specified in the Base DN (discussed earlier).
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 → Logins → Active Directory
-
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.
-
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
Active Directory Single Sign-On (SSO) (Kerberos)
Overview
.png?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9kemY4dnF2MjRlcWhnLmNsb3VkZnJvbnQubmV0L3VzZXJmaWxlcy8zMDcvMzkzL2NrZmluZGVyL2ltYWdlcy9xdS8yMDI2L2tlcmJlcm9zX3Nzb19tYWlsYXJjaGl2YV9mbG93KDIpLnBuZyIsIkNvbmRpdGlvbiI6eyJEYXRlTGVzc1RoYW4iOnsiQVdTOkVwb2NoVGltZSI6MTc4MzEyMDU1OX19fV19&Signature=V0jReHqQkcXQ1mzm~M0~kl5oN1dKa9gIU3LJuwMhEYbOEUBM8HSRoeZBd-uW4tfPC24A6ZEGfuSC-qOLegru6QFvQcsUlDCK9UBpEk4Bb~ssLlDJUzjrTOMAG2yv3EbqqSsd8vlryU4nCNplN6nsoCdBcrHKP-rvYXWEYAAXPOxuwmWfRet6FxRoKZX-UMgfaZ2VMQM55q~NqNr0tBwzEWEaZ6Ruflwb~3cwY9maBspMiXwhLQ1KUawE1ziYRMKjITIOTvI7U4Y0hL3ZK-MtxNXaJzF5OU6SVyvIT-xhVnCGzHCAqLs~cNZ2NSpgSQ~xwLxYBwPFbvc7oTQ7GQm~Iw__&Key-Pair-Id=K2TK3EG287XSFC)
Single Sign-On (SSO) allows a user to authenticate once within an Active Directory domain and access MailArchiva without re-entering credentials.
Benefits include:
-
Improved user experience with fewer passwords to manage.
-
Enhanced security because passwords are not stored in applications.
-
Kerberos tickets are used for authentication.
-
Centralized account and permission management through Active Directory.
1. Understanding the Service Account
A service account is a dedicated Active Directory account used by MailArchiva to perform domain authentication.
Key characteristics:
-
Not intended for interactive user logins.
-
Can be assigned limited permissions following the principle of least privilege.
-
Used for automated authentication processes such as Kerberos SSO.
-
Typically associated with a Service Principal Name (SPN).
2. Environment Preparation
Before configuring Kerberos SSO, ensure the following requirements are met:
3. Create a Service Account in Active Directory
There is no need to create a new
Option A: Using Active Directory Users and Computers (ADUC)
Skip this step if already don
-
Open Active Directory Users and Computers.
-
Navigate to the Users container or your preferred Organizational Unit (OU).
-
Right-click and select New > User.
-
Enter the following information:
-
Set a password.
-
Clear User must change password at next logon.
-
Open the Account tab.
-
Enable This account supports Kerberos AES 256-bit encryption.
Option B: Using PowerShell
-SamAccountName "svc-kerberos-ar" `
-AccountPassword (ConvertTo-SecureString "StrongPassword123!" -AsPlainText -Force) `
-Enabled $true
Enable AES-256 support:
Set-ADUser svc-kerberos-ar ` -Add @{msDS-SupportedEncryptionTypes=24}
4. Create and Verify the Service Principal Name (SPN)
An SPN uniquely identifies the MailArchiva service within Kerberos.
Verify an Existing SPN
setspn -Q HTTP/ar.yourealm.com@YOU_REALM
Create an SPN
setspn -A HTTP/ar.yourealm.com YOU_REALMsvc-kerberos-ar
Parameters
Important:
-
The SPN must be unique within Active Directory.
-
Duplicate SPNs can cause authentication failures.
5. Generate the Keytab File
Generate a keytab file for the service account.
/mapuser svc-kerberos-ar@YOU_REALM ^
/ptype KRB5_NT_PRINCIPAL ^
/crypto AES256-SHA1 ^
/pass StrongPassword123! ^
/out C:tempkrb5_service.keytab
Deploy the Keytab File
Copy the generated krb5_service.keytab file to the appropriate location.
Important
When the service account password changes:
-
The Key Version Number (KVNO) changes.
-
The existing keytab becomes invalid.
-
A new keytab must be generated and deployed to Archiva.
Reset the Service Account Password (Optional)
-Reset `
-NewPassword (Read-Host -AsSecureString)
6. Verify Keytab Contents
Verify the generated keytab file.
ktutil -k /path/to/krb5_service.keytab list
Expected output:
Vno Type Principal 3 aes256-cts-hmac-sha1-96 HTTP/ar.yourealm.com@YOU_REALM
Field Descriptions
Note:
Windows systems require Kerberos utilities to be installed before running these commands.
7. Test Authentication Using the Keytab
Acquire a Kerberos ticket:
kinit -k -t /path/to/krb5_service.keytab HTTP/ar.yourealm.com@YOU_REALM
View the ticket details:
klist -v
Verify:
-
Ticket encryption type is
aes256-cts-hmac-sha1-96. -
KVNO matches the value stored in the keytab.
-
Authentication completes successfully.
8. Configure Client Browsers
Internet Explorer and Microsoft Edge
-
Open Control Panel > Internet Options.
-
Add the Archiva URL to Trusted Sites.
-
If using HTTP, ensure HTTPS-only requirements are not enforced.
-
Configure the security settings for the Trusted Sites zone appropriately.
Microsoft Edge Settings
-
Open Settings.
-
Navigate to Privacy, Search, and Services.
-
Enable Windows Authentication.
-
Restart the browser.
Verification
From a domain-joined workstation:
-
Open MailArchiva
-
Confirm that no password prompt appears.
-
Verify successful login.
For troubleshooting, use:
-
klist -
Windows Event Viewer
-
Kerberos logs
9. Configure Tomcat for SSO (Optional)
When upgrading from versions earlier than 10, Tomcat must be configured to support larger Kerberos authentication headers.
Step 1: Stop the Archiva Service
Stop the MailArchiva service before making configuration changes.
Step 2: Edit server.xml
Step 3: Increase Header Size
Locate each <Connector> definition in Tomcat's server.xml and ensure the following attribute is present:
maxHttpHeaderSize="65536"
Step 4: Restart MailArchiva
Start the MailArchiva service after saving the configuration changes.
Summary
Remember:
-
Regenerate the keytab whenever the service account password changes.
-
Ensure SPNs remain unique within Active Directory.
-
Configure Tomcat with an increased
maxHttpHeaderSize. -
Clients must be domain-joined and properly configured for Kerberos authentication.
-
Time synchronization is critical for successful Kerberos operation.
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:
- 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 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:
| SAML Test Connector Fields | Value |
|---|---|
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.