Microsoft 标识平台中的签名密钥滚动更新
本文介绍了你需要了解的有关 Microsoft 标识平台用来为安全令牌签名的公钥的信息。 请务必注意,这些密钥会定期滚动更新,并且在紧急情况下可立即滚动更新。 所有使用 Microsoft 标识平台的应用程序都应该能以编程方式处理密钥滚动更新过程。 你将了解密钥的工作原理,如何评估滚动更新对应用程序的影响。 你还将了解如何更新应用程序或建立定期手动滚动更新过程,以在必要时处理密钥滚动更新。
Microsoft 标识平台中签名密钥的概述
Microsoft 标识平台使用基于行业标准构建的公钥加密,在它自己和使用它的应用程序之间建立信任关系。 实际上,它的工作原理如下所述:Microsoft 标识平台使用签名密钥,该密钥由公钥和私钥对组成。 当用户登录到使用 Microsoft 标识平台进行身份验证的应用程序时,Microsoft 标识平台会创建一个包含用户相关信息的安全令牌。 此令牌由Microsoft 标识平台在其私钥发送回应用程序之前进行签名。 若要验证该令牌是否有效且来自 Microsoft 标识平台,应用程序必须使用由 Microsoft 标识平台公开的公钥(包含在租户的 OpenID Connect 发现文档或 SAML/WS-Fed 联合元数据文档中)来验证令牌的签名。
出于安全考虑,Microsoft 标识平台的签名密钥会定期更新,且紧急情况下,可立即滚动更新。 这些密钥滚动更新之间没有设置或保证的时间。 与Microsoft 标识平台集成的任何应用程序都应准备好处理密钥滚动更新事件,无论其发生频率如何。 如果应用程序不处理突然刷新,并且尝试使用过期的密钥验证令牌上的签名,则应用程序将错误地拒绝令牌。 建议使用 标准库 来确保密钥元数据正确刷新并保持最新状态。 如果未使用标准库,请确保实现遵循 最佳做法 部分。
OpenID Connect 发现文档和联合元数据文档中始终提供多个有效密钥。 应用程序应该做好使用文档中指定的任何以及所有密钥的准备,因为一个密钥可能很快会滚动更新,另一个密钥可能就会取而代之,依此类推。 由于我们支持新平台、新云或新的身份验证协议,目前的密钥数量随时间的推移,可能会根据 Microsoft 标识平台的内部体系结构发生变化。 JSON 响应中的键顺序和公开密钥的顺序都不应被视为对应用程序有意义的顺序。
仅支持单个签名密钥的应用程序或需要手动更新签名密钥的应用程序本质上不太安全且不太可靠。 应将它们更新为使用标准库,以确保它们始终使用最新的签名密钥,这是应采取的最佳做法之一。
密钥元数据缓存和验证的最佳做法
- 使用特定于租户的终结点发现密钥,如 OpenID Connect (OIDC) 和联合元数据中所述
- 即使应用程序跨多个租户部署,也建议始终独立发现和缓存应用程序服务的每个租户的密钥(使用特定于租户的终结点)。 目前在租户之间通用的密钥将来可能会变得不同。
- 使用以下缓存算法确保缓存具有复原能力和安全性
密钥元数据缓存算法:
我们的 标准库 实现密钥的复原和安全缓存。 建议使用它们来避免实现中的细微缺陷。 对于自定义实现,下面是粗略算法:
一般注意事项:
- 验证令牌的服务应具有能够存储许多不同密钥(10-1000)的缓存。
- 应将密钥 ID(OIDC 密钥元数据规范中的“kid”)单独缓存为缓存密钥。
- 缓存中密钥的生存时间应配置为 24 小时,每小时刷新一次。 这可确保系统能够快速响应正在删除的密钥,但有足够的缓存持续时间,不受提取密钥问题的影响。
- 应刷新密钥:
- 进程启动时或缓存为空时
- 定期(建议每 1 小时)作为后台作业
- 如果收到的令牌是使用未知密钥签名的(标头中未知的子项或潮汐)动态
KeyRefresh 过程(IdentityModel 的概念算法)
初始化
配置管理器是使用特定地址设置的,用于提取配置数据和必要的接口来检索和验证此数据。
配置检查
在提取新数据之前,系统首先根据预定义的刷新间隔检查现有数据是否仍然有效。
数据检索 如果数据已过时或缺失,系统会锁定以确保只有一个线程提取新数据以避免重复(和线程耗尽)。 然后,系统会尝试从指定的终结点检索最新的配置数据。
验证
检索新数据后,会对其进行验证,以确保它满足所需的标准且未损坏。 仅当使用新密钥成功验证传入请求时,才会接受元数据。
错误处理
如果在数据检索期间发生任何错误,则会记录这些错误。 如果无法提取新数据,系统将继续使用最后一个已知良好的配置运行
自动更新系统会根据刷新间隔定期检查和更新配置数据(建议使用抖动为 12 小时或减 1 小时)。 如果需要,它还可以手动请求更新,确保数据始终是最新的。
使用新密钥 验证令牌(如果令牌到达时未从配置中已知)的签名密钥,系统会尝试在热路径上使用同步调用提取配置,以在常规预期更新之外处理元数据中的新密钥(但不超过 5 分钟)
此方法可确保系统始终使用最新的和有效的配置数据,同时妥善处理错误并避免冗余操作。
此算法的 .NET 实现可从 BaseConfigurationManager 获取。 可能会根据复原能力和安全评估进行更改。 另请参阅此处的说明
KeyRefresh 过程(伪代码):
此过程使用全局(lastSuccessfulRefreshTime 时间戳)来防止刷新键过于频繁的条件。
if (lastSuccessfulRefreshTime is set and more recent than 5 minutes ago)
return // without refreshing
// Load keys URL using the, see OpenID Connect (OIDC)
// Fetch the list of keys from the tenant-specific keys URL discovered above
foreach(key in the list) {
if (key id (kid) exists in cache) // cache[tid][kid]
set TTL = now + 24 h
else
add key to the cache with TTL = now + 24 h
}
set lastSuccessfulRefreshTime to now (current timestamp)
服务启动过程:
- 用于更新密钥的 KeyRefresh
- 启动每小时调用 KeyRefresh 的后台作业
用于验证密钥的 TokenValidation 过程(伪代码):
Get token from input request (input token)
Get key id from input token (**kid** / **tid** header claim for JWT)
if (key id is found in cache) { // cache[tid][kid]
validate token according to the key and return
}
else (key is not found cache) {
Call KeyRefresh to opportunistically refresh the cache
if (key id is found in cache) {
validate token according to the key and return
}
else
return token validation failure
}
如何评估应用程序是否会受到影响以及如何应对
应用程序如何处理密钥滚动更新取决于各种变量,例如应用程序类型或所使用的标识协议和库。 以下部分评估了最常见类型的应用程序是否受密钥滚动更新的影响,并提供有关如何更新应用程序以支持自动滚动更新或手动更新密钥的指南。
- 访问资源的本机客户端应用程序
- 访问资源的 Web 应用程序/API
- 保护资源的和使用 Azure 应用服务构建的 Web 应用程序/API
- 使用 ASP.NET OWIN OpenID Connect、WS-Fed 或 WindowsAzureActiveDirectoryBearerAuthentication 中间件保护资源的 Web 应用程序/API
- 使用 ASP.NET Core OpenID Connect 或 JwtBearerAuthentication 中间件保护资源的 Web 应用程序/API
- 使用 Node.js
passport-azure-ad
模板保护资源的 Web 应用程序/API - 保护资源的和使用 Visual Studio 2015 或更高版本创建的 Web 应用程序/API
- 保护资源的和使用 Visual Studio 2013 创建的 Web 应用程序
- 保护资源的和使用 Visual Studio 2013 创建的 Web API
- 保护资源的和使用 Visual Studio 2012 创建的 Web 应用程序
- 使用任何其他库保护资源或手动实现任何受支持协议的 Web 应用程序/API
本指南不适用于:
- 从 Microsoft Entra 应用程序库(包括自定义)添加的应用程序具有单独的签名密钥指导。 详细信息。
- 通过应用程序代理发布的本地应用程序无需担心签名密钥。
访问资源的本机客户端应用程序
只访问资源的应用程序(例如,Microsoft Graph、KeyVault、Outlook API 和其他 Microsoft API)将仅获取一个令牌并将其传递给资源所有者。 鉴于它们不保护任何资源且不检查令牌,因此无需确保为其正确签名。
本机客户端应用程序(不管是桌面还是移动应用程序)都属于此类别,因此不受滚动更新的影响。
访问资源的 Web 应用程序/API
只访问资源的应用程序(例如,Microsoft Graph、KeyVault、Outlook API 和其他 Microsoft API)将仅获取一个令牌并将其传递给资源所有者。 鉴于它们不保护任何资源且不检查令牌,因此无需确保为其正确签名。
使用“仅限应用”流(客户端凭据/客户端证书)来请求令牌的 Web 应用程序和 Web API 属于此类别,因而不受滚动更新的影响。
保护资源的和使用 Azure 应用服务构建的 Web 应用程序/API
Azure App Services 的身份验证/授权 (EasyAuth) 功能已包含自动处理密钥滚动更新所需要的逻辑。
使用 ASP.NET OWIN OpenID Connect、WS-Fed 或 WindowsAzureActiveDirectoryBearerAuthentication 中间件保护资源的 Web 应用程序/API
如果应用程序使用 ASP.NET OWIN OpenID Connect、WS-Fed 或 WindowsAzureActiveDirectoryBearerAuthentication 中间件,则它已包含必要的逻辑来自动处理密钥滚动更新。
可以通过查看应用程序的 Startup.cs 或 Startup.Auth.cs 文件中的以下代码片段,来确认应用程序是否正在使用上述任何中间件。
app.UseOpenIdConnectAuthentication(
new OpenIdConnectAuthenticationOptions
{
// ...
});
app.UseWsFederationAuthentication(
new WsFederationAuthenticationOptions
{
// ...
});
app.UseWindowsAzureActiveDirectoryBearerAuthentication(
new WindowsAzureActiveDirectoryBearerAuthenticationOptions
{
// ...
});
使用 .NET Core OpenID Connect 或 JwtBearerAuthentication 中间件保护资源的 Web 应用程序/API
如果应用程序使用 ASP.NET OWIN OpenID Connect 或 JwtBearerAuthentication 中间件,则它已包含必要的逻辑来自动处理密钥滚动更新。
可以通过查看应用程序的 Startup.cs 或 Startup.Auth.cs 中的以下代码片段,来确认应用程序是否正在使用上述任何中间件
app.UseOpenIdConnectAuthentication(
new OpenIdConnectAuthenticationOptions
{
// ...
});
app.UseJwtBearerAuthentication(
new JwtBearerAuthenticationOptions
{
// ...
});
使用 Node.js passport-azure-ad
模块保护资源的 Web 应用程序/API
如果应用程序使用 Node.js passport-ad 模块,则它已包含必要的逻辑来自动处理密钥滚动更新。
可以通过搜索应用程序的 app.js 中的以下代码片段,来确认应用程序是否正在使用 passport-ad
var OIDCStrategy = require('passport-azure-ad').OIDCStrategy;
passport.use(new OIDCStrategy({
//...
));
保护资源的和使用 Visual Studio 2015 或更高版本创建的 Web 应用程序/API
如果应用程序通过 Visual Studio 2015 或更高版本中的 Web 应用程序模板构建,且从“更改身份验证” 菜单中选择了“工作或学校帐户” ,则应用程序已包含自动处理密钥滚动更新所需要的逻辑。 此逻辑嵌入在 OWIN OpenID Connect 中间件中,可检索和缓存来自 OpenID Connect 发现文档中的密钥并定期刷新它们。
如果已手动将身份验证添加到解决方案,则应用程序可能不包含必要的密钥滚动更新逻辑。 你可以自行编写该逻辑,或遵循使用任何其他库或手动实现任何受支持协议的 Web 应用程序/API 中的步骤。
保护资源的和使用 Visual Studio 2013 创建的 Web 应用程序
如果应用程序通过 Visual Studio 2013 中的 Web 应用程序模板生成,并且在“更改身份验证”菜单中选择了“组织帐户”,则应用程序已包含自动处理密钥滚动更新所需的逻辑 。 此逻辑将组织的唯一标识符和签名密钥信息存储到与项目关联的两个数据库表中。 可以在项目的 Web.config 文件中找到数据库的连接字符串。
如果已手动将身份验证添加到解决方案,则应用程序可能不包含必要的密钥滚动更新逻辑。 需要自行编写,或者按照使用任何其他库或手动实现任何受支持的协议的 Web 应用程序/API 中的步骤操作。
以下步骤有助于验证该逻辑是否在应用程序中正常工作。
- 在 Visual Studio 2013 中,打开解决方案,并选择右侧窗口上的“服务器资源管理器”选项卡。
- 依次展开“数据连接”、“DefaultConnection”和“表” 。 找到“IssuingAuthorityKeys”表,右键单击它,然后选择“显示表数据”。
- 在 IssuingAuthorityKeys 表中至少有一行与密钥的指纹值相对应。 删除该表中的所有行。
- 右键单击“Tenants”表,然后选择“显示表数据”。
- 在 Tenants 表中,至少有一行与唯一的目录租户标识符相对应。 删除该表中的所有行。 如果未删除 Tenants 表和 IssuingAuthorityKeys 表中的行,则运行时会出现错误。
- 生成并运行应用程序。 登录到帐户后,可以停止应用程序。
- 返回“服务器资源管理器”,查看“IssuingAuthorityKeys”和“Tenants”表中的值 。 你会注意到,它们会自动使用联合元数据文档中的相应信息重新填充。
保护资源的和使用 Visual Studio 2013 创建的 Web API
如果在 Visual Studio 2013 中使用 Web API 模板创建了 Web API 应用程序,然后在“更改身份验证”菜单中选择了“组织帐户”,则应用程序中已包含必需的逻辑 。
如果是手动配置的身份验证,请参阅下面的说明,了解如何将 Web API 配置为自动更新其密钥信息。
以下代码片段演示如何从联合元数据文档获取最新密钥,并使用 JWT 令牌处理程序来验证令牌。 该代码片段假设你使用自己的缓存机制来持久保存密钥(以便验证将来从 Microsoft 标识平台获取的令牌),无论是将它保存在数据库中、配置文件中,还是保存在其他位置。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.IdentityModel.Tokens;
using System.Configuration;
using System.Security.Cryptography.X509Certificates;
using System.Xml;
using System.IdentityModel.Metadata;
using System.ServiceModel.Security;
using System.Threading;
namespace JWTValidation
{
public class JWTValidator
{
private string MetadataAddress = "[Your Federation Metadata document address goes here]";
// Validates the JWT Token that's part of the Authorization header in an HTTP request.
public void ValidateJwtToken(string token)
{
JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler()
{
// Do not disable for production code
CertificateValidator = X509CertificateValidator.None
};
TokenValidationParameters validationParams = new TokenValidationParameters()
{
AllowedAudience = "[Your App ID URI goes here]",
ValidIssuer = "[The issuer for the token goes here, such as https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/]",
SigningTokens = GetSigningCertificates(MetadataAddress)
// Cache the signing tokens by your desired mechanism
};
Thread.CurrentPrincipal = tokenHandler.ValidateToken(token, validationParams);
}
// Returns a list of certificates from the specified metadata document.
public List<X509SecurityToken> GetSigningCertificates(string metadataAddress)
{
List<X509SecurityToken> tokens = new List<X509SecurityToken>();
if (metadataAddress == null)
{
throw new ArgumentNullException(metadataAddress);
}
using (XmlReader metadataReader = XmlReader.Create(metadataAddress))
{
MetadataSerializer serializer = new MetadataSerializer()
{
// Do not disable for production code
CertificateValidationMode = X509CertificateValidationMode.None
};
EntityDescriptor metadata = serializer.ReadMetadata(metadataReader) as EntityDescriptor;
if (metadata != null)
{
SecurityTokenServiceDescriptor stsd = metadata.RoleDescriptors.OfType<SecurityTokenServiceDescriptor>().First();
if (stsd != null)
{
IEnumerable<X509RawDataKeyIdentifierClause> x509DataClauses = stsd.Keys.Where(key => key.KeyInfo != null && (key.Use == KeyType.Signing || key.Use == KeyType.Unspecified)).
Select(key => key.KeyInfo.OfType<X509RawDataKeyIdentifierClause>().First());
tokens.AddRange(x509DataClauses.Select(token => new X509SecurityToken(new X509Certificate2(token.GetX509RawData()))));
}
else
{
throw new InvalidOperationException("There is no RoleDescriptor of type SecurityTokenServiceType in the metadata");
}
}
else
{
throw new Exception("Invalid Federation Metadata document");
}
}
return tokens;
}
}
}
保护资源的和使用 Visual Studio 2012 创建的 Web 应用程序
如果应用程序是在 Visual Studio 2012 中生成的,则你可能已使用标识和访问工具配置了应用程序。 你可能还使用验证颁发者名称注册表(VINR)。 VINR 负责维护受信任标识提供程序(Microsoft 标识平台)的相关信息以及用于验证其颁发的令牌的密钥。 使用 VINR 还可轻松地自动更新存储在 Web.config 文件中的密钥信息,具体方法是:下载与用户的目录关联的最新联合元数据文档,使用最新文档检查配置是否过期,并根据需要更新应用程序以使用新密钥。
如果是使用 Microsoft 提供的代码示例或演练文档创建的应用程序,则密钥滚动更新逻辑已包含在项目中。 你会注意到,下面的代码已存在于项目中。 如果应用程序还没有此逻辑,请按照以下步骤添加它,并验证它是否正常工作。
- 在“解决方案资源管理器”中,添加对相应项目的 System.IdentityModel 程序集的引用 。
- 打开 Global.asax.cs 文件并添加以下 using 指令:
using System.Configuration; using System.IdentityModel.Tokens;
- 在 Global.asax.cs 文件中添加以下方法:
protected void RefreshValidationSettings() { string configPath = AppDomain.CurrentDomain.BaseDirectory + "\\" + "Web.config"; string metadataAddress = ConfigurationManager.AppSettings["ida:FederationMetadataLocation"]; ValidatingIssuerNameRegistry.WriteToConfig(metadataAddress, configPath); }
- 在 Global.asax.cs 中的 Application_Start() 方法内调用 RefreshValidationSettings() 方法,如下所示:
protected void Application_Start() { AreaRegistration.RegisterAllAreas(); ... RefreshValidationSettings(); }
执行这些步骤后,系统使用联合元数据文档中的最新信息(包括最新密钥)更新应用程序的 Web.config。 每次在 IIS 中回收应用程序池时,都会进行此更新;默认情况下,IIS 设置为每 29 个小时回收一次应用程序。
遵循以下步骤验证密钥滚动更新逻辑是否正常工作。
- 确认应用程序正在使用上面的代码后,打开 Web.config 文件并导航到 <issuerNameRegistry> 块,注意查找以下几行:
<issuerNameRegistry type="System.IdentityModel.Tokens.ValidatingIssuerNameRegistry, System.IdentityModel.Tokens.ValidatingIssuerNameRegistry"> <authority name="https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/"> <keys> <add thumbprint="AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00" /> </keys>
- 在 <add thumbprint=""> 设置中,通过将任何字符替换为不同的字符来更改指纹值。 保存 Web.config 文件。
- 生成并运行应用程序。 如果你能完成登录过程,则应用程序会通过从你的目录的联合元数据文档下载所需的信息来成功地更新密钥。 如果登录时遇到问题,请通过阅读“使用 Microsoft 标识平台 文章向 Web 应用程序添加登录”,或下载并检查以下代码示例:Microsoft Entra ID 的多租户云应用程序,确保应用程序中的更改是正确的。
使用任何其他库保护资源或手动实现任何受支持协议的 Web 应用程序/API
如果使用其他库或手动实现任何受支持的协议,则需要查看库或实现,以确保从 OpenID Connect 发现文档或联合元数据文档检索密钥。 进行此项检查的方法之一是在代码或库的代码中执行搜索,以找到对 OpenID 发现文档或联合元数据文档的任何调用。
如果密钥存储在某处或在应用程序中进行了硬编码,则可按照本指南文档末尾的说明执行手动滚动更新,手动检索密钥并进行相应更新。 强烈建议使用本文中所述的任何方法增强应用程序以支持自动滚动更新,从而避免将来在 Microsoft 标识平台增大其滚动更新频率或发生紧急带外滚动更新时出现中断和开销。
如何测试应用程序以确定它是否会受影响
可以使用以下 PowerShell 脚本来验证应用程序是否支持自动密钥滚动更新。
若要使用 PowerShell 检查和更新签名密钥,需要 MSIdentityTools PowerShell 模块。
安装 MSIdentityTools PowerShell 模块:
Install-Module -Name MSIdentityTools
使用 Connect-MgGraph 命令和管理员帐户登录,以同意所需范围:
Connect-MgGraph -Scope "Application.ReadWrite.All"
获取可用的签名密钥指纹列表:
Get-MsIdSigningKeyThumbprint
选取任意密钥指纹,并配置 Microsoft Entra ID,使其将该密钥用于应用程序(从 Microsoft Entra 管理中心获取应用 ID):
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <Thumbprint>
通过登录以获取新令牌来测试 Web 应用程序。 密钥更新更改是即时的,但请确保使用新的浏览器会话(例如,Internet Explorer 的“InPrivate”、“Chrome 的”Incognito“或 Firefox 的”专用“模式),以确保你获得新令牌。
对于每个返回的签名密钥指纹,运行
Update-MsIdApplicationSigningKeyThumbprint
cmdlet 并测试 Web 应用程序登录过程。如果 Web 应用程序正确登录,则它支持自动滚动更新。 如果没有,请修改应用程序以支持手动滚动更新。 有关详细信息,请参阅建立手动滚动更新过程。
运行以下脚本以还原到正常行为:
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default
如果应用程序不支持自动滚动更新,如何执行手动滚动更新
如果应用程序不支持自动滚动更新,则需要建立一个定期监视 Microsoft 标识平台签名密钥的过程,并手动执行相应滚动更新。
若要使用 PowerShell 检查和更新签名密钥,需要 MSIdentityTools
PowerShell 模块。
安装
MSIdentityTools
PowerShell 模块:Install-Module -Name MSIdentityTools
获取最新的签名密钥(从 Microsoft Entra 管理中心获取租户 ID):
Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest
将此密钥与应用程序当前硬编码或配置为使用的密钥进行比较。
如果最新密钥不同于你的应用程序使用的密钥,请下载最新的签名密钥:
Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>
更新应用程序的代码或配置以使用新密钥。
配置 Microsoft Entra ID,使其将该密钥用于应用程序(从 Microsoft Entra 管理中心获取应用 ID):
Get-MsIdSigningKeyThumbprint -Latest | Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId>
通过登录以获取新令牌来测试 Web 应用程序。 密钥更新更改是即时的,但请确保使用新的浏览器会话来确保颁发新令牌。 例如,使用 Microsoft Edge 的“InPrivate”、“Chrome 的”Incognito“或 Firefox 的”专用“模式。
如果遇到任何问题,请还原到以前使用的密钥,并与 Azure 支持部门联系:
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <PreviousKeyThumbprint>
更新应用程序以支持手动滚动更新后,还原为正常行为:
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default