Configurer l’authentification dans votre assistant

Le package MSAL (Microsoft Authentication Library) du SDK des assistants .NET vous fournit des outils qui vous permettent de créer des jetons d’accès pour les clients d’assistant, et les services externes à partir d’un assistant auto-hébergé du Microsoft 365 Agents SDK.

Le package Microsoft.Agents.Athentication.Msal fournit la classe MsalAuth, qui est le fournisseur d’authentification principal. Vous pouvez la configurer pour les types de justificatifs suivants :

• Locataire unique avec clé secrète client et multilocataire avec clé secrète client
• Certificat client à l’aide de l’empreinte
• Certificat client utilisant le nom de l’objet (notamment SN+I)
• Identité managée affectée par l’utilisateur
• Identité managée affectée par le système
• Informations d’identification fédérées
• Identité de charge de travail

Installer le package d’authentification

Installez le package d’authentification MSAL depuis NuGet :

dotnet add package Microsoft.Agents.Authentication.Msal

Locataire unique vs locataire multiple

L’authentification par clé secrète client prend en charge à la fois les configurations monolocataire et multilocataire.

Configurer une connexion

Le package d’authentification MSAL vous permet de créer et d’utiliser plusieurs clients distincts avec le moteur d’hébergement Agent Framework. Avec le package d’authentification MSAL, vous pouvez fournir plusieurs configurations de connexion dans le fichier de configuration de l’application. Chaque configuration de connexion peut être utilisée pour créer un client d’authentification nommé afin de prendre en charge les communications avec des services externes ou d’autres assistants.

Variables d’environnement pour chaque type d’authentification

L’assistant obtient la configuration MSAL à l’exécution à partir de variables d’environnement.

Les sections suivantes décrivent les paramètres de configuration requis et optionnels pour chacun des types d’authentification pris en charge pour l’authentification MSAL, ainsi que des exemples d’extraits de configuration pour chaque type.

Locataire unique avec clé secrète client

Utilisez ces paramètres pour configurer une connexion monolocataire qui s’authentifie avec une clé secrète client.

Voici un exemple d’appsettings pour un seul client 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"
          ],
      }
    }
  }

Mutualisé avec clé secrète du client

Utilisez ces paramètres pour configurer une connexion multilocataire qui s’authentifie avec une clé secrète client.

Voici un exemple de paramètres de configuration pour un environnement multilocataire avec une clé secrète client :

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

Identité managée affectée par l’utilisateur

Utilisez ces paramètres pour configurer l’acquisition de jetons avec une identité managée attribuée par l’utilisateur.

Voici un exemple de paramètres d’application pour l’identité managée affectée par l’utilisateur :

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

Identité managée affectée par le système

Lorsque vous utilisez SystemManagedIdentity, l’assistant ignore tout identifiant client fourni et utilise l’identité gérée par le système.

Voici un exemple de paramètres d’application pour le type d’authentification de l’identité managée affectée par le système :

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

Informations d’identification fédérées

Utilisez ces paramètres pour configurer une connexion qui échange des identifiants fédérés contre des jetons d’accès.

Voici un exemple d’appsettings pour 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"
        ]
      }
    }
  }

Identité de charge de travail

Utilisez ces paramètres pour configurer l’authentification par identité de charge de travail à l’aide d’un fichier de jeton fédéré.

Voici un exemple d’appsettings pour un seul client 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"
        ]
      }
    }
  }

Options d’assertion de client d’identité de charge de travail ou d’informations d’identification fédérées facultatives

Utilisez ces paramètres optionnels pour personnaliser le contenu des assertions client pour les identifiants fédérés ou les flux d’identité de charge de travail.

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

Certificat utilisant le nom de l’objet (y compris SN+I)

Utilisez ces paramètres pour configurer l’authentification basée sur le certificat par nom du sujet, y compris les scénarios SN+I.

Voici un exemple de fichier appsettings pour un certificat utilisant le nom du sujet pour Subject Name and Issuer (SNI) et le mode multilocataire :

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

Voici un exemple de fichier appsettings pour le nom de sujet du certificat avec SN+I et locataire unique :

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

Certificat client à l’aide de l’empreinte

Utilisez ces paramètres pour configurer l’authentification par certificat à l’aide de l’empreinte de certificat.

Voici un exemple d’appsettings pour certificat à l’aide de l’empreinte du certificat :

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

Fournisseur de configuration par défaut pour MSAL

Pour faciliter la configuration, nous fournissons une extension de fournisseur de services pour ajouter les paramètres de configuration par défaut pour MSAL à votre assistant.

Voici un exemple de fournisseur de configuration MSAL par défaut pour un hôte principal ASP.NET dans une classe Program.cs :

Ceci est géré par l’instance inscrite IConnections. L’instance IConnections est ajoutée par défaut lorsque vous utilisez AddAgent.

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

Cependant, si vous n’utilisez pas AddAgent, vous devez explicitement enregistrer l’instance IConnections.

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

Plus d’options de configuration MSAL

Il existe plusieurs options de configuration partagée qui contrôlent les paramètres généraux pour l’acquisition de jetons à partir de Microsoft Entra Identity.

Ces paramètres sont les suivants :

Utilisez les paramètres partagés suivants pour contrôler le délai d’expiration des requêtes MSAL, le comportement de réessai et le niveau de détail des journaux.

Ces paramètres sont partagés avec tous les clients qui créent à l’aide du fournisseur d’authentification MSAL. Ces paramètres sont destinés à être lus à partir d’un lecteur IConfiguration, dans une section de configuration appelée « MSALConfiguration ».

Voici un exemple d’entrée dans un fichier appsettings.json :

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

Dans ce cas, ce bloc de paramètres indique à tous les clients MSAL créés avec le fournisseur MSAL d’activer la journalisation des données personnelles, de définir le délai d’expiration sur 40 secondes et de réduire le nombre de nouvelles tentatives à 1.

Cette extension recherche une section de configuration nommée « MSALConfiguration » dans votre objet IConfiguration et crée un objet MSAL Configuration à partir de celui-ci.

Si la section MSALConfig est introuvable , elle crée l’objet de configuration MSAL à l’aide de valeurs par défaut.

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

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

Prise en charge de la journalisation pour l’authentification

Le système d’authentification MSAL autorise la journalisation indépendante des flux d’authentification pour l’intégration de télémétrie si vous devez résoudre les problèmes d’acquisition de jetons.

Pour activer la journalisation, ajoutez une entrée pour Microsoft.Agents.Authentication.Msal dans les paramètres de votre application afin de mettre en place un ILogger pour signaler les opérations sur les jetons de vos connexions. Si vous ajoutez cette option MSALEnabledLogPII, cela inclut également les données personnelles de votre connexion.

Voici un exemple de bloc de journalisation dans ce cas :

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

Dans ce cas, la journalisation est activée pour plusieurs modules : Microsoft.Agents.Authentication.Msal, où le niveau de trace est « Trace » pour MSAL.

Le SDK JavaScript requiert un AuthenticationProvider pour obtenir des jetons web JSON (JWT) afin d’envoyer des activités au canal cible. Pour plus d’informations, consultez Jetons d’accès dans la plateforme d’identités Microsoft.

Le package @microsoft/agents-hosting fournit un fournisseur d’authentification par défaut basé sur Microsoft Authentication Library (MSAL). Vous pouvez la configurer pour les types d’authentifications suivants :

• Locataire unique avec clé secrète client
• Mutualisé avec clé secrète du client
• Identité managée par l’utilisateur
• Identité managée par le système
• Informations d’identification fédérées
• Identité de charge de travail
• Certificat

Installer le package d’authentification

Installez le package d’authentification MSAL depuis npm :

npm install @microsoft/agents-hosting

Locataire unique vs locataire multiple

L’authentification du secret client et du certificat client prend en charge à la fois les configurations monolocataire et multilocataire.

Les identités managées attribuées par l’utilisateur, les identités managées système, les informations d’identification fédérées et l’identité de charge de travail prennent uniquement en charge les configurations à locataire unique.

Configurer une connexion

La bibliothèque d’authentification MSAL vous permet de créer et d’utiliser plusieurs clients distincts avec le moteur d’hébergement Agent Framework. En utilisant la bibliothèque d’authentification MSAL, vous pouvez définir plusieurs configurations de connexion dans le fichier de configuration de l’application. Chaque configuration de connexion peut créer un client d’authentification nommé afin de prendre en charge les communications avec des services externes ou d’autres assistants.

Les sections suivantes décrivent les paramètres de configuration obligatoires et facultatifs pour chacun des types d’authentification pris en charge par le fournisseur d’authentification MSAL. Elles incluent également des exemples d’extraits de configuration pour chaque type.

Variables d’environnement pour chaque type d’authentification

L’assistant obtient la configuration MSAL à l’exécution à partir des variables d’environnement en utilisant la fonction d’assistance loadAuthConfigFromEnv(): AuthConfiguration. Le CloudAdapter s’initialise avec la AuthConfiguration.

Les paramètres de connexion utilisent le format CONNECTIONS__<CONNECTION_NAME>__SETTINGS__<PROPERTY>.

Lorsque AUTHTYPE est présent, le Kit de développement logiciel (SDK) utilise cette valeur pour sélectionner le flux d’acquisition du jeton. Lorsque AUTHTYPE est omis, le Kit de développement logiciel (SDK) revient au comportement hérité et déduit le flux d’authentification à partir des informations d’identification configurées.

Locataire unique avec clé secrète client

Utilisez ces paramètres pour configurer une connexion monolocataire qui s’authentifie avec une clé secrète client.

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

La configuration recommandée pour le développement local est une application à locataire unique avec un secret client.

Mutualisé avec clé secrète du client

Pour les scénarios multilocataires utilisant un secret client, définissez le point de terminaison d’autorité sur le locataire 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

Utilisez ces paramètres pour configurer l’acquisition de jetons avec une identité managée affectée par l’utilisateur.

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

L’identité managée est la configuration recommandée pour les scénarios de production. Pour en savoir plus, consultez Identités managées pour ressources Azure.

SystemManagedIdentity

Lorsque vous utilisez le type d’authentification SystemManagedIdentity, l’ID client est ignoré et l’identité managée du système pour le service est utilisée.

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

FederatedCredentials

Utilisez ces paramètres pour configurer une application à locataire unique qui s’authentifie via Federated Credentials.

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

Pour plus d’informations, voir Authentification utilisant les informations d’identification d’identité fédérés.

WorkloadIdentity

Utilisez ces paramètres pour configurer l’acquisition de jetons via l’identité de charge de travail 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

Locataire unique avec certificat client

Utilisez ces paramètres pour configurer une connexion monolocataire qui s’authentifie avec un certificat client.

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

Multilocataire avec certificat client

Pour les scénarios multilocataires utilisant un certificat client, définissez le point de terminaison d’autorité sur le locataire 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

Rétrocompatibilité avec Azure Bot Framework SDK

Pour charger la configuration en utilisant le même format que l’Azure Bot Framework SDK, utilisez loadPrevAuthConfigFromEnv(): AuthConfiguration.

Utilisez ces noms de paramètres hérités lors de la migration des configurations du Bot Framework SDK.

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

Fournisseur d’authentification personnalisé

Les utilisateurs qui ont besoin d’un fournisseur d’authentification personnalisé peuvent implémenter l’interface :

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

Par exemple, implémenter le AuthProvider en utilisant le @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
  }

Pour instancier le CloudAdapter par l’utilisation de 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())

Le package MSAL (Microsoft Authentication Library) d’Agents SDK Python vous fournit des outils qui vous permettent de créer des jetons d’accès pour les clients d’assistant, et les services externes à partir d’un assistant auto-hébergé du Microsoft 365 Agents SDK.

Le package microsoft-agents-authentication-msal fournit la classe MsalAuth, qui est le fournisseur d’authentification principal. Vous pouvez la configurer pour les types de justificatifs suivants :

• Le secret du client
• Certificat client
• Identité managée affectée par l’utilisateur
• Identité managée affectée par le système

Installer le package d’authentification

Installez le package d’authentification MSAL à partir de PyPI :

pip install microsoft-agents-authentication-msal

Locataire unique vs locataire multiple

L’authentification du secret client et du certificat client prend en charge à la fois les configurations monolocataire et multilocataire.

Les identités managées attribuées par l’utilisateur et les identités managées affectées par le système prennent uniquement en charge les configurations à locataire unique.

Configurer une connexion

La bibliothèque MSAL d’authentification vous permet de créer et d’utiliser plusieurs clients distincts avec le moteur d’hébergement Agent Framework. Chaque configuration de connexion crée un client d’authentification nommé afin de prendre en charge les communications avec des services externes ou d’autres assistants.

Fournir une configuration via des variables d’environnement utilisant la convention d’affectation de noms à double trait de soulignement (__) pour les paramètres imbriqués. La classe MsalConnectionManager lit ces variables pour créer des instances de AgentAuthConfiguration pour chaque connexion nommée.

Variables d’environnement pour chaque type d’authentification

L’assistant obtient la configuration MSAL à l’exécution à partir des variables d’environnement en utilisant la fonction d’assistance load_configuration_from_env().

Les sections suivantes décrivent les paramètres de configuration requis pour chacun des types d’authentification pris en charge, ainsi que des exemples de variables d’environnement pour chaque type.

Locataire unique avec clé secrète client

Utilisez ces paramètres pour configurer une connexion monolocataire qui s’authentifie avec une clé secrète client.

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}

La configuration recommandée pour le développement local est une application à locataire unique avec un secret client.

Mutualisé avec clé secrète du client

Pour les scénarios multilocataires utilisant un secret client, définissez le point de terminaison d’autorité sur le locataire 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

Identité managée affectée par l’utilisateur

Utilisez ces paramètres pour configurer l’acquisition de jetons avec une identité managée attribuée par l’utilisateur.

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

L’identité managée est la configuration recommandée pour les scénarios de production. Pour en savoir plus, consultez Identités managées pour ressources Azure.

Identité managée affectée par le système

Lorsque vous utilisez le type d’authentification SystemManagedIdentity, l’ID client est ignoré et l’identité managée du système pour le service est utilisée.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity

Locataire unique avec certificat client

Utilisez ces paramètres pour configurer une connexion monolocataire qui s’authentifie avec un certificat client.

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}

Multilocataire avec certificat client

Pour les scénarios multilocataires utilisant un certificat client, définissez le point de terminaison d’autorité sur le locataire 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

Configurer le gestionnaire de connexions

La classe MsalConnectionManager peut gérer plusieurs connexions d’authentification pour votre assistant. Il lit les configurations de connexion et crée des instances MsalAuth pour chaque connexion nommée.

Voici un exemple montrant comment configurer le gestionnaire de connexion et démarrer votre assistant :

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

Voir l’exemple de démarrage rapide Python pour un exemple complet d’utilisation de l’assistant MsalConnectionManager dans un agent Python.

Fournisseur d’authentification personnalisé

Les utilisateurs qui ont besoin d’un fournisseur d’authentification personnalisé peuvent implémenter la classe de 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

Prise en charge de la journalisation pour l’authentification

Le système d’authentification MSAL utilise le module Python logging standard sous le nom microsoft_agents.authentication.msal de l’enregistreur. Pour permettre une journalisation détaillée des flux d’authentification pour dépanner l’acquisition de jetons, configurez le journal dans votre application :

import logging

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