Configurar autenticação num agente JavaScript

O SDK JavaScript requer um AuthenticationProvider para obter tokens JWT para enviar atividades para o canal de destino. Para saber mais, consulte Tokens de acesso na plataforma de identidade Microsoft

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

  • Segredo do Cliente
  • Certificado de cliente
  • Identidades gerenciadas atribuídas pelo usuário
  • Credenciais de Identidade Federada (FIC)

Inquilino único vs multiinquilino

A autenticação por Client Secret e Client Certificate suporta as configurações single-tenant e multitenant.

As Identidades Geridas Atribuídas pelo Utilizador e as Credenciais de Identidade Federada suportam apenas configurações de inquilino único.

Observação

Para multiinquilino, precisa de configurar a instância do Azure Bot como multiinquilino e o registo da aplicação Microsoft EntraID deve ser configurado como Contas em qualquer diretório organizacional (Qualquer inquilino Microsoft Entra ID - Multiinquilino). Para saber mais, consulte Aplicações de inquilino único e de multi-inquilino

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

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

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

Inquilino único com Segredo do Cliente

Nome da configuração Tipo Valor padrão Description
tenantId Corda Nulo O ID do inquilino do Microsoft Entra ID para o registo da aplicação.
clientId Corda Nulo O ID do cliente (ID da aplicação) do registo da aplicação.
clientSecret Corda Nulo O segredo associado ao registo da aplicação. Deve ser usado apenas para fins de teste e desenvolvimento. 
tenantId={tenant-id-guid}
clientId={app-id-guid}
clientSecret={app-registration-secret}

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

Inquilino único com Certificado de Cliente

Nome da configuração Tipo Valor padrão Description
tenantId Corda Nulo O ID do inquilino do Microsoft Entra ID para o registo da aplicação.
clientId Corda Nulo O ID do cliente (ID da aplicação) do registo da aplicação.
certPemFile Corda Nulo Caminho para o ficheiro de certificado PEM.
certKeyFile Corda Nulo Caminho para o ficheiro de chave privada do certificado. 
tenantId={tenant-id-guid}
clientId={app-id-guid}
certPemFile={path-to-pem-file}
certKeyFile={path-to-key-file}

Observação

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

Inquilino único com Identidade Gerida Atribuída pelo Utilizador

Nome da configuração Tipo Valor padrão Description
tenantId Corda Nulo O ID do inquilino do Microsoft Entra ID para o registo da aplicação.
clientId Corda Nulo O ID de cliente de idade gerida a utilizar ao criar o token de acesso. 
tenantId={tenant-id-guid}
clientId={app-id-guid}

Esta é a configuração recomendada para cenários de produção. Para saber mais, consulte Identidades gerenciadas para recursos do Azure.

Observação

O agente precisa ser executado em qualquer serviço do Azure que ofereça 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.

Inquilino único com Credencial de Identidade Federada

Nome da configuração Tipo Valor padrão Description
tenantId Corda Nulo O ID do inquilino do Microsoft Entra ID para o registo da aplicação.
clientId Corda Nulo O ID do cliente (ID da aplicação) do registo da aplicação.
FICClientId Corda Nulo O ID de cliente de identidade gerida 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 federada.

Multitenant com ClientSecret

Nome da configuração Tipo Valor padrão Description
clientId Corda Nulo O ID do cliente (ID da aplicação) do registo da aplicação.
clientSecret Corda Nulo O segredo associado ao registo da aplicação. Deve ser usado apenas para fins de teste e desenvolvimento. 
clientId={app-id-guid}
clientSecret={app-registration-secret}

Multitenant com Certificado de Cliente

Nome da configuração Tipo Valor padrão Description
clientId Corda Nulo O ID do cliente (ID da aplicação) do registo da aplicação.
certPemFile Corda Nulo Caminho para o ficheiro de certificado PEM.
certKeyFile Corda Nulo Caminho para o ficheiro de chave privada do certificado. 
clientId={app-id-guid}
certPemFile={path-to-pem-file}
certKeyFile={path-to-key-file}

Compatibilidade retroativa com o Azure Bot Framework SDK

Para carregar a configuração usando o mesmo formato do SDK do Azure Bot Framework, fornecemos outra função loadBotAuthConfigFromEnv(): AuthConfigurationauxiliar.

Nome da configuração Tipo Valor padrão Description
MicrosoftAppTenantId Corda Nulo O ID do tenant ID do Microsoft Entra (formato legado do SDK do Bot Framework).
MicrosoftAppId Corda Nulo O ID do cliente (ID da aplicação) do registo da aplicação (formato legado do Bot Framework SDK).
Microsoft App Password Corda Nulo O segredo da aplicação (formato legado do Bot Framework SDK). 
MicrosoftAppTenantId={tenant-id-guid}
MicrosoftAppId={app-id-guid}
MicrosoftAppPassword={app-registration-secret}

Provedor de autenticação personalizado

Os 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, vamos implementar o AuthProvider utilizando o @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 instanciar o CloudAdapter usando o DevTokenProvider

const adapter = new CloudAdapter(authConfig, new DevTokenProvider())
  • Last updated on