匯出 (0) 列印
全部展開

使用 Graph API 來查詢 Azure AD

更新日期: 2014年5月

note附註
注意:此範例已過時。其中的技術、方法和 (或) 使用者介面指示已被更新的功能取代。若要查看可建立類似應用程式的更新版範例,請參閱 WebApp-GraphAPI-DotNet

此範例應用程式適用對象為想針對 Windows Azure Active Directory (Windows Azure AD) 的現有應用程式增加功能及建置新應用程式的 .NET 開發人員。此逐步解說以使用 Azure AD 將登入新增至 Web 應用程式為基礎,其產生的範例應用程式,可示範如何為 Windows Azure AD 客戶提供網頁單一登入使用者經驗。此逐步解說將顯示如何使用 Windows Azure AD Graph API 來讀取目錄資料。Graph API 是允許應用程式存取客戶 Windows Azure 目錄資料的 RESTful API。

應用程式在許多案例中都需要存取目錄資料,這些案例包括:

  • 擷取使用者、群組、連絡人清單以用於人員/群組選擇器

  • 讀取詳細的租用戶、使用者和群組資訊

  • 驗證群組成員資格

  • 修改使用者、群組和群組成員資格

  • 更新使用者密碼

  • 停用使用者帳戶

note附註
當多租用戶應用程式嘗試取得權杖,以便存取最近剛同意應用程式之 Azure AD 租用戶的 Graph API 時,權杖要求會失敗,並帶有錯誤 ACS50012。若要解決此問題,請等候幾分鐘後再試。或者,由提供同意記錄的租用戶管理員,在同意之後向應用程式呈報。如需詳細資訊,請參閱 ACS 錯誤碼

本文件分為下列幾節:

完成本教學課程需要具備下列必要條件:

本逐步解說結束時,您的應用程式便已設定為可從 Azure AD 租用戶讀取資料。應用程式可以讀取下列目錄實體:使用者、群組、連絡人、公司資訊、授權和角色;如果您的應用程式獲得寫入權限,則還能更新實體。

在此範例應用程式中,我們會檢閱如何從 Azure AD 公司讀取目錄資料。其他進階主題包括:

  • 取得完整的使用者詳細資料

  • 建立和更新使用者

  • 取得群組清單

  • 更新群組成員資格

在您更新此應用程式後,單一登入經驗仍保持不變,因此可以存取 Graph API。使用者驗證成功後,應用程式會向 Azure AD 驗證端點要求權杖,而如果成功,應用程式就會在對 Graph API 的呼叫中使用該權杖來取得租用戶的所有使用者。應用程式會顯示使用者清單,並顯示其 Display NamesUser Principal Names

解決方案架構

在此逐步解說中,我們將使用 OAuth 2.0 用戶端認證流程來驗證應用程式。在存取 Graph API 端點前,應用程式必須先向 Azure AD 驗證端點取得有效權杖 -- 方法是透過呈現有效的應用程式認證 (用戶端 ID 和密碼)。如果認證獲得驗證,就會將已簽署的權杖傳回給應用程式。之後,應用程式會在對 Graph API 之呼叫的授權標頭中加入該權杖。Graph API 服務會驗證連入要求中的權杖,如果通過了,下一步是檢查授權。

應用程式授權是由 Graph API 及其基礎「角色型存取控制 (RBAC)」服務進行驗證。對 Graph API 的呼叫受限於應用程式的權限。如果驗證和授權都通過了,就會將資料傳回給應用程式。

應用程式的驗證和授權組態會使用儲存於租用戶目錄的 Service Principal 物件,儲存於 Azure AD 中。在 Azure AD 中由具有唯一識別、認證和權限的 Service Principal 物件來代表應用程式。這類似於 Active Directory 中代表使用者的 User Principal 物件,每個物件都有唯一的識別、認證和權限。

應用程式的 Service Principal 具有用於驗證的唯一識別碼和密碼。管理授權的方法是將應用程式的「服務主體」新增至具有必要權限的角色。租用戶管理員可以在 Azure AD 管理入口網站中建立應用程式「服務主體」並將其新增至角色。或者,租用戶管理員也可以使用 Windows PowerShell 來管理「服務主體」。如需詳細資訊,請參閱使用 Windows PowerShell 管理 Azure AD

使用 Azure AD 將登入新增至 Web 應用程式逐步解說中,您已在 Azure AD 管理入口網站中設定應用程式權限,藉以授權應用程式允許使用 Azure AD 使用者認證進行單一登入。您現在將更新應用程式組態,以便啟用 Expense Reporting 應用程式對 Graph API 進行驗證並獲得呼叫 Graph API 的授權。我們將執行下列步驟:

  • 授權:設定應用程式權限以允許對目錄的讀取/寫入存取權。

  • 驗證:取得應用程式金鑰,即您應用程式的密碼。將用來對 Graph API 驗證您的應用程式。

  1. 移至 Microsoft Azure 管理入口網站 (https://manage.WindowsAzure.com),登入後按一下 [Active Directory]。(疑難排解提示:"Active Directory" 項目遺失或無法使用)

  2. 按一下以選取您的目錄、按一下 [應用程式] 然後按一下您在單一登入逐步解說中建立的 Expense Reporting 範例應用程式。



    外部存取

  3. 按一下頁面底部的 [管理存取]。

  4. 選取 [變更這個應用程式的目錄存取]。



    您想要做什麼事?
  5. 選取 [單一登入、讀取目錄資料]。接著按一下核取記號,儲存您的變更。



    目錄存取

  1. 在 Expense Reporting 應用程式頁面上展開 [啟用應用程式讀取或寫入目錄資料]。在 [建立金鑰] 區段中選取 [設定金鑰]。



    設定金鑰

  2. 若要新增金鑰,請在 [設定] 頁面的 [金鑰] 區段中,選取金鑰的週期 (預設為 1 年),然後按一下畫面底部的 [儲存]。如此會產生一個金鑰值,即您應用程式的密碼。

    Warning警告
    建立金鑰後就會顯示金鑰值,但無法稍後擷取該值。因此,請立即複製金鑰值並將其儲存至安全位置,以供未來使用。此外,您的應用程式可擁有多個金鑰,例如,您可能會想針對測試和生產使用一或多個金鑰。



    圖表金鑰

到目前為止,您已擁有用戶端 ID (應用程式 ID)、應用程式金鑰 (金鑰值) 並已設定應用程式的讀取權限。

note附註
在此逐步解說範例應用程式中,我們使用金鑰值做為驗證應用程式的密碼。在 OAuth 2.0 中則是使用用戶端認證授與流程,其中 grant_type=client_credentials)。

開啟 Visual Studio,然後開啟您先前建立的單一登入逐步解說專案 "Expense Reporting"。我們將以下列步驟修改單一登入逐步解說應用程式:

  1. 新增 Graph 協助程式類別專案

  2. 更新至 WCF Data Services 5.3 或更新版本

  3. 更新 Web.config 檔案

  4. 修改 HomeController

  5. 新增使用者檢視

  6. 更新通用的 _Layout 檢視

下載 Azure AD Graph API 協助程式程式庫。Graph 協助程式類別專案包含可促進驗證和呼叫 Graph API 的程式庫和類別。其中包括原始程式碼,應加入並建置為本逐步解說的一部分。

  1. 若要新增 Graph 協助程式至 Expense Reporting 專案,請在 [方案 'ExpenseReport'] 方案上按一下滑鼠右鍵,按一下 [加入],然後按一下 [現有專案]。

  2. 在 [加入現有專案] 對話方塊中,瀏覽至 Graph 協助程式路徑,然後開啟 Microsoft.WindowsAzure.ActiveDirectory.GraphHelper.csproj 專案檔案。

Graph 協助程式專案現在已新增至您的 ExpenseReport 方案。

Web.config 檔案的 appSettings 區段包含應用程式的特定組態資訊 - 新增 ClientIdPassword 金鑰值對組至應用程式的 Web.config 檔案。

  • ClientId:相當於 Azure AD 管理入口網站應用程式管理頁面中的用戶端識別碼值。

  • 密碼:相當於 Azure AD 管理入口網站應用程式管理頁面中的應用程式金鑰值。您應已從建立金鑰的上一步驟中記下此值,請注意無法重新擷取該值。如果您忘了或遺失先前的金鑰,請在相同應用程式下再建立另一個金鑰。

<appSettings>
    <add key="ClientId" value="<insert your ClientId here>"/>
    <add key="Password" value="<insert your Application Key here>"/>
    ...

進行變更後,儲存 Web.config 檔案。

  1. 在 Visual Studio 中,以滑鼠右鍵按一下 Expense Reporting 專案 [參考] 資料夾,然後按一下 [加入參考...]

  2. 在 [參考管理員] 對話方塊中,按一下 [擴充功能],然後選取 Microsoft.Data.OData 版本 5.3.0.0 組件以及 Microsoft.Data.Services.Client 版本 5.3.0.0 組件。



    OData 參考
  3. 在同一個 [參考管理員] 對話方塊中,展開左側的 [方案] 功能表,然後按一下 Microsoft.WindowsAzure.ActiveDirectory.GraphHelper 的核取方塊。按 [確定],參考就會加入您的專案。



    加入圖表協助程式參考

開啟 HomeController.cs 檔案,此檔案位於 Controllers 資料夾中。將下列組件加入至檔案,然後儲存檔案。

using System.Configuration;
using System.Security.Claims;
using System.Data.Services.Client;
using Microsoft.WindowsAzure.ActiveDirectory;
using Microsoft.WindowsAzure.ActiveDirectory.GraphHelper;

在現有 ActionResults 所在 (Index、About、Contact) 的 HomeController.cs 檔案中,找到 HomeController 類別。新增一個名為 UsersActionResult,如下所示:

       public ActionResult Users()
       {
            //get the tenantName
            string tenantName = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;



            // retrieve the clientId and password values from the Web.config file
            string clientId = ConfigurationManager.AppSettings["ClientId"];
            string password = ConfigurationManager.AppSettings["Password"];



            // get a token using the helper
            AADJWTToken token = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);

            // initialize a graphService instance using the token acquired from previous step
            DirectoryDataService graphService = new DirectoryDataService(tenantName, token);

            //  get Users
            //
            var users = graphService.users;
            QueryOperationResponse<User> response;
            response = users.Execute() as QueryOperationResponse<User>;
            List<User> userList = response.ToList();
            ViewBag.userList = userList;


            //  For subsequent Graph Calls, the existing token should be used.
            //  The following checks to see if the existing token is expired or about to expire in 2 mins
            //  if true, then get a new token and refresh the graphService
            //
            int tokenMins = 2;
            if (token.IsExpired || token.WillExpireIn(tokenMins))
            {
                AADJWTToken newToken = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);
                token = newToken;
                graphService = new DirectoryDataService(tenantName, token);
            }

            //  get tenant information
            //
            var tenant = graphService.tenantDetails;
            QueryOperationResponse<TenantDetail> responseTenantQuery;
            responseTenantQuery = tenant.Execute() as QueryOperationResponse<TenantDetail>;
            List<TenantDetail> tenantInfo = responseTenantQuery.ToList();
            ViewBag.OtherMessage = "User List from tenant: " + tenantInfo[0].displayName;


            return View(userList);
       }

在名為 Users.cshtmlViews/Home 資料夾下方建立新檢視,然後新增下列程式碼:

@model IEnumerable<Microsoft.WindowsAzure.ActiveDirectory.User> 
@{
    ViewBag.Title = "Users";
}

<h1>@ViewBag.Message</h1>
<h2>@ViewBag.OtherMessage</h2>
<table>
    <tr>
        <th>
            DisplayName
        </th>
        <th>
            UPN
        </th>
        <th></th>
    </tr>

@if (User.Identity.IsAuthenticated)
{

  foreach (var user in Model) {
    <tr>
        <td>
         @Html.DisplayFor(modelItem => user.displayName)    
        </td>
        <td>
         @Html.DisplayFor(modelItem => user.userPrincipalName)
        </td>
   </tr>
  }
}
</table>

Views/Shared 資料夾中,開啟 _Layout.cshtml 檔案。在檔案的 <header> 區段中,於 <nav> 元素中新增下列清單項目:"<li>@Html.ActionLink("Users", "Users", "Home")</li>"。然後儲存檔案。

               <nav>
                        <ul id="menu">
                            <li>@Html.ActionLink("Home", "Index", "Home")</li>
                            <li>@Html.ActionLink("About", "About", "Home")</li>
                            <li>@Html.ActionLink("Contact", "Contact", "Home")</li>
                            <li>@Html.ActionLink("Users", "Users", "Home")</li>
                        </ul>
                    </nav>

若要執行應用程式,請按 F5。出現提示時,使用 Azure AD 目錄中的使用者認證 (即在您目錄網域中具有組織帳戶的使用者) 進行登入。

單一登入經驗與前一個逐步解說中看到的相同,也需要使用 Azure AD 認證進行驗證。如果您已將應用程式發佈至網站,您應使用本逐步解說中的更新內容來更新應用程式。成功驗證使用者後,從右上方功能表中選取 [使用者] 索引標籤。

顯示使用者

應用程式會開始呼叫 Graph API 的程序:先向 Azure AD 驗證端點要求權杖。成功後,將在後續 Graph 呼叫中使用權杖,以取得租用戶的所有使用者。應用程式接著會顯示使用者清單,並顯示其 Display NamesUser Principal Names

Graph API 逐步解說應用程式的程式碼說明到此完成。下一節包含進階 Graph API 範例應用程式的更詳細資訊和連結,此範例應用程式會顯示其他讀取和寫入作業。

單一登入成功後,應用程式會向 Azure AD 驗證端點要求權杖,並使用租用戶名稱 (從已登入使用者的租用戶識別碼宣告取得)、ClientID 和密碼進行驗證。支援權杖取得之方法的詳細資料可在相同名稱檔案的 DirectoryDataServiceAuthorizationHelper 類別中找到。GetAuthorization 方法會提供租用戶名稱 (租用戶擁有的任何已驗證網域)、用戶端識別碼及密碼,藉以管理向 Azure AD 驗證取得 JSON Web Token (JWT) 權杖的程序。

成功的要求會傳回 JWT 權杖,以便用於對 Graph API 的呼叫中,該權杖會被插入至後續要求的授權標頭中。取得所有使用者的 Graph API 呼叫是 HTTP GET 要求,包含下列標頭:

Content-Type: application/json; odata=minimalmetadata
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

建議由應用程式快取 JWT 權杖以用於後續呼叫;範例應用程式中,在進行第二個 Graph API 呼叫前會先檢查 JWT 權杖是否過期。如果權杖已過期,則會取得新權杖。如果使用已過期權杖呼叫 Graph API,會傳回下列錯誤回應,且用戶端應要求新權杖。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="contoso.com", error="invalid_token", error_description="Your access token has expired. Please renew it before submitting the request.", 

note附註
目前提供可管理 Azure AD 驗證權杖取得之「Azure 驗證程式庫 (AAL)」的預覽版。AAL 釋出後,我們會將範例應用程式與文件更新為使用 AAL。AAL 預覽版的文件位在此處

其他 REST 呼叫 (包括讀取與寫入方法) 都可在透過此處下載的另一個 MVC4 範例應用程式中找到。

此範例應用程式示範的其他 REST 功能,包括:

  • 取得和設定使用者詳細資料,包括相片縮圖

  • 建立、更新群組

  • 更新群組成員資格

  • 用以處理大量傳回物件的分頁

社群新增項目

Microsoft 正展開一份線上問卷調查,了解您對於 MSDN 網站的看法。 如果您選擇參加,您離開 MSDN 網站時即會顯示線上問卷調查。

您是否想要參加?
顯示:
© 2014 Microsoft