Utiliser l’authentification OAuth avec Microsoft Dataverse
OAuth 2.0 est le protocole standard d'autorisation. Une fois que les utilisateurs d’application fournissent des identifiants d’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 Azure Active Directory (AAD). Pour vous authentifier avec AAD à l'aide d'un compte d'entreprise ou d'établissement d'enseignement Microsoft, utilisez les bibliothèques d'authentification Azure Active Directory (ADAL) ou la bibliothèque d'authentification Microsoft (MSAL).
Notes
Cette rubrique présente les concepts courants relatifs à la connexion à Dataverse à l'aide d'OAuth avec les bibliothèques d'authentification. Ce contenu est axé sur la façon dont un développeur peut se connecter à Dataverse et non sur l'utilisation en interne d'OAuth ou des bibliothèques. Pour des informations complètes relatives à l'authentification, consultez la documentation Azure Active Directory. La rubrique Qu'est-ce que l'authentification ? est un bon début.
Les exemples que nous proposons sont pré-configurés avec des valeurs d'enregistrement appropriées de telle sorte que vous les exécutiez sans générer l'enregistrement de votre propre application. Lorsque vous publiez vos propres applications, vous devez utiliser vos propres valeurs d'enregistrement.
Enregistrement de l'application
Lorsque vous vous connectez avec OAuth, vous devez tout d'abord enregistrer une application dans votre client Azure AD. La manière dont vous devez enregistrer votre application dépend du type d'application que vous souhaitez créer.
Dans tous les cas, commencez par les étapes de base pour enregistrer une application tel que décrit dans la rubrique AAD : Démarrage rapide : Enregistrer une application avec le point de terminaison Azure Active Directory v1.0. Pour obtenir des instructions spécifiques sur Dataverse, consultez Procédure pas à pas : Enregistrer une application avec Azure Active Directory > Créer un enregistrement d'application.
Les décisions que vous devez prendre à cette étape dépendent notamment du choix du type d’application (voir ci-dessous).
Types d'enregistrement d'application
Lorsque vous enregistrez une application avec Azure AD, vous devez choisir le type d’application. Vous pouvez enregistrer deux types d'applications :
| Type d'application | Description |
|---|---|
| Application Web/API | Client Web Type d'application cliente qui exécute tout le code sur un serveur Web. Client basé sur un agent 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. |
| natif | Type d'application cliente installé de manière native sur un appareil. |
Lorsque vous sélectionnez Application Web/APII, vous devez fournir une URL de connexion qui correspond à l'URL à laquelle Azure AD envoie la réponse d'authentification, y compris un jeton si l'authentification a réussi. Lorsque vous développez une application, elle est généralement définie sur https://localhost/appname:[port] afin que vous puissiez développer et déboguer votre application localement. Lorsque vous publiez votre application, vous devez changer cette valeur avec l'URL publiée de l'application.
Lorsque vous sélectionnez Natif, vous devez fournir une URI de redirection. Il s'agit d'un identifiant unique vers lequel Azure AD redirige l'agent utilisateur dans une demande OAuth 2.0. Il s'agit généralement d'une valeur formatée comme suit : app://<guid>.
Accorder l'accès à Dataverse
Si votre application est un client qui autorise l'utilisateur authentifié à exécuter des opérations, vous devez configurer l'application pour avoir l'autorisation Accéder à Dynamics 365 en tant qu'utilisateurs de l'organisation.
Pour les étapes spécifiques de cette procédure, consultez Procédure pas à pas : Enregistrer une application avec Azure Active Directory > Appliquer les autorisations.
Si votre application utilise l'authentification S2S (serveur à serveur), cette étape peut être ignorée. Cette configuration exige un utilisateur système spécifique et les opérations seront effectuées par ce compte d'utilisateur plutôt que par tout utilisateur qui doit être authentifié.
Activer le flux implicite
Si vous configurez une application pour une application sur une seule page, vous devez modifier le manifeste pour définir la valeur oauth2AllowImplicitFlow sur true. Pour plus d'informations : Procédure pas à pas : enregistrement et configuration d'une application SPA avec adal.js
Utiliser les certificats et les clés secrètes client
Pour les scénarios serveur à serveur, il n'y a pas de compte d'utilisateur interactif à authentifier. Dans ces cas, vous devez fournir quelques moyens pour confirmer que l'application est fiable. Cela se fait via les certificats et les clés secrètes client.
Pour les applications enregistrées avec le type d'application Application Web/API, vous pouvez configurer les clés secrètes. Celles-ci sont définies à l'aide de la zone Clés sous Accès API dans Paramètres pour l'enregistrement 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 établir une connexion
Utilisez une des bibliothèques clientes d'authentification Azure Active Directory prises en charge par Microsoft pour vous connecter à Dataverse. Il existe deux bibliothèques de ce type disponibles auprès de Microsoft : Bibliothèque d'authentification Azure Active Directory (ADAL), et Bibliothèque d'authentification Microsoft (MSAL). Ces bibliothèques sont disponibles pour différentes plateformes, comme décrit dans les liens fournis.
Notes
Parmi les deux bibliothèques d'authentification mentionnées, ADAL ne reçoit plus de mises à jour et ne sera prise en charge que jusqu'en juin 2022. MSAL est la bibliothèque d'authentification recommandée à utiliser pour les nouveaux projets.
Actuellement, tous nos exemples utilisent les bibliothèques clientes .NET Client hormis pour Utiliser OAuth avec le partage des ressources cross-origin pour se connecter à une application sur une seule page qui utilise la bibliothèque JavaScript ADAL.js.Pour un exemple de code qui illustre l'utilisation des bibliothèques ADAL et MSAL pour l'authentification avec Dataverse voir Exemple de démarrage rapide.
Versions de la bibliothèque cliente ADAL .NET
Dataverse prend en charge l'authentification des applications avec le point de terminaison d'API Web à l'aide du protocole OAuth 2.0. Pour vos applications .NET personnalisées, utilisez ADAL v3.19 ou une version supérieure pour l'authentification des applications avec le point de terminaison d'API Web. Lorsque vous utilisez les API XrmTooling (telles que CrmServiceClient) disponible dans le package Microsoft.CrmSdk.XrmTooling.CoreAssembly NuGet, la version correcte de la bibliothèque ADAL sera importée automatiquement dans votre projet Visual Studio. Utilisez les API XrmTooling du package v9.1.0.13 NuGet (ou version supérieure). Consultez les notes de version du package pour l'historique des versions.
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. Cela ne nécessite que quelques lignes de code, et quelques lignes supplémentaires pour configurer un client HttpClient pour exécuter une requête.
Exemple simple
Ci-après figure la quantité minimale de code nécessaire pour exécuter une seule requête API Web, mais cette approche n'est pas recommandée. Notez que ce code utilise la bibliothèque ADAL et est tiré de l'exemple QuickStart mentionné ci-dessus.
string resource = "https://contoso.api.crm.dynamics.com";
var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
var redirectUri = new Uri("app://58145B91-0C36-4500-8554-080854F2AC97");
var authContext = new AuthenticationContext(
"https://login.microsoftonline.com/common", false);
var token = authContext.AcquireTokenAsync(
resource, clientId, redirectUri,
new PlatformParameters(
PromptBehavior.SelectAccount // Prompt the user for a logon account.
),
UserIdentifier.AnyUser
).Result;
var client = new HttpClient
{
BaseAddress = new Uri(resource + "/api/data/v9.2/"),
Timeout = new TimeSpan(0, 2, 0)
};
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"));
var response = client.GetAsync("WhoAmI").Result;
cette approche simple ne représente pas un bon schéma à suivre, car le token expire sous une heure environ. Les bibliothèques ADAL masquent le jeton pour vous et l'actualisent à chaque appel de la méthode AcquireTokenAsync. Cependant dans cet exemple simple, le jeton n'est acquis qu'une seule fois.
Exemple illustrant un gestionnaire de message DelegatingHandler
L'approche recommandée consiste à mettre en place une classe dérivée de DelegatingHandler et qui sera transmise au constructeur du HttpClient. Ce gestionnaire vous permet de remplacer la méthode HttpClient.SendAsync afin que le jeton d'accès soit actualisé par les appels de méthode AcquireToken* avec chaque requête envoyée par le client HTTP.
Vous trouverez, ci-après, un exemple d'une classe personnalisée dérivée du DelegatingHandler. Ce code est obtenu de l'exemple Démarrage rapide amélioré utilisant une 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}/";
//Build Microsoft.Identity.Client (MSAL) OAuth Token Request
var authBuilder = PublicClientApplicationBuilder.Create(clientId)
.WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
.WithRedirectUri(redirectUrl)
.Build();
var scope = serviceUrl + "//.default";
string[] scopes = { scope };
AuthenticationResult authBuilderResult;
if (username != string.Empty && password != string.Empty)
{
//Make silent Microsoft.Identity.Client (MSAL) OAuth Token Request
var securePassword = new SecureString();
foreach (char ch in password) securePassword.AppendChar(ch);
authBuilderResult = authBuilder.AcquireTokenByUsernamePassword(scopes, username, securePassword)
.ExecuteAsync().Result;
}
else
{
//Popup authentication dialog box to get token
authBuilderResult = authBuilder.AcquireTokenInteractive(scopes)
.ExecuteAsync().Result;
}
//Note that an Azure AD 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);
}
}
En utilisant cette classe OAuthMessageHandler, la méthode Main simple ressemblerait à 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();
}
}
}
Les valeurs de chaîne de configuration ont été déplacées dans une chaîne de connexion de fichier App.config et le client HTTP est configuré 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 le SendAsync de substitution, il s'applique pour les méthodes HttpClient pour envoyer une requête.
Découvrir l'autorité au moment de l'exécution
L'URL de l'autorité d'authentification et l'URL de la ressource peuvent être déterminées dynamiquement au moment de l'exécution à l'aide du code ADAL suivant. Il s'agit de la méthode recommandée à utiliser par rapport à l'URL de l'autorité (https://login.microsoftonline.com/common) bien connue affichée précédemment dans un extrait de code.
AuthenticationParameters ap = AuthenticationParameters.CreateFromResourceUrlAsync(
new Uri("https://mydomain.crm.dynamics.com/api/data/")).Result;
String authorityUrl = ap.Authority;
String resourceUrl = ap.Resource;
Pour l'API Web, une autre méthode pour obtenir l'URL de l'autorité consiste à envoyer un message quelconque au service Web ne spécifiant aucun jeton d'accès. On parle dans ce cas de non-remise temporaire. La réponse peut être analysée pour obtenir l'URL de l'autorité.
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "");
Se connecter en tant qu'application
Certaines applications que vous allez créer n'ont pas pour but d'être exécutées de manière interactive par un utilisateur. Par exemple, vous pouvez souhaiter créer une application cliente Web qui peut exécuter des opérations sur les données Dataverse ou une application de console qui exécute une tâche programmée de toute sorte.
Tandis que vous exécutez ces scénarios avec les informations d'identification pour un utilisateur ordinaire, ce compte d'utilisateur doit utiliser une licence payée. Cette approche n'est pas recommandée.
Dans ces cas, vous pouvez créer un utilisateur d'application spécifique lié à une application enregistrée Azure Active Directory et utiliser une clé secrète configurée pour l'application ou télécharger 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 se 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 avec la clé secrète d'application ou une empreinte de certificat
Enregistrer votre application
Lors de l'enregistrement d'une application, vous suivez de nombreuses étapes identiques décrites dans Procédure pas à pas : Enregistrer une application avec Azure Active Directory, avec les exceptions suivantes :
Vous ne devez pas accorder l'autorisation Accéder à Dynamics 365 comme utilisateurs de l'organisation.
Cette application est associée à un compte d'utilisateur spécifique.
Vous devez configurer une clé secrète pour l'enregistrement de l'application OU télécharger un certificat de clé publique.
Lors de l'enregistrement de l'application, sélectionnez la section Clés sur la page Paramètres.
Pour ajouter un certificat :
- Sélectionnez Télécharger la clé publique.
- Sélectionnez le fichier que vous voulez télécharger. Il doit être dans l'un des formats suivants : .cer, .pem, .crt.
Pour ajouter un mot de passe :
- Ajoutez une description pour votre clé.
- Sélectionnez une durée.
- Sélectionnez Enregistrer.
La colonne la plus à droite contient la valeur de la clé une fois que vous enregistrez les modifications apportées à la configuration. Veillez à copier la clé à utiliser dans votre code d'application cliente, puisqu'il n'est pas accessible une fois que vous quittez cette page.
Un compte utilisateur Dataverse lié à l'application enregistrée
Vous devez tout d'abord créer un rôle de sécurité personnalisé qui définira quel accès et quels privilèges ce compte aura dans l'organisation Dataverse. Pour plus d'informations : Créer ou configurer un rôle de sécurité personnalisé
Après avoir créé le rôle de sécurité personnalisé, vous devez créer le compte d'utilisateur qui l'utilisera.
Créer manuellement un utilisateur de l'application Dataverse
La procédure pour créer cet utilisateur est différente de celle de la création d'un utilisateur autorisé. Effectuez les opérations suivantes :
Accédez à Paramètres > Sécurité > Utilisateurs
Dans la liste déroulante Afficher, sélectionnez Utilisateurs d’application.
Cliquez sur Nouveau. Vérifiez tandis que vous utilisez le formulaire Utilisateur de l’application.
Si vous ne voyez pas les champs ID d'application, URI de l'ID d'application et ID d'objet Azure AD dans le formulaire, vous devez sélectionner le formulaire Utilisateur de l'application dans la liste :
Ajoutez les valeurs appropriées aux champs :
Champ valeur Nom d’utilisateur Nom pour l'utilisateur ID d'application Valeur de l'ID d'application de l'application enregistrée auprès d'Azure AD. Nom complet Nom de votre application. Adresse de messagerie principale Adresse de messagerie interne de l'utilisateur. Les champs URI de l'ID d'application et ID d'objet Azure AD sont verrouillés et vous ne pouvez pas définir les valeurs de ces champs.
Lorsque vous créez cet utilisateur les valeurs de ces champs sont récupérées auprès de Azure AD selon la valeur ID d’application lorsque vous enregistrez l’utilisateur.
Associez l'utilisateur de l'application au rôle de sécurité personnalisé créé.
Se connecter à l'aide de la clé secrète de l'application
Si vous vous connectez à l'aide d'une clé secrète configurée pour l'application, utilisez la classe ClientCredential qui transmet le clientId et clientSecret plutôt que des UserCredential avec les paramètres userName et password.
string serviceUrl = "https://yourorg.crm.dynamics.com";
string clientId = "<your app id>";
string secret = "<your app secret>";
AuthenticationContext authContext = new AuthenticationContext("https://login.microsoftonline.com/<Tenant-ID-here>");
ClientCredential credential = new ClientCredential(clientId, secret);
AuthenticationResult result = authContext.AcquireToken(serviceUrl, credential);
string accessToken = result.AccessToken;
Se connecter à l'aide d'une empreinte de certificat
Si vous vous connectez à l'aide d'un certificat et si vous utilisez le Microsoft.Xrm.Tooling.Connector.CrmServiceClient, vous pouvez utiliser le code suivant :
string CertThumbPrintId = "DC6C689022C905EA5F812B51F1574ED10F256FF6";
string AppID = "545ce4df-95a6-4115-ac2f-e8e5546e79af";
string InstanceUri = "https://yourorg.crm.dynamics.com";
string ConnectionStr = $@"AuthType=Certificate;
SkipDiscovery=true;url={InstanceUri};
thumbprint={CertThumbPrintId};
ClientId={AppID};
RequireNewInstance=true";
using (CrmServiceClient svc = new CrmServiceClient(ConnectionStr))
{
if (svc.IsReady)
{
//your code goes here
}
}
Voir aussi
Authentification auprès des services Web Microsoft Dataverse
Authentification des applications .NET Framework
Présentation de la bibliothèque d'authentification Microsoft
Notes
Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)
Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).
Commentaires
Envoyer et afficher des commentaires pour