Set up multi-factor authentication¶
Multi-factor authentication (MFA) asks the user for a second proof in addition to their identifier and password. CyberElements offers several ways to obtain one. This page covers four of them, in the order in which they are usually considered, then details the one that has no integration page of its own: the one-time password sent by email.
Four factors, not the whole picture
These four are the ones this page walks through — they are not the only second factors the platform can request. Also available, and outside the scope of this page:
- an OTP sent by SMS, through one of the many operators offered by the OTP Token Generators module;
- a Radius connector towards a third-party MFA solution, through the OTP - Radius type of that same module;
- authentication by x509 certificate, which is not a token but an authentication method of the domain itself — User certificate, or User certificate and form to keep the password as well;
- an MFA enforced upstream by a SAML provider, or by any other delegated authentication. The second factor is then requested before the platform is involved, which neither configures nor sees it.
MFA is set on the identity provider, never on a user
Whichever factor you pick, it is enabled on an identity provider and applies to every user who signs in through it. There is no per-user setting: to subject only part of your population to MFA, put those users behind a dedicated identity provider.
Choosing a factor¶
| Factor | What the user does | What it requires | Procedure |
|---|---|---|---|
| Neomia Pulse | Nothing. The user is recognised by the way they type on their keyboard. | The Neomia Pulse option, an identity provider of type local or LDAP, and a second factor from this table on the same provider. |
Neomia Pulse integration |
| FIDO2 | Presents their authenticator — plugging in a security key, or approving on the device or the vault that holds the passkey — then enters a PIN if the authenticator asks for one. | A FIDO2 authenticator per user, a relying party declared in the console, and a personal account — an anonymous identity provider is excluded. | Yubico integration |
| TOTP | Reads a six-digit code in an authenticator application. | An application on the user's phone or workstation (Google Authenticator, FreeOTP, Microsoft Authenticator, and so on) and one enrolment per user. | Google Authenticator integration |
| OTP by email | Copies a code received by email. | An SMTP server reachable by the platform and an email address held in a user attribute. | Setting up an OTP by email |
Neomia Pulse is configured on top of another factor
Enabling Neomia Pulse requires another MFA to be enabled on the same domain. Its settings then decide what that other factor is used for: it can be skipped when Pulse validates the user, and required when Pulse does not. Neomia Pulse is therefore a way to spare the second factor rather than to replace it.
Where each factor is declared, and where it is enabled¶
The configuration has two possible stages — declaring the factor in its own module, then enabling it on the identity provider — but two of the four skip one of them:
| Factor | Declared in | Enabled on the identity provider |
|---|---|---|
| Neomia Pulse | nothing to declare | ✅ the Enable neomia Pulse authentication option |
| FIDO2 | Relying parties | ❌ nothing to enable — see the note below |
| TOTP | OTP Token Generators | ✅ as an authentication token |
| OTP by email | an SMTP server, then OTP Token Generators | ✅ as an authentication token |
FIDO2 has no switch on the identity provider
Security keys are not enabled provider by provider: the platform offers the factor as soon as at least one relying party is declared, on every identity provider that is not anonymous — a key has to be attached to a personal account. And it is the user who enrols their authenticator from the portal, not the administrator who assigns it.
Neomia Pulse has nothing to declare beforehand
Pulse is not a token to be created in a module: the option is enabled directly on the identity provider, which is also where its behaviour is set.
The rest of this page covers the OTP by email end to end. The three other factors are covered by their integration page, linked in the table above.
Setting up an OTP by email¶
An OTP by email sends the user a single-use code by email once their identifier and password have been accepted. The user enters that code on the portal to finish signing in.
Before you start: what an OTP by email actually protects¶
An OTP by email does not always add a factor
Read this before choosing this factor over the three others.
If the user signs in with their Active Directory account and collects the code from a mailbox attached to that same account, the second factor adds close to nothing: an attacker who has obtained the credentials opens the mailbox with those very credentials and reads the code.
An OTP by email is worth deploying when the mailbox is not reachable with the credentials being checked, that is when:
- the user signs in with a local account, or with an account distinct from their mailbox;
- the code is sent to an address other than the one belonging to the sign-in account.
Step 1 — Have an SMTP server available¶
The code is sent by the platform through an SMTP server declared in the SMTP servers module. If none is available yet, declare one before going any further:
Then use the SMTP configuration test block of that module to confirm delivery: a failure diagnosed at this stage is a failure you will not be looking for later in the sign-in flow.
The test message does not use the sender you will configure
The test sends from noreply@cleanroom.com, an address written into the product: it cannot be changed anywhere, and it also serves as the reply-to address. Your own sender is the SMTP sender of the token, set in step 2 — it is the one the real OTP messages carry.
The consequence is worth knowing before you conclude: an SMTP server that restricts sending addresses can reject the test while letting the actual messages through, and the other way round.
The connection is opened by the platform
The flow to the SMTP server leaves from the platform, not from the user's workstation. If your SMTP server sits on your LAN, that flow must be allowed.
Step 2 — Create the OTP token¶
Open the OTP Token Generators module and click +. In the Add OTP token window, select the OTP - email type, then fill in the fields.
| Field | What to enter |
|---|---|
| OTP Type | OTP - email. This choice cannot be changed afterwards — a different channel means a different token. |
| Name | The name of the token. It is shown to the user on the portal, so it should read as a factor name rather than as an internal reference. |
| Description | Free text, visible to administrators only. |
| OTP usable characters | The alphabet the code is drawn from. |
| OTP Length | The number of characters in the code. |
| Validity period of a token (seconds) | How long the user has to enter the code before it is refused. |
| Message before the OTP | The sentence preceding the code in the message body. |
| Mail subject | The subject of the message. |
| SMTP sender | The sender address of the message. |
| SMTP server | The server declared in step 1. |
The complete list of fields, with their default values and constraints, is in the reference page: Generic block and Email delivery.
Click Validate to save the token.
Step 3 — Enable the token on an identity provider¶
Open the Identity Providers module and edit the provider that should request the OTP.
| Field | What to enter |
|---|---|
| Authentication token | The token created in step 2. Several tokens can be selected. |
| User attribute used to send the OTP | The name of the user attribute holding the address the code is sent to. |
| Token expiration duration | How long a validated OTP remains accepted before it is requested again. 0 disables expiration, which means the OTP is requested at every sign-in. |
| Time unit | Hours or Days, applied to the previous field. |
| Expiration starts | Whether the countdown starts at the last OTP validation or at the last successful sign-in. |
Which attribute holds the address
The attribute is the one of the directory the identity provider points at, not a name of our choosing: use the attribute your users actually carry an address in. For a local directory, the address entered in the user's properties is the one to target; for an LDAP directory, it is the directory's own mail attribute.
Click Validate. The users of that identity provider are asked for a code on their next sign-in.
Step 4 — Check on a test identity provider first¶
Enabling MFA on an identity provider applies it to every user behind it, including yourself if you sign in through it. Before enabling the token on your production provider, create a test identity provider carrying a single account and run a full sign-in through it: identifier, password, receipt of the message, entry of the code.
A user with no address never receives a code
A user whose attribute is empty cannot be sent anything, and their sign-in cannot complete. Check that the attribute is filled in for every account behind the identity provider before enabling the token on it.