Partager via

Utiliser les chaînes de connexion des outils XRM pour se connecter à Microsoft Dataverse

  • Article

Avec Dataverse, les outils XRM vous permettent de vous connecter à votre environnement Dataverse à l’aide de chaînes de connexion. Ceci est similaire au concept des chaînes de connexion utilisées avec SQL Server. Les chaînes de connexion assurent une prise en charge native dans les fichiers de configuration, notamment la capacité d’encoder les sections de configuration pour un maximum de sécurité. Cela vous permet de configurer les connexions Dataverse au moment du déploiement sans les coder en dur dans votre application pour vous connecter à votre environnement de Dataverse.

Créer une chaîne de connexion

Vous spécifiez la chaîne de connexion dans le fichier app.config ou web.config de votre projet, comme illustré dans l’exemple suivant.

<connectionStrings>  
    <add name="MyCDSServer" connectionString="AuthType=OAuth;Username=jsmith@contoso.onmicrosoft.com;Password=passcode;Url=https://contosotest.crm.dynamics.com;AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;TokenCacheStorePath=c:\MyTokenCache;LoginPrompt=Auto"/>
</connectionStrings>

Important

Si vous ajoutez les informations sensibles au app.config ou web.config file, par exemple un mot de passe de compte, veillez à prendre les précautions qui s’imposent pour protéger les informations.

Après avoir créé la chaîne de connexion, vous devez l’utiliser pour créer un objet CrmServiceClient.

//Use the connection string named "MyCDSServer"  
//from the configuration file  
CrmServiceClient svc = new CrmServiceClient(ConnectionString);

Vous pouvez aussi utiliser la classe ServiceClient.

ServiceClient svc = new ServiceClient(ConnectionString);

Notes

Vous devrez utiliser la directive using suivante dans votre code pour référencer l’espace de noms System.Configuration et accéder à la chaîne de connexion dans votre code : using System.Configuration;

Après avoir créé un objet client service, vous pouvez utiliser l’objet pour exécuter des actions dans Dataverse. Pour plus d’informations, voir : Utiliser les outils XRM pour exécuter des actions dans Dataverse

Paramètres de la chaîne de connexion

La chaîne de connexion contient une série de paires nom=valeur séparées par des points-virgules. Le tableau suivant répertorie les paramètres pris en charge. Ils peuvent être saisis dans n’importe quel ordre.

Nom du paramètre Description
ServiceUri, Service Uri, Url, ou Server Précise l’URL vers l’environnement Dataverse. L’URL peut utiliser le protocole http ou https, et le port est facultatif. Le port par défaut est 80 pour le protocole http et 443 pour le protocole https. L’URL du serveur est généralement au format https://<organization-name>.crm.dynamics.com

Le nom d’organisation est nécessaire.
UserName, User Name, UserId, ou User Id Spécifie le nom de l’ID d’utilisateur associé aux informations d’identification.
Password Spécifie le mot de passe d’utilisateur associé aux informations d’identification.
HomeRealmUri ou Home Realm Uri Spécifie l’URI du domaine d’accueil.
AuthenticationType ou AuthType Spécifie le type d’authentification pour se connecter à l’environnement Dataverse. Les valeurs valides vont : AD, IFD (AD FS activé), OAuth, Certificate, ClientSecret ou Office365. Cependant, seulement OAuth, Certificate, ClientSecret et Office365 sont des valeurs autorisées pour les environnements Dataverse.

REMARQUE : le type d’authentification Office365 est obsolète et nous vous recommandons d’utiliser OAuth comme type d’authentification préféré. Plus d’informations : Que dois-je faire pour corriger mon code d’application s’il est affecté ?
RequireNewInstance Spécifie s’il faut réutiliser une connexion existante en cas de rappel lorsque la connexion est toujours active. Si la valeur est true, le système sera contraint de créer une connexion unique. Si paramétrée sur false, la connexion existante peut être réutilisée.
ClientId, AppId ou ApplicationId Spécifie la valeur ClientID attribuée lorsque vous avez enregistré votre application dans Microsoft Entra ID ou Active Directory Federation Services (AD FS).
ClientSecret ou Secret Nécessaire lorsque le type Auth est défini sur ClientSecret. Chaîne de clé secrète client à utiliser pour l’authentification.
RedirectUri ou ReplyUrl Spécifie l’URI de redirection de l’application que vous avez enregistrée dans Microsoft Entra ID ou Active Directory Federation Services (AD FS).

Ce paramètre n’est applicable que lorsque le type d’authentification est spécifié en tant que OAuth.
TokenCacheStorePath Spécifie le chemin d’accès complet à l’emplacement où le cache de jeton de l’utilisateur doit être stocké. Le processus d’exécution doit avoir accès au chemin d’accès spécifié. Il incombe aux processus de définir et de configurer ce chemin d’accès.

Ce paramètre n’est applicable que lorsque le type d’authentification est spécifié en tant que OAuth.
LoginPrompt Spécifie si l’utilisateur est invité à fournir les informations d’identification si elles ne sont pas fournies. Les valeurs valides sont :

- Always : invite toujours l’utilisateur à spécifier les informations d’identification.
- Auto : permet à l’utilisateur de choisir si l’invite doit être affichée ou non dans l’interface de contrôle de la connexion.
- Never : n’invite pas l’utilisateur à spécifier les informations d’identification. Si l’utilisation d’une méthode de connexion ne dispose pas d’une interface utilisateur, vous devez utiliser cette valeur.

Ce paramètre n’est applicable que lorsque le type d’authentification est spécifié en tant que OAuth.
StoreName ou CertificateStoreName Spécifie le nom du magasin où le certificat identifié par empreinte se trouve. Une fois défini, l’empreinte est requise.
Thumbprint ou CertThumbprint Spécifie l’empreinte du certificat à utiliser lors d’une connexion S2S. Une fois défini, l’AppID est requis et les valeurs ID utilisateur et Mot de passe sont ignorées.
Integrated Security Spécifie d’utiliser les informations d’identification Windows actuelles pour tenter de créer un jeton pour les instances. À partir de Microsoft.CrmSdk.XrmTooling.CoreAssembly version 9.1.0.21 de NuGet

Notes

Lorsque vous utilisez l’AuthType\AuthenticationType OAuth
Pour des raisons de développement et de prototypage, nous avons fourni l’AppId ou le ClientId suivant et l’URI de redirection unique pour une utilisation dans les flux OAuth.
Pour une utilisation de production, vous devez créer un AppId ou un ClientId spécifiques à votre client dans le Portail de gestion Azure.
Exemple d’AppId ou de ClientId = 51f81489-12ee-4a9e-aaae-a2591f45987d
Exemple de RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97

Exemples de chaîne de connexion

Les exemples ci-dessous montrent comment utiliser les chaînes de connexion pour se connecter aux déploiements et scénarios d’authentification en ligne. Ces exemples de chaînes de connexion pour les instances de déploiement local et IFD sont désormais disponibles dans la documentation Dynamics 365 Customer Engagement (on-premises) à l’adresse : Utiliser des chaînes de connexion dans les outils XRM pour se connecter à Customer Engagement

Compte nommé utilisant Office365

Créez une nouvelle connexion à Dataverse en utilisant un nom d’utilisateur ou un mot de passe via Office365.

Notes

Ce AuthType est obsolète et nous vous recommandons d’utiliser OAuth comme type d’authentification préféré. Informations complémentaires : S’authentifier à l’aide d’Office365

<add name="MyCDSServer" 
 connectionString="
  AuthType=Office365;
  Username=jsmith@contoso.onmicrosoft.com; 
  Password=passcode;
  Url=https://contoso.crm.dynamics.com"/>

OAuth utilisant un compte nommé dans Microsoft 365 avec UX pour demander l’authentification

Créez une nouvelle connexion Dataverse à l’aide d’un ID utilisateur ou d’un mot de passe via OAuth.

Notes

OAuth est le type d’authentification préféré pour la connexion à Dataverse lors de l’utilisation d’un flux interactif. Ce type d’authentification prend entièrement en charge les fonctionnalités de l’accès conditionnel Microsoft Entra ID et de l’authentification multifacteur.

<add name="MyCDSServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith@contoso.onmicrosoft.com;
  Password=passcode;
  Url=https://contosotest.crm.dynamics.com;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>

OAuth utilisant l’utilisateur actuellement connecté avec retour à l’UX pour inviter à s’authentifier

Créez une nouvelle connexion à Dataverse à l’aide de l’utilisateur actuellement connecté via OAuth.

Notes

OAuth est le type d’authentification préféré pour la connexion à Dataverse lors de l’utilisation d’un flux interactif. Ce type d’authentification prend entièrement en charge les fonctionnalités de l’accès conditionnel Microsoft Entra ID et de l’authentification multifacteur.

<add name="MyCDSServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith@contoso.onmicrosoft.com;
  Integrated Security=true;
  Url=https://contosotest.crm.dynamics.com;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache\msal_cache.data;
  LoginPrompt=Auto"/>

Authentification basée sur un certificat

Créez une connexion à Dataverse à l’aide d’un ID d’application ou de client et d’un certificat.

<add name="MyCDSServer" 
  connectionString="
  AuthType=Certificate;
  url=https://contosotest.crm.dynamics.com;
  thumbprint={CertThumbPrintId};
  ClientId={AppId};"
  />

Authentification basée sur le ClientId ou la clé secrète client

Créez une connexion à Dataverse à l’aide d’un ID d’application ou de client et d’une clé secrète client.

<add name="MyCDSServer" 
  connectionString="
  AuthType=ClientSecret;
  url=https://contosotest.crm.dynamics.com;
  ClientId={AppId};
  ClientSecret={ClientSecret}"
  />

Déterminer l’état de votre connexion

Pour déterminer si la demande de connexion a été réussie, vérifiez la valeur de la propriété CrmServiceClient.IsReady . Si la valeur est true, la connexion est réussie et vous êtes prêt à travailler. Sinon, vérifiez les valeurs des propriétés CrmServiceClient.LastCrmError et CrmServiceClient.LastCrmException pour identifier la cause de l’échec de la connexion.

Voir aussi

Créer des applications clientes Windows à l’aide des outils XRM
Utilisation des constructeurs CrmServiceClient pour se connecter à Dataverse
Utiliser les outils XRM pour exécuter des actions dans Dataverse
CrmServiceClient

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é).