共用方式為

案例：呼叫 Web API 的 Web API (代理者案例)

瞭解如何建置可代表使用者呼叫另一個 Web API 的 Web API。

閱讀本文之前，您應該先熟悉 AD FS 概念和代理者流程

概觀

  • 用戶端 (Web 應用程式) - 未呈現在下圖中 - 呼叫受保護 Web API，並在其 "Authorization" Http 標頭中提供 JWT 持有人權杖。

  • 受保護 Web API 會驗證權杖，並使用 MSAL AcquireTokenOnBehalfOf 方法來要求另一個權杖 (來自 AD FS)，讓它本身可以代表使用者來呼叫第二個 Web API (名為下游 Web API)。

  • 受保護 Web API 會使用此權杖來呼叫下游 API。 它也可以呼叫 AcquireTokenSilentlater 來要求其他下游 API 的權杖 (但仍然代表相同的使用者)。 AcquireTokenSilent 會視需要重新整理權杖。

    概觀

若要進一步了解如何在 AD FS 中設定代理者驗證案例，請使用此處提供的範例，並逐步進行應用程式註冊和程式碼設定步驟。

必要條件

  • GitHub 用戶端工具
  • 已設定且正在執行的 AD FS 2019 或更新版本
  • Visual Studio 2013 或更新版本

AD FS 中的應用程式註冊

本節顯示如何在 AD FS 中將原生應用程式註冊為公用用戶端以及將 Web API 註冊為信賴憑證者 (RP)

  1. 在 [AD FS 管理] 中，以滑鼠右鍵按一下 [應用程式群組]，然後選取 [新增應用程式群組]。

  2. 在 [應用程式群組精靈] 上，針對 [名稱] 輸入 [WebApiToWebApi]，然後在 [用戶端伺服器應用程式] 下方選取 [存取 Web API 的原生應用程式] 範本。 按一下 [下一步] 。

    [新增應用程式群組精靈] 的 [歡迎] 頁面螢幕快照，其中顯示已醒目提示存取 Web API 範本的原生應用程式。

  3. 複製 [用戶端識別碼] 值。 稍後會在應用程式的 App.config 檔案中，將其用作 ClientId 的值。 針對 [重新導向 URI:]，輸入下列內容 - https://ToDoListClient. 按一下新增。 按一下 [下一步] 。

    [新增應用程式群組精靈] 的 [原生應用程式] 頁面螢幕快照，其中顯示重新導向 U R I 。

  4. 在 [設定 Web API] 畫面上，輸入 [識別碼:]https://localhost:44321/. 按一下新增。 按一下 [下一步] 。 稍後將會在應用程式的 App.config 和 Web.config 檔案中使用此值。

    [新增應用程式群組精靈] 之 [設定 Web API] 頁面的螢幕快照，其中顯示正確的標識符。

  5. 在 [套用存取控制原則] 畫面上，選取 [允許所有人]，然後按 [下一步]。

    [新增應用程式群組精靈] 的 [選擇 存取控制 原則] 頁面的螢幕快照，其中已醒目提示 [允許所有人] 選項。

  6. 在 [設定應用程式權限] 畫面上，選取 [openid] 和 [user_impersonation]。 按一下 [下一步] 。

    [新增應用程式群組精靈] 的 [設定應用程式許可權] 頁面的螢幕快照，其中顯示已選取開啟的標識符。

  7. 在 [摘要] 畫面上，按 [下一步]。

  8. 在 [完成] 畫面上，按一下 [關閉]。

  9. 在 [AD FS 管理] 中，按一下 [應用程式群組]，然後選取 [WebApiToWebApi] 應用程式群組。 按一下滑鼠右鍵並選取 [內容]。

    [A D F S 管理] 對話框的螢幕快照，其中顯示醒目提示的 WebApiToWebApi 群組，以及下拉式清單中的 [屬性] 選項。

  10. 在 [WebApiToWebApi 內容] 畫面上，按一下 [新增應用程式…]。

    [WebApiToWebApi 屬性] 對話框的螢幕快照，其中顯示列出的 WebApiToWebApi - Web A P I 應用程式。

  11. 在 [獨立應用程式] 下方，選取 [伺服器應用程式]。

    [將新應用程式新增至 WebApiToWebApi 精靈] 的 [歡迎] 頁面螢幕快照，其中已醒目提示 [伺服器應用程式] 選項。

  12. 在 [伺服器應用程式] 畫面上，將 https://localhost:44321/ 新增為 [用戶端識別碼] 和 [重新導向 URI]。

    [將新應用程式新增至 WebApiToWebApi 精靈] 的 [伺服器應用程式] 頁面螢幕快照，其中顯示正確的用戶端識別符，並重新導向 U R I。

  13. 在 [設定應用程式認證] 畫面上，選取 [產生共用秘密]。 複製秘密以供稍後使用。

    [將新應用程式新增至 WebApiToWebApi 精靈] 的 [設定應用程式認證] 應用程式頁面的螢幕快照，其中顯示已選取 [產生共用密碼] 選項，並醒目提示產生的共享密碼。

  14. 在 [摘要] 畫面上，按 [下一步]。

  15. 在 [完成] 畫面上，按一下 [關閉]。

  16. 在 [AD FS 管理] 中，按一下 [應用程式群組]，然後選取 [WebApiToWebApi] 應用程式群組。 按一下滑鼠右鍵並選取 [內容]。

    [A D F S 管理] 對話框的第二個螢幕快照，其中顯示醒目提示的WebApiToWebApi 群組，以及下拉式清單中的 [屬性] 選項。

  17. 在 [WebApiToWebApi 內容] 畫面上，按一下 [新增應用程式…]。

    [WebApiToWebApi 屬性] 對話框的第二個螢幕快照，其中顯示列出的 WebApiToWebApi - Web A P I 應用程式。

  18. 在 [獨立應用程式] 下方，選取 [Web API]。

    [將新的應用程式新增至 WebApiToWebApi 精靈] 的螢幕快照，其中已醒目提示 Web A P I 選項。

  19. 在 [設定 Web API] 上，將 https://localhost:44300 新增為 [識別碼]。

    [將新應用程式新增至 WebApiToWebApi 精靈] 之 [設定 Web A P I] 頁面的螢幕快照，其中顯示正確的重新導向 U R I。

  20. 在 [套用存取控制原則] 畫面上，選取 [允許所有人]，然後按 [下一步]。

    [將新應用程式新增至 WebApiToWebApi 精靈] 的 [選擇 存取控制 原則] 頁面的螢幕快照，其中已醒目提示 [允許所有人] 選項。

  21. 在 [設定應用程式權限] 畫面上，按 [下一步]。

    [將新應用程式新增至 WebApiToWebApi 精靈] 的 [設定應用程式許可權] 頁面的螢幕快照，其中已指出 [下一步] 選項。

  22. 在 [摘要] 畫面上，按 [下一步]。

  23. 在 [完成] 畫面上，按一下 [關閉]。

  24. 在 [WebApiToWebApi – Web API 2 內容] 畫面上，按一下 [確定]

  25. 在 [WebApiToWebApi 內容] 畫面上，選取 [WebApiToWebApi – Web API]，然後按一下 [編輯...]。

    [WebApiToWebApi 屬性] 對話框的螢幕快照，其中顯示醒目提示的 WebApiToWebApi - Web A P I 應用程式。

  26. 在 [WebApiToWebApi – Web API 屬性] 畫面上，選取 [發行轉換規則] 索引標籤，然後按一下 [新增規則...]。

    顯示 [發行轉換規則] 索引卷標的 [WebApiToWebApi - Web A P I 屬性] 對話框的螢幕快照。

  27. 在 [新增轉換宣告規則精靈] 上，從下拉式清單中選取 [使用自訂規則傳送宣告]，然後按 [下一步]。

    [新增轉換宣告規則精靈] 之 [選取規則範本] 頁面的螢幕快照，其中顯示已選取 [使用自定義規則傳送宣告] 選項。

  28. 在 [宣告規則名稱:] 欄位中輸入 PassAllClaims，並在 [自訂規則:] 欄位中輸入 [x:[] => issue(claim=x);] 宣告規則，然後按一下 [完成]。

    [新增轉換宣告規則精靈] 的 [設定規則] 頁面螢幕快照，其中顯示上述設定。

  29. 在 [WebApiToWebApi – Web API 內容] 畫面上，按一下 [確定]

  30. 在 [WebApiToWebApi 內容] 畫面上，選取 [WebApiToWebApi – Web API 2]，然後按一下 [編輯...]
    [WebApiToWebApi 屬性] 對話框的螢幕快照，其中顯示醒目提示的 WebApiToWebApi - Web A P I 2 應用程式。

  31. 在 [WebApiToWebApi – Web API 2 內容] 畫面上，選取 [發行轉換規則] 索引標籤，然後按一下 [新增規則...]

  32. 在 [新增轉換宣告規則精靈] 上，從下拉式清單中選取 [使用自訂規則傳送宣告]，然後按 [下一步] [新增轉換宣告規則精靈] 的 [選取規則範本] 頁面的第二個螢幕快照，其中顯示已選取 [使用自定義規則傳送宣告] 選項。

  33. 在 [宣告規則名稱:] 欄位中輸入 PassAllClaims，並在 [自訂規則:] 欄位中輸入 [x:[] => issue(claim=x);] 宣告規則，然後按一下 [完成]。

    [新增轉換宣告規則精靈] 之 [設定規則] 頁面的第二個螢幕快照，其中顯示上述設定。

  34. 依序在 [WebApiToWebApi – Web API 2 內容] 畫面和 [WebApiToWebApi 內容] 畫面上，按一下 [確定]。

程式碼設定

本節顯示如何設定 Web API 來呼叫另一個 Web API

  1. 從此處下載範例

  2. 使用 Visual Studio 來開啟範例

  3. 開啟 App.config 檔案。 修改下列項目：

    • ida:Authority - 輸入 https://[your AD FS hostname]/adfs/

    • ida:ClientId - 在上述 [AD FS 中的應用程式註冊] 區段中輸入來自 #3 的值。

    • ida:RedirectUri - 在上述 [AD FS 中的應用程式註冊] 區段中輸入來自 #3 的值。

    • todo:TodoListResourceId – 在上述 [AD FS 中的應用程式註冊] 區段中輸入來自 #4 的「識別碼」值

    • ida: todo:TodoListBaseAddress - 在上述 [AD FS 中的應用程式註冊] 區段中輸入來自 #4 的「識別碼」值。

      應用程式組態檔的螢幕快照，其中顯示已修改的值。

  4. 在 ToDoListService 下方，開啟 Web.config 檔案。 修改下列項目：

    • ida:Audience - 在上述 [AD FS 中的應用程式註冊] 區段中輸入來自 #12 的「用戶端識別碼」值

    • ida:ClientId - 在上述 [AD FS 中的應用程式註冊] 區段中輸入來自 #12 的「用戶端識別碼」值。

    • Ida: ClientSecret - 在上述 [AD FS 中的應用程式註冊] 區段中輸入從 #13 所複製的共用秘密。

    • ida:RedirectUri - 在上述 [AD FS 中的應用程式註冊] 區段中輸入來自 #12 的 RedirectUri 值。

    • ida: AdfsMetadataEndpoint - 輸入 https://[your AD FS hostname]/federationmetadata/2007-06/federationmetadata.xml

    • ida:OBOWebAPIBase - 在上述 [AD FS 中的應用程式註冊] 區段中輸入來自 #19 的「識別碼」值。

    • ida:Authority - 輸入 https://[your AD FS hostname]/adfs

      ToDoListService 下 Web 組態檔的螢幕快照，其中顯示已修改的值。

  5. 在 WebAPIOBO 下方，開啟 Web.config 檔案。 修改下列項目：

    • ida: AdfsMetadataEndpoint - 輸入 https://[your AD FS hostname]/federationmetadata/2007-06/federationmetadata.xml

    • ida:Audience - 在上述 [AD FS 中的應用程式註冊] 區段中輸入來自 #12 的「用戶端識別碼」值

      WebAPIOBO 底下 Web 組態檔的螢幕快照，其中顯示已修改的值。

測試範例

本節顯示如何測試上面所設定的範例。

變更程式碼之後，請重新建置解決方案

  1. 在 Visual Studio 上，以滑鼠右鍵按一下解決方案，然後選取 [設定啟動專案...]

    當您以滑鼠右鍵按兩下方案，並醒目提示 [設定啟始專案] 選項時所顯示清單的螢幕快照。

  2. 在 [內容] 頁面上，確定已針對每個專案 (TodoListSPA 除外) 將 [動作] 設定為 [開始]。

    [方案屬性頁] 對話框的螢幕快照，其中顯示已選取 [多個啟動專案] 選項，並將所有項目的動作設定為 [開始]。

  3. 在 Visual Studio 頂端，按一下綠色箭號。

    Visual Studio UI 的螢幕快照，其中已指出 [開始] 選項。

  4. 在原生應用程式的 [主要] 畫面上，按一下 [登入]。

    [待辦事項 列表用戶端] 對話框的螢幕快照。

    如果您看不到原生應用程式畫面，則請從系統上專案存放庫儲存所在的資料夾搜尋和移除 *msalcache.bin 檔案。

  5. 系統會將您重新導向至 AD FS 登入頁面。 繼續並登入。

    [登入] 頁面的螢幕快照。

  6. 登入之後，請在 [建立待辦事項] 中輸入文字 [Web Api 對 Web Api 呼叫]。 按一下 [新增項目]。 這將會呼叫可接著呼叫 Web API 2 (WebAPIOBO) 的 Web API (待辦事項服務)，並在快取中新增項目。

    [待辦事項 列表用戶端] 對話框的螢幕快照，其中新增了要填入 [待辦事項 專案] 區段的專案。

後續步驟

AD FS OpenID Connect/OAuth 流程和應用程式案例