Verbinding maken met Microsoft Dynamics 365-webservices via OAuth

Artikel
03/03/2017

Gepubliceerd: januari 2017

Is van toepassing op: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

OAuth is de verificatiemethode die wordt ondersteund door de web-API van Microsoft Dynamics 365 en is een van de twee verificatiemethoden voor de Organisatieservice; de andere is verificatie met Active Directory. Een voordeel van het gebruik van OAuth is dat uw toepassing multifactorverificatie kan ondersteunen. U kunt verificatie met OAuth gebruiken wanneer uw toepassing verbinding maakt met de Organisatieservice of de Discovery-service.

Aanroepen van webservicemethoden moeten zijn toegestaan met de identiteitsprovider voor dat service-eindpunt. Autorisatie wordt toegestaan wanneer een geldig toegangstoken voor OAuth 2.0 (gebruiker) is uitgegeven door Microsoft Azure Active Directory en wordt vermeld in de kopteksten van de berichtaanvragen.

De aanbevolen verificatie-API voor gebruik met de web-API van Dynamics 365 is Azure Active Directory Authentication Library (ADAL), die beschikbaar is voor allerlei platforms en programmeertalen. De ADAL-API beheert OAuth 2.0-verificatie met de identiteitsprovider van de Dynamics 365-webservice. Meer informatie over het werkelijk gebruikte OAuth-protocol vindt u in OAuth gebruiken om te verifiëren met de CRM-service.

Voordat u OAuth-verificatie kunt gebruiken om verbinding te maken met de Dynamics 365-webservices, moet uw toepassing eerst worden geregistreerd bij Microsoft Azure Active Directory.Azure Active Directory wordt gebruikt om te verifiëren of de toepassing toegang kan krijgen tot de zakelijke gegevens die zijn opgeslagen in een Dynamics 365-tenant.

Verifiëren met ADAL

De eenvoudige OAuth-webserviceverificatie met ADAL wordt uitgevoerd met slechts een paar regels code.

// TODO Substitute your correct CRM root service address, 
string resource = "https://mydomain.crm.dynamics.com";

// TODO Substitute your app registration values that can be obtained after you
// register the app in Active Directory on the Microsoft Azure portal.
string clientId = "e5cf0024-a66a-4f16-85ce-99ba97a24bb2";
string redirectUrl = "https://localhost/SdkSample";


// Authenticate the registered application with Azure Active Directory.
AuthenticationContext authContext = 
    new AuthenticationContext("https://login.windows.net/common", false);
AuthenticationResult result = authContext.AcquireToken(resource, clientId, new
                                                       Uri(redirectUrl));

De verificatiecontext wordt geretourneerd met een bekende certificeringsinstantie. Als u de Azure Active Directory-tenant niet kent die samenhangt met het Dynamics 365-exemplaar dat u aanroept, kunt u een constante tekenreeks gebruiken met "https://login.windows.net/common", wat de URL is van de certificeringsinstantie voor een scenario met meerdere tenants. Een alternatieve methode voor het dynamisch detecteren van de certificeringsinstantie wordt verderop in dit onderwerp beschreven.

De volgende regel met code haalt het verificatieresultaat op met de toegangstoken die u zoekt. U kunt berichtaanvragen verzenden naar de webservice met dit token.

Andere interessante items in deze code zijn de gebruikte tekenreekswaarden. De resourcevariabele bevat het rootadres van de Transport Layer Security (TLS) of Secure Sockets Layer (SSL), met het domein (organisatie ) van uw Dynamics 365-server. De variabelen clientId en redirectUrl bevatten de app-registratiegegevens die het resultaat zijn van het registreren van de app met Active Directory. Raadpleeg Overzicht: een Dynamics 365-app registreren bij Azure Active Directory voor meer informatie over de app-registratie.

Gebruik de toegangstoken in berichtaanvragen

Afhankelijk van de Dynamics 365-API die u gebruikt, zijn er twee verschillende methoden om een berichtaanvraag te verzenden naar de webservices. Voor de web-API zou u gewoonlijk een HTTP-berichtaanvraag verzenden. Voor de Organisatieservice zou u een berichtaanvraag verzenden met de webclientproxy.

Http-berichtaanvraag

Zodra u de toegangstoken hebt, moet u de autorisatiekoptekst van de berichtaanvraag instellen die u verzendt aan de webservice voor de toegangstokenwaarde en Bearer als tokentype opgeven. Voor meer informatie over de autorisatiekoptekst raadpleegt u sectie 14.8 van het HTTP/1.1-protocol De volgende code laat zien hoe dit wordt uitgevoerd met de System.Net.Http.HttpClient-klasse.

using (HttpClient httpClient = new HttpClient())
{
    httpClient.Timeout = new TimeSpan(0, 2, 0);  // 2 minutes
    httpClient.DefaultRequestHeaders.Authorization = 
        new AuthenticationHeaderValue("Bearer", result.AccessToken);

Webclientaanvragen

Stel de eigenschapswaarde HeaderToken in op de toegangstoken als u OrganizationWebProxyClient of DiscoveryWebProxyClient gebruikt van de Organisatieservice.

Vernieuw de toegangstoken

Het wordt aanbevolen om de toegangstoken te vernieuwen voor elke aanroep naar een Dynamics 365-webservicemethode. Dit is een alternatief voor het schrijven van code die de vervaldatum van de toegangstoken controleert en de token vernieuwt wanneer deze bijna is verlopen.

Als u de toegangstoken wilt vernieuwen, die door ADAL in de cache is geplaatst, roept u de methode AcquireToken weer aan met dezelfde context.

AuthenticationResult result = authContext.AcquireToken(resource, clientId, new Uri(redirectUrl));

Vervolgens kunt u de autorisatiekoptekst opnieuw instellen met result.AccessToken wanneer u de web-API gebruikt of met HeaderToken wanneer u de Organisatieservice gebruikt.

httpClient.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", result.AccessToken);

De certificeringsinstatie detecteren tijdens runtime

De URL van de certificeringsinstantie en de URL van de resource kunnen dynamisch worden vastgesteld tijdens runtime met de volgende ADAL-code. Dit is de aanbevolen methode in vergelijking met de bekende certificeringsinstantie-URL die eerder in een stukje code is getoond.

AuthenticationParameters ap = AuthenticationParameters.CreateFromResourceUrlAsync(
                        new Uri("https://mydomain.crm.dynamics.com/api/data/")).Result;

String authorityUrl = ap.Authority;
String resourceUrl  = ap.Resource;

Een andere manier om de certificeringsinstantie-URL voor de web-API op te halen is het verzenden van een berichtaanvraag naar de webservice zonder een toegangstoken op te geven. Dit wordt een bearer verificatie genoemd. De respons kan worden geparseerd om de certificeringsinstantie-URL te verkrijgen.

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", “”);

Zie ook

Overzicht: een Dynamics 365-app registreren bij Azure Active Directory
Documentatie multifactorverificatie
OAuth 2.0

Microsoft Dynamics 365

Delen via