---
title: "使用 Microsoft Entra ID 设置 SSO"
description: "在 Microsoft Entra ID 中注册 Bird SAML 或 OIDC 连接，设置 Entra 缺省未提供的 NameID 格式，填充 mail 属性，并了解应用分配。"
canonical: "https://bird.com/zh-sg/wendang/knowledge-base/account-security/sso-microsoft-entra-id"
---

# 使用 Microsoft Entra ID 设置 SSO

本页介绍 SSO 连接中 Entra 一侧的配置。Bird 一侧的操作（验证域名、测试、激活及强制要求 SSO）对所有提供商都相同，详见 [SSO 与用户预配](/docs/knowledge-base/account-security/sso)。

Entra 和 Bird 各自需要对方的值，因此从哪边开始取决于协议。操作时请同时打开两边。

## SAML

SAML 请从 Bird 开始。SAML 连接的 Entity ID 和 Assertion Consumer Service URL 由连接本身生成，因此请选择 **I have not set up my provider yet** 来创建连接，注册随后显示的值，然后回到 **Supply the details**。[不使用占位值设置 SAML](/docs/knowledge-base/account-security/sso) 详细介绍了该流程。

Entra 的字段名称与 Bird 不一致：

| Bird 中 **Register these with your identity provider** 下的名称 | Microsoft Entra ID 中的名称                |
| --------------------------------------------------------------- | ------------------------------------------ |
| Assertion Consumer Service URL                                  | Reply URL (Assertion Consumer Service URL) |
| Entity ID                                                       | Identifier (Entity ID)                     |
| Sign-in URL for this connection                                 | Sign on URL                                |

是否填写 **Sign on URL** 决定了 My Apps 磁贴的行为。填写后，磁贴会在 Bird 发起登录，然后向 Entra 请求断言。留空时，磁贴会直接向 Bird 发送断言。只要连接允许身份提供商发起的登录，Bird 两种方式都接受。

### 手动设置 NameID 格式

Entra 的联合元数据不声明任何 NameID 格式。Bird 会从元数据中读取提供商发布的格式，因此 Entra 连接默认以永久标识符为键，首次测试会因 Entra 实际发送的格式不匹配而失败。

在连接上打开 **Edit**，在运行首次测试之前将 **Identify members by** 设置为成员的邮箱地址。在 Entra 中，将 **Unique User Identifier (Name ID)** 声明设为 `user.mail`，并将名称标识符格式设为 Email address。

Okta 和 Google 都会声明格式，因此此步骤仅针对 Entra。

### 关闭 Sign SAML response

将 **Sign SAML response** 保持关闭，让 Entra 签名断言而非外层响应。开启响应签名后，内部断言未签名，Bird 会拒绝所有登录，并报告一个看似证书问题的签名错误。

### 断言有效期与证书轮换

Entra 签发的断言有效期从签发前 5 分钟到签发后 60 分钟，比 Okta 或 Google 的窗口更宽，Bird 可以接受。

轮换时请保留重叠期。在 Bird 连接中添加新证书，同时保留旧证书；在 Entra 中激活新证书；最后从 Bird 移除旧证书。如果在 Entra 激活新证书之前就删除旧证书，所有登录都会被拒绝，直到两边一致。

Entra 的客户端密钥和签名证书都会过期。记下日期并提前计划更换；使用过期凭据的登录会在当天立即失败。

## OIDC

OIDC 请从 Entra 门户开始。Bird 需要颁发者、客户端 ID 和客户端密钥来创建 OIDC 连接，因此请先在 Entra 注册应用。Bird 的 **Redirect URI** 对所有连接都相同，且在 **Add connection** 中创建连接之前就会显示，可以提前注册。

在 Entra 中注册应用、添加客户端密钥，然后将客户端 ID 和密钥复制到 Bird。

使用**特定于租户**的颁发者，即包含你的租户 ID 的 `v2.0` 颁发者。不要使用多租户 `common` 端点：其发现文档中的颁发者是模板而非实际值，基于它创建的连接会导致所有登录失败。Bird 使用 `client_secret_basic` 向令牌端点进行身份验证。

将 Bird 的 **Redirect URI** 注册为应用注册中的重定向 URI。

### 填充每个成员的 mail 属性

Bird 从 ID 令牌的 `email` 声明中读取成员地址。Entra 仅在用户的 **mail** 属性已设置时才发出该声明，该属性位于 Entra 个人资料的 Contact information 下。如果租户的用户没有邮箱（例如组织使用其他邮件提供商），该属性通常为空，Bird 测试会报告未收到邮箱地址，即使用户的主体名称是一个完全可用的地址。

为每位将通过 Bird 登录的成员填充 **mail**。

### My Apps 磁贴

要让磁贴显示，请将应用注册的 **Home page URL** 设置为 Bird 中连接的 Initiate login URI，将 **Visible to users** 设为 Yes，并分配用户。没有 Home page URL 时磁贴会被隐藏。

### 应用分配不会限制谁可以访问 Bird

在 Entra 应用上设置 **Assignment required** 本身并不能阻止未分配的成员通过 OIDC 登录 Bird。Bird 请求的标准 `openid` 和 `email` 作用域会被 Entra 视为 Microsoft Graph 权限，因此 Entra 针对 Graph 而非你的 Bird 应用来评估分配。

要让 Entra 强制执行分配以及与之关联的应用级条件访问，请在应用注册的 **Expose an API** 下公开一个作用域，并让 Bird 在连接中请求该作用域。在此之前，能通过此连接访问你组织的成员取决于其地址是否在已验证的域名中。

这仅适用于 OIDC 路径。SAML 应用在 Entra 中是独立资源，分配直接针对它进行评估。

## 后续步骤

- [SSO 与用户预配](/docs/knowledge-base/account-security/sso)：验证域名、测试连接并要求 SSO
- [使用 Okta 设置 SSO](/docs/knowledge-base/account-security/sso-okta)
- [使用 Google Workspace 设置 SSO](/docs/knowledge-base/account-security/sso-google-workspace)

## Related resources

- [Should I use an API key or an OAuth token, and how do I rotate one?](/explained/platform/api-key-or-oauth-token-and-how-do-i-rotate-one) (answer)
- [Authentication & API keys](/docs/guides/authentication) (docs)

[Get an implementation brief](/learn/workspace?topic=account-access)