Added documentation.

src/OrchardCore.Modules/OrchardCore.Microsoft.Authentication/Views/MicrosoftEntraIDSettings.Edit.cshtml

@@ -26,7 +26,7 @@
     <label asp-for="TenantId" class="form-label">@T["TenantId"]</label>
     <input asp-for="TenantId" class="form-control" />
     <span asp-validation-for="TenantId"></span>
-    <span class="hint">@T["The Tenant (Directory) ID found on the Microsoft Entra ID App registration parameters."]</span>
+    <span class="hint">@T["The Tenant (Directory) ID found on the Microsoft Entra ID App registration parameters. For multitenant App registrations, use 'common' or 'organizations'."]</span>
 </div>
 
 <div class="mb-3" asp-validation-class-for="CallbackPath">

src/docs/reference/modules/Microsoft.Authentication/README.md

@@ -23,27 +23,27 @@ If no value is provided, setup Microsoft Account app to use the default path /si
 
 ## Microsoft Entra ID (Azure Active Directory)
 
-Authenticates users with their Microsoft Entra ID Account, like Microsoft work or school accounts. If the site allows to register new users, a local user is created and the Microsoft Entra ID account is linked. If a local user with the same email is found, then the external login is linked to that account, after authenticating.
+Authenticates users with their Microsoft Entra ID Account, including Microsoft work, school, and personal accounts (such as Skype, Xbox, Outlook.com). If the site allows to register new users, a local user is created and the Microsoft Entra ID account is linked. If a local user with the same email is found, then the external login is linked to that account, after authenticating.
 
 First, you need to create an Microsoft Entra ID app on the [Azure Portal](https://portal.azure.com) for your Microsoft Entra ID tenant.
 
 1. Go to the "Azure Active Directory" menu, which will open your organization's Active Directory settings.
 2. Open "App registrations" and click "New registration" to start creating a new app registration.
 3. Use the following settings:
     - Name: We suggest the name of your web app, e.g. "My App". This is not the same display name that you need to specify for the login later and it doesn't need to match anything else.
-    - Supported account types: The feature supports both single and multitenant Microsoft Entra ID, but not personal accounts.
+    - Supported account types: The feature supports both single and multitenant Microsoft Entra ID, including personal accounts.
     - Redirect URI: While supposedly optional, you have to specify one for the login flow to work with web apps. Add the URL that will handle Microsoft Entra ID login redirects; by default, this is `/signin-oidc` under your app's root URL, e.g. "<https://example.com/signin-oidc>" (upon login, users will be redirected to the page they visited previously, this isn't for that).
 4. Once the app is created, note the following details of it, as displayed in the Azure Portal, which will be necessary to configure in Orchard Core later:
     - Application (client) ID
-    - Directory (tenant) ID
+    - Directory (tenant) ID (not required for multitenant usage)
 5. Configure the rest of the authentication settings of the app under its "Authentication" menu. There, under "Implicit grant and hybrid flows", enable both "Access tokens (used for implicit flows)" and "ID tokens (used for implicit and hybrid flows)". Without these, login will fail with errors.
 6. Configure the `email` claim under the "Token configuration" menu. Click "Add optional claim", as "Token type" select "ID", then select "email" and click "Add". Without this, Orchard can't match logins based on the user's email, and thus existing users won't be able to log in.
 
 You are now ready to configure Microsoft Entra ID login in Orchard too. After enabling the "Microsoft Entra ID (Azure Active Directory) Authentication" feature, you will see the "Security" → "Microsoft Entra ID" menu in the admin. We recommend to configure at least the following settings:
 
 - Display Name: The text that will be displayed on the Orchard login screen. We recommend something like "My Company Microsoft account".
 - AppId: Use the above-mentioned "Application (client) ID" from the Azure Portal.
-- TenantId: Use the above-mentioned "Directory (tenant) ID" from the Azure Portal.
+- TenantId: Use the above-mentioned "Directory (tenant) ID" from the Azure Portal. For multitenant applications, use 'common' or 'organizations' as noted below.
 - CallbackPath: We recommend not changing this unless you want to handle the login callback from your custom code, or if the `/signin-oidc` path is used by something else. This is the path within the application's base path where the user-agent will be returned after login. The middleware will process this request when it arrives. If no value is provided, the default `/signin-oidc` is used, which requires no further setup. If you change this, you will also need to use it under "Redirect URIs" of the app in the Azure Portal.
 
 Now, the login screen will display a button for Microsoft Entra ID login:
@@ -52,6 +52,23 @@ Now, the login screen will display a button for Microsoft Entra ID login:
 
 Existing users who have the same e-mail address in Orchard and in Microsoft Entra ID will be able to log in and attach their two accounts. New users will be able to register if registration is otherwise enabled and set up, see below.
 
+### Multitenant App registrations
+
+This feature supports either single-tenant or multi-tenant app registrations. Be aware of the audiences allowed to authenticate.
+
+- Single-tenant apps are only available in the tenant they were registered in, also known as their home tenant.
+- Multi-tenant apps are available to users in both their home tenant and other tenants.
+
+When you register and configure an application, you can configure it to be single-tenant or multi-tenant by setting the audience and tenant ID as follows:
+
+| Audience | Single/multi-tenant | Tenant ID | Who can sign in |
+|----------|---------------------|-----------|-----------------|
+| Accounts in your  directory only | Single tenant | Use the "Directory (tenant) ID" from the Azure Portal. | All user and guest accounts in your directory can authenticate. Use this option if your target audience is internal to your organization. |
+| Accounts in any Microsoft Entra directory | Multi-tenant | `organizations` | All users and guests with a work or school account from Microsoft can authenticate. This includes schools and businesses that use Microsoft 365. Use this option if your target audience is business or educational customers. |
+| Accounts in any Microsoft Entra directory and personal Microsoft accounts (such as Skype, Xbox, Outlook.com) | Multi-tenant | `common` | All users with a work or school, or personal Microsoft account can authenticate. It includes schools and businesses that use Microsoft 365 as well as personal accounts that are used to sign in to services like Xbox and Skype. Use this option to target the widest set of Microsoft accounts. |
+
+> When configuring your application for multitenancy, it's crucial to be aware of the security implications. Allowing users from any Microsoft Entra directory and personal Microsoft accounts to authenticate can significantly broaden the potential user base. 
+
 ### Recipe Step
 
 The Microsoft Entra ID can be set during recipes using the settings step. Here is a sample step: