Utiliser les chaînes de connexion des outils XRM

  • Article

Avec Dynamics 365 Customer Engagement (on-premises), les outils XRM permettent de vous connecter à votre instance à 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 Dynamics 365 Customer Engagement (on-premises) au moment du déploiement sans les coder en dur dans votre application pour vous connecter à votre instance.

Note

La documentation de chaîne de connexion qui s’applique aux utilisateurs de Dataverse est désormais disponible dans la documentation Power Apps : Utiliser les chaînes de connexion des outils XRM pour se connecter à 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="MyCRMServer" connectionString="AuthType=AD;Url=https://contoso:8080/Test;" />  
</connectionStrings>

Important

Si vous ajoutez les informations sensibles au fichier app.config ou web.config, 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 pre-configured connection string named "MyCRMServer"
CrmServiceClient crmSvc = new CrmServiceClient(ConfigurationManager.ConnectionStrings["MyCRMServer"].ConnectionString);

Note

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 CrmServiceClient, vous pouvez l’utiliser pour exécuter des actions dans Dynamics 365 Customer Engagement (on-premises). Pour plus d’informations, voir : Utiliser les outils XRM pour exécuter des actions

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 Spécifie l’URL vers le serveur Dynamics 365 Server. 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://crm-server:port/organization-name ou pour Dynamics 365 Customer Engagement (on-premises).

Le nom d’organisation est nécessaire. Vous pouvez spécifier le nom convivial ou le nom unique de l’organisation à laquelle vous vous connectez.

Exemple : https://contoso/test, https://contoso:5555/test, https://contoso/test ou https://10.10.10.2/test.
Domain Spécifie le domaine qui recherchera les informations d’identification.
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 à Dynamics 365 Customer Engagement (on-premises). Les valeurs valides vont : AD, IFD (AD FS activé), OAuth ou Office365.

- AD et IFD sont autorisés uniquement pour les instances Dynamics 365 Customer Engagement (on-premises).
- OAuthest autorisé pour Dynamics 365 Customer Engagement (on-premises) et les instances Dataverse. Pour la version « on-premises », l’inscription à ADFS 3.x+ et à App\Client Id avec ADFS est obligatoire pour le type OAuth.
- Office365 est autorisé uniquement pour les instances Dataverse.
- L’utilisation d’un certificat ou d’une clé secrète client pour l’authentification est prise en charge dans Dataverse, mais pas dans Dynamics 365 Customer Engagement (on-premises).
RequireNewInstance Spécifie s’il faut réutiliser une connexion existante en cas de rappel lorsque la connexion est toujours active. La valeur par défaut est false qui indique que la connexion existante est réutilisée. Si la valeur est true, le système sera contraint de créer une connexion unique.
ClientId, AppId ou ApplicationId Spécifie la valeur ClientID attribuée lorsque vous avez enregistré votre application dans Azure Active Directory ou Active Directory Federation Services (AD FS).
RedirectUri ou ReplyUrl Spécifie l’URI de redirection de l’application que vous avez enregistrée dans Azure Active Directory 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.
SkipDiscovery Spécifie si l’instance de détection doit être appelée pour déterminer l’URI de connexion d’une instance donnée. À partir de Microsoft.CrmSdk.XrmTooling.CoreAssembly version 9.0.2.7 de NuGet, la valeur par défaut sera = true. La valeur par défaut des versions antérieures était false.
Remarque : Si la valeur est définie sur true, il est important que l’utilisateur fournisse une URI correcte et exacte pour l’instance cible.
Thumbprint ou CertificateThumbprint 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.
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.

Note

Lors de l’utilisation de l’authentification de type 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. Nous les utilisons dans tous nos exemples de code.

Exemple d’AppId ou de ClientId = 51f81489-12ee-4a9e-aaae-a2591f45987d
Exemple de RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97

Pour une utilisation de production, vous devez créer un AppId ou un ClientId spécifiques à votre client dans le Portail de gestion Azure.

Exemples de chaîne de connexion

Les exemples ci-dessous montrent comment utiliser les chaînes de connexion pour se connecter à Dynamics 365 Customer Engagement (on-premises) et aux déploiements IFD. Ces exemples de chaînes de connexion pour les instances Dataverse sont désormais disponibles dans la documentation Power Apps dans : Utiliser les chaînes de connexion des outils XRM pour se connecter à Dataverse

Authentification locale intégrée

<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;" />

Compte nommé utilisant l’authentification locale

<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;
Domain=CONTOSO;
Username=jsmith;
Password=passcode" />

OAuth utilisant un compte nommé dans Dynamics 365 Customer Engagement (on-premises) avec UX pour demander l’authentification

Créer une connexion à l’aide d’un UserID ou d’un mot de passe via OAuth.

Note

OAuth est le type d’authentification recommandé pour se connecter à Dynamics 365 Customer Engagement (on-premises) à l’aide d’un flux interactif. Ce type d’authentification prend entièrement en charge les fonctionnalités de l’accès conditionnel Azure Active Directory et de l’authentification multifacteur.

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Password=passcode;
  Url=https://contoso:8080/Test;
  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 connexion à l’aide de l’utilisateur actuellement connecté via OAuth.

Note

OAuth est le type d’authentification recommandé pour se connecter à Dynamics 365 Customer Engagement (on-premises) à l’aide d’un flux interactif. Ce type d’authentification prend entièrement en charge les fonctionnalités de l’accès conditionnel Azure Active Directory et de l’authentification multifacteur. Pour en savoir plus sur le paramètre Integrated Security, voir la rubrique ici.

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Integrated Security=true;
  Url=https://contoso:8080/Test;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>

IFD utilisant un compte nommé avec la délégation à un sous-domaine

<add name="MyCRMServer"
connectionString="AuthType=IFD;Url=https://contoso:8080/Test;
 HomeRealmUri=https://server-1.server.com/adfs/services/trust/mex/;
Domain=CONTOSO; 
Username=jsmith; 
Password=passcode" />

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 de la cause de l’échec de la connexion.

Voir aussi

Créer des applications clientes Windows à l’aide des outils XRM
Utiliser les constructeurs CrmServiceClient pour se connecter à Dynamics 365 Customer Engagement (on-premises) et à Dataverse
Utiliser les outils XRM pour exécuter des actions
CrmServiceClient