Configurar a autenticação em um agente JavaScript

O SDK do JavaScript requer um AuthenticationProvider para obter tokens JWT para enviar atividades para o canal de destino. Para saber mais, confira os tokens do Access na plataforma de identidade da Microsoft

O pacote @microsoft/agents-hosting fornece um provedor de autenticação padrão com base na MSAL, que pode ser configurado para os seguintes tipos de credenciais:

• Segredo de Cliente
• Certificado do Cliente
• Identidades Gerenciadas Atribuídas pelo Usuário
• Credenciais de identidade federadas (FIC)

Locatário único versus multilocatário

A autenticação de Segredo do Cliente e Certificado de Cliente dá suporte a configurações tanto de locatário único quanto multilocatário.

Identidades Gerenciadas Atribuídas pelo Usuário e Credenciais de Identidade Federadas dão suporte apenas a configurações de locatário único.

Note

Para multilocatário, você precisa configurar a instância do Bot do Azure como multilocatário e o registro do aplicativo do Microsoft Entra ID deve ser configurado como Contas em qualquer diretório organizacional (qualquer locatário do Microsoft Entra ID – Multilocatário). Para saber mais, consulte Aplicativos únicos e multilocatários

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

A configuração é obtida em runtime de variáveis de ambiente, usando a função loadAuthConfigFromEnv(): AuthConfigurationauxiliar. A CloudAdapter instância precisa ser inicializada com o AuthConfiguration.

Com base nas variáveis fornecidas, o tipo de autenticação é inferido, conforme descrito abaixo.

Locatário único com segredo do cliente

Nome da Configuração	Tipo	Valor Padrão	Description
tenantId	String	Nulo	O ID do locatário do Microsoft Entra ID para o registro do aplicativo.
clientId	String	Nulo	O ID do cliente (ID do aplicativo) do registro do aplicativo.
clientSecret	String	Nulo	O segredo associado ao registro do aplicativo. Deve ser usado apenas para fins de teste e desenvolvimento.

tenantId={tenant-id-guid}
clientId={app-id-guid}
clientSecret={app-registration-secret}

Essa é a configuração recomendada para desenvolvimento local.

Locatário único com Certificado de Cliente

Nome da Configuração	Tipo	Valor Padrão	Description
tenantId	String	Nulo	O ID do locatário do Microsoft Entra ID para o registro do aplicativo.
clientId	String	Nulo	O ID do cliente (ID do aplicativo) do registro do aplicativo.
certPemFile	String	Nulo	Caminho para o arquivo de certificado PEM.
certKeyFile	String	Nulo	Caminho para o arquivo de chave privada para o certificado.

tenantId={tenant-id-guid}
clientId={app-id-guid}
certPemFile={path-to-pem-file}
certKeyFile={path-to-key-file}

Note

O arquivo de chave não deve usar nenhuma senha.

Locatário único com Identidade Gerenciada Atribuída pelo Usuário

Nome da Configuração	Tipo	Valor Padrão	Description
tenantId	String	Nulo	O ID do locatário do Microsoft Entra ID para o registro do aplicativo.
clientId	String	Nulo	A ID do cliente de identidade gerenciada a ser usada ao criar o token de acesso.

tenantId={tenant-id-guid}
clientId={app-id-guid}

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

Note

O agente precisa ser executado em qualquer serviço do Azure que dê suporte a Identidades Gerenciadas. Para ver quais serviços do Azure dão suporte a identidades gerenciadas, consulte identidades gerenciadas para recursos do Azure. A identidade gerenciada deve corresponder à configurada no EntraID. Para obter mais informações, consulte Como configurar identidades gerenciadas.

Locatário único com Credencial de Identidade Federada

Nome da Configuração	Tipo	Valor Padrão	Description
tenantId	String	Nulo	O ID do locatário do Microsoft Entra ID para o registro do aplicativo.
clientId	String	Nulo	O ID do cliente (ID do aplicativo) do registro do aplicativo.
FICClientId	String	Nulo	A ID do cliente de identidade gerenciada da Credencial de Identidade Federada.

tenantId={tenant-id-guid}
clientId={app-id-guid}
FICClientId={client-id-of-the-FIC}

Para obter mais detalhes, consulte Autenticação usando credenciais de identidade federadas.

Multilocatário com ClientSecret

Nome da Configuração	Tipo	Valor Padrão	Description
clientId	String	Nulo	O ID do cliente (ID do aplicativo) do registro do aplicativo.
clientSecret	String	Nulo	O segredo associado ao registro do aplicativo. Deve ser usado apenas para fins de teste e desenvolvimento.

clientId={app-id-guid}
clientSecret={app-registration-secret}

Multilocatário com Certificado de Cliente

Nome da Configuração	Tipo	Valor Padrão	Description
clientId	String	Nulo	O ID do cliente (ID do aplicativo) do registro do aplicativo.
certPemFile	String	Nulo	Caminho para o arquivo de certificado PEM.
certKeyFile	String	Nulo	Caminho para o arquivo de chave privada para o certificado.

clientId={app-id-guid}
certPemFile={path-to-pem-file}
certKeyFile={path-to-key-file}

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, fornecemos outra função loadBotAuthConfigFromEnv(): AuthConfigurationauxiliar.

Nome da Configuração	Tipo	Valor Padrão	Description
MicrosoftAppTenantId	String	Nulo	A ID do locatário do Microsoft Entra ID (formato herdado do SDK do Bot Framework).
MicrosoftAppId	String	Nulo	A ID do cliente (ID do aplicativo) do registro do aplicativo (formato herdado do SDK do Bot Framework).
MicrosoftAppPassword	String	Nulo	O segredo do aplicativo (formato herdado 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>
}

Por exemplo, vamos implementar o AuthProvider usando @azure/identity:

import { EnvironmentCredential } from "@azure/identity"
import { AuthProvider, AuthConfiguration } from "@microsoft/agents-bot-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 criar uma instância do CloudAdapter usando o DevTokenProvider

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