Mailhardener authentication guide

This article explains the various options and settings for authenticating with the Mailhardener Dashboard application and the Mailhardener API.

The Mailhardener Dashboard application is a multi-user environment with multi-tenant support and role-based access control (RBAC). Single Sign-on (SSO) two-factor authentication (2FA/MFA) are supported for authentication, as well as password authentication. The Mailhardener Dashboard application features built-in Identity and Access Management (IAM).

Authentication methods

Mailhardener supports the following authentication methods:

• Password authentication with optional Time-based One-Time Password (TOTP) second-factor.
• Single Sign On (SSO) via third party identity provider:
  • Microsoft Entra ID - Microsoft Azure AD or Microsoft Account (MSA).
  • Google Accounts - Google Workspace or Google Account.
• OAuth 2.0 for API clients, using the 'Client Credentials' grant type.

Multi-user support

The Mailhardener Dashboard application features multi-user support with role-based access control (RBAC). All tiers allow an unlimited number of user accounts, except for Mailhardener Free, which is limited to a single user.

Identity and access management (IAM) is performed from the Mailhardener Dashboard using the 'team' module. The team module requires the Account Administrator role; users with lesser-privileged roles do not have access to IAM controls in the Mailhardener Dashboard application.

Multi-tenant support

Mailhardener is a multi-tenant environment, a single user account can be member of multiple teams (Mailhardener customer environments).

The hierarchy is:

Level	Ownership	Resources
Customer account	Customer organization	Name, billing information, authentication policies
Team membership	Account administrators of the team	Role and domain ACL
User account	User or API client	Display name, email address, authentication data

The customer account may also be referred to as 'the team'.

If a user account is a member of a single team, then successful authentication will display the Mailhardener Dashboard for this team.

If a user account is a member of multiple teams (multi-tenant), the user will be prompted to select which team they want to log in for.

This selection is prompted after successful authentication.

Different teams that a user belongs to may have varying authentication requirements, if one of the teams requires 2FA for example, the user is required to enable 2FA. If the user uses SSO login that conflicts with the SSO requirements of a team then it will not or no longer be possible to select this team. For users with multiple team memberships a team switcher is shown in the top-right corner of the Mailhardener Dashboard application. This allows seamless switching between teams.

Revoking access of a user to a Mailhardener environment will not remove the user account itself, as the user may still be a team-member of other Mailhardener tenants. If a user account no longer has access to any tenants, the user will be prompted a choice of deleting their user account permanently, or creating a new Mailhardener environment for their own use. User accounts that do not have access to any Mailhardener environment will eventually be deleted automatically.

MSP multi-tenant support

For Managed Service Providers (MSPs), Mailhardener offers a multi-tenant solution tailored for MSP use. Mailhardener customers using the 'Mailhardener for MSP' solution receive access to the Mailhardener multi-tenant interface, also known as the MSP portal.

The customers/clients of the MSP organization each receive an isolated Mailhardener environment, known as a tenant. Tenant environments are managed from the MSP portal by MSP employees. Optionally, a tenant may be granted access to their own isolated environment.

The MSP environment is best visualized as an interface 'above' that of the tenants. The hierarchy for MSPs thus adds layers above the tenants:

Level	Ownership	Resources
MSP environment	MSP organization	Name, billing information, authentication policies for the MSP
MSP team membership	Account administrators of the MSP team	MSP role
MSP user account	MSP employee	Display name, email address, authentication data
Tenant (customer)	Customer of MSP	Name, resource limits, authentication policies for the tenant
Tenant team members	Customer account administrators	Role and domain ACL
Tenant user	Customer employee	Display name, email address, authentication data

Access roles for MSP users (MSP employees) differ from tenant user roles.

API access

Mailhardener offers access to the Mailhardener public API. The public API and its documentation are available by default for customers using the 'Mailhardener for MSP' package. API access is available on request for customers using 'Mailhardener for Enterprise' or 'Mailhardener Large' package.

API clients authenticate with the API using OAuth 2.0 with the client_credentials grant. For more details on the OAuth authentication and credential provisioning, please refer to the API documentation.

API client credentials are managed via the 'team' (IAM) module in the Mailhardener Dashboard application. Note that API credential management features are only shown if API access is enabled for the account.

Managing access (IAM)

Team members (user accounts) and API clients are managed from the 'team' module in the Mailhardener Dashboard, this module requires the Account Administrator role to access.

The team module displays an overview of all users that have access to the Mailhardener environment, displayed information is:

• Name - this is the display name used to identify the owner of the account. This name can be changed by the user itself from the 'My Account' module.
• Email (login) - this is the email address of the user, it is the primary identification. When using SSO the SSO identity must match this email address.
• Identity provider - the SSO identity provider for this account. If user uses password authentication, this will show 'Mailhardener' as identity provider. For prospect users (invited user that have not yet created their Mailhardener account) this column will show 'Pending'.
• 2FA - Indicates if the user has 2FA set up for their account. Show either 'yes' or 'no'. If 2FA is used this column will also display a 2FA reset button (circular arrow icon) to perform 2FA reset.
• Role - Displays the role of the user. Account Administrators can change role of a user (except themselves) by clicking the 'change role' button (pencil icon).
• Domains - Displays the domain access list (ACL) or 'All domains' if user is not limited to a domain subset. An ACL can be setup or modified by clicking the 'change access' button (pencil icon). Account Administrators cannot be limited to a domain subset.
• Remove - Displays a button (trashcan icon) to revoke access of a user to the environment.

Adding a new team user

New team members are created by granting access to the Mailhardener environment, this is performed by clicking 'add team member' from the team module.

Clicking 'add team member' opens a prompt where the account administrator is asked for a name, email address and desired role of the new team member. The name is a display name used solely to identify the person associated with the user account, the email address is the unique identifier for this user account. Depending on the selected role, the domain access ACL can be created optionally.

In case the invited person (identified by the email address) does not have a Mailhardener user account yet, they will receive an email message inviting them to create a user account to join the team of the inviter at Mailhardener. Prospect team members that have not accepted the invitation yet are shown as 'invitation pending' in the team overview. The email message contains a URL to accept the invitation by creating a new user account. The URL contains a one-time use token, which attaches the newly created user account to the team of the inviting customer. Once the invitation is accepted the URL cannot be reused. If an account administrator revokes (deletes) the invitation before it is accepted, the URL will no longer be usable. Following the URL leads to a landing page in the Mailhardener Dashboard application to accept the invitation for that team. Depending on the SSO requirements of the inviting team's environment, the new user can either create an account with a password or authenticate using one of the allowed SSO identity providers. If 2FA is mandated for the team then the user is prompted to set up a TOTP authentication code using their authenticator app of choice.

Because Mailhardener is a multi-tenant application, it is also possible that the newly added team member already has an existing user account with Mailhardener. In that case the user is added to the team immediately, skipping the invitation stage. The user will receive a notification by email that he or she has been added to the team. Because the user manages their own display name, it may be possible that the display name shown in the team overview differs from the display name the administrator used in the 'add team member' wizard.

A user can change their display name from the 'My Account' module in the Mailhardener dashboard, this will also be reflected in the team overview visible to the account administrator(s). If password authentication is used, the user can also change their email address and therefore their login identity. If the user uses SSO for login, the email address cannot be changed.

Updating access

The user role or domain ACL can be changed by clicking the edit button (pencil icon) behind the role or access control list. Roles can be up or downgraded to higher or lesser privileged access. Domain access (ACL) can be changed or removed at any time.

Users with Account Administrator role always have access to all domains, no ACL can be configured for these users. Domain Administrators cannot change their own role.

Revoking access

Revoking access is also performed via the 'team' module by clicking the delete (trashcan) icon. After confirming the user will no longer have access to the Mailhardener environment the organization. Because Mailhardener is a multi-tenant application the user account may continue to exist, albeit without access to the Mailhardener environment of the team the user was removed from. The user will receive an email notification informing them that access to the team has been revoked.

Each Mailhardener account requires at least one user with Account Administrator role, it is not possible to remove an account administrator if this would leave the account unmanaged.

Due to the multi-tenant nature of Mailhardener, revoking access of a user may not delete the user account itself from Mailhardener. The user may still be able to log in to Mailhardener, but will no longer have access to your Mailhardener environment.

User roles (RBAC)

Mailhardener features role-based access control (RBAC). Available roles depend on the type of account (regular single-tenant interface, or MSP multi-tenant interface) and type of user (regular or API client).

Regular user roles

For regular Mailhardener environments, the following roles are available:

• Account Administrator — highest privileged role, has access to all modules, including billing and team (user) management.
• Domain Administrator — can manage domains and domain settings, cannot access billing or team (user) management settings.
• Domain Viewer — read-only account. Can view domains and reports, cannot make changes to domains or domain settings.

MSP administrator roles

Mailhardener customers using the 'Mailhardener for MSP' solution receive access to the Mailhardener multi-tenant interface, also known as the MSP portal. Client environments (tenants) are managed from the MSP portal. Users with access to the MSP portal (the employees of the MSP) can be assigned one of the following roles:

• MSP Account Administrator — highest privileged role, has access to all modules, including billing and team (user) management.
• MSP Customer Administrator — can manage customers (tenants), manage users for tenants, manage domains and domain settings, cannot access billing or team management settings of the MSP account itself.
• MSP Customer Viewer — read-only account. Can view tenants, tenant users, domains and reports, cannot make changes to tenants, domains or domain settings.

If user access is granted to a tenant (a customer of the MSP) then regular user roles apply to those users.

API client roles

API clients have access to API endpoints based on role similar to that of regular users. API clients cannot be restricted to a domain subset (ACL).

• API Account Access — highest privileged role, has access to all API endpoints, including billing and team (user) management.
• API Domain Access — read/write access to API endpoints to manage domains and domain settings, cannot access billing or team (user) management API endpoints.
• API Domain Viewer — read-only account. Can access API endpoints for domains and reports, cannot make changes to domains or domain settings.

Selective resource access (ACL)

For regular users (not API client or MSP portal users) with lower-privileged roles (not Account Administrator) it is possible to restrict the access to a subset of domains using an Access Control List (ACL). This can be configured by account administrators via the 'team' module in the Mailhardener Dashboard.

When creating, or updating a user account a selection of domains can be made this user will have access to. The domain list can be updated at any time, the domain access restriction can also be disabled at any time, allowing the user access to all domains. This feature is not available for the Account Administrator role (the highest privileged role), users with Account Administrator role always have access to all domains.

For subdomain access control the subdomain must be added to the Mailhardener Dashboard as a separate domain, before it can be added to an ACL.

For team members that are not restricted in domain access (showing as 'all domains' in the Mailhardener Dashboard) any newly added domain will automatically become visible.

MSP multi-tenant support

The 'Mailhardener for MSP' solution features a multi-tenant environment enabling Managed Service Providers (MSPs) to provide and manage isolated Mailhardener environments (tenants) to their respective clients. In this case the 'multi-tenant' term is used to indicate that in MSP mode there are multiple isolated Mailhardener environments that can be managed from a single interface.

MSPs receive access to the 'MSP portal', which is the MSP-specific interface within the Mailhardener Dashboard application. The MSP portal is an interface 'above' the tenants, allowing the MSP to supervise their client's Mailhardener Dashboard environments. For MSP use, a differentiation is made between MSP user accounts (MSP employees) and tenant user accounts (customer employees). MSP user accounts can supervise (view) the tenant environments, whereas tenant user accounts are isolated to their respected environment.

MSP user accounts can also be multi-tenant themselves, for example: an MSP employee can be a team member in an MSP account, and also be a team member in a regular (non-MSP) environment that isn't managed by the MSP already. Switching between the MSP account and the regular account changes the Mailhardener Dashboard application interface between the MSP portal view and regular Mailhardener Dashboard view seamlessly.

Two-factor authentication (2FA)

For email/password authentication and OpenID Connect SSO, Mailhardener supports two-factor authentication (2FA) using TOTP authentication codes (RFC6238). Any authenticator app of choice can be used, such as Google Authenticator or Microsoft Authenticator.

2FA enforcement

The Mailhardener Dashboard supports 2FA enforcement per user role. If 2FA is required then users that do not have 2FA enabled will be required to set up 2FA upon next login.

Available options are:

• Do not require 2FA - users may set up a 2nd factor, but this is not required. Users without 2FA may still log in to the Mailhardener environment.
• Require 2FA for account administrator role - users with 'Account Administrator' role are required to use 2FA. Users with less privileged accounts are not required to use 2FA, but may still use 2FA.
• Require 2FA for domain administrators role or higher - users with 'Domain Administrator' role or higher ('Account Administrator') are required to use 2FA. Users with less privileged accounts (Viewer) are not required to use 2FA, but may still use 2FA.
• Always require 2FA, for all roles - All users are required to use 2FA for access to the Mailhardener environment.

2FA enforcement can be configured in the 'team' module of the Mailhardener Dashboard, this requires the Account Administrator role to access.

When enforcing 2FA, the user account which is making this change must have 2FA enabled to prevent account lockout. Any other user accounts that do not have 2FA enabled will be prompted to set up 2FA TOTP on next login.

2FA can be combined with SSO, but may result in a double 2FA prompt in the login flow, see section 'Combining 2FA and SSO' below.

2FA reset

If a user loses access to their TOTP code, then 2FA can be reset by an Account Administrator for other users from the 'team' module in the Mailhardener Dashboard. Resetting TOTP is performed by clicking on the 'reset TOTP' icon (circular arrow icon) in the '2FA' column of the team overview table.

An email notification will be sent to the user indicating the 2FA code has been reset by the administrator, additionally this event is logged in the audit log.

Resetting 2FA removes the 2nd factor TOTP code for the user. Upon next successful authentication (using password authentication or SSO) the user will not be prompted for 2FA, unless 2FA is enforced for the Mailhardener environment. When TOTP is required for the environment the user will be prompted to set up a new OTP code upon next successful authentication.

When using (and especially when enforcing) 2FA, it is recommended to have at least two users with Account Administrator role to prevent account lockout. In the event of accidental account lockout due to loss of TOTP, please contact Mailhardener support.

Single Sign-on (SSO)

Mailhardener supports Single Sign On (SSO) for logging in to the Mailhardener Dashboard application using the OpenID Connect (OIDC) protocol.

Currently, the following identity providers are supported:

• Microsoft Entra ID (Microsoft Azure AD and Microsoft Personal Account (MSA))
• Google Accounts (Google Workspace, GMail, etc.)

Other SSO providers may be added in the future. If your preferred SSO provider is not currently supported, please contact Mailhardener support to register your interest.

For enterprise customers it is possible to authenticate with Mailhardener using a self-hosted SSO solution (on-premise or cloud hosted) either via OIDC (preferred) or SAML. Please contact Mailhardener sales for discussing possibilities.

Combining 2FA and SSO

Account administrators should understand that combining SSO with 2FA may cause the login flow to ask for 2FA twice: once by the SSO identity provider, and once by Mailhardener.

OpenID connect is an off-site authentication flow, users are directed away from the application to perform the authentication on the secure authentication page hosted by the IDP. Authentication requirements are controlled by the administrator of the corporate account of the SSO tenant. Service providers implementing OIDC (Mailhardener, in this case) cannot control whether 2FA is required during the authentication flow as the IDP, nor will the IDP indicate whether 2FA was used when the user is redirected back to the application.

SSO enforcement

SSO login for the Mailhardener Dashboard can be enforced, restricted or disabled from the 'team' module in the Mailhardener Dashboard, the Account Administrator role is required to access these settings.

The following options are available:

• Do not enforce SSO (allow password login) — this allows users to use password-based authentication and SSO authentication. Users with password authentication may migrate their account to use SSO (with any IDP) at their own initiative.
• Enforce SSO using any provider — Enforcing SSO will require all users to authenticate using SSO (optional with 2FA). Any IDP is allowed. Users attempting to log in with password authentication will be denied access to the Mailhardener Dashboard, and will be prompted to migrate their account to use SSO authentication instead.
• Enforce SSO using [provider] — All users will be required to use SSO authentication flow with specified identity provider. Login using password authentication, or any other identity provider will be prompted to migrate to SSO with a specific provider.

When enforcement is enabled, users with a conflicting authentication method will be prompted to migrate their account to the enforce authentication option upon next login. New users added to the team will exclusively see the authentication options available for the tenant when creating their user account (accepting the invitation).

SSO setup

SSO support for all IDPs is enabled by default for all new Mailhardener tenants.

Mailhardener does not require setup for using OIDC SSO, but depending on the account settings at the IDP it may be required to approve Mailhardener as a trusted application.

For Google accounts ensure the following application ID is added at trusted application:

348556459797-u2srgi6srm409hp1lpb3daurdopop5ja.apps.googleusercontent.com

For Microsoft Entra ID ensure the following application ID is added at trusted application:

e03cae52-4fc3-4368-acf6-ce042b59a632

Migrating existing users to SSO

Existing user accounts using password authentication can be migrated to use SSO authentication instead. This action requires a successful authentication of the account at the IDP, so this migration must be performed by the user itself.

Migration is only possible if the SSO account identifier (the email address) matches that of the user account known to Mailhardener. After migration to SSO, the user can no longer change their email address (SSO identity), nor can a user migrate to a different SSO provider (if allowed by the SSO enforcement policy).

To migrate an account from password authentication to SSO authentication using the same email address for SSO identity as the Mailhardener identity, the user must:

• Navigate to the Mailhardener Dashboard
• Log out in case any existing session is active
• Select 'continue with {IDP}' button in the Mailhardener Dashboard login prompt
• Perform the regular SSO authentication flow with selected IDP, using their SSO identity with matching email address.
• After successful SSO login flow the user will be prompted to migrate their account to use SSO instead.
• Migrating from password login to SSO login destroys the stored password hash, so this action is not reversible.

To migrate a user to SSO that registered with Mailhardener using a different email address, the user should first update their email address for their user account. To do this the user should:

• Log in using password authentication,
• Navigate to the 'My Account' module of the Mailhardener Dashboard
• Change their email address to match that of the SSO identity (note: this is only allowed when using password authentication)
• Log out, then perform the regular SSO migration flow using the new email address as identity. Due to multi-tenant support it is not allowed for Account Administrators to change the email addresses of team members.
• If the Mailhardener environment is already set up for SSO enforcement then that will prevent the user to authenticate with password to change email address. In such a case an Account Administrator should add the SSO identity as a new team member via the 'team' module in the Mailhardener Dashboard, and revoke access of the former user account.

Migration of a user with SSO to use a different SSO identity provider is not allowed by default. To migrate an existing SSO identity to use a different identity provider, please contact Mailhardener customer support.

Best practices

Mailhardener allows for various options to provide authentication options for an as wide audience as possible. Which settings are best for which customer depend on the preferred authentication method of the customer and the security policies of the organization.

Generally, it is recommended to use SSO if your organization uses an identity provider that is supported by Mailhardener. When doing so, it is recommended to enforce SSO and limit it to the IDP of choice (select 'Enforce SSO using [IDP]'), unless you are planning to provide access to third parties (for example: external auditors).

Enabling TOTP 2FA is recommended for users that use password authentication with Mailhardener. TOTP can also be added for SSO use, but may result in double TOTP prompts (once by the SSO provider, once by Mailhardener), it is recommended to set up a multifactor policy on the SSO provider side instead.

When using 2FA, especially when enforced, it is recommended to have at least two users with Account Administrator role to prevent account lockout.

External integrations

Mailhardener supports integrating with third-party applications. This is currently used for the 'Mailhardener for MSP' package, offering integrations with third-party PSA and ticketing services. For third-party integrations Mailhardener supports OpenAuth 2.0 authentication for Mailhardener to interact with a third-party account.

Third party integrations are managed from the 'integrations' module in the MSP portal. The MSP account administrator role is required to manage integrations.

FAQ

How many team members can I add?

Mailhardener does not limit the number of team members (users) for Mailhardener environments.

If your package has multi-user support (that is: all packages except Mailhardener Free) then you can add unlimited team members.

Which packages support SSO?

All tiers, including Mailhardener Free, support SSO and TOTP 2FA, with enforcement.

We believe that security should be accessible to everyone, and not be a paid feature.

Why am I asked for 2FA TOTP twice?

When enabling 2FA TOTP with Mailhardener and combining that with SSO, then it is possible that during the authentication flow the user is asked for two TOTP codes. Once by the SSO identity provider (for example: Microsoft Entra), and once by Mailhardener itself.

This is caused by limitations of the OpenID-connect protocol (the protocol that enables SSO). Unfortunately, the Service Provider (Mailhardener, in this case) cannot specify whether 2FA should be required in the SSO authentication flow, nor does the IDP indicate whether 2FA was used after successful authentication.

How do I limit SSO to corporate managed identities only?

A common concern of corporate/enterprise account administrators is how to 'lock' SSO user accounts to only allow SSO login with identities managed by the organization.

Unfortunately, OpenID Connect (the protocol used for SSO login with Microsoft Entra, Google Accounts, etc.) does not expose the tenant ID to the Service Provider (Mailhardener, in this case). This prevents Mailhardener from offering the option to 'only allow SSO logins with accounts managed by [Acme Corp]' kind of feature.

However, we do allow locking the SSO logins to a specific SSO identity provider. Since identity providers use the email-address as the username, it must be unique. None of the identity providers allow multiple accounts with the same email address. For example: it is not possible to register a personal account with Microsoft that matches the email address used by their employer's Azure AD identity.

How do I limit access to corporate email addresses only?

Following the 'locking SSO to corporate tenant' question, the common followup question we receive is if account administrators can limit access to their Mailhardener environment to only allow @example-corp.com email addresses.

This is possible by leveraging SSO enforcement. Account Administrators control which users are added to the team, they should only invite team-members (users) that match the access requirements of their organization. Users with SSO login are not able to change their email address, or migrate to a different identity provider.

Only users with the 'Account Administrator' role (the highest privilege role) have access to the IAM settings, only they can add new team members to their environment. Because Account Administrators can also manage authentication settings/policies of the account, offering the option to restrict accounts to use an email address with a specific domain suffix would not serve a practical purpose.

Why does user information change after adding a team member?

Users are allowed to change their display name from the 'My Account' module in their Mailhardener Dashboard. If a user changes the display name, it will also be reflected on the 'team' module visible to Account Administrators.

Adding a new team member requires the Account Administrator to enter a display name and an email address. Due to Mailhardener being multi-tenant it is possible that the user account already exists when inviting a new team member. In that case the display name chosen by the Account Administrator is ignored and the name chosen by the user is displayed instead.

Why does deleting, then adding a user still show the same IDP?

Deleting a team member revokes access to the team, the user account itself will continue to exist as the user may still be a member of a different team. Hence, re-adding the same team member (by email address) will then show the user with the same display name, identity provider (IDP) and TOTP settings.

If a team-member must be migrated to a different SSO identity provider using the same email address, please contact Mailhardener support.

Can I use automated provisioning?

Access and Identity Management (IAM) is typically performed from the 'team' module in the Mailhardener Dashboard application.

Automated provisioning and de-provisioning of user accounts (sometimes known as 'directory management') is possible by using the Mailhardener API to automatically (de)provisioning, updating and reporting of user accounts.

For customers with access to the MSP portal automated provisioning of tenants can also be achieved using selected PSA integrations.

Mailhardener does not (yet) support automated provisioning using the SCIM 2.0 protocol, but this may be added in the future.

How do I bulk-insert users?

For one-time bulk-insertion of user accounts without using the API or PSA integration, please contact Mailhardener customer support.

Does Mailhardener support my self-hosted SSO solution?

Authenticating with Mailhardener using a self-hosted SSO solution is possible, for as long as the SSO solution supports the OpenID-Connect 2.0 (OIDC 2.0) protocol. Custom SSO endpoint integration is available on request for enterprise customers only.

On-premise identity solutions that support OIDC (for example: Keycloak) will require Mailhardener to be able to access the service, which may require a VPN connection. This is possible, but will require collaboration between Mailhardener and customer infrastructure teams.

For more details, please contact Mailhardener sales to discuss possibilities.

Does Mailhardener support SAML?

SAML-based authentication is not supported by default, but available on request for enterprise customers only.

For Microsoft Enterprise Azure AD, Microsoft does recommend using Microsoft Entra ID over SAML for new integrations. Microsoft Entra ID (via OIDC) is fully supported by Mailhardener out-of-the-box.

On-premise identity solutions that support SAML (for example: Microsoft Active Directory) will require Mailhardener to be able to access the service, which typically requires a VPN connection. This is possible, but will require collaboration between Mailhardener and customer infrastructure teams.

For more details, please contact Mailhardener sales to discuss possibilities.