适用于 web 服务的 OAuth 2.0 代理刷新令牌

开发 Web 服务时，可能需要使用 OAuth 2.0 代理 (OBO) 流获取令牌。 OBO 流适用于这样的用例：其中一个应用程序调用某个服务或 Web API，而后者又需要调用另一个服务或 Web API。 OBO 通过请求链传播委托用户权标识和权限。 当应用程序需要无限期地使用访问令牌和刷新令牌时（通常在脱机访问方案中）时，安全存储刷新令牌至关重要。

可能的用例

此解决方案使用 Azure Key Vault、Azure Functions 和 Azure DevOps 来安全地更新和存储 OBO 刷新令牌。

体系结构

下载此体系结构的 Visio 文件。

数据流

• Azure Key Vault 保存每个 Microsoft Entra ID 租户的机密加密密钥。
• Azure Functions 计时器触发的函数从 Key Vault 获取最新的密钥。 另一个 Azure Functions 函数从 Microsoft 标识平台检索刷新令牌，然后使用最新的密钥版本保存该令牌。
• 数据库存储最新的加密密钥和不透明数据。
• Azure DevOps 持续交付管道管理并同步机密轮换和令牌刷新过程。

如果已将管道用于基础结构即代码 (IaC) 或持续集成和交付 (CI/CD)，则 Azure Pipelines 是添加密钥轮换策略的方便位置。 无需使用 Azure Pipelines，只要限制用于设置和检索机密的路径即可。

应用以下策略以允许 Azure DevOps 服务连接的服务主体在Key Vault 中设置保密。 将 <Key Vault Name> 和 <Service Connection Principal> 变量替换为环境的正确值。

az keyvault set-policy --name $<Key Vault Name> --spn $<Service Connection Principal> --secret-permissions set

设置 Azure Pipelines 创建和更新密钥后，可以计划管道定期运行。 管道将更新 Key Vault 密钥以与密钥轮换同步，并使用新的机密版本保存加密令牌。 有关详细信息，请参阅配置管道的计划。

托管标识

Azure 服务（例如 Azure Functions）访问 Key Vault 的首选方法是使用服务的托管标识。 可以通过 Azure 门户、Azure CLI 或 Azure 资源管理器 (ARM) 模板为 IaC 方案授予访问权限。

Azure 门户

在 Azure 门户，添加 Key Vault 访问策略，以允许 Azure Functions 标识对象 ID 获取和设置机密。 有关详细信息，请参阅添加系统分配的标识和使用应用服务和 Azure Functions 的 Key Vault 引用。

Azure CLI

还可使用 Azure CLI 设置 Azure Key Vault 策略：

az keyvault set-policy --name $<Key Vault Name> --spn $<Service Connection Principal> --secret-permissions set
az keyvault set-policy --name $<Key Vault Name> --spn $<Managed Identity Principal> --secret-permissions get

ARM 模板

以下 ARM 模板授予 Azure Functions 对 Azure Key Vault 的访问权限。 将 *** 变量替换为环境的正确值。

{
  "type": "Microsoft.KeyVault/vaults",
  "apiVersion": "2019-09-01",
  "name": "***",
  "location": "***",
  "properties": {
    "sku": {
      "family": "A",
      "name": "standard"
    },
    "tenantId": "***",
    "enableSoftDelete": true,
    "enabledForDeployment": false,
    "enabledForTemplateDeployment": false,
    "enabledForDiskEncryption": false,
    "accessPolicies": [
      {
        "tenantId": "***",
        "objectId": "<Managed Identity Principal>",
        "permissions": {
          "secrets": [
            "get"
          ]
        }
      },
      {
        "tenantId": "***",
        "objectId": "<Service Connection Principal>",
        "permissions": {
          "secrets": [
            "set"
          ]
        }
      }
    ]
  }
}

令牌存储

可以使用任何数据库以加密形式存储令牌。 下图显示了在数据库中存储刷新令牌的序列：

序列有两个函数：userId() 和 secretId()。 可以将这些函数定义为 token.oid、 token.tid 和 token.sub 的某种组合。 有关详细信息，请参阅使用 id_token。

将加密密钥存储为机密后，可以在 Azure Key Vault 中查找密钥的最新版本。

令牌使用情况

使用密钥非常简单。 以下序列根据最新的密钥版本查询密钥。

令牌刷新与 DoWork 函数正交，因此 Azure Functions 使用 Durable Functions 异步执行 DoWork 和令牌刷新。 有关具有持久函数的 HTTP 触发函数的详细信息，请参阅 HTTP 功能。

不建议在 HTTP 请求管道中使用 Azure Key Vault，因此请尽可能缓存响应。 在示例中，Key Vault 对 getSecret(secretId, secretVersion) 调用的响应可缓存。

密钥轮换和令牌刷新

可以在刷新令牌的同时轮换密钥，以便使用最新版本的加密机密对最新令牌进行加密。 此进程使用内置 Azure Functions 计时器触发器支持。 有关详细信息，请参阅适用于 Azure Functions 的计时器触发器。

以下序列图演示了将令牌刷新与密钥轮换同步的过程：

用户和访问控制

Microsoft 标识平台提供在泄露时撤销刷新令牌的功能。 请参阅令牌撤销和 Revoke-AzureADUserAllRefreshToken。

若要从 Microsoft Entra ID 中删除用户，只需删除该用户的记录。 若要删除每个用户的应用程序访问权限，请删除用户数据的 refreshToken 部分。

若要删除一组用户（例如目标租户中的所有用户）的访问权限，可以使用 Azure Pipelines 基于 secretId() 删除组的机密。

作者

本文由 Microsoft 维护， 它最初是由以下贡献者撰写的。

首席作者：

• Jason Mostella | 高级软件工程师

后续步骤

• Microsoft 标识平台和 OAuth 2.0 代理流
• 如何使用应用服务和 Azure Functions 的托管标识
• 使用应用服务和 Azure Functions 的 Key Vault 引用
• 保护 Azure Functions