Skip to content

Commit be1471d

Browse files
committed
Update steps for the user guide
1 parent 2a7b678 commit be1471d

File tree

1 file changed

+40
-14
lines changed

1 file changed

+40
-14
lines changed

15/umbraco-cms/reference/security/two-factor-authentication.md

+40-14
Original file line numberDiff line numberDiff line change
@@ -242,13 +242,20 @@ When a 2FA login is requested for a member, the `MemberTwoFactorRequestedNotific
242242

243243
## Two-factor authentication for Users
244244

245-
Umbraco controls how the UI is for user login and user edits, but will still need a view for configuring each 2FA provider.
245+
The following guide will take you through implementing an option for backoffice users to enable two-factor authentication.
246+
247+
This guide will not cover setting up the UI for user login and edits as this is handled elsewhere in the CMS.
246248

247249
### Example implementation for Authenticator Apps for Users
248250

249-
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.
251+
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.
252+
253+
1. Install the GoogleAuthenticator Nuget Package on your project.
254+
2. Create a new file in your project: `UmbracoUserAppAuthenticator.cs`.
255+
3. Update the file with the following code snippet.
256+
257+
{% code title="UmbracoUserAppAuthenticator.cs" lineNumbers="true" %}
250258

251-
{% code title="TwoFactorAuthInfo.cs" lineNumbers="true" %}
252259
```csharp
253260
using System.Runtime.Serialization;
254261
using Google.Authenticator;
@@ -308,8 +315,9 @@ public class UmbracoUserAppAuthenticator : ITwoFactorProvider
308315

309316
ArgumentNullException.ThrowIfNull(user);
310317

318+
var applicationName = "My application name";
311319
var twoFactorAuthenticator = new TwoFactorAuthenticator();
312-
SetupCode setupInfo = twoFactorAuthenticator.GenerateSetupCode("My application name", user.Username, secret, false);
320+
SetupCode setupInfo = twoFactorAuthenticator.GenerateSetupCode(applicationName, user.Username, secret, false);
313321
return Task.FromResult<ISetupTwoFactorModel>(new TwoFactorAuthInfo()
314322
{
315323
QrCodeSetupImageUrl = setupInfo.QrCodeSetupImageUrl,
@@ -333,20 +341,23 @@ public class UmbracoUserAppAuthenticator : ITwoFactorProvider
333341
public bool ValidateTwoFactorSetup(string secret, string token) => ValidateTwoFactorPIN(secret, token);
334342
}
335343
```
344+
336345
{% endcode %}
337346

338-
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.
347+
4. Update `namespace` on line 7 to match your project.
348+
5. Customize the `applicationName` variable on line 59.
349+
6. Create a new file in your project: `UmbracoUserAppAuthenticatorComposer.cs`.
350+
7. Implement a new composer and register the `UmbracoUserAppAuthenticator` implementation as shown below.
339351

340-
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.
352+
{% code title="UmbracoUserAppAuthenticatorComposer.cs" lineNumbers="true" %}
341353

342-
{% code title="UmbracoAppAuthenticatorComposer.cs" lineNumbers="true" %}
343354
```csharp
344355
using Umbraco.Cms.Core.Composing;
345356
using Umbraco.Cms.Core.Security;
346357

347358
namespace My.Website;
348359

349-
public class UmbracoAppAuthenticatorComposer : IComposer
360+
public class UmbracoUserAppAuthenticatorComposer : IComposer
350361
{
351362
public void Compose(IUmbracoBuilder builder)
352363
{
@@ -356,11 +367,18 @@ public class UmbracoAppAuthenticatorComposer : IComposer
356367
}
357368
}
358369
```
370+
359371
{% endcode %}
360372

361-
The last thing required is to register the provider in the Backoffice client so that the user can enable it. This can be done in a `umbraco-package.json` file.
373+
8. Update the `namespace` on line 4 to match your project.
374+
375+
With the 2FA in place, the provider needs to be registered in the backoffice client in order for the user to be able to use it.
376+
377+
9. Add a new file to your project directory: `~/App_Plugins/TwoFactorProviders/umbraco-package.json`.
378+
10. Add the following code to the new file:
362379

363380
{% code title="~/App_Plugins/TwoFactorProviders/umbraco-package.json" lineNumbers="true" %}
381+
364382
```json
365383
{
366384
"$schema": "../../umbraco-package-schema.json",
@@ -379,27 +397,35 @@ The last thing required is to register the provider in the Backoffice client so
379397
]
380398
}
381399
```
400+
382401
{% endcode %}
383402

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

386-
* 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.
405+
### Test the set up for Users
406+
407+
Each user can now enable the configured 2FA providers on their user.
408+
409+
1. Access the Umbraco backoffice.
410+
2. Click the user avatar in the top-right corner.
387411

388412
![User panel](images/user-panel.jpg)
389413

390-
* When clicking the `Configure Two-Factor` button, a new panel is shown, listing all enabled two-factor providers.
414+
3. Select `Configure Two-Factor` button to get a list of all enabled two-factor providers.
391415

392416
![Configure 2fa](images/configure-2fa.jpg)
393417

394-
* When clicking `Enable` on one of these, the configured view for the specific provider will be shown
418+
4. Select `Enable` to show the configured view.
395419

396420
![Enable 2fa](images/enable-2fa.jpg)
397421

398-
* When the authenticator is enabled correctly, a disable button is shown instead.
422+
5. Follow the instructions to configure 2FA.
423+
424+
When the authenticator is enabled correctly, a disable button is shown instead.
399425

400426
![Disable 2fa](images/disable-2fa.jpg)
401427

402-
* 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.
428+
To disable the two-factor authentication on your user, it is required to enter the verification code.
403429

404430
![Verify disable](images/verify-disable.jpg)
405431

0 commit comments

Comments
 (0)