通过

如何委派用户注册和产品订阅

  • 项目

适用于：开发人员 | 基本 | 基本 v2 | 标准 | 标准 v2 | 高级

委派让网站可以拥有用户数据，并执行自定义验证。 通过委派，可以使用现有网站（而不是开发人员门户的内置功能）处理开发人员登录/注册（以及相关帐户管理操作）和产品订阅。

委派开发人员登录和注册

要将开发人员登录和注册以及开发人员帐户管理选项委派给现有网站，请在站点上创建一个特殊的委派终结点。 此特殊委派会充当从 API 管理开发人员门户发起的任何登录/注册和相关请求的入口点。

最终工作流将是：

  1. 开发人员可单击 API 管理开发人员门户中的登录或注册链接，或帐户管理链接。
  2. 浏览器重定向到委派终结点。
  3. 然后，委派终结点会将用户重定向到或向其显示登录/注册或帐户管理 UI。
  4. 操作完成后，系统会将用户重定向回 API 管理开发人员门户中上次离开的位置。

设置 API 管理通过委派终结点路由请求

  1. 在 Azure 门户，导航到 API 管理实例。

  2. 在左侧菜单中的“开发人员门户”下，选择“委派”。

  3. 单击复选框以启用“委派登录和注册”。

    屏幕截图显示了门户中登录与注册的委派。

  4. 确定特殊委派终结点的 URL，将其输入“委派终结点 URL”字段中。

  5. 在“委派验证密钥”字段中，执行以下任一项：

    • 输入一个用于计算所提供签名的机密，以验证请求是否来自 API 管理。
    • 单击“生成”按钮让 API 管理为你生成一个随机密钥。

  6. 单击“保存”。

创建委派终结点

创建新的委派终结点以在站点上实现的推荐步骤：

  1. 根据操作，将会收到以下格式的请求：

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

    查询参数：

    参数 说明
    operation 标识委派请求类型。 可用操作：SignIn、SignUp、ChangePassword、ChangeProfile、CloseAccount 和 SignOut。
    returnUrl 在 SignIn 或 SignUp 时，提供用户单击了登录或注册链接的 URL。
    userId 在 ChangePassword、ChangeProfile、CloseAccount 和 SignOut 时，提供希望管理的帐户的用户 ID。
    加密盐 用于计算安全哈希的特殊加密盐字符串。
    信号 计算的安全哈希，用于与用户自行计算的哈希进行比较。

  2. 验证请求是否来自 Azure API 管理（可选，但强烈推荐执行以确保安全）。

    • 根据 returnUrl（或 UserId）和加盐查询参数计算字符串的 HMAC-SHA512 哈希。 例如，查看示例代码。

      对于 SignIn 和 SignUp：

      HMAC(salt + '\n' + returnUrl)

      对于 ChangePassword、ChangeProfile、CloseAccount 和 SignOut：

      HMAC(salt + '\n' + userId)

    • 将上面计算的哈希与 sig 查询参数的值进行比较。 如果两个哈希匹配，则继续进行下一步。 否则，拒绝请求。

  3. 验证是否收到登录/注册或帐户管理操作请求。

  4. 向用户显示登录/注册或帐户管理 UI。

  5. 在你这一端完成操作后，可在 API 管理中管理用户。 例如，如果用户注册，则在 API 管理中为用户创建相应的帐户。

    • 请使用 API 管理 REST API 创建用户。
    • 将用户 ID 设置为用户存储中的相同值或一个新的易于跟踪的 ID。

  6. 登录或注册后，如果用户已成功进行身份验证，则：

    • 通过 API 管理 REST API 请求共享访问令牌。

    • 将 returnUrl 查询参数追加到从上述 API 调用接收的 SSO URL。 例如：

      https://contoso.developer.azure-api.cn/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}

    查询参数：

    参数 说明
    operation 标识委派请求类型。 有效的产品订阅请求选项包括：
    • Subscribe：请求为用户订阅具有所提供的 ID 的给定产品（见下）。
    • Unsubscribe：请求为用户取消某个产品的订阅
    productId 在“订阅”中，用户请求订阅的产品 ID。
    userId Subscribe 上发出请求的用户的 ID。
    subscriptionId 在 取消订阅上的产品订阅 ID。
    加密盐 用于计算安全哈希的特殊加密盐字符串。
    信号 计算的安全哈希，用于与用户自行计算的哈希进行比较。

  2. 验证请求是否来自 Azure API 管理（可选，但强烈推荐执行以确保安全）

    • 根据 productId、userId（或 subscriptionId）和 salt 查询参数计算字符串的 HMAC-SHA512：

      对于订阅：

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

      对于“取消订阅”：

      HMAC(salt + '\n' + subscriptionId)

    • 将上面计算的哈希与 sig 查询参数的值进行比较。 如果两个哈希匹配，则继续进行下一步。 否则，拒绝请求。

  3. 根据在 operation 中请求的操作类型（例如账单、更多问题等等）处理产品订阅。

  4. 在你这一端完成操作后，可在 API 管理中管理订阅。 例如，可通过为订阅调用 REST API 为用户订阅 API 管理产品。

示例代码

这些代码示例演示了如何在委派用户登录或注册时生成 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');

重要

需要重新发布开发人员门户才能使委派更改生效。

后续步骤