Merge branch 'main' into cms15/twoFactor

Author: sofietoft

10/umbraco-forms/installation/install.md

@@ -15,12 +15,14 @@ Umbraco contains the **Forms** section, by default. You will see a similar inter
 
 To install the Umbraco Forms package (**Umbraco.Forms**), follow these steps:
 
-1.  Run the following command on a command prompt of your choice:
+1.  Identify the Umbraco CMS version your project is running.
+2.  Find a compatible version of Umbraco Forms that matches your Umbraco CMS version. A list of Umbraco Forms versions can be found on [nuget.org](https://www.nuget.org/packages/Umbraco.Forms#versions-body-tab).
+3.  Run the following command on a command prompt of your choice, replacing `<version_number>` with the appropriate version identified above:
 
     ```
-    dotnet add package Umbraco.Forms
+    dotnet add package Umbraco.Forms --version <version_number>
     ```
-2.  Restart the web application using the following command:
+4.  Restart the web application using the following command:
 
     ```
      dotnet run

13/umbraco-cms/reference/security/external-login-providers.md

@@ -255,14 +255,19 @@ public class ProviderBackOfficeExternalLoginProviderOptions : IConfigureNamedOpt
         // Choose to automatically redirect to the external login provider
         // effectively removing the login button.
         options.AutoRedirectLoginToExternalProvider = false;
+
+        // [OPTIONAL]
+        // Set the button color and look.
+        options.ButtonColor = UuiButtonColor.Positive;
+        options.ButtonLook = UuiButtonLook.Primary;
     }
 }
 ```
 {% endcode %}
 
 **Icons**
 
-If you want to use a custom icon for the login button, you need to add the icon to the Umbraco backoffice. You can do this by adding the icon to the `~/App_Plugins/MyPlugin/BackOffice/Icons` folder. The icon should be a SVG file. The icon should be named the same as the icon name you specify in the `options.Icon` property.
+If you want to use a custom icon for the login button, you need to add the icon to the Umbraco backoffice. You can do this by adding the icon to the `~/App_Plugins/MyPlugin/BackOffice/Icons` folder. The icon should be an SVG file. The icon should be named the same as the icon name you specify in the `options.Icon` property.
 
 {% hint style="info" %}
 You can use the [Umbraco Icon Picker](../../fundamentals/data/defining-content/README.md#adding-icons-to-the-document-type) to see available icons.
@@ -362,7 +367,7 @@ The `CustomBackofficeView` allows for specifying a JavaScript module to render a
 * You want to display something different where external login providers are listed: in the login screen vs the backoffice panel vs on the logged-out screen. This same view will render in all of these cases but you can use the current route parameters to customize what is shown.
 * You want to change how the button interacts with the external login provider. For example, instead of having the site redirect on button-click, you want to open a popup window to load the external login provider.
 
-The path to the custom view is a virtual path, like this example: `"~/App_Plugins/MyPlugin/BackOffice/my-external-login.js"`.
+The path to the custom view is a virtual path, like this example: `"/App_Plugins/MyPlugin/BackOffice/my-external-login.js"`.
 
 When a custom view is specified it is 100% up to this module to perform all required logic.
 
@@ -374,7 +379,7 @@ The module should define a Custom Element and export it as default. The Custom E
 * `userViewState`: The current view state of the user. This can be one of the following values:
   * `loggingIn`: The user is on the login screen.
   * `loggedIn`: The user is on the backoffice panel.
-  * `loggedOut`: The user clicked the logout button and is on the logged-out screen.
+  * `loggedOut`: The user clicks the logout button and is on the logged-out screen.
   * `timedOut`: The user's session has timed out and they are on the timed-out screen.
 
 **TypeScript**
@@ -396,7 +401,7 @@ interface IExternalLoginCustomViewElement {
 
 **Examples**
 
-The Custom Element can be implemented in a number of ways with many different libraries or frameworks. The following examples show how to make a button appear and redirect to the external login provider. You will learn how to use the `externalLoginUrl` property to redirect to the external login provider. The login form should look like this when you open Umbraco:
+The Custom Element can be implemented in several ways with many different libraries or frameworks. The following examples show how to make a button appear and redirect to the external login provider. You will learn how to use the `externalLoginUrl` property to redirect to the external login provider. The login form should look like this when you open Umbraco:
 
 ![Login form with custom external login button](./images/external-login-provider-javascript.png)
 
@@ -475,7 +480,7 @@ class MyLitView extends LitElement {
       providerName: { type: String },
       displayName: { type: String },
       externalLoginUrl: { type: String },
-      userViewState: { type: String }
+      userViewState: { type: String, state: true }
     };
   }
 
@@ -514,7 +519,7 @@ export default MyLitView;
 
 ### Static extension class
 
-The extension class is required to extend on the default authentication implementation in Umbraco CMS. A generic example of such extension class can be seen below.
+The extension class is required to extend the default authentication implementation in Umbraco CMS. A generic example of such an extension class can be seen below.
 
 {% tabs %}
 {% tab title="User Authentication" %}

13/umbraco-cms/reference/security/images/2fa-user-disable.png

@@ -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.
+
 {% 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.
@@ -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" %}
@@ -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.
@@ -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;
@@ -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
 {
@@ -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
 {
@@ -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,
@@ -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;
 
@@ -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">
@@ -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 () {
@@ -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.
+
+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
 

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

@@ -14,17 +14,18 @@ Umbraco contains the **Forms** section, by default. You will see a similar inter
 
 To install the Umbraco Forms package (**Umbraco.Forms**), follow these steps:
 
-1. Run the following command on a command prompt of your choice:
-
-```
-dotnet add package Umbraco.Forms
-```
-
-2. Restart the web application using the following command:
-
-```
-    dotnet run
-```
+1.  Identify the Umbraco CMS version your project is running.
+2.  Find a compatible version of Umbraco Forms that matches your Umbraco CMS version. A list of Umbraco Forms versions can be found on [nuget.org](https://www.nuget.org/packages/Umbraco.Forms#versions-body-tab).
+3.  Run the following command on a command prompt of your choice, replacing `<version_number>` with the appropriate version identified above:
+
+    ```
+    dotnet add package Umbraco.Forms --version <version_number>
+    ```
+4.  Restart the web application using the following command:
+
+    ```
+     dotnet run
+    ```
 
 ## Start Building Forms