diff --git a/data-explorer/includes/cross-repo/ingest-data-serilog-2.md b/data-explorer/includes/cross-repo/ingest-data-serilog-2.md index 7ca74ebcb0..9680a4762c 100644 --- a/data-explorer/includes/cross-repo/ingest-data-serilog-2.md +++ b/data-explorer/includes/cross-repo/ingest-data-serilog-2.md @@ -5,9 +5,18 @@ ms.date: 07/02/2024 -## Create a Microsoft Entra service principal +## Authentication -Microsoft Entra application authentication is used for applications that need to access your KQL database table without a user present. To ingest data using the Serilog connector, you need to create and register a Microsoft Entra service principal, and then authorize this principal as the identity used by the connector to ingest data to your KQL database. +Microsoft Entra authentication is used for applications that need to access your KQL database table without a user present. To ingest data using the Serilog connector, you can use one of the following authentication methods: + ++ A Microsoft Entra service principal is a security identity used by applications to access specific Azure resources. This identity is used to authenticate the connector to your KQL database using a client ID and password, and can be used for applications that are running outside of Azure. + ++ A Managed identity is used to authenticate the connector to your KQL database using a client ID. Managed identities are used for applications that are running within Azure. + +### [Microsoft Entra service principal authentication](#tab/service-principal) +### Create a Microsoft Entra service principal + +Create a Microsoft Entra service principal and then authorize this principal as the identity used by the connector to ingest data to your KQL database. The Microsoft Entra service principal can be created through the [Azure portal](/azure/active-directory/develop/howto-create-service-principal-portal) or programmatically, as in the following example. @@ -16,6 +25,15 @@ You'll later grant permissions for this service principal to access Kusto resour [!INCLUDE [entra-service-principal](../entra-service-principal.md)] +### [Managed Identity authentication](#tab/managed-identity) +### Create a managed identity + +Create a managed identity and authorize it as the identity used by the connector to ingest data to your KQL database. For more information on creating a Managed Identity, see [Manage user-assigned managed identities](/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azcli/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azcli). + +[!INCLUDE [managed-identity](../managed-identity.md)] + +--- + ## Create a target table and ingestion mapping Create a target table for the incoming data and an ingestion mapping to map the ingested data columns to the columns in the target table. In the following steps, the table schema and mapping correspond to the data sent from the [sample app](#run-the-sample-app). diff --git a/data-explorer/includes/cross-repo/ingest-data-serilog-3.md b/data-explorer/includes/cross-repo/ingest-data-serilog-3.md index cbee880a53..5fef7cb37f 100644 --- a/data-explorer/includes/cross-repo/ingest-data-serilog-3.md +++ b/data-explorer/includes/cross-repo/ingest-data-serilog-3.md @@ -31,6 +31,10 @@ Use the following steps to: 1. Configure the Serilog sink, replacing placeholders using the information in the table that follows: + ### [Microsoft Entra service principal authentication](#tab/service-principal) + + For Microsoft Entra service principal authentication use the following code: + ```csharp var log = new LoggerConfiguration() .WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions @@ -41,19 +45,43 @@ Use the following steps to: BufferBaseFileName = "" }) .CreateLogger(); + + ``` + + ### [Managed Identity authentication](#tab/managed-identity) + + For Managed Identity authentication use the following code: + + ``` csharp + var log = new LoggerConfiguration() + .WriteTo.AzureDataExplorerSink( + new AzureDataExplorerSinkOptions + { + IngestionEndpointUri = "", + DatabaseName = "", + TableName = "", + BufferBaseFileName = "" + }).WithAadUserAssignedManagedIdentity("") + .CreateLogger(); + ``` + --- + + Use the table below to set the values for the sink options: + | Variable | Description | |---|---| - | *IngestionEndPointUri* | The [ingest URI](#ingestion-uri). | - | *DatabaseName* | The case-sensitive name of the target database. | - | *TableName* | The case-sensitive name of an existing target table. For example, **SerilogTest** is the name of the table created in [Create a target table and ingestion mapping](#create-a-target-table-and-ingestion-mapping). | - | *AppId* | The application client ID required for authentication. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | - | *AppKey* | The application key required for authentication. You saved this value as `password` in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | - | *Tenant* | The ID of the tenant in which the application is registered. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | - | *BufferBaseFileName* | Optional base file name for the buffer file. Set this value if you require your logs to be durable against loss resulting connection failures to your cluster. For example, `C:/Temp/Serilog`. | + | `IngestionEndPointUri` | The [ingest URI](#ingestion-uri). | + | `DatabaseName` | The case-sensitive name of the target database. | + | `TableName` | The case-sensitive name of an existing target table. For example, **SerilogTest** is the name of the table created in [Create a target table and ingestion mapping](#create-a-target-table-and-ingestion-mapping). | + | `AppId` | The Application client ID required for Microsoft Entra service principal authentication. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | + | `AppKey` | The application key required for Microsoft Entra service principal authentication. You saved this value as `password` in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | + | `Tenant` | The ID of the tenant in which the application is registered when using Microsoft Entra service principal authentication. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | + | `BufferBaseFileName` | Optional base file name for the buffer file. Set this value if you require your logs to be durable against loss resulting connection failures to your cluster. For example, `C:/Temp/Serilog`. | + | `ManagedIdentityClientId` | The client ID of the user-assigned managed identity, when using Managed Identity authentication. | - For more options, see [Sink Options](https://github.com/Azure/serilog-sinks-azuredataexplorer#options). + For more options, see [Sink Options](https://github.com/Azure/serilog-sinks-azuredataexplorer#options). 1. Send data to your database using the Serilog sink. For example: @@ -88,13 +116,14 @@ If you don't have your own data to test, you can use the sample log generator ap | Variable | Description | |---|---| - | *IngestionEndPointUri* | The [ingest URI](#ingestion-uri). | - | *DatabaseName* | The case-sensitive name of the target database. | - | *TableName* | The case-sensitive name of an existing target table. For example, **SerilogTest** is the name of the table created in [Create a target table and ingestion mapping](#create-a-target-table-and-ingestion-mapping). | - | *AppId* | Application client ID required for authentication. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | - | *AppKey* | Application key required for authentication. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | - | *Tenant* | The ID of the tenant in which the application is registered. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | - | *BufferBaseFileName* | The base file name for the buffer file. Set this value if you require your logs to be durable against loss resulting connection failures to your cluster. For example, `C:/Temp/Serilog` | + | `IngestionEndPointUri` | The [ingest URI](#ingestion-uri). | + | `DatabaseName` | The case-sensitive name of the target database. | + | `TableName` | The case-sensitive name of an existing target table. For example, **SerilogTest** is the name of the table created in [Create a target table and ingestion mapping](#create-a-target-table-and-ingestion-mapping). | + | `AppId` | Application client ID required for Microsoft Entra service principal authentication. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | + | `AppKey` | Application key required for Microsoft Entra service principal authentication. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | + | `Tenant` | The ID of the tenant in which the application is registered when using Microsoft Entra service principal authentication. You saved this value in [Create a Microsoft Entra service principal](#create-a-microsoft-entra-service-principal). | + | `BufferBaseFileName` | The base file name for the buffer file. Set this value if you require your logs to be durable against loss resulting connection failures to your cluster. For example, `C:/Temp/Serilog` | + | `ManagedIdentityClientId` | The client ID of the user-assigned managed identity, when using Managed Identity authentication.| You can set the environment variables manually or using the following commands: @@ -107,6 +136,7 @@ If you don't have your own data to test, you can use the sample log generator ap $env:tenant="" $env:databaseName="" $env:tableName="" + $env:managedIdentityClientId="" ``` ### [Mac/Linux](#tab/linux) @@ -118,6 +148,7 @@ If you don't have your own data to test, you can use the sample log generator ap export tenant="" export databaseName="" export tableName="" + export managedIdentityClientId="" ``` --- diff --git a/data-explorer/includes/managed-identity.md b/data-explorer/includes/managed-identity.md new file mode 100644 index 0000000000..ea09f71418 --- /dev/null +++ b/data-explorer/includes/managed-identity.md @@ -0,0 +1,48 @@ +--- +ms.topic: include +ms.date: 01/09/2025 +--- + + + +1. Sign in to your Azure subscription via Azure CLI. Then authenticate in the browser. + + ```azurecli-interactive + az login + ``` + +1. Choose the subscription to host the managed identity. This step is needed when you have multiple subscriptions. + + ```azurecli-interactive + az account set --subscription YOUR_SUBSCRIPTION_GUID + ``` + +1. Create a user assigned managed identity. In this example, the managed identity is called `my-managed-identity`. + + ```azurecli-interactive + az identity create --name "my-managed-identity" --resource-group "my-resource-group" + ``` + +1. Assign the Contributor role for the subscription scope to the managed identity. In this example, the managed identity is called `my-managed-identity`. + + ```azurecli-interactive + az role assignment create --role "Contributor" --assignee "" --scope /subscriptions/YOUR_SUBSCRIPTION_GUID + ``` + +1. From the returned JSON data, copy the `clientId` for future use. The JSON has the following format: + + ```json + { + "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "id": "/subscriptions/00001111-aaaa-2222-bbbb-3333cccc4444/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-managed-identity", + "location": "eastus", + "name": "my-managed-identity", + "principalId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "resourceGroup": "my-resource-group", + "tags": {}, + "tenantId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "type": "Microsoft.ManagedIdentity/userAssignedIdentities" + } + ``` + +You've created your user-assigned managed identity.