Microsoft.Agents.Authentication.Msal 0.2.154-alpha

Microsoft.Agents.Authentication.Msal

Provides the MSAL IAccessTokenProvider implementation to get tokens.

Example configuration

  "Connections": {
    "BotServiceConnection": {
      "Assembly": "Microsoft.Agents.Authentication.Msal",
      "Type": "MsalAuth",
      "Settings": {
        "AuthType": "ClientSecret", // this is the AuthType for the connection, valid values can be found in Microsoft.Agents.Authentication.Msal.Model.AuthTypes.  The default is ClientSecret.
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}",
        "ClientId": "00000000-0000-0000-0000-000000000000", // this is the Client ID used for the connection.
        "ClientSecret": "00000000-0000-0000-0000-000000000000", // this is the Client Secret used for the connection.
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

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

General Configuration

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.

An example of this entry in an appsettings.json file is:

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

ClientSecret

Example for ClientSecret for Azure Bot Service

  "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"
          ],
      }
    }
  }

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.

Example for UserManagedIdentity

  "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

  "Connections": {
    "BotServiceConnection": {
      "Assembly": "Microsoft.Agents.Authentication.Msal",
      "Type": "Microsoft.Agents.Authentication.Msal.MsalAuth",
      "Settings": {
        "AuthType": "SystemManagedIdentity",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

CertificateSubjectName

Example for CertificateSubjectName for SN+I

  "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

Example for CertificateSubjectName using the certificate thumbprint

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

    // 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:

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