Authentifizierung in Ihrem Agent konfigurieren

Der Microsoft Authentication Library (MSAL) (MSAL)-Authentifizierungsanbieter des .NET Agents SDK ist ein Hilfsprogramm, mit dem Sie Zugriffstoken für Agent-Clients und externe Dienste von einem selbst gehosteten Microsoft 365 Agents SDK-Agent erstellen können.

Das Microsoft.Agents.Athentication.Msal-Paket stellt die MsalAuth-Klasse bereit, die den zentralen Authentifizierungsanbieter darstellt. Sie können den Authentifizierungsanbieter für die folgenden Arten von Anmeldeinformationen konfigurieren:

• Einzelmandant mit geheimem Clientschlüssel und Mehrfachmandant mit geheimem Clientschlüssel
• Client-Zertifikat mit Fingerabdruck
• Clientzertifikat mit Subjektnamen (einschließlich SN+I)
• Benutzerseitig zugewiesene verwaltete Identität
• Systemseitig zugewiesene verwaltete Identität
• Verbundanmeldeinformationen
• Workloadidentität

Authentifizierungspaket installieren

Installieren Sie das MSAL-Authentifizierungspaket über NuGet:

dotnet add package Microsoft.Agents.Authentication.Msal

Einzelmandant vs. Mehrfachmandant

Die Client-Secret-Authentifizierung unterstützt sowohl Einzelmandant- als auch Mehrfachmandant-Konfigurationen.

Eine -Verbindung konfigurieren

Das MSAL-Authentifizierungspaket ermöglicht es Ihnen, mehrere unterschiedliche Clients mit der Agents Framework-Hosting-Engine zu erstellen und zu verwenden. Mit dem MSAL-Authentifizierungspaket können Sie mehrere Verbindungskonfigurationen in der Anwendungskonfigurationsdatei definieren. Jede Verbindungskonfiguration kann verwendet werden, um einen benannten Authentifizierungsclient zu erstellen, der die Kommunikation mit externen Diensten oder anderen Agenten unterstützt.

Umgebungsvariablen für jeden Authentifizierungstyp

Der Agent erhält zur Laufzeit die MSAL-Konfiguration aus Umgebungsvariablen.

Die folgenden Abschnitte beschreiben die erforderlichen und optionalen Konfigurationseinstellungen für jeden der unterstützten Authentifizierungstypen bei der MSAL-Authentifizierung sowie Beispielkonfigurationen für jeden Typ.

Einzelmandant mit geheimem Clientschlüssel

Mit diesen Einstellungen können Sie eine Einzelmandant-Verbindung konfigurieren, die mit einem geheimen Clientschlüssel authentifiziert wird.

Hier ist ein Beispiel für Appsettings für die Einzelmandanten-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"
          ],
      }
    }
  }

Mehrfachmandant mit geheimem Clientschlüssel

Verwenden Sie diese Einstellungen, um eine mandantenübergreifende Verbindung zu konfigurieren, die mit einem geheimen Clientschlüssel authentifiziert wird.

Hier ist ein Beispiel für AppSettings für eine mehrinstanzfähige Verbindung mit geheimem Clientschlüssel:

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

Benutzerseitig zugewiesene verwaltete Identität

Verwenden Sie diese Einstellungen, um die Token-Akquisition mit einer benutzerzugewiesenen verwalteten Identität zu konfigurieren.

Hier ist ein Beispiel für AppSettings für benutzerseitig zugewiesene verwaltete Identität:

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

Systemseitig zugewiesene verwaltete Identität

Wenn Sie SystemManagedIdentity verwenden, ignoriert der Agent jede angegebene Client-ID und verwendet die systemverwaltete Identität.

Hier ist ein Beispiel für appsettings für den benutzerseitig zugewiesene verwaltete Identität-Authentifizierungstyp:

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

Verbundanmeldeinformationen

Verwenden Sie diese Einstellungen, um eine Verbindung zu konfigurieren, die föderierte Zugangsdaten gegen Zugriffstoken austauscht.

Hier ist ein Beispiel für appsettings für 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"
        ]
      }
    }
  }

Workloadidentität

Verwenden Sie diese Einstellungen, um die Authentifizierung der Arbeitslast-Identität mittels einer föderierten Token-Datei zu konfigurieren.

Hier ist ein Beispiel für Appsettings für die Einzelmandanten-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"
        ]
      }
    }
  }

Optionale Verbundanmeldeinformationen oder Workloadidentitäts-Client-Assertion-Optionen

Verwenden Sie diese optionalen Einstellungen, um den Inhalt von Client-Assertions für Verbundanmeldeinformationen oder Workloadidentitätsflows anzupassen.

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

Zertifikat mit Subjektnamen (einschließlich SN+I)

Verwenden Sie diese Einstellungen, um die zertifikatsbasierte Authentifizierung anhand des Subjektnamens des Zertifikats zu konfigurieren, einschließlich SN+I-Szenarien.

Im Folgenden finden Sie ein Beispiel für Appsettings für Zertifikate unter Verwendung des Subjektnamens für den Subjektnamen und Aussteller (SNI) und die Mehrinstanzenfähigkeit:

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

Hier ist ein Beispiel für Appsettings für den Zertifikatsubjektnamen für SN+I und einen einzelnen Mandanten:

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

Client-Zertifikat mit Fingerabdruck

Verwenden Sie diese Einstellungen, um die zertifikatsbasierte Authentifizierung anhand des Zertifikats-Daumenabdrucks zu konfigurieren.

Hier ist ein Beispiel für Appsettings für ein Zertifikat mit dem Zertifikat-Fingerabdruck:

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

Standardkonfiguration-Anbieter für MSAL

Um die Einrichtung zu vereinfachen, stellen wir eine Service Provider-Erweiterung zur Verfügung, mit der Sie die Standardkonfigurationen für MSAL zu Ihrem Agent hinzufügen können.

Hier ist ein Beispiel für einen Standard-Konfigurationsanbieter für MSAL für einen ASP.NET Core-Host in einer Program.cs-Klasse.

Die registrierte IConnections Instanz verwaltet dies. Die IConnections-Instanz wird standardmäßig hinzugefügt, wenn Sie AddAgent verwenden.

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

Falls AddAgent nicht verwendet wird, muss die IConnections-Instanz explizit registriert werden.

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

Weitere MSAL-Konfigurationsoptionen

Es gibt verschiedene gemeinsame Konfigurationsoptionen, die allgemeine Einstellungen für das Abrufen von Token aus Microsoft Entra Identity steuern.

Diese Einstellungen sind:

Verwenden Sie die folgenden gemeinsamen Einstellungen, um das MSAL-Anfrage-Timeout, das Wiederholungsverhalten und die Protokollierungsdetails zu steuern.

Diese Einstellungen werden mit allen Clients geteilt, die mit dem MSAL-Authentifizierungsanbieter erstellen. Diese Einstellungen sollen aus einem IConfiguration-Reader in einem Konfigurationsabschnitt namens „MSALConfiguration“ gelesen werden.

Hier ist ein Beispiel für den Eintrag in einer appsettings.json Datei:

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

In diesem Fall würde dieser Einstellungsblock alle mit dem MSAL-Anbieter erstellten MSAL-Clients anweisen, die Protokollierung persönlicher Daten zu aktivieren, das Zeitlimit auf 40 Sekunden zu setzen und die Anzahl der Wiederholungen auf 1 zu reduzieren.

Diese Erweiterung sucht in Ihrem IConfiguration-Objekt nach einem Konfigurationsbereich mit dem Namen „MSALConfiguration“ und erstellt daraus ein MSAL-Konfigurationsobjekt.

Falls die MSALConfig-Sektion nicht gefunden wird, wird das MSAL-Konfigurationsobjekt mit den Standardwerten erstellt.

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

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

Protokollierungsunterstützung für die Authentifizierung

Das MSAL-Authentifizierungssystem ermöglicht eine unabhängige Protokollierung von Authentifizierungsabläufen zur Telemetrieintegration, falls Sie Probleme bei der Token-Beschaffung beheben müssen.

Um Protokollierung zu aktivieren, fügen Sie einen Eintrag für Microsoft.Agents.Authentication.Msal zu den App-Einstellungen Ihrer Anwendung hinzu, um eine ILogger für die Protokollierung von Token-Vorgängen Ihrer Verbindungen einzurichten. Wenn Sie die MSALEnabledLogPII Option hinzufügen, werden auch persönliche Daten für Ihre Verbindung einbezogen.

Hier ist ein Beispiel für den Protokollierungsblock in diesem Fall:

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

In diesem Fall ist die Protokollierung für mehrere Module aktiviert, darunter Microsoft.Agents.Authentication.Msal, wobei die Überwachungsebene für MSAL auf Überwachen gesetzt ist.

Das JavaScript SDK benötigt einen AuthenticationProvider, um JSON Web Tokens (JWT) zu erstellen und Aktivitäten an den Zielkanal zu übermitteln. Weitere Informationen finden Sie unter Zugriffstoken in der Microsoft Identitätsplattform.

Das @microsoft/agents-hosting-Paket stellt einen Standard-Authentifizierungsanbieter bereit, der auf der Microsoft Authentication Library (MSAL) (MSAL) basiert. Sie können das Paket für die folgenden Authentifizierungstypen konfigurieren:

• Einzelmandant mit geheimem Clientschlüssel
• Mehrfachmandant mit geheimem Clientschlüssel
• Benutzerseitig verwaltete Identität
• Systemseitig verwaltete Identität
• Verbundanmeldeinformationen
• Workloadidentität
• Zertifikat

Authentifizierungspaket installieren

Installieren Sie das MSAL-Authentifizierungspaket über npm:

npm install @microsoft/agents-hosting

Einzelmandant vs. mehrinstanzfähig

Die Authentifizierung mit geheimem Clientschlüssel und Clientzertifikat unterstützt sowohl Einzelmandanten- als auch mehrinstanzfähige Mandantkonfigurationen.

Benutzerseitig zugewiesene verwaltete Identitäten, Anmeldeinformatiopnen für Verbundidentitäten und Workload-Identität unterstützen nur Einzelmandantenkonfigurationen.

Eine -Verbindung konfigurieren

Die MSAL-Authentifizierungsbibliothek ermöglicht es Ihnen, mit der Agents Framework Hosting-Engine mehrere verschiedene Clients zu erstellen und zu nutzen. Durch die Verwendung der MSAL-Authentifizierungsbibliothek können Sie mehrere Verbindungskonfigurationen in der Anwendungskonfigurationsdatei konfigurieren. Jede Verbindungskonfiguration kann einen benannten Authentifizierungsclient erstellen, um die Kommunikation mit externen Diensten oder anderen Agenten zu unterstützen.

In den folgenden Abschnitten werden die erforderlichen und optionalen Konfigurationseinstellungen für alle unterstützten Authentifizierungsarten des MSAL-Authentifizierungsanbieters beschrieben. Sie enthalten auch Beispielkonfigurationen für jeden Authentifizierungstyp.

Umgebungsvariablen für jeden Authentifizierungstyp

Der Agent erhält zur Laufzeit die MSAL-Konfiguration aus Umgebungsvariablen mithilfe der Hilfsfunktion loadAuthConfigFromEnv(): AuthConfiguration. Der CloudAdapter wird mit AuthConfiguration initialisiert.

Die Verbindungseinstellungen verwenden das Format CONNECTIONS__<CONNECTION_NAME>__SETTINGS__<PROPERTY>.

Wenn AUTHTYPE vorhanden ist, verwendet das SDK diesen Wert, um den Token-Beschaffungsprozess auszuwählen. Wenn AUTHTYPE ausgelassen wird, fällt das SDK auf das Legacy-Verhalten zurück und bestimmt den Authentifizierungsfluss anhand der konfigurierten Anmeldeinformationen.

Einzelmandant mit geheimem Clientschlüssel

Mit diesen Einstellungen können Sie eine Einzelmandant-Verbindung konfigurieren, die mit einem geheimen Clientschlüssel authentifiziert wird.

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

Die Einzelmandant-Konfiguration mit geheimem Clientschlüssel wird für die lokale Entwicklung empfohlen.

Mehrfachmandant mit geheimem Clientschlüssel

Für Mehrinstanzen-Szenarien, die ein Client Secret verwenden, setzen Sie den Authority Endpoint auf den botframework.com-Mandant:

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

Verwenden Sie diese Einstellungen, um den Token-Erwerb mit einer benutzerzugewiesenen verwalteten Identität zu konfigurieren.

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

Verwaltete Identität ist die empfohlene Konfiguration für Produktionsszenarien. Weitere Informationen finden Sie unter What is managed identities for Azure resources? (Worum handelt es sich bei verwalteten Identitäten für Azure-Ressourcen?).

SystemManagedIdentity

Wenn Sie den Authentifizierungstyp SystemManagedIdentity verwenden, wird die Client-ID ignoriert und die systemverwaltete Identität des Dienstes verwendet.

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

FederatedCredentials

Verwenden Sie diese Einstellungen, um eine Single-Tenant-App zu konfigurieren, die mithilfe von Federated Credentials authentifiziert wird.

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

Weitere Informationen finden Sie unter Authentifizierung mithilfe von Verbundidentitäts-Anmeldeinformationen.

WorkloadIdentity

Mit diesen Einstellungen konfigurieren Sie den Token-Abruf über 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

Einzelmandant mit Clientzertifikat

Mit diesen Einstellungen können Sie eine Einzelmandant-Verbindung konfigurieren, die mit einem Client-Zertifikat authentifiziert wird.

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

Mehrinstanzenfähigkeit mit Clientzertifikat

Für mehrinstanzfähige Szenarien, die ein Client-Zertifikat verwenden, setzen Sie den Authority Endpoint auf den Mandanten 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

Abwärtskompatibilität mit Azure Bot Framework SDK

Um die Konfiguration im selben Format wie das Azure Bot Framework SDK zu laden, verwenden Sie loadPrevAuthConfigFromEnv(): AuthConfiguration.

Verwenden Sie diese Legacy-Einstellungsnamen beim Migrieren bestehender Bot Framework-SDK-Konfigurationen.

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

Benutzerdefinierter Authentifizierungsanbieter

Benutzer, die einen angepassten Authentifizierungsanbieter benötigen, können die Schnittstelle implementieren:

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

Als Beispiel lässt sich AuthProvider unter Verwendung von @azure/identity implementieren:

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
  }

Um CloudAdapter mithilfe von DevTokenProvider zu instanziieren

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())

Das Python Agents SDK-Microsoft Authentifizierungsbibliothek (MSAL)-Paket stellt Ihnen die Tools bereit, mit dem Sie Zugriffstoken für Agent-Clients und externe Dienste von einem selbst gehosteten Microsoft 365 Agents SDK-Agent erstellen können.

Das microsoft-agents-authentication-msal-Paket stellt die MsalAuth-Klasse bereit, die den zentralen Authentifizierungsanbieter darstellt. Sie können den Authentifizierungsanbieter für die folgenden Arten von Anmeldeinformationen konfigurieren:

• Geheimer Clientschlüssel
• Clientzertifikat
• Benutzerseitig zugewiesene verwaltete Identität
• Systemseitig zugewiesene verwaltete Identität

Authentifizierungspaket installieren

Installieren Sie das MSAL-Authentifizierungspaket von PyPI:

pip install microsoft-agents-authentication-msal

Einzelmandant vs. Mehrfachmandant

Die Authentifizierung mit geheimem Clientschlüssel und Clientzertifikat unterstützt sowohl Einzelmandanten- als auch mehrinstanzfähige Mandantkonfigurationen.

Benutzerseitig zugewiesene verwaltete Identitäten und systemseitig zugewiesene verwaltete Identitäten unterstützen nur Einzelmandantenkonfigurationen.

Eine -Verbindung konfigurieren

Die MSAL-Authentifizierungsbibliothek ermöglicht es Ihnen, mehrere Clients mit der Agents Framework-Hosting-Engine zu erstellen und zu verwenden. Jede Verbindungskonfiguration erstellt einen benannten Authentifizierungs-Client, um die Kommunikation mit externen Diensten oder anderen Agenten zu ermöglichen.

Konfiguration über Umgebungsvariablen bereitzustellen, die die doppelte Unterstrich-(__)-Namenskonvention für verschachtelte Einstellungen verwenden. Die MsalConnectionManager-Klasse liest diese Variablen aus, um AgentAuthConfiguration-Instanzen für jede benannte Verbindung zu erstellen.

Umgebungsvariablen für jeden Authentifizierungstyp

Der Agent erhält zur Laufzeit die MSAL-Konfiguration aus Umgebungsvariablen mithilfe der Hilfsfunktion load_configuration_from_env().

Die folgenden Abschnitte beschreiben die erforderlichen Konfigurationseinstellungen für jeden der unterstützten Authentifizierungstypen und enthalten Beispiele für Umgebungsvariablen für jeden Typ.

Einzelmandant mit geheimem Clientschlüssel

Mit diesen Einstellungen können Sie eine Einzelmandant-Verbindung konfigurieren, die mit einem geheimen Clientschlüssel authentifiziert wird.

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}

Die Einzelmandant-Konfiguration mit geheimem Clientschlüssel wird für die lokale Entwicklung empfohlen.

Mehrfachmandant mit geheimem Clientschlüssel

Für Mehrinstanzen-Szenarien, die ein Client Secret verwenden, setzen Sie den Authority Endpoint auf den botframework.com-Mandant:

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

Benutzerseitig zugewiesene verwaltete Identität

Verwenden Sie diese Einstellungen, um die Token-Akquisition mit einer benutzerzugewiesenen verwalteten Identität zu konfigurieren.

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

Verwaltete Identität ist die empfohlene Konfiguration für Produktionsszenarien. Weitere Informationen finden Sie unter What is managed identities for Azure resources? (Worum handelt es sich bei verwalteten Identitäten für Azure-Ressourcen?).

Systemseitig zugewiesene verwaltete Identität

Wenn Sie den Authentifizierungstyp SystemManagedIdentity verwenden, wird die Client-ID ignoriert und die systemverwaltete Identität des Dienstes verwendet.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity

Einzelmandant mit Clientzertifikat

Mit diesen Einstellungen können Sie eine Einzelmandant-Verbindung konfigurieren, die mit einem Client-Zertifikat authentifiziert wird.

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}

Mehrinstanzenfähigkeit mit Clientzertifikat

Für mehrinstanzfähige Szenarien, die ein Client-Zertifikat verwenden, setzen Sie den Authority Endpoint auf den Mandanten 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

Verbindungsmanager einrichten

Die Klasse MsalConnectionManager kann mehrere Authentifizierungsverbindungen für Ihren Agenten verwalten. Sie liest die Verbindungskonfigurationen aus und erstellt MsalAuth-Instanzen für jede benannte Verbindung.

Hier ist ein Beispiel, wie man den Verbindungsmanager einrichtet und seinen Agenten startet:

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()
)

Siehe das Python-Quickstart-Beispiel für ein vollständiges Beispiel zur Verwendung von MsalConnectionManager in einem Python-Agenten.

Benutzerdefinierter Authentifizierungsanbieter

Nutzer, die einen angepassten Authentifizierungsanbieter benötigen, können die AccessTokenProviderBase Basisklasse implementieren:

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

Protokollierungsunterstützung für die Authentifizierung

Das MSAL Authentifizierungssystem verwendet das Standards Python logging Modul unter dem Protokollnamen microsoft_agents.authentication.msal. Um detaillierte Protokollierung von Authentifizierungsabläufen zur Fehlerbehebung bei der Token-Beschaffung zu ermöglichen, konfigurieren Sie den Logger in Ihrer Anwendung:

import logging

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