Configure authentication in a .NET agent

The .NET Agents SDK Microsoft Authentication Library (MSAL) authentication provider is a utility that helps you create access tokens for agent clients and external services from a Microsoft 365 Agents SDK self-hosted agent.

This utility 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:

• Single tenant with ClientSecret and Multitenant with ClientSecret
• Client Certificate using Thumbprint
• Client Certificate using Subject Name (including SN+I)
• User Managed Identity
• System Managed Identity
• Federated Credentials
• Workload Identity

Configure a Connection

The MSAL Authentication provider lets you create and use multiple distinct clients with 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 you can use when you create an instance of the MSAL Authentication Provider.

These settings are:

Single tenant with ClientSecret

Here is an example appsettings for SingleTenant ClientSecret for Azure Bot Service:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "ClientId": "{{BOT_ID}}",
        "ClientSecret": "{{BOT_SECRET}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "Scopes": [
            "https://api.botframework.com/.default"
          ],
      }
    }
  }

MultiTenant with ClientSecret

Here is an example appsettings for MultiTenant ClientSecret for Azure Bot Service:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "ClientId": "{{BOT_ID}}",
        "ClientSecret": "{{BOT_SECRET}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
            "https://api.botframework.com/.default"
          ],
      }
    }
  }

UserManagedIdentity

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.

Here is an example appsettings for UserManagedIdentity:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "UserManagedIdentity",
        "ClientId": "{{BOT_ID}}",
        "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.

Here is an example appsettings for SystemManagedIdentity auth type:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "SystemManagedIdentity",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

FederatedCredentials

Here is an example appsettings for FederatedCredentials:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedClientId": "{{BOT_FEDERATED_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

WorkloadIdentity

Here is an example for SingleTenant WorkloadIdentity:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "WorkloadIdentity",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedTokenFile": "{{BOT_FEDERATED_TOKENFILE}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

Optional Federated Credentials or Workload Identity client assertion options

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "WorkloadIdentity",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedTokenFile": "{{BOT_FEDERATED_TOKENFILE}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ],
        "AssertionRequestOptions": {
            "ClientId": null,
            "TokenEndpoint": null,
            "Claims": null,
            "ClientCapabilities": null,
        }
      }
    }
  }

CertificateSubjectName

Here is an example appsettings for CertificateSubjectName for SN+I and MultiTenant

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "CertificateSubjectName",
        "ClientId": "{{BOT_ID}}",
        "CertSubjectName": "{{BOT_CERT_SUBJECTNAME}}",
        "SendX5C": true,
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Here is an example appsettings for CertificateSubjectName for SN+I and SingleTenant

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "CertificateSubjectName",
        "ClientId": "{{BOT_ID}}",
        "CertSubjectName": "{{BOT_CERT_SUBJECTNAME}}",
        "SendX5C": true,
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Certificate

Here is an example appsettings for CertificateSubjectName using the certificate thumbprint:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "Certificate",
        "ClientId": "{{BOT_ID}}",
        "CertThumbprint": "{{BOT_CERT_THUMBPRINT}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Default configuration provider for MSAL

To ease setup, we provide a service provider extension to add the default configuration settings for MSAL to your Agent.

Here is an example of default MSAL configuration provider for an Asp.net core host:

In a Program.cs class.

This is managed by the registered IConnections instance. This is added by default when using AddAgent.

// Register your AgentApplication
builder.AddAgent<MyAgent>();

However, if not using AddAgent, the IConnections instance must be registered.

    // Add Connections object to access configured token connections.
    builder.Services.AddSingleton<IConnections, ConfigurationConnections>();

Additional MSAL configuration options

There are several shared configuration options that control general settings for acquiring tokens from Microsoft Entra Identity.

These settings are:

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.

Here is an example of the entry in an appsettings.json file:

{
  "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.

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.

    // Add default agent MsalAuth support
    builder.Services.AddDefaultMsalAuth(builder.Configuration);

    // Register your AgentApplication
    builder.AddAgent<MyAgent>();

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 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.

Here is an example of the logging block in this case:

  "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.