Last updated
Was this helpful?
Last updated
Was this helpful?
This article includes guides for implementing two-factor authentication options for both backoffice users and website members:
Two-factor authentication (2FA) for Umbraco Users and Members is activated by implementing an ITwoFactorProvider
interface and registering the implementation. The implementation can use third-party packages to support authentication apps like the Microsoft- or Google Authentication Apps.
The following guide will take you through implementing an option for your website members to enable two-factor authentication.
As an example, the guide will use the . This package works for both Google and Microsoft authenticator apps. It can be used to generate the QR code needed to activate the app for the website.
Install the GoogleAuthenticator Nuget Package on your project.
Create a new file in your project: UmbracoAppAuthenticator.cs
.
Update the file with the following code snippet.
Update namespace
on line 7 to match your project.
Customize the applicationName
variable on line 64.
Create a Composer and register the UmbracoAppAuthenticator
implementation as shown below.
At this point, the 2FA is active, but no members have set up 2FA yet. The setup of 2FA depends on the type. In the case of App Authenticator, the view showing the option to edit member profiles needs to be modified.
Add or choose a members-only page that should have the two-factor authentication setup.
The page needs to be behind the public access.
The page should not be using strongly types models.
Open the view file for the selected page.
Add the following code:
Update the @using
in line 4 to match the namespace of your project.
[Optional] Customize the text fields and buttons to match your websites tone of voice (lines 33-39).
Login to the website using a test member.
Navigate to the page where the QR code was added.
Scan the QR code and add the verification code.
Logout of the website.
Login and verify that it asks for the two factor authentication.
You can also check that the Two-factor Authentication option is checked on the member in the Umbraco backoffice.
The following guide will take you through implementing an option for backoffice users to enable two-factor authentication.
This guide will not cover setting up the UI for user login and edits as this is handled elsewhere in the CMS.
Install the GoogleAuthenticator Nuget Package on your project.
Create a new file in your project: UmbracoUserAppAuthenticator.cs
.
Update the file with the following code snippet.
Update namespace
on line 7 to match your project.
Customize the applicationName
variable on line 59.
Create a new file in your project: UmbracoUserAppAuthenticatorComposer.cs
.
Implement a new composer and register the UmbracoUserAppAuthenticator
implementation as shown below.
Update the namespace
on line 4 to match your project.
With the 2FA in place, the provider needs to be registered in the backoffice client so the user can use it.
Add a new file to your project directory: ~/App_Plugins/TwoFactorProviders/umbraco-package.json
.
Add the following code to the new file:
At this point, the 2FA is active, but no users have set up 2FA yet.
Each user can now enable the configured 2FA providers on their user.
Access the Umbraco backoffice.
Click the user avatar in the top-right corner.
Select Configure Two-Factor
button to get a list of all enabled two-factor providers.
Select Enable
to show the configured view.
Follow the instructions to configure 2FA.
When the authenticator is enabled correctly, a disable button is shown instead.
To disable the two-factor authentication on your user, it is required to enter the verification code.
If the code is correct, the provider is disabled.
When a user with 2FA enabled logs in, they will be presented with a screen to enter the verification code:
While the 2FA is enabled, the user will be presented with this screen after entering the username and password.
If the code is correct, the user will be logged in. If the code is incorrect, the user will be presented with an error message.
This screen is set up to work well with 2FA providers that require a one-time code to be entered. The code field follows best practices for accessibility in terms of labeling and autocompletion.
The 2FA experience can be customized in Umbraco. This can be done by creating a custom view for the activation screen and the login screen. This is useful if you have a 2FA provider that requires something else than a one-time code to be entered.
The following examples show how to customize the 2FA activation screen and the 2FA login screen.
The examples are using the @umbraco-cms/backoffice
package to get access to the Umbraco backoffice components and services. This package is included in Umbraco and can be used to create custom elements that look and feel like the rest of the Umbraco backoffice.
The 2FA activation screen can be customized. This should be done if you have a 2FA provider that does not require a one-time code to be entered.
To customize the 2FA activation screen, you need to create a JavaScript module. The module should export a default custom element to be used in the activation screen. This module should be placed in the App_Plugins/TwoFactorProviders
folder.
This module will show a QR code and an input field for the user to enter the code from the authenticator app. When the user submits the form, the code will be sent to the server to validate. If the code is correct, the provider will be enabled.
To replace the default activation screen with the custom view, you need to register the element in the umbraco-package.json
file that you created before. The final form of the file should look like this:
The 2FA login screen can also be customized. This should be done if you have a 2FA provider that requires something else than a one-time code to be entered.
You should only customize the 2FA login screen in certain cases, for example:
If you have a provider that requires a non-numeric field or additional info.
If you have a provider that requires the user to scan a QR code, you should additionally show the QR code.
If you need to authenticate the user in a different way than the default option.
You need to create a JavaScript module that exports a default custom element to be used in the login screen. This module should be placed in the App_Plugins
folder. The module should be registered using a composer.
You can use the following code as a starting point. This will give you a view looking like this, where the user can enter a code and click a button to verify the code. This is similar to the built-in view in Umbraco. In a real world scenario, you would probably want to authenticate the user in a different way.
The element registers two properties: providers and returnPath. These properties are used to render the view. The providers property is an array of strings, where each string is the name of a 2FA provider. The returnPath is the path to redirect to after a successful login. Both supplied by the login screen automatically.
We need to register the custom view using a composer. This can be done on the IUmbracoBuilder
in your startup or a composer. In this case, we will add a composer to your project. This composer will overwrite the IBackOfficeTwoFactorOptions
to use the custom view.
When a 2FA login is requested for a member, the MemberTwoFactorRequestedNotification
is published. This notification can also be used to send the member a one-time password via e-mail or phone. Even though these 2FA types are as App Authentication, it is still a massive improvement compared to no 2FA.
As an example, the guide will use the . This package works for both Google and Microsoft authenticator apps. It can be used to generate the QR code needed to activate the app for the website.
When a 2FA login is requested for a user, the UserTwoFactorRequestedNotification
is published. This notification can also be used to send the user a one-time password via e-mail or phone. Even though these 2FA types are as App Authentication, it is still a massive improvement compared to no 2FA.
The examples are using the library to create custom elements. This is the recommended way of creating custom elements in Umbraco. Lit is a light-weight library that augments the to provide a declarative, performant, and interoperable way to create web components.
They are written in vanilla JavaScript and C#, but the same principles can be applied to other languages. For more information about creating custom elements in Umbraco with a bundler and TypeScript, see the article.
The following code is an example of a custom 2FA login screen using . This is the recommended way of creating a custom 2FA login screen. Lit is a light-weight library that augments the to provide a declarative, performant, and interoperable way to create web components.
Umbraco users and members support a two-factor authentication (2FA) abstraction for implementing a 2FA provider of your choice.