Utiliser l’authentification OAuth avec Microsoft Dataverse

OAuth 2.0 est le protocole standard d’autorisation. Une fois que les utilisateurs d’application fournissent les informations d’identification pour l’authentification, OAuth détermine s’ils sont autorisés à accéder aux ressources.

Les applications clientes doivent prendre en charge l’utilisation d’OAuth pour accéder aux données à l’aide de l’API web. OAuth active l’authentification à deux facteurs (2FA) ou l’authentification basée sur un certificat pour des scénarios d’application serveur à serveur.

OAuth exige un fournisseur d’entités pour l’authentification. Pour Dataverse, le fournisseur d’identité est Microsoft Entra ID. Pour vous authentifier à l’aide d’un compte professionnel ou scolaire Microsoft, utilisez le Microsoft Authentication Library (MSAL).

Note

Cet article présente les concepts courants liés à la connexion à Dataverse à l’aide d’OAuth avec des bibliothèques d’authentification. Ce contenu se concentre sur la façon dont un développeur peut se connecter à Dataverse, mais ne couvre pas les fonctionnements internes d’OAuth ou les bibliothèques. Pour obtenir des informations complètes relatives à l’authentification, consultez la documentation Microsoft Entra ID. L’article Qu’est-ce que l’authentification ? est un bon point de départ.

Les exemples que nous fournissons sont préconfigurés avec les valeurs d’inscription appropriées afin que vous puissiez les exécuter sans générer votre propre inscription d’application. Lorsque vous publiez vos propres applications, vous devez utiliser vos propres valeurs d’enregistrement.

Inscription d’application

Lorsque vous vous connectez à l’aide d’OAuth, vous devez d’abord enregistrer une application dans votre tenant Microsoft Entra ID. La manière dont vous enregistrez votre application dépend du type d’application que vous souhaitez créer.

Dans tous les cas, commencez par les étapes de base pour inscrire une application décrite dans l’article : Démarrage rapide : Inscrire une application auprès du Plateforme d'identités Microsoft. Pour obtenir des instructions spécifiques à Dataverse, consultez Procédure pas à pas : Inscrire une application avec l’ID Microsoft Entra.

Les décisions que vous devez prendre dans cette étape dépendent principalement du choix du type d’application (voir la section suivante).

Types d’enregistrement d’application

Lorsque vous inscrivez une application auprès de Microsoft Entra ID, choisissez le type d’application. Vous pouvez inscrire deux types d’applications :

Type de lettrage Description
Application Web/API Client Web
Type d’application cliente qui exécute tout le code sur un serveur Web.

Client basé sur un assistant utilisateur
Type d’application cliente qui télécharge le code depuis un serveur Web et s’exécute dans un agent utilisateur (par exemple, un navigateur Web), comme une application sur une seule page.
Native Type d’application cliente installé de manière native sur un appareil.

Lorsque vous sélectionnez application web/API, entrez l’URL de connexion. Microsoft Entra ID envoie la réponse d’authentification à cette URL, y compris un jeton si l’authentification réussit. Pendant que vous développez une application, définissez cette URL https://localhost/appname:[port] pour que vous puissiez développer et déboguer votre application localement. Lorsque vous publiez votre application, remplacez cette valeur par l’URL publiée de l’application.

Lorsque vous sélectionnez Native, entrez un URI de redirection. Cette URL est un identificateur unique vers lequel Microsoft Entra ID redirige l’agent utilisateur dans une requête OAuth 2.0. Cette URL est généralement une valeur au format suivant : app://<guid>.

Accorder l'accès à Dataverse

Si votre application est un client qui permet à l’utilisateur authentifié d’effectuer des opérations, configurez l’application pour qu’elle dispose de l’Dynamics 365 Access en tant qu’autorisation déléguée pour les utilisateurs de l’organisation.

Pour obtenir des étapes spécifiques pour définir des autorisations, consultez Enregistrer une application avec Microsoft Entra ID.

Si votre application utilise l’authentification Server-to-Server (S2S), vous n’avez pas besoin d’effectuer cette étape. Cette configuration nécessite un utilisateur système spécifique et les opérations effectuées par ce compte d’utilisateur plutôt que tout utilisateur qui doit être authentifié.

Utiliser des secrets client et des certificats

Pour les scénarios serveur à serveur, il n’existe aucun compte d’utilisateur interactif à authentifier. Dans ces cas, vous devez fournir quelques moyens pour confirmer que l’application est fiable. Confirmez l’approbation à l’aide de secrets client ou de certificats.

Pour les applications que vous inscrivez à l’aide du type d’application /API web , vous pouvez configurer des secrets. Définissez ces secrets dans la zone Clés sous Accès à l’API dans les paramètres de l’inscription de l’application.

Pour un type d’application ou l’autre, vous pouvez télécharger un certificat.

Pour plus d’informations : Se connecter en tant qu’application

Utiliser les bibliothèques d’authentification pour se connecter

Utilisez l’une des bibliothèques clientes d’authentification Microsoft Entra ID prises en charge par Microsoft pour vous connecter à Dataverse, comme Microsoft Authentication Library (MSAL). Cette bibliothèque est disponible pour différentes plateformes, comme décrit dans les liens fournis.

Note

Microsoft Authentication Library (ADAL) ne reçoit pas activement les mises à jour et n'est pris en charge que jusqu'en juin 2022. Utilisez MSAL comme bibliothèque d’authentification pour les projets.

Pour obtenir un exemple de code qui illustre l’utilisation de bibliothèques MSAL pour l’authentification avec Dataverse, consultez Démarrage rapide : Exemple d’API web (C#)

bibliothèques clientes .NET

Dataverse prend en charge l’authentification d’application avec le point de terminaison de l’API web à l’aide du protocole OAuth 2.0. Pour vos applications .NET personnalisées, utilisez MSAL pour l’authentification d’application à l’aide du point de terminaison de l’API web.

Dataverse SDK pour .NET inclut des classes clientes CrmServiceClient et ServiceClient pour gérer l’authentification. La classe CrmServiceClient utilise actuellement ADAL pour l’authentification tandis que ServiceClient utilise MSAL. L’écriture de votre code d’application pour utiliser ces clients élimine le besoin de gérer directement l’authentification. Les deux clients fonctionnent avec les points de terminaison SDK et API Web.

Utiliser le jeton AccessToken avec vos requêtes

L’intérêt d’utiliser les bibliothèques d’authentification est d’obtenir un jeton d’accès que vous pouvez inclure dans vos requêtes. L’obtention du jeton ne nécessite que quelques lignes de code, et quelques lignes supplémentaires pour configurer un client HttpClient pour exécuter une requête.

Important

Comme illustré dans l’exemple de code de cet article, utilisez une étendue « < environment-url>/user_impersonation » pour un client public. Dans le cas d’un client confidentiel, utilisez l’étendue « <environment-url>/.default ».

Exemple simple

L’exemple suivant est la quantité minimale de code nécessaire pour exécuter une seule requête d’API web, mais il n’est pas l’approche recommandée. L’exemple de code utilise la bibliothèque MSAL et est extrait de l’exemple de démarrage rapide : exemple d’API web (C#).

string resource = "https://contoso.api.crm.dynamics.com";
var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
var redirectUri = "http://localhost"; // Loopback for the interactive login.

// MSAL authentication
var authBuilder = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
    .WithRedirectUri(redirectUri)
    .Build();
var scope = resource + "/user_impersonation";
string[] scopes = { scope };

AuthenticationResult token =
    authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync().Result;

// Set up the HTTP client
var client = new HttpClient
{
    BaseAddress = new Uri(resource + "/api/data/v9.2/"),
    Timeout = new TimeSpan(0, 2, 0)  // Standard two minute timeout.
};

HttpRequestHeaders headers = client.DefaultRequestHeaders;
headers.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);
headers.Add("OData-MaxVersion", "4.0");
headers.Add("OData-Version", "4.0");
headers.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

// Web API call
var response = client.GetAsync("WhoAmI").Result;

Cette approche simple ne représente pas un bon schéma à suivre, car le token expire dans environ une heure. Les bibliothèques MSAL mettent en cache le jeton pour vous et le rafraîchissent chaque fois que la méthode AcquireTokenInteractive est appelée. Cependant dans cet exemple simple, le jeton n’est acquis qu’une seule fois.

Exemple illustrant un gestionnaire de message DelegatingHandler

Implémentez une classe dérivée de DelegatingHandler, puis passez-la au constructeur de HttpClient. À l’aide de ce gestionnaire, vous pouvez redéfinir la méthode HttpClient.SendAsync afin que le jeton d’accès soit actualisé par les appels à la méthode AcquireToken* à chaque requête envoyée par le client HTTP.

Le code suivant est un exemple de classe personnalisée dérivée de DelegatingHandler. Ce code est extrait de l’exemple de démarrage rapide amélioré qui utilise la bibliothèque d’authentification MSAL.

class OAuthMessageHandler : DelegatingHandler
{
    private AuthenticationHeaderValue authHeader;
    public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl, string username, string password,
            HttpMessageHandler innerHandler)
        : base(innerHandler)
    {
        string apiVersion = "9.2";
        string webApiUrl = $"{serviceUrl}/api/data/v{apiVersion}/";
        var authBuilder = PublicClientApplicationBuilder.Create(clientId)
                        .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
                        .WithRedirectUri(redirectUrl)
                        .Build();
        var scope = serviceUrl + "/user_impersonation";
        string[] scopes = { scope };
        // First try to get an authentication token from the cache using a hint.
        AuthenticationResult authBuilderResult=null;
        try
        {
            authBuilderResult = authBuilder.AcquireTokenSilent(scopes, username)
               .ExecuteAsync().Result;
        }
        catch (Exception ex)
        {
            System.Diagnostics.Debug.WriteLine(
                $"Error acquiring auth token from cache:{System.Environment.NewLine}{ex}");
            // Token cache request failed, so request a new token.
            try
            {
                if (username != string.Empty && password != string.Empty)
                {
                    // Request a token based on username/password credentials.
                    authBuilderResult = authBuilder.AcquireTokenByUsernamePassword(scopes, username, password)
                                .ExecuteAsync().Result;
                }
                else
                {
                    // Prompt the user for credentials and get the token.
                    authBuilderResult = authBuilder.AcquireTokenInteractive(scopes)
                                .ExecuteAsync().Result;
                }
            }
            catch (Exception msalex)
            {
                System.Diagnostics.Debug.WriteLine(
                    $"Error acquiring auth token with user credentials:{System.Environment.NewLine}{msalex}");
                throw;
            }
        }
        //Note that an Microsoft Entra ID access token has finite lifetime, default expiration is 60 minutes.
        authHeader = new AuthenticationHeaderValue("Bearer", authBuilderResult.AccessToken);
    }

    protected override Task<HttpResponseMessage> SendAsync(
              HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
    {
        request.Headers.Authorization = authHeader;
        return base.SendAsync(request, cancellationToken);
    }
}

Lorsque vous utilisez cette OAuthMessageHandler classe, la méthode simple Main ressemble à ceci.

class Program
{
    static void Main(string[] args)
    {
        try
        {
            //Get configuration data from App.config connectionStrings
            string connectionString = ConfigurationManager.ConnectionStrings["Connect"].ConnectionString;

            using (HttpClient client = SampleHelpers.GetHttpClient(connectionString, SampleHelpers.clientId,
                SampleHelpers.redirectUrl))
            {
                // Use the WhoAmI function
                var response = client.GetAsync("WhoAmI").Result;

                if (response.IsSuccessStatusCode)
                {
                    //Get the response content and parse it.
                    JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
                    Guid userId = (Guid)body["UserId"];
                    Console.WriteLine("Your UserId is {0}", userId);
                }
                else
                {
                    Console.WriteLine("The request failed with a status of '{0}'",
                                response.ReasonPhrase);
                }
                Console.WriteLine("Press any key to exit.");
                Console.ReadLine();
            }
        }
        catch (Exception ex)
        {
            SampleHelpers.DisplayException(ex);
            Console.WriteLine("Press any key to exit.");
            Console.ReadLine();
        }
    }
}

Lisez les informations importantes suivantes sur l'utilisation d'une chaîne de connexion ou d'une authentification par nom d'utilisateur/mot de passe dans le code de l'application.

Important

Microsoft vous recommande d’utiliser le flux d’authentification le plus sécurisé disponible. Le flux d’authentification décrit dans cet article nécessite un très haut degré de confiance dans l’application et comporte des risques qui ne sont pas présents dans d’autres flux. Vous ne devez utiliser ce flux que si d’autres flux plus sécurisés, tels que les identités managées, ne sont pas viables.

Déplacez les valeurs de la chaîne de configuration dans une chaîne de connexion du fichier App.config, et configurez le client HTTP dans la méthode GetHttpClient.

public static HttpClient GetHttpClient(string connectionString, string clientId, string redirectUrl, string version = "v9.2")
{
    string url = GetParameterValueFromConnectionString(connectionString, "Url");
    string username = GetParameterValueFromConnectionString(connectionString, "Username");
    string password = GetParameterValueFromConnectionString(connectionString, "Password");
    try
    {
        HttpMessageHandler messageHandler = new OAuthMessageHandler(url, clientId, redirectUrl, username, password,
                        new HttpClientHandler());

        HttpClient httpClient = new HttpClient(messageHandler)
        {
            BaseAddress = new Uri(string.Format("{0}/api/data/{1}/", url, version)),

            Timeout = new TimeSpan(0, 2, 0)  //2 minutes
        };

        return httpClient;
    }
    catch (Exception)
    {
        throw;
    }
}

Voir l'exemple Démarrage rapide amélioré pour le code complet.

Même si cet exemple utilise HttpClient.GetAsync plutôt que la méthode surchargée SendAsync, la même logique s’applique à n'importe laquelle des méthodes HttpClient qui envoient une requête.

Se connecter en tant qu’application

Certaines applications que vous créez ne sont pas destinées à s’exécuter de manière interactive par un utilisateur. Par exemple, vous souhaiterez peut-être créer une application cliente web qui peut effectuer des opérations sur des données Dataverse ou une application console qui effectue une tâche planifiée d’un certain type.

Bien que vous puissiez réaliser ces scénarios en utilisant des informations d’identification pour un utilisateur ordinaire, ce compte d’utilisateur a besoin d’une licence payante. N’utilisez pas cette approche.

Dans ces cas, créez un utilisateur d’application spécial lié à une application Microsoft Entra ID inscrite. Ensuite, utilisez un secret de clé configuré pour l’application ou chargez un certificat X.509 . Un autre avantage de cette approche consiste à ne pas utiliser une licence payée.

Exigences pour se connecter en tant qu’application

Pour vous connecter en tant qu’application, vous avez besoin des éléments suivants :

  • Une application inscrite
  • Un utilisateur Dataverse lié à l'application enregistrée
  • Se connecter à l’aide du secret d’application ou d’une empreinte numérique de certificat

Inscrire votre application

Lors de l’inscription d’une application, suivez la plupart des mêmes étapes décrites dans La procédure pas à pas : Inscrire une application auprès de Microsoft Entra ID, avec les exceptions suivantes :

  • Vous n’avez pas besoin d’accorder l’autorisation Accéder à Dynamics 365 comme utilisateurs de l’organisation.

    Cette application est liée à un compte d’utilisateur spécifique.

  • Vous devez configurer un secret pour l’inscription de l’application ou charger un certificat de clé publique.

Vous pouvez créer ou afficher les informations d’identification dans votre enregistrement d’application sous Gérer>Certificats et secrets.

Pour ajouter un certificat (clé publique) :

  1. Dans l’onglet Certificats, sélectionnez Charger un certificat.
  2. Sélectionnez les fichiers à charger. Il doit s’agir d’un fichier de type .cer, .pem ou .crt.
  3. Rédigez une description.
  4. Sélectionnez Ajouter.

Pour ajouter une clé secrète client (mot de passe d’application) :

  1. Dans l’onglet Clés secrètes client, ajoutez une description pour votre clé secrète client.
  2. Sélectionnez une période d’expiration.
  3. Sélectionnez Ajouter.

Important

Une fois les modifications de configuration enregistrées, une valeur secrète s’affiche. Veillez à copier la valeur secrète à utiliser dans le code de votre application cliente, car vous ne pouvez pas accéder à cette valeur une fois que vous quittez la page.

Pour plus d’informations, voir Ajouter des informations d’identification

Un compte utilisateur Dataverse lié à l'application enregistrée

Tout d’abord, créez un rôle de sécurité personnalisé qui définit l’accès et les privilèges dont dispose ce compte au sein de l’organisation Dataverse. Pour plus d’informations, consultez Créer ou configurer un rôle de sécurité personnalisé.

Après avoir créé le rôle de sécurité personnalisé, créez le compte d’utilisateur qui l’utilise.

Créer manuellement un utilisateur de l’application Dataverse

La procédure de création d’un utilisateur d’application se trouve dans l’article Administrer Power Platform : Créer un utilisateur d’application.

Une fois que vous avez créé un utilisateur d’application, associez-le au rôle de sécurité personnalisé que vous avez créé.

Se connecter à l’aide du secret d’application

Si vous vous connectez à l’aide d’un secret client et que vous utilisez le Microsoft.Xrm.Tooling.Connector.CrmServiceClient, vous pouvez utiliser un code similaire à celui indiqué ici :

string SecretID = "00000000-0000-0000-0000-000000000000";
string AppID = "00001111-aaaa-2222-bbbb-3333cccc4444";
string InstanceUri = "https://yourorg.crm.dynamics.com";

string ConnectionStr = $@"AuthType=ClientSecret;
                        SkipDiscovery=true;url={InstanceUri};
                        Secret={SecretID};
                        ClientId={AppID};
                        RequireNewInstance=true";
using (ServiceClient svc = new ServiceClient(ConnectionStr))
{
    if (svc.IsReady)
    {
    //your code goes here
    }

}

Se connecter à l’aide d’une empreinte numérique de certificat

Si vous vous connectez à l’aide d’un certificat et en utilisant le Microsoft.Xrm.Tooling.Connector.CrmServiceClient, vous pouvez utiliser un code similaire, comme indiqué ici :

string CertThumbPrintId = "DC6C689022C905EA5F812B51F1574ED10F256FF6";
string AppID = "00001111-aaaa-2222-bbbb-3333cccc4444";
string InstanceUri = "https://yourorg.crm.dynamics.com";

string ConnectionStr = $@"AuthType=Certificate;
                        SkipDiscovery=true;url={InstanceUri};
                        thumbprint={CertThumbPrintId};
                        ClientId={AppID};
                        RequireNewInstance=true";
using (ServiceClient svc = new ServiceClient(ConnectionStr))
{
    if (svc.IsReady)
    {
    //your code goes here
    }

}

Voir aussi

Authentication avec Microsoft Dataverse services web
Authentification des applications .NET Framework
Overview du Microsoft Authentication Library

  • Last updated on