[APIM] Loggers with managed identities - SFI

Author: dlepow

articles/api-management/api-management-howto-app-insights.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: azure-api-management
 ms.topic: how-to
-ms.date: 07/11/2024
+ms.date: 09/04/2024
 ms.author: danlep
 ms.custom: engagement-fy23, devx-track-arm-template, devx-track-bicep
 ---
@@ -20,7 +20,7 @@ You can easily integrate Azure Application Insights with Azure API Management. A
 * Learn strategies for reducing performance impact on your API Management service instance.
 
 > [!NOTE]
-> In an API Management [workspace](workspaces-overview.md), a workspace owner can independently integrate Application Insights and enable Application Insights logging for the workspace's APIs. The general guidance to integrate a workspace with Application Insights is similar to the guidance for an API Management instance; however, configuration is scoped to the workspace only. Currently, you must integrate Application Insights in a workspace by configuring an instrumentation key or connection string. 
+> In an API Management [workspace](workspaces-overview.md), a workspace owner can independently integrate Application Insights and enable Application Insights logging for the workspace's APIs. The general guidance to integrate a workspace with Application Insights is similar to the guidance for an API Management instance; however, configuration is scoped to the workspace only. Currently, you must integrate Application Insights in a workspace by configuring a connection string (recommended) or an instrumentation key. 
 
 > [!WARNING]
 > When using our [self-hosted gateway](self-hosted-gateway-overview.md), we do not guarantee all telemetry will be pushed to Azure Application Insights given it relies on [Application Insights' in-memory buffering](./../azure-monitor/app/telemetry-channels.md#built-in-telemetry-channels).
@@ -34,9 +34,9 @@ You can easily integrate Azure Application Insights with Azure API Management. A
     > [!NOTE]
     > The Application Insights resource **can be** in a different subscription or even a different tenant than the API Management resource.
 
-* If you plan to configure a managed identity for API Management to use with Application Insights, you need to complete the following steps:
+* If you plan to configure managed identity credentials to use with Application Insights, complete the following steps:
 
-    1. Enable a system-assigned or user-assigned [managed identity for API Management](api-management-howto-use-managed-service-identity.md) in your API Management instance.
+    1. Enable a system-assigned or user-assigned [managed identity for API Management](api-management-howto-use-managed-service-identity.md).
 
         * If you enable a user-assigned managed identity, take note of the identity's **Client ID**.
 
@@ -46,18 +46,18 @@ You can easily integrate Azure Application Insights with Azure API Management. A
 
 The following are high level steps for this scenario.
 
-1. First, you create a connection between Application Insights and API Management
+1. First, create a connection between Application Insights and API Management
 
     You can create a connection between Application Insights and your API Management using the Azure portal, the REST API, or related Azure tools. API Management configures a *logger* resource for the connection.
 
-    > [!NOTE]
-    > If your Application Insights resource is in a different tenant, then you must create the logger using the [REST API](#create-a-connection-using-the-rest-api-bicep-or-arm-template) as shown in a later section of this article.
-
     > [!IMPORTANT]
-    > Currently, in the portal, API Management only supports connections to Application Insights using an Application Insights instrumentation key. To use an Application Insights connection string or an API Management managed identity, use the REST API, Bicep, or ARM template to create the logger. [Learn more](../azure-monitor/app/sdk-connection-string.md) about Application Insights connection strings.
+    > Currently, in the portal, API Management only supports connections to Application Insights using an Application Insights instrumentation key. For enhanced security, we recommend using an Application Insights connection string with an API Management managed identity. To configure a connection string with a managed identity, use the [REST API](#create-a-connection-using-the-rest-api-bicep-or-arm-template) or related tools as shown in a later section of this article. [Learn more](../azure-monitor/app/sdk-connection-string.md) about Application Insights connection strings.
     > 
 
-1. Second, you enable Application Insights logging for your API or APIs.
+    > [!NOTE]
+    > If your Application Insights resource is in a different tenant, then you must create the logger using the [REST API](#create-a-connection-using-the-rest-api-bicep-or-arm-template) or related tools as shown in a later section of this article.
+
+1. Second, enable Application Insights logging for your API or APIs.
 
     In this article, you enable Application Insights logging for your API using the Azure portal. API Management configures a *diagnostic* resource for the API.
 
@@ -66,6 +66,10 @@ The following are high level steps for this scenario.
 
 Follow these steps to use the Azure portal to create a connection between Application Insights and API Management. 
 
+> [!NOTE]
+> Where possible, Microsoft recommends using a connection string with a managed identity for enhanced security. To configure a connection string with a managed identity, use the [REST API](#create-a-connection-using-the-rest-api-bicep-or-arm-template) or related tools as shown in a later section of this article.
+
+
 1. Navigate to your **Azure API Management service instance** in the **Azure portal**.
 1. Select **Application Insights** from the menu on the left.
 1. Select **+ Add**.  
@@ -87,28 +91,31 @@ Follow these steps to use the Azure portal to create a connection between Applic
 
 ## Create a connection using the REST API, Bicep, or ARM template
 
-Follow these steps to use the REST API, Bicep, or ARM template to create a connection between Application Insights and API Management. You can configure a logger that uses a connection string, system-assigned managed identity, or user-assigned managed identity.
+Follow these steps to use the REST API, Bicep, or ARM template to create an Application Insights logger for your API Management instance. You can configure a logger that uses a system-assigned or user-assigned managed identity with a connection string (recommended), or a logger that uses only a connection string.
+
+
+### Logger with system-assigned managed identity and connection string credentials
 
-### Logger with connection string credentials
+See the [prerequisites](#prerequisites) for using an API Management managed identity.
 
 The Application Insights connection string appears in the **Overview** section of your Application Insights resource.
 
 #### [REST API](#tab/rest)
 
 Use the API Management [Logger - Create or Update](/rest/api/apimanagement/current-preview/logger/create-or-update) REST API with the following request body.
 
-If you are configuring the logger for a workspace, use the [Workspace Logger - Create or Update](/rest/api/apimanagement/workspace-logger/create-or-update?view=rest-apimanagement-2023-09-01-preview&preserve-view=true) REST API.
-
 ```JSON
 {
   "properties": {
     "loggerType": "applicationInsights",
-    "description": "adding a new logger with connection string",
+    "description": "adding a new logger with system-assigned managed identity",
     "credentials": {
-         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
+         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
+         "identityClientId":"SystemAssigned"
     }
   }
 }
+
 ```
 
 #### [Bicep](#tab/bicep)
@@ -121,9 +128,10 @@ resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/log
   parent: '<APIManagementInstanceName>'
   properties: {
     loggerType: 'applicationInsights'
-    description: 'Application Insights logger with connection string'
+    description: 'Application Insights logger with system-assigned managed identity'
     credentials: {
       connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
+      identityClientId: 'systemAssigned'
     }
   }
 }
@@ -140,17 +148,17 @@ Include a JSON snippet similar to the following in your Azure Resource Manager t
   "name": "ContosoLogger1",
   "properties": {
     "loggerType": "applicationInsights",
-    "description": "Application Insights logger with connection string",
+    "description": "Application Insights logger with system-assigned managed identity",
     "resourceId": "<ApplicationInsightsResourceID>",
     "credentials": {
-      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
-    },
+      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
+      "identityClientId": "SystemAssigned"
+    }
   }
 }
 ```
 ---
-
-### Logger with system-assigned managed identity credentials
+### Logger with user-assigned managed identity and connection string credentials
 
 See the [prerequisites](#prerequisites) for using an API Management managed identity.
 
@@ -162,10 +170,10 @@ Use the API Management [Logger - Create or Update](/rest/api/apimanagement/curre
 {
   "properties": {
     "loggerType": "applicationInsights",
-    "description": "adding a new logger with system-assigned managed identity",
+    "description": "adding a new logger with user-assigned managed identity",
     "credentials": {
          "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
-         "identityClientId":"SystemAssigned"
+         "identityClientId":"<ClientID>"
     }
   }
 }
@@ -174,18 +182,18 @@ Use the API Management [Logger - Create or Update](/rest/api/apimanagement/curre
 
 #### [Bicep](#tab/bicep)
 
-Include a snippet similar to the following in your Bicep template.
+Include a snippet similar the following in your Bicep template.
 
 ```Bicep
-resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
+resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
   name: 'ContosoLogger1'
   parent: '<APIManagementInstanceName>'
   properties: {
     loggerType: 'applicationInsights'
-    description: 'Application Insights logger with system-assigned managed identity'
+    description: 'Application Insights logger with user-assigned managed identity'
     credentials: {
       connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
-      identityClientId: 'systemAssigned'
+      identityClientId: '<ClientID>'
     }
   }
 }
@@ -202,52 +210,52 @@ Include a JSON snippet similar to the following in your Azure Resource Manager t
   "name": "ContosoLogger1",
   "properties": {
     "loggerType": "applicationInsights",
-    "description": "Application Insights logger with system-assigned managed identity",
+    "description": "Application Insights logger with user-assigned managed identity",
     "resourceId": "<ApplicationInsightsResourceID>",
     "credentials": {
       "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
-      "identityClientId": "SystemAssigned"
+      "identityClientId": "<ClientID>"
     }
   }
 }
 ```
 ---
-### Logger with user-assigned managed identity credentials
 
-See the [prerequisites](#prerequisites) for using an API Management managed identity.
+### Logger with connection string credentials only
+
+The Application Insights connection string appears in the **Overview** section of your Application Insights resource.
 
 #### [REST API](#tab/rest)
 
 Use the API Management [Logger - Create or Update](/rest/api/apimanagement/current-preview/logger/create-or-update) REST API with the following request body.
 
+If you are configuring the logger for a workspace, use the [Workspace Logger - Create or Update](/rest/api/apimanagement/workspace-logger/create-or-update?view=rest-apimanagement-2023-09-01-preview&preserve-view=true) REST API.
+
 ```JSON
 {
   "properties": {
     "loggerType": "applicationInsights",
-    "description": "adding a new logger with user-assigned managed identity",
+    "description": "adding a new logger with connection string",
     "credentials": {
-         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
-         "identityClientId":"<ClientID>"
+         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
     }
   }
 }
-
 ```
 
 #### [Bicep](#tab/bicep)
 
-Include a snippet similar the following in your Bicep template.
+Include a snippet similar to the following in your Bicep template.
 
 ```Bicep
-resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
+resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
   name: 'ContosoLogger1'
   parent: '<APIManagementInstanceName>'
   properties: {
     loggerType: 'applicationInsights'
-    description: 'Application Insights logger with user-assigned managed identity'
+    description: 'Application Insights logger with connection string'
     credentials: {
       connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
-      identityClientId: '<ClientID>'
     }
   }
 }
@@ -264,17 +272,17 @@ Include a JSON snippet similar to the following in your Azure Resource Manager t
   "name": "ContosoLogger1",
   "properties": {
     "loggerType": "applicationInsights",
-    "description": "Application Insights logger with user-assigned managed identity",
+    "description": "Application Insights logger with connection string",
     "resourceId": "<ApplicationInsightsResourceID>",
     "credentials": {
-      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
-      "identityClientId": "<ClientID>"
-    }
+      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
+    },
   }
 }
 ```
 ---
 
+
 ## Enable Application Insights logging for your API
 
 Use the following steps to enable Application Insights logging for an API. You can also enable Application Insights logging for all APIs.