Konfigurowanie uwierzytelniania w agencie języka JavaScript

Zestaw SDK języka JavaScript wymaga elementu AuthenticationProvider, aby uzyskać tokeny JWT w celu wysyłania działań do kanału docelowego. Aby dowiedzieć się więcej, zobacz Access tokens in the Microsoft identity platform (Tokeny dostępu na platformie tożsamości firmy Microsoft)

Pakiet @microsoft/agents-hosting udostępnia domyślnego dostawcę uwierzytelniania na podstawie biblioteki MSAL, który można skonfigurować dla następujących typów poświadczeń:

• Tajemnica klienta
• Certyfikat klienta
• Tożsamości zarządzane przypisane przez użytkownika
• Poświadczenia tożsamości federacyjnej (FIC)

Pojedyncza dzierżawa a wielodostępne

Uwierzytelnianie sekretem klienta i certyfikatem klienta obsługuje zarówno konfiguracje jednostanowe, jak i wielostanowe.

Tożsamości zarządzane przypisane przez użytkownika i poświadczenia tożsamości federacyjnej obsługują tylko konfiguracje z jedną dzierżawą.

Uwaga / Notatka

W przypadku środowiska wielodostępnego należy skonfigurować wystąpienie usługi Azure Bot jako wielodostępne, a rejestracja aplikacji Microsoft Entra ID musi być skonfigurowana jako Konta w dowolnym katalogu organizacyjnym (dowolna dzierżawa Microsoft Entra ID — wielodostępna). Aby dowiedzieć się więcej, zobacz Pojedyncze i wielodostępne aplikacje

Zmienne środowiskowe dla każdego typu uwierzytelniania

Konfiguracja jest uzyskiwana w czasie wykonywania ze zmiennych środowiskowych przy użyciu funkcji pomocnika loadAuthConfigFromEnv(): AuthConfiguration. Wystąpienie CloudAdapter musi zostać zainicjowane za pomocą polecenia AuthConfiguration.

Na podstawie podanych zmiennych typ uwierzytelniania jest wnioskowany zgodnie z poniższym opisem.

Pojedyncza dzierżawa z kluczem tajnym klienta

Nazwa ustawień	Typ	Wartość domyślna	Opis
tenantId	Sznurek	Null	Identyfikator dzierżawy Microsoft Entra ID dla rejestracji aplikacji.
clientId	Sznurek	Null	Identyfikator klienta (identyfikator aplikacji) rejestracji aplikacji.
clientSecret	Sznurek	Null	Tajemnica przypisana do rejestracji aplikacji. Należy używać tylko do celów testowania i programowania.

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

Jest to zalecana konfiguracja programowania lokalnego.

Pojedyncza dzierżawa z certyfikatem klienta

Nazwa ustawień	Typ	Wartość domyślna	Opis
tenantId	Sznurek	Null	Identyfikator dzierżawcy Microsoft Entra ID na potrzeby rejestracji aplikacji.
clientId	Sznurek	Null	Identyfikator klienta (identyfikator aplikacji) rejestracji aplikacji.
certPemFile	Sznurek	Null	Ścieżka do pliku certyfikatu PEM.
certKeyFile	Sznurek	Null	Ścieżka do pliku klucza prywatnego dla certyfikatu.

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

Uwaga / Notatka

Plik klucza nie powinien używać żadnego hasła.

Pojedyncza dzierżawa z tożsamością zarządzaną przypisaną przez użytkownika

Nazwa ustawień	Typ	Wartość domyślna	Opis
tenantId	Sznurek	Null	Identyfikator Microsoft Entra ID tenant ID dla rejestracji aplikacji.
clientId	Sznurek	Null	Identyfikator klienta tożsamości zarządzanej do użycia podczas tworzenia tokenu dostępu.

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

Jest to zalecana konfiguracja dla scenariuszy produkcyjnych. Aby dowiedzieć się więcej, zobacz Tożsamości zarządzane dla zasobów platformy Azure.

Uwaga / Notatka

Agent musi działać w dowolnej usłudze platformy Azure obsługującej tożsamości zarządzane. Aby zobaczyć, które usługi platformy Azure obsługują tożsamości zarządzane, zobacz Tożsamości zarządzane dla zasobów platformy Azure. Tożsamość zarządzana powinna być zgodna z tożsamością skonfigurowaną w elemencie EntraID. Aby uzyskać więcej informacji, zobacz Jak skonfigurować tożsamości zarządzane.

Pojedynczy dzierżawca z poświadczeniami federacyjnymi tożsamości

Nazwa ustawień	Typ	Wartość domyślna	Opis
tenantId	Sznurek	Null	Identyfikator dzierżawy Microsoft Entra ID na potrzeby rejestracji aplikacji.
clientId	Sznurek	Null	Identyfikator klienta (identyfikator aplikacji) rejestracji aplikacji.
FICClientId	Sznurek	Null	Identyfikator klienta tożsamości zarządzanej poświadczeń tożsamości federacyjnej.

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

Aby uzyskać więcej informacji, zobacz Uwierzytelnianie przy użyciu poświadczeń tożsamości federacyjnej.

Wielodostępne z kluczem tajnym klienta ClientSecret

Nazwa ustawień	Typ	Wartość domyślna	Opis
clientId	Sznurek	Null	Identyfikator klienta (identyfikator aplikacji) rejestracji aplikacji.
clientSecret	Sznurek	Null	Tajemnica skojarzona z rejestracją aplikacji. Należy używać tylko do celów testowania i programowania.

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

Wielodostępność przy użyciu certyfikatu klienta

Nazwa ustawień	Typ	Wartość domyślna	Opis
clientId	Sznurek	Null	Identyfikator klienta (identyfikator aplikacji) rejestracji aplikacji.
certPemFile	Sznurek	Null	Ścieżka do pliku certyfikatu PEM.
plik klucza certyfikatu	Sznurek	Null	Ścieżka do pliku klucza prywatnego dla certyfikatu.

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

Zgodność z poprzednimi wersjami za pomocą zestawu SDK usługi Azure Bot Framework

Aby załadować konfigurację przy użyciu tego samego formatu co zestaw SDK usługi Azure Bot Framework, udostępniamy inną funkcję pomocnika loadBotAuthConfigFromEnv(): AuthConfiguration.

Nazwa ustawień	Typ	Wartość domyślna	Opis
MicrosoftAppTenantId	Sznurek	Null	Identyfikator dzierżawy Microsoft Entra ID (format starszej wersji zestawu SDK platformy Bot Framework).
MicrosoftAppId	Sznurek	Null	Identyfikator klienta (identyfikator aplikacji) rejestracji aplikacji (starszy format zestawu SDK platformy Bot Framework).
MicrosoftAppPassword	Sznurek	Null	Sekret aplikacji (starszy format SDK Bot Framework).

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

Niestandardowy dostawca uwierzytelniania

Użytkownicy, którzy wymagają dostosowanego dostawcy uwierzytelniania, mogą zaimplementować interfejs:

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

Na przykład zaimplementujmy metodę AuthProvider, używając @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
  }

Aby utworzyć CloudAdapter wystąpienie obiektu przy użyciu elementu DevTokenProvider

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