Configurer l’authentification dans un agent .NET

Le fournisseur d’authentification MSAL (Microsoft Authentication Library) du Kit de développement logiciel (SDK) des assistants .NET est un utilitaire qui vous permet 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.

Cet utilitaire prend en charge plusieurs profils distincts qui peuvent être utilisés pour créer des jetons d’accès. Chaque jeton d’accès peut être créé à l’aide de l’un des types d’authentification suivants :

• Locataire unique avec ClientSecret et Multilocataire avec ClientSecret
• Certificat client à l’aide de l’empreinte
• Certificat client utilisant le nom de l’objet (y compris SN+I)
• 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

Configurer une connexion

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

Il existe plusieurs paramètres possibles que vous pouvez utiliser lorsque vous créez une instance du fournisseur d’authentification MSAL.

Ces paramètres sont les suivants :

Locataire unique avec ClientSecret

Voici un exemple de paramètres d'application pour Locataire uniqueClientSecret pour Azure Bot Service :

  "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

Voici un exemple de paramètres d'application pour Partagé au sein d'une architecture mutualiséeClientSecret pour Azure Bot Service :

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

UserManagedIdentity

Lorsque vous utilisez les types d’identité managée, votre hôte ou client doit s’exécuter avec un service Azure et doit avoir configuré ce service avec une identité managée affectée par le système ou une identité managée affectée par l’utilisateur.

Voici un exemple d’appsettings pour UserManagedIdentity :

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

SystemManagedIdentity

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

Lorsque vous utilisez les types d’identité managée, votre hôte ou client doit s’exécuter avec un service Azure et doit avoir configuré ce service avec une identité managée affectée par le système ou une identité managée affectée par l’utilisateur.

Voici un exemple d’appsettings pour le type d’authentification SystemManagedIdentity :

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

FederatedCredentials

Voici un exemple d’appsettings pour FederatedCredentials :

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

WorkloadIdentity

Voici un exemple pour Locataire uniqueWorkloadIdentity :

  "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

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

CertificateSubjectName

Voici un exemple d’appsettings pour CertificateSubjectName SN+I et Partagé au sein d'une architecture mutualisée

  "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 d’appsettings pour CertificateSubjectName 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

Voici un exemple d’appsettings pour CertificateSubjectName à 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. Cette opération est ajoutée par défaut lors de l’utilisation de AddAgent.

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

Toutefois, si elle n’est pas utilisée AddAgent, l’instance IConnections doit être inscrite.

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

Options de configuration MSAL supplémentaires

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 :

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 ».

La configuration MSAL est une configuration facultative, si elle n’est pas définie ou fournie, la configuration par défaut de ces valeurs est utilisée.

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 informations 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, vous devez ajouter une entrée pour Microsoft.Agents.Authentication.Msal à vos paramètres d’application appsettings pour configurer un ILogger afin de signaler les opérations de jeton pour vos connexions, si vous avez ajouté l’option MSALEnabledLogPII, cela inclut également des informations d’identification personnelles pour 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.