Configurar a autenticação em um 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:

• Locatário único com ClientSecret e Multi-inquilino 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 criar e usar vários clientes distintos com o mecanismo de alojamento da estrutura de agentes. Como tal, o fornecedor de autenticação MSAL permite que várias configurações sejam fornecidas no ficheiro de configuração da aplicação, onde cada configuração pode ser usada para criar um cliente de autenticação nomeado para dar suporte a comunicações com serviços externos ou outros agentes.

Há várias definições possíveis que pode usar ao criar uma instância do Fornecedor de Autenticação MSAL.

Essas definições são:

Inquilino único com ClientSecret

Aqui está um exemplo de appsettings para SingleTenantClientSecret para 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"
          ],
      }
    }
  }

Multi-inquilino com ClientSecret

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

Ao usar os Tipos de Identidade Gerida, o seu anfitrião ou cliente deve estar a ser executado com um Serviço do Azure e ter configurado esse serviço com uma identidade Gerida Atribuída pelo Sistema ou uma identidade Gerida Atribuída pelo Utilizador.

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 de autenticação SystemManagedIdentity, o ID do cliente é ignorado e a identidade gerida pelo sistema para o serviço é usada.

Ao usar os Tipos de Identidade Gerida, o seu anfitrião ou cliente deve estar a ser executado com um Serviço do Azure e ter configurado esse serviço com uma identidade Gerida Atribuída pelo Sistema ou uma identidade Gerida Atribuída pelo Utilizador.

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 para SingleTenantWorkloadIdentity:

  "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 SN+I e 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"
        ]
      }
    }
  },

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

Certidão

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

Configuração MSAL é uma configuração opcional, se não definida ou fornecida, é utilizada a configuração predefinida para esses valores.

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 de fluxos de autenticação para integração de telemetria, caso precise resolver problemas de 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.