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

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

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

委派開發人員登入和註冊

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

最終工作流程如下：

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

透過委派端點來設定 API 管理至路由要求

1. 在 Azure 入口網站，在您的 API 管理資源中搜尋開發人員入口網站。

2. 按一下 [委派] 項目。

3. 按一下核取方塊以啟用 [委派登入與註冊]。

   

4. 決定特別委派端點的 URL，並在該 [Delegation endpoint URL] 欄位中輸入。

5. 在 [委派驗證金鑰] 欄位中：

   • 輸入用來計算簽章的秘密，來驗證源自 API 管理的要求。
   • 按一下 API 管理的 [產生] 按鈕，來為您產生隨機金鑰。

6. 按一下 [檔案] 。

建立您的委派端點

在您的網站上實作建立新的委派端點的建議步驟：

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

   http://www.yourwebsite.com/apimdelegation?operation={operation}&returnUrl={URL of source page}&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	特殊 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={product to subscribe to}&userId={user making request}&salt={string}&sig={string}

   - 或者 -

   http://www.yourwebsite.com/apimdelegation?operation={operation}&subscriptionId={subscription to manage}&salt={string}&sig={string}

   查詢參數：

   參數	描述
   operation	識別委派要求類型。 有效的產品訂閱要求選項包含： 訂閱：為使用者訂閱具有已提供識別碼的 (請參閱下面) 指定產品要求。 取消訂閱：為使用者取消訂閱產品的要求
   productId	在 [訂閱] 上，使用者要求訂閱的產品識別碼。
   userId	在 [訂閱] 上，要求使用者的識別碼。
   subscriptionId	在 [取消訂閱] 作業中的產品訂閱識別碼。
   salt	特殊 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 雜湊的 NodeJS 程式碼

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 或 Azure AD B2C 進行驗證。
• 更多開發人員入口網站問題？ 在我們的常見問題集中尋找解答。