Merge pull request #1 from tracyboehrer/main

Added create bot, add OAuth, and Activity Protocol Specs
microsoft · Nov 14, 2024 · 4732661 · 4732661
2 parents af9809d + 8676350
commit 4732661
Show file tree

Hide file tree

Showing 15 changed files with 585 additions and 2 deletions.
diff --git a/docs/HowTo/MSALAuthConfigurationOptions.md b/docs/HowTo/MSALAuthConfigurationOptions.md
@@ -0,0 +1,260 @@
+# DotNet MSAL Authentication provider
+
+The MSAL authentication provider is a utility aid you on creating access tokens for bot clients and external services from the Microsoft Agents Framework self hosted Agent.
+
+This utility has supports multiple distinct profiles that can be used to create access tokens.
+Each access token can be created using one of the following auth types:
+
+- Client Secret
+- Client Certificate using Thumbprint
+- Client Certificate using Subject Name
+- User Managed Identity
+- System Managed Identity
+
+> Refer to [Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-8.0) for recommendations for configuration and secrets best practices.
+
+### General Configuration
+
+There are several shared configuration options that control general settings for acquiring tokens from Microsoft Entra ID.
+
+These settings are:
+
+|Setting Name  |Type  |Default Value  |Description  |
+|--------------|---------|----------------|----------------------------------------------|
+|MSALRequestTimeout     |TimeSpan         |30seconds         |This setting controls how long the client will wait for a response from Entra ID after a request has been made.         |
+|MSALRetryCount     |Int         |3         |This setting controls how many retry attempts the provider will make for an individual request for a token         |
+|MSALEnabledLogPII     |Bool         |False         |This setting controls if the attached logger will be provided with PII data from MSAL         |
+
+These settings are shared with all clients creating using the MSAL Authentication Provider.
+These settings are intended to be read from an IConfiguration Reader, in from a configuration section a section called "MSALConfiguration".
+
+> MSAL Configuration is an optional configuration, if not set or provided, the default configuration for these values are used.
+
+#### An example of this entry in an appsettings.json file is:
+
+```json
+{
+  "MSALConfiguration": {
+    "MSALEnabledLogPII": "true",
+    "MSALRequestTimeout": "00:00:40",
+    "MSALRetryCount": "1"
+  },
+}
+```
+
+In this case, this settings block would instruct all MSAL clients created with the MSAL provider to enabled PII logging, set the timeout to 40 seconds, and reduce the retry count to 1.
+
+## Configuring a Connection
+
+The MSAL Authentication provider is intended to allow for multiple distinct clients to be created and used by the Agents Framework Hosting engine. As such, the MSAL Authentication provider allows for multiple configurations to be provided in the application configuration file, where each configuration can be used to create a named authentication client to support communications with external services or other Agents.
+
+There are several possible settings for the creating an instance of the MSAL Authentication Provider.
+
+These settings are:
+
+|Setting Name  |Type  |Default Value  |Description  |
+|--------------|------|---------------|-------------|
+|AuthType     |AuthTypes Enum (Certificate, CertificateSubjectName, ClientSecret, UserManagedIdentity, SystemManagedIdentity) |ClientSecret        |This is the type of authentication that will be created.|
+|AuthorityEndpoint     |String         |Null         |When present, used as the Authority to request a token from.|
+|TenantId     |String         |Null         |When present and AuthorityEndpoint is null, used to create an Authority to request a token from|
+|Scopes     |String list         |Null         |Default Lists of scopes to request tokens for. Is only used when no scopes are passed from the bot connection request|
+
+### ClientSecret
+|Setting Name  |Type  |Default Value  |Description  |
+|--------------|------|---------------|-------------|
+|ClientId     |String    |Null         |ClientId (AppId) to use when creating the Access token.|
+|ClientSecret     |string         |Null         |When AuthType is ClientSecret, Is Secret associated with the client, this should only be used for testing and development purposes.         |
+
+#### Example for MultiTenant ClientSecret for Azure Bot Service
+
+```json
+  "Connections": {
+    "BotServiceConnection": {
+      "Assembly": "Microsoft.Agents.Authentication.Msal",
+      "Type": "Microsoft.Agents.Authentication.Msal.MsalAuth",
+      "Settings": {
+        "AuthType": "ClientSecret",
+        "ClientId": "<<ClientID>>",
+        "ClientSecret": "<<ClientSecret>>",
+        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
+        "TenantId": "<<ClientTenantId>>",
+        "Scopes": [
+            "https://api.botframework.com/.default"
+          ],
+      }
+    }
+  }
+```
+
+#### Example for ClientSecret for Azure Bot Service using Single Tenant
+
+```json
+  "Connections": {
+    "BotServiceConnection": {
+      "Assembly": "Microsoft.Agents.Authentication.Msal",
+      "Type": "Microsoft.Agents.Authentication.Msal.MsalAuth",
+      "Settings": {
+        "AuthType": "ClientSecret",
+        "ClientId": "<<ClientID>>",
+        "ClientSecret": "<<ClientSecret>>",
+        "AuthorityEndpoint": "https://login.microsoftonline.com/<<ClientTenantId>>",
+        "TenantId": "<<ClientTenantId>>",
+        "Scopes": [
+            "https://api.botframework.com/.default"
+          ],
+      }
+    }
+  }
+```
+
+### UserManagedIdentity
+|Setting Name  |Type  |Default Value  |Description  |
+|--------------|------|---------------|-------------|
+|ClientId     |String    |Null         |Managed Identity ClientId to use when creating the Access token.|
+
+> When using the Managed Identity Types, your host or client must be running with an Azure Service and have set up that service with either a System Assigned Managed identity, or a User Assigned Managed identity.
+
+#### Example for UserManagedIdentity
+
+```json
+  "Connections": {
+    "BotServiceConnection": {
+      "Assembly": "Microsoft.Agents.Authentication.Msal",
+      "Type": "Microsoft.Agents.Authentication.Msal.MsalAuth",
+      "Settings": {
+        "AuthType": "UserManagedIdentity",
+        "ClientId": "<ClientID>",
+        "TenantId": "<<ClientTenantId>>",
+        "Scopes": [
+          "https://api.botframework.com/.default"
+        ]
+      }
+    }
+  }
+```
+
+### SystemManagedIdentity
+
+When using Auth type **SystemManagedIdentity**, Client ID is ignored and the system managed identity for the service is used.
+
+> When using the Managed Identity Types, your host or client must be running with an Azure Service and have set up that service with either a System Assigned Managed identity, or a User Assigned Managed identity.
+
+#### Example for SystemManagedIdentity
+
+```json
+  "Connections": {
+    "BotServiceConnection": {
+      "Assembly": "Microsoft.Agents.Authentication.Msal",
+      "Type": "Microsoft.Agents.Authentication.Msal.MsalAuth",
+      "Settings": {
+        "AuthType": "SystemManagedIdentity",
+        "Scopes": [
+          "https://api.botframework.com/.default"
+        ]
+      }
+    }
+  }
+```
+
+### CertificateSubjectName
+|AuthType      |Type  |Default Value  |Description  |
+|--------------|------|---------------|-------------|
+|ClientId     |String    |Null         |ClientId (AppId) to use when creating the Access token.|
+|CertSubjectName     |String         |Null         |This is the subject name that is sought|
+|CertStoreName     |String         |"My"         |Indicates which certificate store to look in|
+|ValidCertificateOnly     |bool         |True         |Requires the certificate to have a valid chain.          |
+|SendX5C     |bool         |False         |Enables certificate auto rotation with appropriate configuration.          |
+
+> Certificates should stored in the **Current User** certificate store.
+
+#### Example for CertificateSubjectName for SN+I
+
+```json
+  "Connections": {
+    "BotServiceConnection": {
+      "Assembly": "Microsoft.Agents.Authentication.Msal",
+      "Type": "Microsoft.Agents.Authentication.Msal.MsalAuth",
+      "Settings": {
+        "AuthType": "CertificateSubjectName",
+        "ClientId": "<ClientID>",
+        "CertSubjectName": "<<CertificateSubjectName>>",
+        "SendX5C": true,
+        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
+        "TenantId": "<<ClientTenantId>>",
+        "Scopes": [
+          "https://api.botframework.com/.default"
+        ]
+      }
+    }
+  },
+```
+
+### Certificate
+|AuthType      |Type  |Default Value  |Description  |
+|--------------|------|---------------|-------------|
+|ClientId     |String    |Null         |ClientId (AppId) to use when creating the Access token.|
+|CertThumbprint |String         |Null         |Thumbprint of the certificate to load, only valid when AuthType is set as Certificate|
+|CertStoreName     |String         |"My"         |When AuthType is either CertificateSubjectName or Certificate, Indicates which certificate store to look in|
+|ValidCertificateOnly     |bool         |True         |Requires the certificate to have a valid chain.          |
+|SendX5C     |bool         |False         |Enables certificate auto rotation with appropriate configuration.          |
+
+#### Example for CertificateSubjectName using the certificate thumbprint
+
+```json
+  "Connections": {
+    "BotServiceConnection": {
+      "Assembly": "Microsoft.Agents.Authentication.Msal",
+      "Type": "Microsoft.Agents.Authentication.Msal.MsalAuth",
+      "Settings": {
+        "AuthType": "CertificateSubjectName",
+        "ClientId": "<ClientID>",
+        "CertThumbprint": "<<CertificateThumbprint>>",
+        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
+        "TenantId": "<<ClientTenantId>>",
+        "Scopes": [
+          "https://api.botframework.com/.default"
+        ]
+      }
+    }
+  },
+```
+
+#### Default Configuration Provider for MSAL
+
+To easy setup, we provide a service provider extension to add the default configuration settings for MSAL to your host.
+
+#### An example of this from an Asp.net core host:
+
+In a Program.cs class.
+```csharp
+    // Add default bot MsalAuth support
+    builder.Services.AddDefaultMsalAuth(builder.Configuration);
+
+    // Add Connections object to access configured token connections.
+    builder.Services.AddSingleton<IConnections, ConfigurationConnections>();
+```
+
+This extension will look for a configuration section named "MSALConfiguration" in your IConfiguration Object and create an MSAL Configuration object from it.  
+
+> If the MSALConfig section is **not** found, it will create the MSAL Configuration Object using default values.  
+
+### Logging Support for Authentication
+
+The MSAL Authentication system allows for independent logging of authentication flows for telemetry integration should you need to troubleshoot token acquisition.
+
+To enable logging, you would add a entry for :::no-loc text="Microsoft.Agents.Authentication.Msal"::: to your applications app settings to setup an ILogger to report on token operations for your connections, should you have added the MSALEnabledLogPII Option, this will also include PII for your connection.
+
+#### An example of the logging block in this case would be:
+
+```json
+  "Logging": {
+    "LogLevel": {
+      "Default": "Warning",
+      "Microsoft.Agents": "Warning",
+      "Microsoft.Hosting.Lifetime": "Information",
+      "Microsoft.Agents.Authentication.Msal": "Trace"
+    }
+  }
+```
+
+In this case, logging is enabled for several modules include Microsoft.Agents.Authentication.Msal,  where the trace level is "Trace" for MSAL.
diff --git a/docs/HowTo/azurebot-create-msi.md b/docs/HowTo/azurebot-create-msi.md
@@ -0,0 +1,49 @@
+# Register a Managed Identity bot with Azure
+
+This article shows how to register a bot with Azure AI Bot Service.
+
+Your bot identity can be managed in Azure in a few different ways.
+
+- As a user-assigned managed identity, so that you don't need to manage the bot's credentials yourself.
+- As a single-tenant app.
+- As a multi-tenant app.
+
+> These instructions are for User Managed Identity.  If the bot is to be used for local debugging then Managed Identity will not work.  It is recommended that SingleTenant is used instead.  
+
+> For those on the Microsoft Tenant, using either MultiTenant or SingleTenant with a secret is prohibited.  There are limited options for running locally in this case, with Certiciate SN+I being a viable alternative.  If this does not work for you, the only alternative is to deploy the Agent code to Azure and run there.
+
+## Create the resource
+Create the Azure Bot resource, which will allow you to register your bot with the Azure AI Bot Service.
+
+1. Go to the Azure portal.
+
+1. In the right pane, select **Create a resource**.
+
+1. In the search box enter `bot`, then press Enter.
+
+1. Select the **Azure Bot** card.
+
+   ![Azure Bot Resource](media/azure-bot-resource.png)
+
+1. Select **Create**.
+
+1. Enter values in the required fields and review and update settings.
+
+   a. Provide information under Project details. Select whether your bot will have global or local data residency. Currently, the local data residency feature is available for resources in the "westeurope" and "centralindia" region. For more information, see [Regionalization in Azure AI Bot Service](https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-concept-regionalization?view=azure-bot-service-4.0).
+
+   ![Azure Bot Settings](media/azure-bot-project-details.png)
+
+   b. Provide information under Microsoft App ID. Select how your bot identity will be managed in Azure and whether to create a new identity or use an existing one.
+
+   ![Azure Bot Identity](media/azure-bot-ms-app-id.png)
+
+1. Select **Review + create**.
+
+1. If the validation passes, select **Create**.
+
+1. Once the deployment completes, select Go to resource. You should see the bot and related resources listed in the resource group you selected.
+
+1. If this is a Teams bot
+
+   1. Select **Settings** on the left sidebar, then **Channels**.
+   1. Select **Microsoft Teams** from the list, and choose appropriate options.
diff --git a/docs/HowTo/azurebot-create-single-secret.md b/docs/HowTo/azurebot-create-single-secret.md
@@ -0,0 +1,62 @@
+# Register a SingleTenant bot with Azure
+
+This article shows how to register a bot with Azure AI Bot Service.
+
+Your bot identity can be managed in Azure in a few different ways.
+
+- As a user-assigned managed identity, so that you don't need to manage the bot's credentials yourself.
+- As a single-tenant app.
+- As a multi-tenant app.
+
+> These instructions are for SingleTenant Identity with a Client Secret.
+
+> For those on the Microsoft Tenant, using either MultiTenant or SingleTenant with a Client Secret is prohibited.  There are limited options for running locally in this case, with Certiciate SN+I being a viable alternative.  If this does not work for you, the only alternative is to use [Managed Identity](azurebot-create-msi.md) and deploy the Agent code to Azure and run there.
+
+## Create the resource
+Create the Azure Bot resource, which will allow you to register your bot with the Azure AI Bot Service.
+
+1. Go to the Azure portal.
+
+1. In the right pane, select **Create a resource**.
+
+1. In the search box enter `bot`, then press Enter.
+
+1. Select the **Azure Bot** card.
+
+   ![Azure Bot Resource](media/azure-bot-resource.png)
+
+1. Select **Create**.
+
+1. Enter values in the required fields and review and update settings.
+
+   a. Provide information under Project details. Select whether your bot will have global or local data residency. Currently, the local data residency feature is available for resources in the "westeurope" and "centralindia" region. For more information, see [Regionalization in Azure AI Bot Service](https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-concept-regionalization?view=azure-bot-service-4.0).
+
+   ![Azure Bot Settings](media/azure-bot-project-details.png)
+
+   b. Provide information under Microsoft App ID. Select how your bot identity will be managed in Azure and whether to create a new identity or use an existing one.
+
+   ![Azure Bot Identity](media/azure-bot-ms-app-id-single.png)
+
+1. Select **Review + create**.
+
+1. If the validation passes, select **Create**.
+
+1. Once the deployment completes, select **Go to resource**. You should see the bot and related resources listed in the resource group you selected.
+
+1. If this is a Teams bot
+   1. Select **Settings** on the left sidebar, then **Channels**.
+   1. Select **Microsoft Teams** from the list, and choose appropriate options.
+
+1. Select **Settings**, then **Configuration**
+
+1. Select **Manage Password** next to **Microsoft App ID**
+   ![Azure Bot Configuration](media/azure-bot-configuration-single.png)
+
+1. On the **Overview** pane, record the **Application (client) ID** and **Directory (tenant) ID**
+
+1. Select **Certificates & secrets** on the left then **Client secrets**
+
+1. Create a new secret by click **New client secret**
+
+1. **Very important**: Copy the new secret and store in a safe place.  It is need later when configuring your Agent code.
+