Configurar autenticação em seu agente

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

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

• Locatário único com segredo do cliente e Multilocatário com segredo do cliente
• Certificado do cliente usando Impressão digital
• Certificado do cliente usando o nome da entidade (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 vs multilocatário

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

Configurar uma conexão do

O pacote de autenticação MSAL permite que você crie e use vários clientes distintos com o mecanismo de hospedagem da Estrutura de Agentes. Ao utilizar a biblioteca de autenticação MSAL, você pode fornecer múltiplas 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 MSAL no runtime a partir das variáveis de ambiente.

As próximas seções descrevem as configurações obrigatórias e opcionais para cada um dos tipos de autenticação compatíveis com MSAL, acompanhadas de exemplos de configuração para cada tipo.

Locatário único com segredo do cliente

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

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

Multilocatário com segredo do cliente

Use estas configurações para definir uma conexão de multilocatário que autentica com um segredo do cliente.

Veja 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

Utilize estas configurações para definir a aquisição de tokens 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 estas configurações para definir uma conexão que realiza a troca de 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 estas configurações para definir a autenticação da identidade de carga de trabalho usando um arquivo de token federado.

Aqui está um exemplo de appsettings para locatário ú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 de declaração de cliente de identidade de carga de trabalho ou de credenciais federadas opcionais

Use estas configurações opcionais para personalizar o conteúdo da declaração do cliente em fluxos de identidade de carga de trabalho ou credenciais federadas.

  "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 usando o nome da entidade (incluindo SN+I)

Use essas configurações para definir a autenticação baseada em certificado pelo nome da entidade do certificado, incluindo cenários 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 appsettings para Nome da Entidade 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 definir a autenticação baseada em certificado por impressão digital do certificado.

Aqui está um exemplo 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 MSAL padrão para um host ASP.NET principal em uma classe Program.cs:

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

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

No entanto, caso não esteja usando AddAgent, você deverá registrar explicitamente a instância IConnections.

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

Mais opções de configuração do 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 das solicitações MSAL, o comportamento de repetição e o nível de detalhamento dos logs.

Essas configurações são compartilhadas com todos os clientes que criam usando o Provedor de Autenticação MSAL. Essas configurações devem ser lidas de um Leitor de IConfiguration, em uma seção de configuração chamada "MSALConfiguration".

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

{
  "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" no objeto IConfiguration 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 registro em log, adicione uma entrada de Microsoft.Agents.Authentication.Msal às configurações do aplicativo para configurar um ILogger que vai relatar as operações de token das suas conexões. Se você adicionar a opção MSALEnabledLogPII, isso também incluirá dados pessoais da sua conexão.

Aqui está um exemplo do bloco de registro em log neste 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 Tokens Web JSON (JWT) e enviar atividades para o canal de destino. Para obter mais informações, consulte Tokens de acesso no plataforma de identidade da Microsoft.

O pacote @microsoft/agents-hosting fornece um provedor de autenticação padrão baseado na MSAL (Biblioteca de Autenticação da Microsoft). 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 a partir do npm:

npm install @microsoft/agents-hosting

Locatário único vs. multilocatário

A autenticação de segredo do cliente e certificado do cliente dá suporte a configurações tanto de locatário único quanto em multilocatário.

Identidade Gerenciada Atribuída pelo Usuário, Identidade Gerenciada do Sistema, Credenciais Federadas e Identidade da Carga de Trabalho só suportam configurações de locatário único.

Configurar uma conexão do

A biblioteca de autenticação MSAL permite que você crie e use vários clientes distintos com o mecanismo de hospedagem Estrutura de Agentes. Ao utilizar a biblioteca de autenticação MSAL, você pode fornecer múltiplas 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 suportar comunicações com serviços externos ou outros agentes.

As seções a seguir descrevem as configurações obrigatórias e opcionais para cada um dos tipos de autenticação suportados pelo provedor de autenticação MSAL. Elas também incluem exemplos de trechos de configuração para cada tipo.

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

O agente obtém a configuração da MSAL no runtime a partir das variáveis de ambiente usando a função auxiliar loadAuthConfigFromEnv(): AuthConfiguration. O CloudAdapter é inicializado com o AuthConfiguration.

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

Quando AUTHTYPE está presente, o SDK usa esse valor para selecionar o fluxo de aquisição do token. Quando AUTHTYPE é omitido, o SDK retorna ao comportamento herdado e infere o fluxo de autenticação a partir das propriedades de credenciais configuradas.

Locatário único com segredo do cliente

Use estas configurações para definir uma conexão de locatário único que 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}
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 ponto de extremidade 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 definir aquisições de tokens 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

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

SystemManagedIdentity

Se você usar o tipo de autenticação SystemManagedIdentity, 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 estas configurações para definir um aplicativo de locatário único que 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 mais informações, veja Autenticação usando Credenciais de Identidade Federada.

WorkloadIdentity

Use essas configurações para definir a aquisição de tokens por meio da Identidade de Carga de Trabalho do Microsoft Entra.

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 do cliente

Use estas configurações para definir uma conexão de locatário único que autentica com um certificado do 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

Multilocatário com certificado do cliente

Para cenários multilocatário que usam um certificado do cliente, defina o ponto de extremidade 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 com versões anteriores do SDK do Azure Bot Framework

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

Ao migrar configurações existentes do SDK do Bot Framework, use estes nomes de configuração legados.

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

Provedor de autenticação personalizado

Usuários que precisam de 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 usando o DevTokenProvider

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

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

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

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

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

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

• 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 vs multilocatário

A autenticação de segredo do cliente e certificado do cliente dá suporte a configurações tanto de locatário único quanto em multilocatário.

Identidade Gerenciada Atribuída pelo Usuário e Identidade Gerenciada Atribuída pelo Sistema suportam apenas configurações de locatário único.

Configurar uma conexão do

A biblioteca de autenticação MSAL permite que você crie e use vários clientes distintos com o mecanismo de hospedagem da Estrutura de Agentes. Cada configuração de conexão cria um cliente de autenticação nomeado para suportar 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 classe MsalConnectionManager lê essas variáveis para criar instâncias AgentAuthConfiguration para cada conexão nomeada.

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

O agente obtém a configuração de MSAL no runtime 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 suportados, com exemplos de trechos de variáveis de ambiente para cada tipo.

Locatário único com segredo do cliente

Use estas configurações para definir uma conexão de locatário único que 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}

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 ponto de extremidade 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

Utilize estas configurações para definir a aquisição de tokens com uma identidade gerenciada atribuída pelo usuário.

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

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

Identidade gerenciada atribuída pelo sistema

Se você usar o tipo de autenticação SystemManagedIdentity, 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 do cliente

Use estas configurações para definir uma conexão de locatário único que autentica com um certificado do 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 multilocatário que usam um certificado do cliente, defina o ponto de extremidade 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 classe MsalConnectionManager pode gerenciar múltiplas conexões de autenticação para seu agente. Ela lê as configurações de conexão e cria instâncias de MsalAuth para cada conexão nomeada.

Aqui está 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()
)

Confira o exemplo de início rápido do Python para ver um exemplo completo de como usar o MsalConnectionManager em um agente Python.

Provedor de autenticação personalizado

Usuários que precisam de um provedor de autenticação personalizado podem implementar a classe base AccessTokenProviderBase:

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 dos fluxos de autenticação para solucionar problemas na aquisição de tokens, configure o logger em seu aplicativo:

import logging

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