共用方式為


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

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

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

委派開發人員登入和註冊

若要將開發人員、登入和註冊,以及開發人員帳戶管理作業委派給現有的網站,必須在您的網站上建立特別的委派端點。 此特殊委派可做為從 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 識別委派要求類型。 可用的作業包括:SignInSignUpChangePasswordChangeProfileCloseAccountSignOut
    returnUrl SignInSignUp 作業中,使用者按一下登入或註冊連結後所出現的 URL。
    userId ChangePasswordChangeProfileCloseAccount 以及 SignOut 作業中,想管理的帳戶使用者識別碼。
    salt 特殊 salt 字串,用來計算安全性雜湊。
    sig 已計算的安全性雜湊,用來和您已計算的雜湊,進行比較。
  2. 驗證來自 Azure API 管理的要求 (具選擇性,但基於安全性理由,強烈建議這麼做)。

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

      針對 SignInSignUp

      HMAC(salt + '\n' + returnUrl)
      

      針對 ChangePasswordChangeProfileCloseAccountSignOut

      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 管理 (選擇性,但基於安全性理由,強烈建議這麼做)

    • 根據 productIduserId (或 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 為有效的驗證。

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

產生 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');

重要

您必須重新發佈開發人員入口網站,委派變更才會生效。

下一步