OSOE-598: Add entra authentication for live metrics

Lombiq.Hosting.Azure.ApplicationInsights/ApplicationInsightsOptions.cs

@@ -28,6 +28,7 @@ public class ApplicationInsightsOptions
     /// documentation for more info: <see
     /// href="https://docs.microsoft.com/en-us/azure/azure-monitor/app/live-stream#secure-the-control-channel"/>.
     /// </summary>
+    [Obsolete("Microsoft Entra authentication is the only supported method from 30 September 2025. API key authentication will be removed.")]
     public string QuickPulseTelemetryModuleAuthenticationApiKey { get; set; }
 
     /// <summary>
@@ -69,6 +70,23 @@ public class ApplicationInsightsOptions
     /// </summary>
     public bool EnableClientSideTracking { get; set; } = true;
 
+    /// <summary>
+    /// Gets or sets a value indicating whether to use entra authentication.
+    /// </summary>
+    public bool UseEntraAuthentication { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to authenticate to AI using a Service Principal. When using this option
+    /// you will also need to provide tenantId, clientId, and clientSecret of the service principal.
+    /// </summary>
+    public bool UseServicePrincipalAuthentication { get; set; }
+
+    /// <summary>
+    /// Gets or sets the ServicePrincipalCredentials of the Microsoft Entra application used to secure the control
+    /// channel.
+    /// </summary>
+    public ServicePrincipalCredentials ServicePrincipalCredentials { get; set; }
+
     /// <summary>
     /// Gets or sets a value indicating whether to work in kind of a debug mode completely offline. Telemetry will still
     /// show up in the Debug window.

Lombiq.Hosting.Azure.ApplicationInsights/Extensions/ApplicationInsightsInitializerExtensions.cs

@@ -1,4 +1,5 @@
-using Lombiq.Hosting.Azure.ApplicationInsights;
+using Azure.Identity;
+using Lombiq.Hosting.Azure.ApplicationInsights;
 using Lombiq.Hosting.Azure.ApplicationInsights.Services;
 using Lombiq.Hosting.Azure.ApplicationInsights.TelemetryInitializers;
 using Microsoft.ApplicationInsights.AspNetCore.Extensions;
@@ -35,6 +36,24 @@ public static class ApplicationInsightsInitializerExtensions
             .GetSection("OrchardCore:Lombiq_Hosting_Azure_ApplicationInsights");
         applicationInsightsConfigSection.Bind(applicationInsightsOptions);
 
+        if (applicationInsightsOptions.UseEntraAuthentication)
+            services.Configure<TelemetryConfiguration>(config =>
+            {
+                if (applicationInsightsOptions.UseServicePrincipalAuthentication)
+                {
+                    var credential = new ClientSecretCredential(
+                        applicationInsightsOptions.ServicePrincipalCredentials.TenantId,
+                        applicationInsightsOptions.ServicePrincipalCredentials.ClientId,
+                        applicationInsightsOptions.ServicePrincipalCredentials.ClientSecret);
+                    config.SetAzureTokenCredential(credential);
+                }
+                else
+                {
+                    var credential = new DefaultAzureCredential();
+                    config.SetAzureTokenCredential(credential);
+                }
+            });
+
         if (string.IsNullOrEmpty(applicationInsightsServiceOptions?.ConnectionString) &&
 #pragma warning disable CS0618 // Type or member is obsolete
             string.IsNullOrEmpty(applicationInsightsServiceOptions?.InstrumentationKey) &&
@@ -62,7 +81,9 @@ public static class ApplicationInsightsInitializerExtensions
             (module, _) => module.EnableSqlCommandTextInstrumentation = applicationInsightsOptions.EnableSqlCommandTextInstrumentation);
 
         services.ConfigureTelemetryModule<QuickPulseTelemetryModule>(
+#pragma warning disable CS0618 // Type or member is obsolete
             (module, _) => module.AuthenticationApiKey = applicationInsightsOptions.QuickPulseTelemetryModuleAuthenticationApiKey);
+#pragma warning restore CS0618 // Type or member is obsolete
 
         services.AddSingleton<ITelemetryInitializer, UserContextPopulatingTelemetryInitializer>();
         services.AddSingleton<ITelemetryInitializer, ShellNamePopulatingTelemetryInitializer>();

Lombiq.Hosting.Azure.ApplicationInsights/Lombiq.Hosting.Azure.ApplicationInsights.csproj

@@ -34,7 +34,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
+    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.22.0" />
     <PackageReference Include="OrchardCore.Media.Azure" Version="1.8.0" />
     <PackageReference Include="OrchardCore.Module.Targets" Version="1.8.0" />
     <PackageReference Include="OrchardCore.ContentManagement" Version="1.8.0" />

Lombiq.Hosting.Azure.ApplicationInsights/ServicePrincipalCredentials.cs

@@ -0,0 +1,19 @@
+namespace Lombiq.Hosting.Azure.ApplicationInsights;
+
+public class ServicePrincipalCredentials
+{
+    /// <summary>
+    /// Gets or sets the tenant ID of the Microsoft Entra application used to secure the control channel.
+    /// </summary>
+    public string TenantId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the client ID of the Microsoft Entra application used to secure the control channel.
+    /// </summary>
+    public string ClientId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the client secret of the Microsoft Entra application used to secure the control channel.
+    /// </summary>
+    public string ClientSecret { get; set; }
+}

Readme.md

@@ -86,19 +86,72 @@ The module has its own configuration for further options. These need to come fro
   },
   "OrchardCore": {
     "Lombiq_Hosting_Azure_ApplicationInsights": {
+      // Deprecated, do not use in new projects.
       "QuickPulseTelemetryModuleAuthenticationApiKey": "your API key here"
     }
   }
 }
 
 ```
 
-See the [`ApplicationInsightsOptions` class](Lombiq.Hosting.Azure.ApplicationInsights/ApplicationInsightsOptions.cs) for all options and details. We recommend configuring at least `QuickPulseTelemetryModuleAuthenticationApiKey`.
+> ⚠ Use of QuickPulseTelemetryModuleAuthenticationApiKey is deprecated and will be officially unsupported starting 30 September 2025. See [Entra Authentication for the Live Metrics control channel](#entra-authentication-for-the-live-metrics-control-channel) for more information.
+
+See the [`ApplicationInsightsOptions` class](Lombiq.Hosting.Azure.ApplicationInsights/ApplicationInsightsOptions.cs) for all options and details.
 
 Note that while telemetry from background tasks is collected in form of dependency operations it'll be collected even if `EnableDependencyTrackingTelemetryModule` is `false`.
 
 If you use the security defaults from [Lombiq Helpful Libraries - Orchard Core Libraries - Security](https://github.com/Lombiq/Helpful-Libraries/blob/dev/Lombiq.HelpfulLibraries.OrchardCore/Docs/Security.md), then the security headers necessary to use Application Insight's client-side tracking will automatically be added.
 
+### Entra Authentication for the Live Metrics control channel
+
+Starting 30 September 2025, authentication using API keys is no longer supported for [securing the Live Metrics control channel](https://learn.microsoft.com/en-us/azure/azure-monitor/app/live-stream#secure-the-control-channel). Instead, you'll have to set up Entra Authentication for that (you may omit this if not needed; configuring the connection string is necessary in any case, and enough for simply collecting telemetry).
+
+#### Setting up Entra Authentication for Application Insights
+
+> ⚠ This section is required if you have disabled `Local Authentication` on your AI resource, See [the docs](https://learn.microsoft.com/en-us/azure/azure-monitor/app/azure-ad-authentication?WT.mc_id=Portal-AppInsightsExtension&tabs=net#disable-local-authentication).
+
+If you want to use Entra Authentication for Application Insights, or if you have disabled `Local Authentication` on your AI resource, you will have to set up the `UseEntraAuthentication` option to `true` in the `Lombiq_Hosting_Azure_ApplicationInsights` section of your configuration like below.
+
+```json5
+{
+    "OrchardCore": {
+        "Lombiq_Hosting_Azure_ApplicationInsights": {
+            "UseEntraAuthentication": true
+        }
+    }
+}
+```
+
+To set up Entra Authentication for an application hosted on Azure you will have to set up a Managed Identity for the application and give it the `Monitoring Metrics Publisher` role to be able to publish metrics to AI. See how to set up a managed identity [here](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/managed-identities-status). See more on Assigning Azure roles [here](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal).
+
+You can also use a service principal to authenticate. To set this up, you will have to provide the service principal credentials in the configuration. See the [Service principal](#service-principal) section for more information. This is also the only way to authenticate if you are using a non-Azure (or local) environment - or an Azure resource that does not support Managed Identities.
+
+Once Entra Authentication is set up and the `ConnectionString` has been properly set, metrics should be flowing in.
+
+#### Service principal
+
+Using a Service Principal is the only way to authenticate using Entra if you are using a non-Azure (or local) environment.
+
+If you want to use the Service Principal method for your Application Insights resource, you should set the `UseServicePrincipalAuthentication` option to `true` in addition to `UseEntraAuthentication` in the `Lombiq_Hosting_Azure_ApplicationInsights` section of your configuration. To securely stream metrics with Entra ID you will also have to provide the credentials of the service principal, to set this up [see the docs](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal).
+
+```json5
+{
+  "OrchardCore": {
+    "Lombiq_Hosting_Azure_ApplicationInsights": {
+        "UseEntraAuthentication": true,
+        "UseServicePrincipalAuthentication": true,
+        "ServicePrincipalCredentials": {
+            "TenantId": "your service principal tenant id",
+            "ClientId": "your service principal client id",
+            "ClientSecret": "your service principal client secret"
+        },
+    }
+  }
+}
+```
+
+For more information or scenarios not described here, see the [official documentation](https://learn.microsoft.com/en-us/azure/azure-monitor/app/azure-ad-authentication).
+
 ### Using collected data
 
 All the collected data will be available in the Azure Portal as usual. Some custom properties will be added to all suitable telemetry with the `"OrchardCore."` prefix.