通过

为库和自定义应用程序配置 OIDC SSO

本文向您介绍如何在 Microsoft Entra ID 中为画廊应用程序和自定义（非画廊）应用程序配置 OpenID Connect (OIDC) 单一登录 (SSO)。 使用 OIDC SSO，用户可以使用其Microsoft Entra 凭据登录到应用程序，从而提供无缝的身份验证体验。

OIDC 是基于 OAuth 2.0 构建的身份验证协议，可实现安全的用户身份验证和单一登录。 有关 OIDC 协议的详细信息，请参阅 使用 Microsoft 标识平台的 OIDC 身份验证。

建议使用非生产环境测试本文中的步骤。

在配置 OIDC SSO 之前，了解以下核心概念很有帮助：

  • 应用注册与企业应用程序：应用注册定义应用程序的标识和配置，而企业应用程序表示租户中这些应用的实例。 若要了解详细信息，请参阅 Microsoft Entra ID 中的应用程序和服务主体对象。
  • 权限和同意：应用程序请求访问资源的权限，用户或管理员授予许可。 有关许可框架的详细信息，请参阅 Microsoft标识平台中的权限和同意。
  • 多租户应用程序：可供多个组织使用的应用程序。 有关多租户的指导，请参阅 如何：将应用转换为多租户。
  • 身份验证流：用于身份验证用户的不同方法，例如在单页应用程序中使用 PKCE 的授权代码流。 有关详细信息，请参阅 Microsoft标识平台身份验证流。
  • OIDC SSO：使用 OIDC 协议对应用程序的用户进行身份验证的单一登录方法。 它允许用户登录一次并访问多个应用程序，而无需重新输入凭据。

先决条件

若要配置基于 OIDC 的 SSO，需要：

  • 一个 Microsoft Entra 用户帐户。 如果还没有帐户，可以 免费创建帐户。
  • 以下角色之一：
    • 云应用程序管理员
    • 应用程序管理员
    • 服务主体的所有者
  • 对于自定义应用程序：有关应用程序的详细信息，包括其重定向 URI 和身份验证要求

Microsoft Entra ID 中的画廊应用预配置了 OIDC 支持，通过用户许可的过程使设置变得简单。

添加使用 OIDC 标准 SSO 的企业应用程序时，请选择 “注册 ”按钮。 从应用库中选择应用时，该按钮位于右侧窗格。 选择该按钮即表示你完成了应用程序的注册过程。

若要为画廊应用程序配置基于 OIDC 的 SSO，请执行以下步骤：

  1. 以至少云应用程序管理员身份登录到 Microsoft Entra 管理中心。

  2. 浏览到 Entra ID>企业应用程序>所有应用程序。

  3. 在“所有应用程序”窗格中，选择“新建应用程序”。

  4. 此时会打开“浏览 Microsoft Entra 图库”窗格。 在此示例中，我们使用 SmartSheet。

  5. 选择 注册 SmartSheet。 使用 Microsoft Entra ID 中的用户帐户凭据登录。 如果你已经订阅该应用程序，则会验证用户详细信息和租户信息。 如果该应用程序无法验证用户，它会将你重定向到应用程序服务注册页面。

    完成应用程序的同意屏幕。

    输入登录凭据后，将显示同意屏幕。 同意屏幕提供有关应用程序及其所需的权限的信息。

  6. 依次选择“代表组织同意”和“接受” 。 系统将应用程序添加到租户中，并显示应用程序主页。

请联系应用程序供应商，了解应用程序所需的任何其他配置步骤。

注释

只能添加图库应用程序的一个实例。 添加应用程序并尝试再次提供许可后，无法再次将其添加到租户。

有关用户和管理员同意的详细信息，请参阅 了解用户和管理员同意。 有关同意框架的综合信息，请参阅 Microsoft标识平台中的权限和同意。

对于Microsoft Entra 库中不可用的应用程序，需要手动注册和配置应用程序。 本部分提供使用自定义应用程序设置 OIDC SSO 的分步指南。

步骤 1：注册应用程序

  1. 以至少云应用程序管理员身份登录到 Microsoft Entra 管理中心。
  2. 导航至 Entra ID>应用注册>新注册。
  3. 输入应用程序 的名称 （例如“我的自定义 Web 应用”）。
  4. 在 “支持的帐户类型”下，选择适当的选项：
    • 此组织目录中的帐户仅适用于 单租户应用程序
    • 任何组织目录中的帐户 ，了解有关多租户应用程序的详细信息，请参阅 多租户应用程序
    • 如果要同时支持工作/学校帐户和个人帐户，请选择任何组织目录中的帐户和个人Microsoft帐户
  5. 对于 重定向 URI，请选择平台类型并输入应用程序的重定向 URI：
    • Web：对于服务器端 Web 应用程序（例如 https://yourdomain.com/auth/callback）
    • 单页应用程序（SPA）：对于使用新式身份验证流的客户端应用程序（例如， https://yourdomain.com 或 http://localhost:3000 用于开发）
    • 公共客户端/本机：适用于移动和桌面应用程序
  6. 选择“注册”。

步骤 2：配置身份验证设置

  1. 在应用注册中，导航到 “身份验证”。

  2. 验证是否已为平台类型正确配置重定向 URI。

  3. 配置身份验证流 （安全性非常重要）：

    对于单页应用程序（SPAs）：

    • 确保重定向 URI 列在 单页应用程序 平台下。 此选项会自动使用 PKCE 配置安全的授权代码流，这是对于 SPA 推荐的策略。
    • 除非旧版应用程序需要，否则请勿启用隐式授予选项

    对于 Web 应用程序：

    • 确保重定向 URI 列在 Web 平台下。 此选项配置标准 授权代码流。

    警告

    由于安全漏洞（包括浏览器历史记录中的令牌泄漏）， 不建议 对新应用程序使用隐式授权流。 Microsoft强烈建议将 授权代码流与 PKCE 一起使用 ，转而用于单页应用程序。 只有当您拥有无法更新以支持更安全流程的旧应用程序并且了解相关的安全风险时，才启用这些选项。

    有关身份验证流的详细信息，请参阅 Microsoft标识平台身份验证流。

步骤 3：配置客户端凭据（适用于 Web 应用程序）

如果应用程序是机密客户端（可以安全地存储机密的服务器端 Web 应用程序）：

  1. 导航到“证书与机密”。
  2. 选择 新客户端密码。
  3. 添加说明并选择到期期限。
  4. 选择 “添加 ”并立即复制机密值（无法再次显示）。
  5. 将客户端密码安全地存储在应用程序配置中。

小窍门

对于生产应用程序，请考虑使用证书而不是客户端机密来提高安全性。 请参阅 证书凭据。

步骤 4：配置 API 权限

  1. 导航到 API 权限。
  2. User.Read默认情况下会添加 Microsoft Graph 的权限。
  3. 对于 OIDC 身份验证，通常需要以下委派权限：
    • openid：OIDC 身份验证所必需的
    • 个人资料：访问用户的个人资料信息
    • 电子邮件：访问用户的电子邮件地址
  4. 若要添加更多权限，请执行以下操作：
    • 选择“添加权限”
    • 选择 Microsoft Graph
    • 选择“委派权限”
    • 搜索并选择所需的权限（例如 openid、profile、email）
    • 选择“添加权限”
  5. 如果您的应用程序需要需要管理员许可的权限，请选择 为[您的租户]授予管理员许可。

有关权限和同意的简介，请参阅 Microsoft标识平台中的权限和同意。

步骤 5：配置可选声明（如果需要）

  1. 导航到 令牌配置。
  2. 选择 “添加可选声明”。
  3. 选择要添加的可选声明（例如， email， given_name， family_name）。
  4. 选择 “添加” 以应用更改。

步骤 6：收集应用程序详细信息

注册和配置后，收集应用程序所需的以下信息：

  1. 在 “概述 ”页中，请注意：
    • 应用程序（客户端）ID：应用的唯一标识符
    • 目录（租户）ID：租户的唯一标识符
  2. 选择 终结点 以查看 OIDC 元数据和终结点：
    • OIDC 元数据文档： https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid_configuration
    • 授权终结点：用于启动登录流
    • 令牌终结点：用于交换令牌的授权代码
    • JWKS URI：用于令牌签名验证

这些详细信息用于应用程序的 OIDC 库配置。

步骤 7：配置应用程序代码

使用收集的信息配置应用程序的 OIDC 库，

  • 客户端 ID：步骤 5 中的应用程序（客户端）ID
  • 客户端密码：如果适用（适用于 Web 应用程序）
  • 重定向 URI：步骤 1 中配置的 URI 相同
  • 颁发机构/颁发者： https://login.microsoftonline.com/{tenant}/v2.0/ （将 {tenant} 替换为你的租户 ID）
  • 范围：通常 openid profile email 用于基本 OIDC 身份验证

有关特定实现指南，请参阅适用于 Web 应用程序的 PKCE 的授权代码流 。

步骤 8：测试 OIDC SSO 配置

  1. 使用联机工具：可以使用以下命令测试基本身份验证流 https://jwt.ms：

    • 构造登录 URL： https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id={client_id}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&nonce={random_value}
    • 将 {tenant} 和 {client_id} 替换为你的值
    • 在浏览器中导航到此 URL 以测试身份验证流

  2. 在应用程序中：在应用程序中集成 OIDC 库并测试完整的登录体验。

  3. 分配用户：导航到 企业应用程序、查找应用，并在 “用户”和“组”下分配用户或组。

多租户应用注意事项

如果应用程序需要支持来自多个组织的用户：

  • 使用任何组织目录中的帐户配置应用注册
  • 使用通用终结点： https://login.microsoftonline.com/common/
  • 在应用程序逻辑中实现适当的租户验证

详细指南请参阅 如何：将应用转换成多租户模式。

常见问题故障排除

  • 重定向 URI 无效：确保应用注册中的重定向 URI 与应用程序发送的内容完全匹配
  • 许可问题：检查请求的权限是否需要管理员同意
  • 令牌验证错误：验证是否使用正确的 JWKS URI 并验证令牌签名
  • 多租户问题：确保使用正确的端点（公共端点与特定于租户的端点）

有关全面的故障排除指南，请参阅 Microsoft标识平台错误代码。

相关内容