Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CMS 13: Two Factor authentication for Users #6809

Merged
merged 1 commit into from
Jan 24, 2025
Merged

CMS 13: Two Factor authentication for Users #6809

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added 13/umbraco-cms/reference/security/images/2fa-user-disable.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
106 changes: 73 additions & 33 deletions 13/umbraco-cms/reference/security/two-factor-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ This article includes guides for implementing two-factor authentication options
* [Two-Factor Authentication for Members](#two-factor-authentication-for-members)
* [Two-Factor Authentication for Users](#two-factor-authentication-for-users)

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.
sofietoft marked this conversation as resolved.
Show resolved Hide resolved

{% hint style="info" %}

If you are using [Umbraco Cloud](https://umbraco.com/products/umbraco-cloud/), you can enable multi-factor authentication in Umbraco ID. For more information, see the [Multi-Factor Authentication](https://docs.umbraco.com/umbraco-cloud/set-up/multi-factor-authentication-on-cloud) article.
Expand All @@ -19,8 +21,6 @@ If you are using [Umbraco Cloud](https://umbraco.com/products/umbraco-cloud/), y

## Two-factor authentication for Members

Two-factor authentication (2FA) for Umbraco 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.

{% hint style="info" %}
Expand Down Expand Up @@ -224,7 +224,7 @@ At this point, the 2FA is active, but no members have set up 2FA yet. The setup

![The QR Code is shown along with a field to enter a value to set up the two factor authentication.](images/2fa-Members-QR-code.png)

### Test the set up
### Test the set up for Members

1. Login to the website using a test member.
2. Navigate to the page where the QR code was added.
Expand All @@ -242,11 +242,19 @@ When a 2FA login is requested for a member, the `MemberTwoFactorRequestedNotific

## Two-factor authentication for Users

Umbraco controls how the UI is for user login and user edits, but will still need a view for configuring each 2FA provider.
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.

### Example implementation for Authenticator Apps for Users

In the following example, we will use the [GoogleAuthenticator NuGet Package](https://www.nuget.org/packages/GoogleAuthenticator/). Despite the name, 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.
As an example, the guide will use the [GoogleAuthenticator NuGet Package](https://www.nuget.org/packages/GoogleAuthenticator/). 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.

1. Install the GoogleAuthenticator Nuget Package on your project.
2. Create a new file in your project: `TwoFactorAuthInfo.cs`.
3. Update the file with the following code snippet.

{% code title="TwoFactorAuthInfo.cs" lineNumbers="true" %}

```csharp
using System.Runtime.Serialization;
Expand All @@ -257,6 +265,9 @@ using Umbraco.Cms.Core.Services;

namespace My.Website;

/// <summary>
/// Create a model with the information required to set up the 2FA provider
/// </summary>
[DataContract]
public class TwoFactorAuthInfo
{
Expand All @@ -268,7 +279,7 @@ public class TwoFactorAuthInfo
}

/// <summary>
/// App Authenticator implementation of the ITwoFactorProvider
/// Implement the `ITwoFactorProvider` with the use of the `TwoFactorAuthenticator` from the GoogleAuthenticator NuGet package
/// </summary>
public class UmbracoUserAppAuthenticator : ITwoFactorProvider
{
Expand Down Expand Up @@ -307,8 +318,9 @@ public class UmbracoUserAppAuthenticator : ITwoFactorProvider

ArgumentNullException.ThrowIfNull(user);

var applicationName = "My application name";
var twoFactorAuthenticator = new TwoFactorAuthenticator();
SetupCode setupInfo = twoFactorAuthenticator.GenerateSetupCode("My application name", user.Username, secret, false);
SetupCode setupInfo = twoFactorAuthenticator.GenerateSetupCode(applicationName, user.Username, secret, false);
return Task.FromResult<object>(new TwoFactorAuthInfo()
{
QrCodeSetupImageUrl = setupInfo.QrCodeSetupImageUrl,
Expand All @@ -333,17 +345,19 @@ public class UmbracoUserAppAuthenticator : ITwoFactorProvider
}
```

First, we create a model with the information required to set up the 2FA provider. Then we implement the `ITwoFactorProvider` with the use of the `TwoFactorAuthenticator` from the GoogleAuthenticator NuGet package.
{% endcode %}

4. Update `namespace` on line 7 to match your project.
5. Customize the `applicationName` variable on line 59.
6. Create a new file in your project: `UmbracoAppAuthenticatorComposer.cs`.
7. Implement a new composer and register the `UmbracoAppAuthenticator` implementation as shown below.

Now we need to register the `UmbracoUserAppAuthenticator` implementation and the view to show to set up this provider. This can be done on the `IUmbracoBuilder` in your startup or a composer.
{% code title="UmbracoAppAuthenticatorComposer.cs" lineNumbers="true" %}

```csharp
using Microsoft.Extensions.DependencyInjection;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Security;
using Umbraco.Cms.Web.BackOffice.Security;
using Umbraco.Extensions;

namespace My.Website;

Expand All @@ -363,7 +377,18 @@ public class UmbracoAppAuthenticatorComposer : IComposer
}
```

Now we need to create the view we configured, in the path we choose.
{% endcode %}

8. Update the `namespace` on line 5 to match your project.

In the composer above, a view for the two-factor authentication is configured. This view needs to be created.

9. Open the project directory.
10. Locate or create the path as defined in the composer above: `App_Plugins\TwoFactorProviders`.
11. Create a new file: `twoFactorProviderGoogleAuthenticator.html`.
12. Open the file and add the following markup:

{% code title="twoFactorProviderGoogleAuthenticator.html" lineNumbers="true" %}

```html
<div ng-controller="CustomCode.TwoFactorProviderGoogleAuthenticator as vm">
Expand Down Expand Up @@ -430,19 +455,14 @@ Now we need to create the view we configured, in the path we choose.
</div>
```

As this view uses an angular controller, we need to create that class and configure it in the `package.manifest`.
{% endcode %}

In `package.manifest`, we point to the path of the angular controller that we are creating in the next step.
The view above uses an Angular controller, which needs to be created and configured in a `package.manifest` file.

```json
{
"javascript": [
"~/App_Plugins/TwoFactorProviders/twoFactorProviderGoogleAuthenticator.controller.js"
]
}
```
13. Create a new file: `App_Plugins/TwoFactorProviders/twoFactorProviderGoogleAuthenticator.controller.js`.
14. Add the following code:

And we create the controller in that location:
{% code title="twoFactorProviderGoogleAuthenticator.controller.js" lineNumbers="true" %}

```javascript
!(function () {
Expand Down Expand Up @@ -514,29 +534,49 @@ And we create the controller in that location:
})();
```

At this point, the 2FA is active, but no users have set up 2FA yet.
{% endcode %}

15. Create a new file: `App_Plugins\TwoFactorProviders\package.manifest`.
16. Point to the path of the Angular controller created above:

Each user can now enable the configured 2fa providers on their user. This can be done from the user panel by clicking the user avatar.
{% code title="package.manifest" lineNumbers="true" %}

```json
{
"javascript": [
"~/App_Plugins/TwoFactorProviders/twoFactorProviderGoogleAuthenticator.controller.js"
]
}
```

{% endcode %}

At this point, the 2FA is active, but no users have set it up.

### Test the set up for Users

Each user can now enable the configured 2fa providers on their user.
sofietoft marked this conversation as resolved.
Show resolved Hide resolved

1. Access the Umbraco backoffice.
2. Click the user avatar in the top-right corner.

![User panel](images/user-panel.png)

When clicking the `Configure Two-Factor` button, a new panel is shown, listing all enabled two-factor providers.
3. Select `Configure Two-Factor` button to open a new panel listing all enabled two-factor providers.

![Configure 2fa](images/configure-2fa.png)

When clicking `Enable` on one of these, the configured view for the specific provider will be shown
4. Select `Enable` to show the configured view.

![Enable 2fa](images/enable-2fa.png)

When the authenticator is enabled correctly, a disable button is shown instead.
5. Follow the instructions to configure 2FA.

![Disable 2fa](images/disable-2fa.png)

To disable the two-factor authentication on your user, it is required to enter the verification code. Otherwise, admins are allowed to disable providers on other users.
When the authenticator is enabled correctly, a disable button is shown instead.

![Verify disable](images/verify-disable.png)
![Disable 2fa](images/2fa-user-disable.png)

If the code is correct, the provider is disabled.
To disable the two-factor authentication on your user, it is required to enter the verification code.

### Notification when 2FA is requested for a user

Expand Down
Loading