Configurar autenticação num agente .NET

O fornecedor de autenticação da Biblioteca de autenticação da Microsoft (MSAL) do SDK de Agentes do .NET é um utilitário que ajuda a criar tokens de acesso para clientes de agente e serviços externos a partir de um agente autoalojado do SDK de Agentes do Microsoft 365.

Este utilitário suporta vários perfis distintos que podem ser usados para criar tokens de acesso. Cada token de acesso pode ser criado usando um dos seguintes tipos de autenticação:

• Inquilino único com ClientSecret e Multitenant com ClientSecret
• Certificado de cliente usando thumbprint
• Certificado de cliente usando o nome do assunto (incluindo SN+I)
• Utilizar identidade gerida
• Identidade gerida pelo sistema
• Credenciais federadas
• Identidade da carga de trabalho

Configurar uma conexão

O fornecedor de autenticação MSAL permite-lhe criar e usar múltiplos clientes distintos com o motor de alojamento Agents Framework. Com o fornecedor de autenticação MSAL, pode fornecer múltiplas configurações de ligação no ficheiro de configuração da aplicação. Cada configuração de ligação pode ser usada para criar um cliente de autenticação nomeado para suportar comunicações com serviços externos ou outros agentes.

As secções seguintes descrevem as definições de configuração obrigatórias e opcionais para cada um dos tipos de autenticação suportados pelo fornecedor de autenticação MSAL, juntamente com exemplos de excertos de configuração para cada tipo.

Inquilino único com ClientSecret

Aqui está um exemplo de configurações de aplicação para inquilino único* ClientSecret:

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

Multi-inquilino com ClientSecret

Aqui está um exemplo de appsettings para multi-inquilino com ClientSecret:

  "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

Aqui está um exemplo de appsettings para UserManagedIdentity:

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

SystemManagedIdentity

Ao usar o tipo SystemManagedIdentityde autenticação , o ID do cliente é ignorado e a identidade gerida pelo sistema para o serviço é utilizada.

Aqui está um exemplo de appsettings para SystemManagedIdentity o tipo de autenticação:

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

FederatedCredentials

Aqui está um exemplo de appsettings para 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

Aqui está um exemplo de configurações de aplicação para inquilino único 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"
        ]
      }
    }
  }

Opções opcionais de asserção de cliente de Credenciais Federadas ou Identidade de Carga de Trabalho

  "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

Aqui está um exemplo de appsettings para CertificateSubjectName para o Nome do Assunto e Emissor (SNI) e multi-inquilino

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

Aqui está um exemplo de appsettings para CertificateSubjectName para SN+I e 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

Aqui está um exemplo de appsettings para CertificateSubjectName usar o thumbprint do certificado:

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

Fornecedor de configuração predefinido para MSAL

Para facilitar a configuração, fornecemos uma extensão do fornecedor de serviços para adicionar as definições de configuração predefinidas do MSAL ao seu Agente.

Aqui está um exemplo de fornecedor de configuração MSAL predefinido para um anfitrião Asp.net core:

Numa classe Program.cs.

Isso é gerido pela instância registada IConnections . Isso é adicionado por predefinição ao usar AddAgent.

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

No entanto, se não estiver a utilizar AddAgent, a instância IConnections deve ser registada.

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

Opções adicionais de configuração do MSAL

Há várias opções de configuração partilhadas que controlam as definições gerais para adquirir tokens do Microsoft Entra Identity.

Essas definições são:

Estas definições são partilhadas com todos os clientes que criam usando o Fornecedor de Autenticação MSAL. Estas definições destinam-se a ser lidas a partir de um leitor IConfiguration, numa secção de configuração denominada "MSALConfiguration".

Aqui está um exemplo da entrada num fincheiro appsettings.json:

{
  "MSALConfiguration": {
    "MSALEnabledLogPII": "true",
    "MSALRequestTimeout": "00:00:40",
    "MSALRetryCount": "1"
  },
}

Nesse caso, esse bloco de definições instruiria todos os clientes MSAL criados com o forecedor MSAL a ativar o registro de PII, definir o tempo limite para 40 segundos e reduzir a contagem de repetições para 1.

Esta extensão procurará uma seção de configuração chamada "MSALConfiguration" no seu objeto IConfiguration e criará um objeto de configuração MSAL a partir dele.

Se a seção MSALConfig não for encontrada, ela criará o objeto de configuração do MSAL usando valores predefinidos.

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

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

Suporte de registo para autenticação

O sistema de autenticação MSAL permite o registo independente dos fluxos de autenticação para integração de telemetria, caso precise de resolver problemas na aquisição de tokens.

Para ativar o registo, adicionaria uma entrada para Microsoft.Agents.Authentication.Msal as definições da aplicação para configurar um ILogger para reportar operações de token para as suas ligações, caso tenha adicionado a opção MSALEnabledLogPII, isso também incluirá PII para a sua ligação.

Aqui está um exemplo do bloco de registo neste caso:

  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.Agents": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.Agents.Authentication.Msal": "Trace"
    }
  }

Nesse caso, o registo está ativado para vários módulos e incluem Microsoft.Agents.Authentication.Msal, onde o nível de rastreio é "Rastreio" para MSAL.