使用 OAuth 連線至 Microsoft Dynamics 365 Web 服務

發行項
03/04/2017

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

OAuth 是 Microsoft Dynamics 365 Web API 支援的驗證方法，也是組織服務的兩種驗證方法之一，另一種是 Active Directory 驗證。使用 OAuth 的一項優點是，您的應用程式可支援多因素驗證。您可以使用 OAuth 驗證，當您的應用程式連線至組織服務或探索服務時。

Web 服務的方法呼叫必須經過該服務端點的身分識別提供者授權。當訊息要求的標頭中提供有效的 OAuth 2.0 (使用者) 存取權杖 (由 Microsoft Azure Active Directory 簽發) 時，授權就會核准。

建議搭配 Dynamics 365 Web API 使用的驗證 API 是 Azure Active Directory Authentication Library (ADAL)，適用於各種平台及程式設計語言。 ADAL API 管理 OAuth 2.0 驗證，透過 Dynamics 365 Web 服務身分識別提供者。如需實際使用的 OAuth 通訊協定的詳細資訊，請參閱使用 OAuth 驗證 CRM 服務。

在您使用 OAuth 驗證透過 Dynamics 365 Web 服務連線之前，您的應用程式必須先在 Microsoft Azure Active Directory 註冊。Azure Active Directory 用來驗證您的應用程式已獲准存取 Dynamics 365 用戶中儲存的商務資料。

使用 ADAL 驗證

使用 ADAL 的基本 OAuth Web 服務驗證只需要幾行程式碼就能完成。

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

驗證內容是使用已知的授權提供者傳回。當您不知道與您所呼叫的 Dynamics 365 執行個體關聯的 Azure Active Directory 用戶時，可以使用常數字串 "https://login.windows.net/common"，這是多用戶案例的授權單位 URL。另一種方法是在執行階段動態探索授權單位，將於本主題稍後說明。

下一行程式碼會取得驗證結果，包含您要尋找的存取權杖。您可以使用此權杖傳送訊息要求給 Web 服務。

此程式碼中另外還有一些使用的字串值，值得您深入了解。資源變數包含傳輸層安全性 (TLS) 或安全通訊端層 (SSL) 根位址，包括網域 (組織)，屬於您的 Dynamics 365 伺服器。clientId 和 redirectUrl 變數包含應用程式註冊資訊，這是在 Active Directory 註冊應用程式的結果。如需有關應用程式註冊的詳細資訊，請參閱逐步解說：向 Azure Active Directory 註冊 Dynamics 365 應用程式。

使用訊息要求中的存取權杖

根據您使用的 Dynamics 365 API，有兩種不同的方法可將訊息要求傳送至 Web 服務。針對 Web API，您通常會傳送 HTTP 訊息要求。針對組織服務，您會使用網頁用戶端 Proxy 傳送訊息要求。

HTTP 訊息要求

當您取得存取權杖後，必須將要傳送至 Web 服務的訊息要求的授權標頭設定為存取權杖值，並指定權杖類型為 "Bearer"。如需授權標頭的詳細資訊，請參閱 HTTP/1.1 通訊協定的第 14.8 節。下列程式碼示範如何使用 System.Net.Http.HttpClient 執行這項操作。

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

網頁用戶端要求

只要將 HeaderToken 屬性值設定為存取權杖，當使用組織服務的 OrganizationWebProxyClient 或 DiscoveryWebProxyClient 時。

重新整理存取權杖

這是建議的最佳做法，用來重新整理存取權杖，在每一次呼叫 Dynamics 365 Web 服務方法之前。這是撰寫程式碼來檢查存取權杖到期日和時間的解決方法，並且在即將到期時重新整理權杖。

若要重新整理 ADAL 快取的存取權杖，只要使用相同的內容呼叫 AcquireToken 方法即可。

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

之後，當您使用 Web API 時，再次設定授權標頭為 result.AccessToken，或是使用組織服務時設定 HeaderToken。

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

在執行階段探索授權單位

驗證授權單位 URL，以及資源 URL，可以在執行階段使用下列 ADAL 程式碼動態判斷。這是建議的方法，用來與先前在程式碼片段中顯示的已知授權單位 URL 比較。

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

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

針對 Web API，取得授權單位 URL 的另一種方式是傳送訊息要求至 Web 服務，不指定存取權杖。這稱為承載挑戰。回覆可加以剖析，以取得授權單位 URL。

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

另請參閱

逐步解說：向 Azure Active Directory 註冊 Dynamics 365 應用程式
 各因素驗證文件
 OAuth 2.0

Microsoft Dynamics 365

共用方式為