Mithilfe von OAuth mit Microsoft Dynamics 365-Webdiensten verbinden

Artikel
03/03/2017

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

OAuth ist die Authentifizierungsmethode, die von der Microsoft Dynamics 365 Web-API untersützt wird und ist eine der beiden Authentifizierungsmethoden für den Organisationsdienst – die andere ist die Active Directory-Authentifizierung. Ein Vorteil der Verwendung von OAuth ist, dass die Anwendung mehrstufige Authentifizierung unterstützen kann. Sie können OAuth-Authentifizierung verwenden, wenn die Anwendung entweder eine Verbindung mit dem Organisationsdienst oder dem Suchdienst herstellt.

Methodenaufrufe an die Webdienste müssen mit dem Identitätsanbieter für diesen Dienstendpunkt autorisiert werden. Autorisierung ist genehmigt, wenn ein gültiges OAuth 2.0-(Benutzer-)Zugriffstoken, das von Microsoft Azure Active Directory ausgestellt ist, in den Kopfzeilen der Messageanforderungen bereitgestellt wird.

Die empfohlene Authentifizierungs-API für die Verwendung mit der Dynamics 365-Web-API ist die Azure Active Directory Authentication Library (ADAL), die für eine Vielzahl von Plattformen und Programmiersprachen verfügbar ist. Die ADAL-API verwaltet OAuth 2.0-Authentifizierung mit dem Dynamics 365-Webdienst-Identitätsanbieter. Weitere Details zum tatsächlichen verwendeten OAuth-Protokol finden Sie unter Verwenden von OAuth zur Authentifizierung beim CRM-Dienst.

Bevor Sie OAuth-Authentifizierung verwenden können, um eine Verbindung mit Dynamics 365-Webdiensten herzustellen, muss Ihre Anwendung zuerst bei Microsoft Azure Active Directory registriert werden.Azure Active Directory wird verwendet, um zu überprüfen, dass die Anwendung berechtigt zum Zugriff auf Geschäftsdaten ist, die in einem Dynamics 365-Mandant gespeichert werden.

Authentifizieren mithilfe von ADAL

Grundlegende OAuth-Webdienstauthentifizierung mithilfe ADAL erfolgt mit nur ein paar wenigen Codezeilen.

// 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));

Der Authentifizierungskontext wird mit einem bekannten Behördenanbieter zurückgegeben. Wenn Sie nicht den Azure Active Directory-Mandanten kennen, der der Instanz Dynamics 365 zugeordnet ist, dann können Sie eine konstante Zeichenfolge von " https://login.windows.net/common" verwenden, die die Behörden-URL für ein Szenario mit mehreren Mandanten ist. Eine andere Möglichkeit, um die Behörde dynamisch zur Laufzeit zu erkunden, wird weiter unten in diesem Thema beschrieben.

Die nächste Zeile des Codes ruft Authentifizierungsergebnis ab, das das Zugriffstoken enthält, das Sie suchen. Sie können mit diesem Token dem Webdienst Messageanforderungen senden.

Einige weitere interessante Elemente in diesem Code sind die verwendeten Zeichenfolgenwerte. Die Ressourcenvariable enthält die Transport Layer Security (TLS) oder Secure Sockets Layer (SSL)-Stammadresse, einschließlich der Domäne (Organisation) Ihres Dynamics 365 Servers. Die Variablen clientId und redirectUrl enthalten die App-Registrierungsinformationen, die das Ergebnis des Registrierens der App bei Active Directory sind. Weitere Informationen zur App-Registrierung finden Sie unter Exemplarische Vorgehensweise: Registrieren einer Dynamics 365-App bei Azure Active Directory.

Das Zugriffstoken in den Messageanforderungen verwenden

Je nach Dynamics 365-API, die Sie verwenden, gibt es zwei verschiedene Methoden, um eine Messageanforderung an die Webdienste zu senden. Für die Web-API würden Sie normalerweise eine HTTP-Messageanforderung senden. Für den Organisationsdienst würden Sie eine Messageanforderung mithilfe des Webclientproxys senden.

HTTP-Messageanforderung

Sobald Sie das Zugriffstoken haben, müssen Sie die Autorisierungskopfzeile der Messageanforderung festlegen, die Sie dem Webdienst zum Zugriffstokenwert senden und den Tokentyp von “ Bearer” angeben. Weitere Informationen zur Autorisierungskopfzeile, finden Sie im Abschnitt über 14,8 des HTTP/1.1-Protokolls Der folgende Code veranschaulicht, wie dies mithilfe der System.Net.Http.HttpClient-Klasse erfolgt.

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

Webclientanforderungen

Legen Sie einfach den HeaderToken-Eigenschaftswert für das Zugriffstoken fest, wenn Sie OrganizationWebProxyClient oder DiscoveryWebProxyClient des Organisationsdiensts verwenden.

Das Zugriffstoken aktualisieren

Es ist eine bewährte Methode, um das Zugriffstoken vor jedem Anruf zu einer Dynamics 365-Webdienstmethode zu aktualisieren. Dies ist eine Problemumgehung zum Schreiben von Code, bei der das Zugriffstoken-Ablaufdatum und -zeit überprüft das Token aktualisiert werden, wenn es kurz davor ist, abzulaufen.

Um das Zugriffstoken zu aktualisieren, das durch ADAL zwischengespeichert wird, rufen Sie einfach erneut die AcquireToken-Methode auf, wobei derselbe Kontext verwendet wird.

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

Danach legen Sie erneut die Autorisierungskopfzeile mitresult.AccessToken fest, wenn Sie die Web-API verwenden, oder die HeaderToken, wenn Sie den Organisationsdienst verwenden.

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

Ermitteln Sie die Behörde zur Laufzeit

Die Authentifizierungsbehörden-URL und die Ressourcen-URL können dynamisch zur Laufzeit mithilfe des folgenden ADAL-Codes bestimmt werden. Dies ist die empfohlene Methode, die zu verwenden ist, im Vergleich zur bekannten Behörden-URL, die zuvor in einem Codeausschnitt gezeigt wurde.

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

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

Für die Web-API besteht eine andere Möglichkeit, die Behörden-URL zu erhalten darin, irgendeine Messageanforderung an den Webdienst zu senden, ohne ein Zugriffstoken anzugeben. Dies wird als Trägerabfrage bezeichnet. Die Antwort kann analysiert werden, um die Behörden-URL zu erhalten.

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

Siehe auch

Exemplarische Vorgehensweise: Registrieren einer Dynamics 365-App bei Azure Active Directory
Mehrstufige Authentifizierungsdokumentation
OAuth 2.0

Microsoft Dynamics 365

Teilen über