Microsoft 标识平台最佳做法和建议Microsoft identity platform best practices and recommendations

本文重点说明在与 Microsoft 标识平台集成时的最佳做法、建议和最容易疏忽的问题。This article highlights best practices, recommendations, and common oversights when integrating with the Microsoft identity platform. 此查检表可引导你完成高质量且安全的集成。This checklist will guide you to a high-quality and secure integration. 请定期查看此列表,确保维持应用与标识平台之间的集成的质量和安全性。Review this list on a regular basis to make sure you maintain the quality and security of your app’s integration with the identity platform. 请不要参照该查检表来评审整个应用程序。The checklist isn't intended to review your entire application. 在我们不断改进平台的过程中,该查检表的内容将会更改。The contents of the checklist are subject to change as we make improvements to the platform.

如果你刚刚入门,请查看 Microsoft 标识平台文档来了解身份验证基础知识、Microsoft 标识平台中的应用方案,等等。If you’re just getting started, check out the Microsoft identity platform documentation to learn about authentication basics, application scenarios in the Microsoft identity platform, and more.

使用以下查检表确保应用程序与 Microsoft 标识平台有效集成。Use the following checklist to ensure that your application is effectively integrated with the Microsoft identity platform.

提示

Azure 门户中的集成助手可帮助你应用其中许多最佳做法和建议。The Integration assistant in the Azure portal can help you apply many of these best practices and recommendations. 选择 Azure 门户中的任何应用注册,然后选择“集成助手(预览版)”菜单项,开始使用助手。Select any of your app registrations in the Azure portal, and then select the Integration assistant (preview) menu item to get started with the assistant.

基础知识Basics

复选框 阅读并理解 Microsoft 平台策略checkbox Read and understand the Microsoft Platform Policies. 确保应用程序符合旨在保护用户和平台的所述条款。Ensure that your application adheres to the terms outlined as they're designed to protect users and the platform.

所有权Ownership

复选框 确保用来注册和管理应用的、与帐户关联的信息是最新的。Make sure the information associated with the account you used to register and manage apps is up-to-date.

品牌Branding

复选框 遵守适用于应用程序的品牌准则checkbox Adhere to the Branding guidelines for applications.

复选框 为应用程序提供有意义的名称和徽标。checkbox Provide a meaningful name and logo for your application. 此信息将显示在应用程序的许可提示中。This information appears on your application’s consent prompt. 确保提供的名称和徽标能够代表公司/产品的形象,以帮助用户做出明智的决定。Make sure your name and logo are representative of your company/product so that users can make informed decisions. 确保不要违反任何商标法案。Ensure that you're not violating any trademarks.

隐私Privacy

复选框 提供应用服务条款和隐私声明的链接。Provide links to your app's terms of service and privacy statement.

安全性Security

复选框 管理重定向 URI:checkbox Manage your redirect URIs:

  • 保留所有重定向 URI 的所有权,并使其 DNS 记录保持最新。Maintain ownership of all your redirect URIs and keep the DNS records for them up-to-date.
  • 不要在 URI 中使用通配符 (*)。Don't use wildcards (*) in your URIs.
  • 对于 Web 应用,请确保所有 URI 安全且已经过加密(例如,使用 https 方案)。For web apps, make sure all URIs are secure and encrypted (for example, using https schemes).
  • 对于公共客户端,在适用的情况下请使用特定于平台的重定向 URI(主要适用于 iOS 和 Android)。For public clients, use platform-specific redirect URIs if applicable (mainly for iOS and Android). 否则,请使用包含大量随机内容的重定向 URI,以防在回调应用时发生冲突。Otherwise, use redirect URIs with a high amount of randomness to prevent collisions when calling back to your app.
  • 如果在隔离的 Web 代理中使用应用,则可以使用 https://login.partner.microsoftonline.cn/common/oauth2/nativeclientIf your app is being used from an isolated web agent, you may use https://login.partner.microsoftonline.cn/common/oauth2/nativeclient.
  • 定期审查并修剪所有未使用或不必要的重定向 URI。Review and trim all unused or unnecessary redirect URIs on a regular basis.

复选框 如果应用已注册到目录中,请最小化并手动监视应用注册所有者的列表。If your app is registered in a directory, minimize and manually monitor the list of app registration owners.

复选框 除非有明确的要求,否则不要启用对 OAuth2 隐式授权流的支持。checkbox Don't enable support for the OAuth2 implicit grant flow unless explicitly required. 此处了解有效方案。Learn about the valid scenario here.

复选框 不要仅使用用户名/密码。checkbox Move beyond username/password. 不要使用资源所有者密码凭据流 (ROPC),因为它会直接处理用户的密码。Don't use resource owner password credential flow (ROPC), which directly handles users’ passwords. 此流所需的信任度和用户公开度很高,仅当无法使用其他更安全的流时,才应使用此流。This flow requires a high degree of trust and user exposure and should only be used when other, more secure, flows can't be used. 在某些情况下,此流仍然是必需的,但请注意,使用它会对应用程序施加约束。This flow is still needed in some scenarios, but beware that using it will impose constraints on your application. 有关其他新式方法,请阅读身份验证流和应用程序方案For more modern approaches, read Authentication flows and application scenarios.

复选框 保护和管理 Web 应用、Web API 和守护程序应用的机密应用凭据。checkbox Protect and manage your confidential app credentials for web apps, web APIs and daemon apps. 使用证书凭据,而不是密码凭据(客户端机密)。Use certificate credentials, not password credentials (client secrets). 如果必须使用密码凭据,请不要手动设置。If you must use a password credential, don't set it manually. 不要将凭据存储在代码或配置中,切勿允许人类处理这些凭据。Don't store credentials in code or config, and never allow them to be handled by humans. 如果可能,请使用 Azure 资源的托管标识Azure Key Vault 存储和定期轮换凭据。If possible, use managed identities for Azure resources or Azure Key Vault to store and regularly rotate your credentials.

复选框 确保应用程序请求最低特权权限。checkbox Make sure your application requests the least privilege permissions. 只在有需要时,才请求应用程序绝对需要的权限。Only ask for permissions that your application absolutely needs, and only when you need them. 了解不同的权限类型Understand the different types of permissions. 仅在必要时使用应用程序权限;尽量使用委托的权限。Only use application permissions if necessary; use delegated permissions where possible. 有关 Microsoft Graph 权限的完整列表,请参阅此权限参考For a full list of Microsoft Graph permissions, see this permissions reference.

复选框 如果你在使用 Microsoft 标识平台保护 API,请仔细考虑该 API 应该公开的权限。If you're securing an API using the Microsoft identity platform, carefully think through the permissions it should expose. 考虑解决方案需要哪种适当的粒度级,以及哪些权限需要管理员许可。Consider what's the right granularity for your solution and which permission(s) require admin consent. 在做出任何授权决策之前,请检查传入令牌中的预期权限。Check for expected permissions in the incoming tokens before making any authorization decisions.

实现Implementation

复选框 使用新式身份验证解决方案(OAuth 2.0、OpenID Connect)确保用户安全登录。checkbox Use modern authentication solutions (OAuth 2.0, OpenID Connect) to securely sign in users.

复选框 不要直接对 OAuth 2.0 和 Open ID 等协议进行编程。checkbox Don't program directly against protocols such as OAuth 2.0 and Open ID. 请改用 Microsoft 身份验证库 (MSAL)Instead, leverage the Microsoft Authentication Library (MSAL). MSAL 库将安全协议安全地包装在一个易用的库中,并且你可以获得对条件访问方案的内置支持,以及内置的令牌缓存支持。The MSAL libraries securely wrap security protocols in an easy-to-use library, and you get built-in support for Conditional Access scenarios, and built-in token caching support. 有关详细信息,请参阅 Microsoft 支持的客户端库中间件库列表,以及兼容的第三方客户端库列表。For more info, see the list of Microsoft supported client libraries and middleware libraries and the list of compatible third-party client libraries.

如果必须为身份验证协议手动编写代码,应遵循 Microsoft SDL 等方法。If you must hand code for the authentication protocols, you should follow a methodology such as Microsoft SDL. 请认真对待每个协议的标准规范中的安全注意事项。Pay close attention to the security considerations in the standards specifications for each protocol.

复选框 将现有应用从 Azure Active Directory 身份验证库 (ADAL) 迁移到 Microsoft 身份验证库checkbox Migrate existing apps from Azure Active Directory Authentication Library (ADAL) to Microsoft Authentication Library. MSAL 是 Microsoft 的最新标识平台解决方案,比 ADAL 更普及。MSAL is Microsoft’s latest identity platform solution and is preferred to ADAL. 它适用于 .NET、JavaScript、Android、iOS 和 macOS,并为 Python 和 Java 推出了公共预览版。It is available on .NET, JavaScript, Android, iOS, macOS and is also in public preview for Python and Java. 详细了解如何迁移 ADAL.NETADAL.js 以及 ADAL.NET 和 iOS 中介应用。Read more about migrating ADAL.NET, ADAL.js, and ADAL.NET and iOS broker apps.

复选框 对于移动应用,请使用应用程序注册体验来配置每个平台。For mobile apps, configure each platform using the application registration experience. 要使应用程序能够利用 Microsoft Authenticator 或 Microsoft 公司门户进行单一登录,需要为应用配置“中介重定向 URI”。In order for your application to take advantage of the Microsoft Authenticator or Microsoft Company Portal for single sign-in, your app needs a “broker redirect URI” configured. 这样,在身份验证后,Microsoft 就可将控制权递回给应用程序。This allows Microsoft to return control to your application after authentication. 配置每个平台时,应用注册体验会引导你完成该过程。When configuring each platform, the app registration experience will guide you through the process. 使用快速入门下载工作示例。Use the quickstart to download a working example. 在 iOS 上,请尽可能地使用中介和系统 webview。On iOS, use brokers and system webview whenever possible.

复选框 在 Web 应用或 Web API 中,为每个帐户保留一个令牌缓存。checkbox In web apps or web APIs, keep one token cache per account. 对于 Web 应用,令牌缓存应使用帐户 ID 进行键控。For web apps, the token cache should be keyed by the account ID. 对于 Web API,帐户应使用用于调用该 API 的令牌的哈希值进行键控。For web APIs, the account should be keyed by the hash of the token used to call the API. MSAL.NET 在 .NET Framework 和 .NET Core 子平台中提供自定义令牌缓存序列化。MSAL.NET provides custom token cache serialization in the .NET Framework and .NET Core subplatforms. 出于安全和性能方面的原因,我们建议为每个用户序列化一个缓存。For security and performance reasons, our recommendation is to serialize one cache per user. 有关详细信息,请阅读令牌缓存序列化For more information, read about token cache serialization.

复选框 如果应用所需的数据可以通过 Microsoft Graph 获取,请使用 Microsoft Graph 终结点而不是单个 API 请求此数据的权限。checkbox If the data your app requires is available through Microsoft Graph, request permissions for this data using the Microsoft Graph endpoint rather than the individual API.

复选框 不要查看访问令牌值,或尝试将其分析为客户端。Don't look at the access token value, or attempt to parse it as a client. 此类操作可能会更改值、格式,甚至在不发出警告的情况下将值加密 - 如果客户端需要了解有关用户的某种信息,请始终使用 id_token,或调用 Microsoft Graph。They can change values, formats, or even become encrypted without warning - always use the id_token if your client needs to learn something about the user, or call Microsoft Graph. 只能由 Web API 分析访问令牌(因为格式定义和加密密钥设置就是由这些 API 完成的)。Only web APIs should parse access tokens (since they are the ones defining the format and setting the encryption keys).

最终用户体验End-user experience

复选框 了解同意体验并配置应用同意提示部分,使最终用户和管理员有足够的信息确定是否可信任你的应用。checkbox Understand the consent experience and configure the pieces of your app’s consent prompt so that end users and admins have enough information to determine if they trust your app.

复选框 在执行交互式流之前尝试进行静默身份验证(静默令牌获取),以尽量减少用户在使用应用时输入登录凭据所需的时间。Minimize the number of times a user needs to enter login credentials while using your app by attempting silent authentication (silent token acquisition) before interactive flows.

复选框 不要对每次登录使用“prompt=consent”。Don't use “prompt=consent” for every sign-in. 仅当你已确定需要请求其他权限的许可(例如,如果已更改应用的所需权限)时,才使用 prompt=consent。Only use prompt=consent if you’ve determined that you need to ask for consent for additional permissions (for example, if you’ve changed your app’s required permissions).

复选框 如果适用,请使用用户数据扩充应用程序。checkbox Where applicable, enrich your application with user data. 使用 Microsoft Graph API 可以轻松实现此目的。Using the Microsoft Graph API is an easy way to do this. Graph 浏览器工具可帮助你开始。The Graph Explorer tool that can help you get started.

复选框 注册应用所需的完整权限集,使管理员能够轻松地向其租户授予同意。checkbox Register the full set of permissions that your app requires so admins can grant consent easily to their tenant. 在运行时使用增量许可,以帮助用户了解应用在首次启动时为何要请求可能会给用户带来忧虑或困惑的权限。Use incremental consent at run time to help users understand why your app is requesting permissions that may concern or confuse users when requested on first start.

复选框 实现简洁的单一注销体验checkbox Implement a clean single sign-out experience. 这是一项隐私和安全要求,有助于建立良好的用户体验。It’s a privacy and a security requirement, and makes for a good user experience.

测试Testing

复选框 测试可能会影响用户使用应用程序的能力的条件访问策略checkbox Test for Conditional Access policies that may affect your users’ ability to use your application.

复选框 使用你打算支持的所有可能帐户(例如工作或学校帐户)测试应用程序。Test your application with all possible accounts that you plan to support (for example, work or school accounts).

其他资源Additional resources

浏览有关 v2.0 的深入信息:Explore in-depth information about v2.0: