Configurar a autenticação em seu agente

O pacote .NET Agents SDK Biblioteca do Microsoft Authenticator (MSAL) fornece ferramentas que ajudam você a criar tokens de acesso para clientes de agente e serviços externos de um agente auto-hospedado SDK de Agentes do Microsoft 365.

O pacote Microsoft.Agents.Athentication.Msal fornece a classe MsalAuth, que é o provedor de autenticação principal. Você pode configurá-lo para os seguintes tipos de credenciais:

• Locatário único com segredo do cliente e Multilocatário com segredo do cliente
• Certificado de cliente usando a impressão digital
• Certificado de cliente usando o nome do titular (incluindo SN+I)
• Identidade gerenciada atribuída pelo usuário
• Identidade gerenciada atribuída pelo sistema
• Credenciais federadas
• Identidade da carga de trabalho

Instalar o pacote de autenticação

Instale o pacote de autenticação MSAL do NuGet:

dotnet add package Microsoft.Agents.Authentication.Msal

Locatário único versus multilocatário

A autenticação por segredo do cliente oferece suporte a configurações de locatário único e de vários locatários.

Configurar uma conexão

O pacote de autenticação MSAL permite que você crie e use vários clientes distintos com o mecanismo de hospedagem do Agents Framework. Com o pacote de autenticação MSAL, você pode fornecer várias configurações de conexão no arquivo de configuração do aplicativo. Cada configuração de conexã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.

Variáveis de ambiente para cada tipo de autenticação

O agente obtém a configuração do MSAL em tempo de execução a partir de variáveis de ambiente.

As seções a seguir descrevem as configurações necessárias e opcionais para cada um dos tipos de autenticação de MSAL com suporte, juntamente com snippets de configuração de exemplo para cada tipo.

Locatário único com segredo do cliente

Use essas configurações para configurar uma conexão de locatário único que se autentica com um segredo do cliente.

Aqui está um exemplo de appsettings para locatário ClientSecretúnico:

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

Multilocatário com segredo do cliente

Use essas configurações para configurar uma conexão multilocatário que se autentica com um segredo do cliente.

Aqui está um exemplo de appsettings para multilocatário com segredo do cliente:

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

Identidade gerenciada atribuída pelo usuário

Use essas configurações para configurar a aquisição de token com uma identidade gerenciada atribuída pelo usuário.

Aqui está um exemplo de appsettings para Identidade Gerenciada Atribuída pelo Usuário:

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

Identidade gerenciada atribuída pelo sistema

Quando você usa SystemManagedIdentity, o agente ignora qualquer ID de cliente fornecida e usa a identidade gerenciada pelo sistema.

Aqui está um exemplo de appsettings do tipo de autenticação de Identidade Gerenciada atribuída pelo sistema:

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

Credenciais federadas

Use essas configurações para configurar uma conexão que troca credenciais federadas por tokens de acesso.

Aqui está um exemplo de appsettings para Federated Credentials:

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

Identidade da carga de trabalho

Use essas configurações para configurar a autenticação de identidade de carga de trabalho usando um arquivo de token federado.

Aqui está um exemplo de appsettings para locatário WorkloadIdentityúnico:

  "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 credenciais federadas ou de declaração do cliente para identidade da carga de trabalho

Use essas configurações opcionais para personalizar o conteúdo da declaração do cliente para credenciais federadas ou fluxos de 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,
        }
      }
    }
  }

Certificado com nome do titular (incluindo SN+I)

Use estas configurações para configurar a autenticação baseada em certificado usando o nome do titular do certificado, incluindo cenários de SN+I.

Aqui está um exemplo de appsettings para certificado usando o nome da entidade para Nome da Entidade e Emissor (SNI) e multilocatário:

  "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 configuração de aplicativo para Nome do Titular do Certificado para SN+I e locatário único:

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

Certificado do cliente usando impressão digital

Use essas configurações para configurar a autenticação baseada em certificado por impressão digital do certificado.

Aqui está um exemplo de configuração de appsettings para certificado usando a impressão digital 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"
        ]
      }
    }
  },

Provedor de configuração padrão para MSAL

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

Aqui está um exemplo do provedor de configuração padrão do MSAL para um host do ASP.NET Core na classe Program.cs.

Isso é gerenciado pela instância IConnections registrada. A IConnections instância é adicionada por padrão quando você usa AddAgent.

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

No entanto, se você não estiver usando AddAgent, será necessário registrar explicitamente a IConnections instância.

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

Mais opções de configuração da MSAL

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

Essas configurações são:

Use as seguintes configurações compartilhadas para controlar o tempo limite da solicitação MSAL, o comportamento de repetição e os detalhes de log.

Essas configurações são compartilhadas com todos os clientes que criam usando o Provedor de Autenticação MSAL. Essas configurações destinam-se a ser lidas por um leitor IConfiguration, a partir de uma seção de configuração chamada "MSALConfiguration".

Aqui está um exemplo da entrada em um appsettings.json arquivo:

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

Nesse caso, esse bloco de configurações instruiria todos os clientes MSAL criados com o provedor MSAL a habilitar o registro em log de dados pessoais, definiria o tempo limite como 40 segundos e reduziria a contagem de repetições para 1.

Essa extensão procura uma seção de configuração chamada "MSALConfiguration" em seu IConfiguration objeto e cria 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 MSAL usando valores padrão.

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

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

Suporte ao registro em log para autenticação

O sistema de autenticação MSAL permite o registro em log independente de fluxos de autenticação para integração de telemetria, caso seja necessário solucionar problemas de aquisição de token.

Para habilitar o log, adicione uma entrada para Microsoft.Agents.Authentication.Msal nas configurações do aplicativo para configurar um ILogger para gerar relatórios sobre operações de token das suas conexões. Se você adicionar a opção MSALEnabledLogPII , isso também inclui dados pessoais para sua conexão.

Aqui está um exemplo do bloco de registro nesse caso:

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

Nesse caso, o registro em log está habilitado para vários módulos, incluindo Microsoft.Agents.Authentication.Msal, em que o nível de rastreamento é "Rastreamento" para MSAL.

O SDK do JavaScript requer um AuthenticationProvider para obter JWT (Tokens Web JSON) para enviar atividades para o canal de destino. Para obter mais informações, consulte tokens do Access na plataforma de identidade da Microsoft.

O pacote @microsoft/agents-hosting fornece um provedor de autenticação padrão com base em MICROSOFT AUTHENTICATION LIBRARY (MSAL). Você pode configurá-lo para os seguintes tipos de autenticação:

• Locatário único com segredo do cliente
• Multilocatário com segredo do cliente
• Identidade gerenciada pelo usuário
• Identidade gerenciada pelo sistema
• Credenciais federadas
• Identidade da carga de trabalho
• Certificado

Instalar o pacote de autenticação

Instale o pacote de autenticação MSAL do npm:

npm install @microsoft/agents-hosting

Locatário único versus multilocatário

A autenticação por segredo do cliente e por certificado do cliente oferece suporte a configurações de locatário único e multilocatário.

Identidade Gerenciada Atribuída pelo Usuário, Identidade Gerenciada do Sistema, Credenciais Federadas e Identidade de Carga de Trabalho oferecem suporte apenas a configurações de locatário único.

Configurar uma conexão

A biblioteca de autenticação MSAL permite que você crie e use vários clientes distintos com o mecanismo de hospedagem do Agents Framework. Usando a biblioteca de autenticação MSAL, você pode fornecer várias configurações de conexão no arquivo de configuração do aplicativo. Cada configuração de conexão pode criar um cliente de autenticação nomeado para dar suporte a comunicações com serviços externos ou outros agentes.

As seções a seguir descrevem as configurações necessárias e opcionais para cada um dos tipos de autenticação com suporte para o provedor de autenticação MSAL. Eles também incluem trechos de exemplos de configuração para cada tipo.

Variáveis de ambiente para cada tipo de autenticação

O agente obtém a configuração do MSAL em tempo de execução a partir de variáveis de ambiente ao usar a função auxiliar loadAuthConfigFromEnv(): AuthConfiguration. Inicializa-se o CloudAdapter com o AuthConfiguration.

As configurações de conexão usam o formato CONNECTIONS__<CONNECTION_NAME>__SETTINGS__<PROPERTY>.

Quando AUTHTYPE estiver presente, o SDK usará esse valor para selecionar o fluxo de aquisição de token. Quando AUTHTYPE é omitido, o SDK volta para o comportamento herdado e infere o fluxo de autenticação das propriedades de credencial configuradas.

Locatário único com segredo do cliente

Use estas configurações para configurar uma conexão de locatário único que usa um segredo do cliente para autenticação.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Locatário único com segredo do cliente é a configuração recomendada para desenvolvimento local.

Multilocatário com segredo do cliente

Para cenários multilocatário que usam um segredo do cliente, defina o endpoint de autoridade para o locatário botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

UserManagedIdentity

Use essas configurações para configurar a aquisição de token com uma Identidade Gerenciada Atribuída pelo Usuário.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

A Identidade Gerenciada é a configuração recomendada para cenários de produção. Para saber mais, confira identidades gerenciadas para recursos do Azure.

SystemManagedIdentity

Se você usar o tipo SystemManagedIdentityde autenticação, a ID do cliente será ignorada e a identidade gerenciada pelo sistema para o serviço será usada.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

FederatedCredentials

Use essas configurações para configurar um aplicativo de locatário único que se autentica por meio de Credenciais Federadas.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=FederatedCredentials
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/{tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__FICCLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Para obter mais informações, consulte Autenticação usando credenciais de identidade federadas.

WorkloadIdentity

Use essas configurações para configurar a obtenção de token por meio da Microsoft Entra Workload Identity.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=WorkloadIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/{tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__FEDERATEDTOKENFILE=/var/run/secrets/azure/tokens/azure-identity-token
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Locatário único com certificado de cliente

Use essas configurações para configurar uma conexão de locatário único que se autentica com um certificado de cliente.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=Certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Multitenant com certificado do cliente

Para cenários multilocatários que usam certificado de cliente, defina o endpoint de autoridade para o locatário botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=Certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Compatibilidade retroativa com o SDK do Azure Bot Framework

Para carregar a configuração usando o mesmo formato que o SDK do Azure Bot Framework, use loadPrevAuthConfigFromEnv(): AuthConfiguration.

Use esses nomes de configuração herdados ao migrar as configurações existentes do SDK do Bot Framework.

MicrosoftAppTenantId={tenant-id-guid}
MicrosoftAppId={app-id-guid}
MicrosoftAppPassword={app-registration-secret}

Provedor de autenticação personalizado

Os usuários que exigem um provedor de autenticação personalizado podem implementar a interface:

export interface AuthProvider {
  getAccessToken: (authConfig: AuthConfiguration, scope: string) => Promise<string>
}

Como exemplo, implemente o AuthProvider usando @azure/identity:

import { EnvironmentCredential } from "@azure/identity"
import { AuthProvider, AuthConfiguration } from "@microsoft/agents-hosting"
class DevTokenProvider implements AuthProvider {
  async getAccessToken(authConfig: AuthConfiguration): Promise<string> {
    const id = new EnvironmentCredential()
    const tokenResponse = await id.getToken("https://api.botframework.com/.default")
    return tokenResponse.token
  }

Para instanciar o CloudAdapter por meio do DevTokenProvider

const adapter = new CloudAdapter(authConfig, new DevTokenProvider())

amework.com/.default") retornar tokenResponse.token }

To instantiate the `CloudAdapter` by using the `DevTokenProvider`

```ts
const adapter = new CloudAdapter(authConfig, new DevTokenProvider())

O pacote da Biblioteca do Microsoft Authenticator (MSAL) para o SDK Python Agents fornece ferramentas que ajudam a criar tokens de acesso para clientes de agentes e serviços externos a partir de um agente auto-hospedado do SDK de Agentes do Microsoft 365.

O microsoft-agents-authentication-msal pacote fornece a MsalAuth classe, que é o provedor de autenticação principal. Você pode configurá-lo para os seguintes tipos de credenciais:

• Segredo do cliente
• Certificado do cliente
• Identidade gerenciada atribuída pelo usuário
• Identidade gerenciada atribuída pelo sistema

Instalar o pacote de autenticação

Instale o pacote de autenticação MSAL do PyPI:

pip install microsoft-agents-authentication-msal

Locatário único versus multilocatário

A autenticação por segredo do cliente e por certificado do cliente oferece suporte a configurações de locatário único e multilocatário.

A Identidade Gerenciada Atribuída pelo Usuário e a Identidade Gerenciada Atribuída pelo Sistema só oferecem suporte a configurações de locatário único.

Configurar uma conexão

A biblioteca de autenticação MSAL permite que você crie e use vários clientes distintos com o mecanismo de hospedagem do Agents Framework. Cada configuração de conexão cria um cliente de autenticação nomeado para dar suporte a comunicações com serviços externos ou outros agentes.

Forneça a configuração por meio de variáveis de ambiente que usam a convenção de nomenclatura de sublinhado duplo (__) para configurações aninhadas. A MsalConnectionManager classe lê essas variáveis para construir AgentAuthConfiguration instâncias para cada conexão nomeada.

Variáveis de ambiente para cada tipo de autenticação

O agente obtém a configuração do MSAL em tempo de execução a partir de variáveis de ambiente usando a função auxiliar load_configuration_from_env().

As seções a seguir descrevem as configurações necessárias para cada um dos tipos de autenticação com suporte, juntamente com trechos de variável de ambiente de exemplo para cada tipo.

Locatário único com segredo do cliente

Use essas configurações para configurar uma conexão de locatário único que se autentica com um segredo do cliente.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}

Tenant único com segredo do cliente é a configuração recomendada para desenvolvimento local.

Multitenant com o segredo do cliente

Para cenários multitenant que usam um segredo do aplicativo, defina o endpoint de autoridade para o locatário botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com

Identidade gerenciada atribuída pelo usuário

Use essas configurações para configurar a aquisição de token com uma identidade gerenciada atribuída pelo usuário.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity

A Identidade Gerenciada é a configuração recomendada para cenários de produção. Para saber mais, confira identidades gerenciadas para recursos do Azure.

Identidade gerenciada atribuída pelo sistema

Se você usar o tipo SystemManagedIdentityde autenticação, a ID do cliente será ignorada e a identidade gerenciada pelo sistema para o serviço será usada.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity

Locatário único com certificado de cliente

Use essas configurações para configurar uma conexão de locatário único que se autentica com um certificado de cliente.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}

Multilocatário com certificado do cliente

Para cenários multitenant que usam certificado de cliente, defina o endpoint de autoridade para o locatário botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com

Configurar o gerenciador de conexões

A MsalConnectionManager classe pode gerenciar várias conexões de autenticação para seu agente. Ele lê as configurações de conexão e cria MsalAuth instâncias para cada conexão nomeada.

Veja um exemplo de como configurar o gerenciador de conexões e iniciar seu agente:

from os import environ

from microsoft_agents.hosting.aiohttp import start_agent_process, CloudAdapter
from microsoft_agents.hosting.core import Authorization, AgentApplication, TurnState, MemoryStorage

from dotenv import load_dotenv
from aiohttp.web import Request, Response, Application, run_app
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.activity import load_configuration_from_env

def start_server(
    agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
):
    async def entry_point(req: Request) -> Response:
        agent: AgentApplication = req.app["agent_app"]
        adapter: CloudAdapter = req.app["adapter"]
        return await start_agent_process(req, agent, adapter)

    APP = Application()
    APP.router.add_post("/api/messages", entry_point)
    APP["agent_configuration"] = auth_configuration
    APP["agent_app"] = agent_application
    APP["adapter"] = agent_application.adapter

    try:
        run_app(APP, host="localhost", port=environ.get("PORT", 3978))
    except Exception as error:
        raise error

load_dotenv()
agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

start_server(
    agent_application=AGENT_APP, auth_configuration=CONNECTION_MANAGER.get_default_connection_configuration()
)

Consulte o exemplo de início rápido Python para obter um exemplo completo de como usar o MsalConnectionManager em um agente de Python.

Provedor de autenticação personalizado

Os usuários que exigem um provedor de autenticação personalizado podem implementar a AccessTokenProviderBase classe base:

from microsoft_agents.hosting.core import AccessTokenProviderBase

class CustomAuthProvider(AccessTokenProviderBase):
    async def get_access_token(
        self, resource_url: str, scopes: list[str], force_refresh: bool = False
    ) -> str:
        # Implement custom token acquisition logic
        token = await your_custom_token_logic(resource_url, scopes)
        return token

Suporte ao registro em log para autenticação

O sistema de autenticação MSAL usa o módulo padrão do Python logging com o nome do logger microsoft_agents.authentication.msal. Para habilitar o registro detalhado em log dos fluxos de autenticação para solucionar problemas na obtenção de token, configure o logger em seu aplicativo:

import logging

logging.basicConfig(level=logging.WARNING)
logging.getLogger("microsoft_agents.authentication.msal").setLevel(logging.DEBUG)