如何委派使用者註冊和產品訂閱

適用於：開發人員 | 基本 | 基本 v2 | 標準 | 標準 v2 | 進階 | 進階 v2

委派可讓您的網站擁有使用者資料，並為開發人員入口網站的使用者執行自訂驗證。 透過委派，您可以使用現有網站 （而不是開發人員入口網站的內建功能） 來處理開發人員登入和註冊 （以及相關的帳戶管理作業） 和產品訂閱。

委派開發人員登入和註冊

若要將開發人員、登入和註冊，以及開發人員帳戶管理作業委派給現有的網站，必須在您的網站上建立特別的委派端點。 此特殊委派可做為從 APIM 開發人員入口網站起始之任何登入/註冊相關要求的輸入點。

最終工作流程包含以下步驟：

1. 開發人員按一下 API 管理 開發人員入口網站上的登入或註冊連結或帳戶管理連結。
2. 瀏覽器會重新導向至委派端點。
3. 委派端點可向使用者顯示，或將使用者重新導向至登入/註冊或帳戶管理的 UI。
4. 作業完成後，系統會將使用者重新導向回他們離開 APIM 開發人員入口網站的位置。

設定 API 管理 以透過委派端點路由傳送要求

1. 在 Azure 入口網站中，移至您的 API 管理 實例。

2. 在側邊欄菜單中的 開發人員入口網站下，選擇 委派。

3. 勾選核取方塊以啟用委派。

4. 選取核取方塊以啟用委派登入和註冊。

   

5. 選擇特殊委派端點的 URL，然後在委 派服務端點 欄位中輸入它。

6. 在 委派金鑰中：

   • 產生 主要驗證金鑰 或 次要驗證金鑰 （或兩者），以供委派服務用來驗證來自 API 管理 的要求。 選取任一個按鈕旁的省略符號（...），然後選取「重生成」。
   • 選取任一索引鍵旁的省略符號 （...），然後選取 [複製]。 將金鑰複製到安全位置，並在設定委派服務時使用它們。

7. 選取 [儲存]。

建立您的委派端點

若要建立新的委派端點以在您的網站上實作，請遵循下列步驟：

1. 視作業而定，將會收到以下格式的要求：

   http://www.yourwebsite.com/apimdelegation?operation={operation}&returnUrl={來源頁面的 URL}&salt={string}&sig={string}

   -或-

   http://www.yourwebsite.com/apimdelegation?operation={operation}&userId={user ID of account}&salt={string}&sig={string}

   查詢參數：

   參數	描述
   operation	識別委派要求類型。 可用的作業包括：SignIn、SignUp、ChangePassword、ChangeProfile、CloseAccount、SignOut。
   returnUrl	在 SignIn 或 SignUp 作業中，使用者按一下登入或註冊連結後所出現的 URL。
   userId	在 ChangePassword、ChangeProfile、CloseAccount 以及 SignOut 作業中，想管理的帳戶使用者識別碼。
   鹽	特殊 salt 字串，用來計算安全性雜湊。
   sig	已計算的安全性雜湊，用來和您已計算的雜湊，進行比較。

2. 驗證來自 Azure API 管理的要求 (具選擇性，但基於安全性理由，強烈建議這麼做)。

   • 根據 returnUrl (或 UserId) 以及 salt 查詢參數，計算字串 HMAC-SHA512 的雜湊。 如需範例，請查看範例程式碼。

     針對 SignIn 和 SignUp：

     HMAC(salt + '\n' + returnUrl)
     

     針對 ChangePassword、ChangeProfile、CloseAccount 和 SignOut：

     HMAC(salt + '\n' + userId)
     

   • 比較以上計算的雜湊和 sig 查詢參數的值。 如果兩個雜湊相符，則繼續下一步。 否則，拒絕要求。

3. 驗證是否收到登入/註冊或帳戶管理作業的要求。

4. 向使用者顯示用於登入/註冊或帳戶管理作業的 UI。

5. 在您的網站完成作業後，請在 APIM 管理使用者。 例如，如果使用者註冊，請在 APIM 建立對應的帳戶。

   • 使用 API Management REST API 建立使用者。
   • 將使用者識別碼設定為使用者存放區中的相同值，或能輕鬆追蹤的新識別碼。

6. 完成登入或註冊，且成功驗證使用者之後：

   • 透過 API 管理 REST API要求共用存取權杖。

   • 將 returnUrl 查詢參數附加至您從上述 API 呼叫接收的 SSO URL。 例如：

     https://contoso.developer.azure-api.net/signin-sso?token=<URL-encoded token>&returnUrl=%2Freturn%2Furl

   • 將使用者重新導向至以上已產生的 URL。

委派產品訂閱

委派產品訂閱的作法，類似於委派使用者登入/註冊。 最終工作流程包含以下步驟：

1. 開發人員會在 API 管理 開發人員入口網站中選取產品，然後選取 [ 訂閱 ] 按鈕。
2. 瀏覽器會重新導向至委派端點。
3. 委派端點會執行 (您所設計) 必要的產品訂閱步驟。 這些步驟可能包括：
   • 重新導向至另一個頁面，來要求帳單資訊。
   • 提出進一步的問題。
   • 儲存資訊，且不需要任何使用者動作。

啟用 API 管理功能

在委派頁面上，選取核取方塊以啟用委派功能，然後啟用委派產品訂閱。

建立您的委派端點

若要為您的網站建立新的委派端點，請遵循下列步驟：

1. 視作業而定，將會收到以下格式的要求：

   http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={要訂閱的產品}&userId={提出請求的用戶}&salt={string}&sig={string}

   -或-

   http://www.yourwebsite.com/apimdelegation?operation={operation}&subscriptionId={要管理的訂閱}&salt={字串}&sig={字串}

   查詢參數：

   參數	描述
   operation	識別委派要求類型。 有效的產品訂閱請求選項包括： 訂閱：為使用者訂閱具有已提供識別碼的 (請參閱下面) 指定產品要求。 取消訂閱：為使用者取消訂閱產品的要求
   productId	在 [訂閱] 上，使用者要求訂閱的產品識別碼。
   userId	在 [訂閱] 上，要求使用者的識別碼。
   subscriptionId	在 [取消訂閱] 作業中的產品訂閱識別碼。
   鹽	特殊 salt 字串，用來計算安全性雜湊。
   sig	已計算的安全性雜湊，用來和您已計算的雜湊，進行比較。

2. 確認要求來自 Azure API 管理 （選擇性，但強烈建議安全性） 。

   • 根據 productId、userId (或 subscriptionId) 和 salt 查詢字串，計算字串的 HMAC-SHA512：

     針對 [訂閱]：

     HMAC(salt + '\n' + productId + '\n' + userId)
     

     針對 [取消訂閱]：

     HMAC(salt + '\n' + subscriptionId)
     

   • 比較以上計算的雜湊和 sig 查詢參數的值。 如果兩個雜湊相符，請移至下一個步驟。 否則，拒絕要求。

3. 依據 operation 中要求的作業類型 (例如：帳單、進一步的問題等)，處理任何產品訂閱流程。

4. 在您的網站完成作業後，請在 APIM 管理訂閱。 例如，呼叫適用於訂閱的 REST API，讓使用者訂閱 APIM 產品。

程式碼範例

這些程式碼範例示範了如何在委派使用者登入或註冊時，產生 returnUrl 查詢參數的雜湊。 returnUrl 是使用者按一下登入或註冊連結後所出現頁面的 URL。

• 取得您在 Azure 入口網站 的 [委派] 畫面中設定的委派驗證金鑰。
• 建立 HMAC，以驗證簽章並證明傳遞 returnUrl的有效性。

相同的程式碼經過些微修改後，可用於計算其他雜湊，例如委派產品訂閱時的 productId 與 userId。

產生 returnUrl 雜湊的 C# 程式碼

using System.Security.Cryptography;

string key = "delegation validation key";
string returnUrl = "returnUrl query parameter";
string salt = "salt query parameter";
string signature;
using (var encoder = new HMACSHA512(Convert.FromBase64String(key)))
{
    signature = Convert.ToBase64String(encoder.ComputeHash(Encoding.UTF8.GetBytes(salt + "\n" + returnUrl)));
    // change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
    // compare signature to sig query parameter
}

產生 returnUrl 雜凑的 Node.js 程式碼

var crypto = require('crypto');

var key = 'delegation validation key'; 
var returnUrl = 'returnUrl query parameter';
var salt = 'salt query parameter';

var hmac = crypto.createHmac('sha512', new Buffer(key, 'base64'));
var digest = hmac.update(salt + '\n' + returnUrl).digest();
// change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
// compare signature to sig query parameter

var signature = digest.toString('base64');

相關內容

• 深入瞭解開發人員入口網站
• 使用 Microsoft Entra ID 或 Microsoft Entra 外部識別碼進行驗證
• 更多開發人員入口網站問題？ 在我們的常見問題集中尋找解答。