> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# 单点登录

> 通过 SAML 2.0 或 OpenID Connect，使用你自己的身份提供商，让团队登录 Partner Portal。

单点登录（SSO）让你的团队可以使用他们在工作中已经在用的凭据登录 [LI.FI Partner Portal](https://portal.li.fi/)。你只需连接一次身份提供商（IdP），邮箱与你公司域名匹配的成员即可通过该身份提供商登录。

Partner Portal 支持两种协议：\*\*OpenID Connect（OIDC）\*\*和 **SAML 2.0**。两者都适配 Okta、Microsoft Entra ID、Google Workspace 以及任何其他符合标准的提供商。如果没有特别偏好，建议使用 OIDC——它只需要一个 URL 和一组凭据，无需轮换证书。

## 开始之前

* 你是 Partner Portal 中所在组织的 **Owner**。只有 Owner 才能查看和编辑 SSO 设置。
* 你的组织已启用 SSO。打开 **Settings → Single sign-on**；如果页面显示 **Request access**，请[联系 LI.FI 团队](https://li.fi/contact-us/)，我们会为你启用该功能。
* 你拥有身份提供商的管理员权限，或者有人能够协助你操作。
* 你清楚团队使用的邮箱域名，例如 `example.com` 和 `example-corp.com`。

## 登录流程

登录始终从门户开始。成员打开 [portal.li.fi](https://portal.li.fi/) 并输入他们的工作邮箱。

* 在 **Required** 模式下，邮箱与你某个域名匹配的成员会被自动重定向到你的身份提供商。
* 在 **Optional** 模式下，成员会在密码输入框下方看到 **Continue with SSO** 选项，可自行选择登录方式。

只要你的连接处于激活状态，**Settings → Single sign-on** 页面还会显示一个 **SSO sign-in link**。将它分享给团队，即可直接发起 SSO 登录。该链接不会出现在公开登录页面上。

<Note>
  不支持从身份提供商一侧发起的登录，例如通过 Okta 或 Entra 的应用磁贴发起。成员必须从门户开始登录，或使用 SSO 登录链接。
</Note>

邮箱地址是账户的匹配键。你的身份提供商必须在每次登录时都返回用户的邮箱，否则门户无法将该用户与你的组织匹配起来。

## 设置 OpenID Connect

### 在你的身份提供商中

<Steps>
  <Step title="创建一个 Web 应用">
    创建一个类型为 **Web**（也叫*机密客户端*，confidential client）的新 OIDC 应用，并启用 **Authorization Code** 授权模式。系统不使用隐式（implicit）授权模式。
  </Step>

  <Step title="注册两个重定向 URI">
    将以下两个地址都添加为允许的重定向（回调）URI：

    ```text theme={"system"}
    https://auth-prod.portal.li.fi/login/callback
    https://lifi-prod.eu.auth0.com/login/callback
    ```
  </Step>

  <Step title="允许所需的 scope">
    授予 `openid`、`profile` 和 `email` scope。ID 令牌中必须包含 `email` 声明（claim）。
  </Step>

  <Step title="将 initiate-login 和 sign-out URL 留空">
    门户不使用 initiate-login URI 或 sign-out URL，将它们留空即可。
  </Step>

  <Step title="复制凭据">
    记下 **Client ID**、**Client Secret**，以及你的提供商的 discovery URL，其格式为 `https://<your-idp>/.well-known/openid-configuration`。
  </Step>
</Steps>

### 在 Partner Portal 中

<Steps>
  <Step title="打开 SSO 设置">
    进入 **Settings → Single sign-on**，选择 **OpenID Connect** 作为协议。
  </Step>

  <Step title="输入 discovery URL">
    将你的提供商的 `/.well-known/openid-configuration` URL 粘贴到 **Discovery URL** 中。issuer、签名密钥和各个 endpoint 都会从该 URL 解析得出。
  </Step>

  <Step title="输入凭据">
    填写 **Client ID** 和 **Client Secret**。保存后该密钥不会再次显示；只有在轮换密钥时才需要重新填写新值。
  </Step>

  <Step title="添加你的邮箱域名">
    在 **Email domains** 下，每行输入一个域名。邮箱匹配的成员会被路由到你的身份提供商。
  </Step>

  <Step title="保存">
    点击 **Save**。然后按照[选择 SSO 模式](#choose-an-sso-mode)启用 SSO。
  </Step>
</Steps>

<Note>
  同一页面上的 **Service provider metadata** 卡片（SP Entity ID、ACS URL、SAML metadata URL）仅适用于 SAML。使用 OIDC 时可以忽略它。
</Note>

## 设置 SAML 2.0

### 复制服务提供商信息

<Steps>
  <Step title="打开 SSO 设置">
    进入 **Settings → Single sign-on**，选择 **SAML 2.0** 作为协议。
  </Step>

  <Step title="从 Service provider metadata 中复制各项值">
    该卡片显示你组织的 **SP Entity ID**、**Assertion Consumer Service（ACS）URL** 和 **SAML metadata URL**。它们的格式如下，其中 `org-<your-org-id>` 是你组织专属的标识：

    ```text theme={"system"}
    SP Entity ID       urn:auth0:lifi-prod:org-<your-org-id>
    ACS URL            https://auth-prod.portal.li.fi/login/callback?connection=org-<your-org-id>
    SAML metadata URL  https://auth-prod.portal.li.fi/samlp/metadata?connection=org-<your-org-id>
    ```

    请从你自己的设置页面复制这些值，而不要直接使用本示例中的内容。
  </Step>
</Steps>

### 在你的身份提供商中

<Steps>
  <Step title="创建一个 SAML 2.0 应用">
    如果你的提供商支持通过 metadata URL 导入，粘贴 **SAML metadata URL** 后其余字段会自动填充。否则，请将 **SP Entity ID** 填入 audience 字段，并将 **ACS URL** 填入单点登录或 reply URL 字段。
  </Step>

  <Step title="将 Name ID 设置为用户的邮箱">
    使用邮箱地址作为 Name ID，格式选择 `emailAddress`。
  </Step>

  <Step title="添加属性声明（attribute statements）">
    添加一个名为 `email` 的属性，承载用户的邮箱地址。你也可以选择性地添加 `given_name` 和 `family_name`，分别对应用户的名和姓。

    <Warning>
      仅有 Name ID 是不够的。如果你的身份提供商没有以属性形式发送邮箱，成员将在没有邮箱地址的情况下被创建，从而无法使用门户。
    </Warning>
  </Step>

  <Step title="下载 IdP metadata">
    大多数提供商会为该应用提供 metadata XML 文件或 URL。请下载它，或者记下 **Entity ID**、**sign-in URL** 和 **X.509 签名证书**。
  </Step>
</Steps>

### 返回 Partner Portal

<Steps>
  <Step title="粘贴 IdP metadata XML">
    将身份提供商提供的完整 metadata XML 粘贴到 **IdP metadata XML** 中。保存后，下方的字段会根据该 metadata 自动填充。

    如果你没有 metadata 文件，可以手动填写 **IdP Entity ID**、**IdP Sign-in URL** 和 **X.509 签名证书**（PEM 格式，需包含 `BEGIN CERTIFICATE` 和 `END CERTIFICATE` 行）。**IdP Sign-out URL** 为可选项。
  </Step>

  <Step title="映射属性">
    将 **Email attribute** 设置为你的断言（assertion）中承载邮箱的属性名，默认值为 `email`。你也可以选择性地设置 **First name attribute** 和 **Last name attribute**。
  </Step>

  <Step title="添加你的邮箱域名">
    在 **Email domains** 下，每行输入一个域名。
  </Step>

  <Step title="保存">
    点击 **Save**。然后按照[选择 SSO 模式](#choose-an-sso-mode)启用 SSO。
  </Step>
</Steps>

<a id="choose-an-sso-mode" />

## 选择 SSO 模式

**SSO mode** 卡片控制你组织成员的登录方式。

| 模式           | 行为                            |
| ------------ | ----------------------------- |
| **Disabled** | 仅支持标准登录。SSO 已配置但未启用。          |
| **Optional** | 成员可以选择通过 SSO 或密码登录。适合在推广阶段使用。 |
| **Required** | 成员必须通过 SSO 登录，该组织的密码登录会被禁用。   |

我们建议按以下步骤推广：

1. 保存你的连接配置，并切换到 **Optional** 模式。
2. 让一名成员通过你的身份提供商登录，确认连接可用。
3. 切换到 **Required** 模式。

<Warning>
  在 **Required** 模式下，你组织中的所有成员从下次登录开始都必须通过你的身份提供商登录，且邮箱与你的域名匹配的任何人都会被自动重定向过去。请先在 Optional 模式下测试连接。
</Warning>

## 故障排查

<AccordionGroup>
  <Accordion title="“IdP-Initiated login is not enabled for connection …”">
    成员是从你的身份提供商一侧发起的登录，例如点击了 Okta 或 Entra 的应用磁贴。请改为从 [portal.li.fi](https://portal.li.fi/) 开始登录，或使用设置页面中的 **SSO sign-in link**。

    在 Okta 中，你可以打开该应用的 **General** 设置，将 **Login initiated by** 设为 *Either Okta or App*，勾选 **Redirect to app to initiate login (SP-initiated)**，并将 **Login URL** 设置为 `https://portal.li.fi`，从而让该磁贴可以正常使用。
  </Accordion>

  <Accordion title="输入邮箱后没有跳转到我们的身份提供商">
    自动跳转仅在 **Required** 模式下发生。在 **Optional** 模式下，请在密码输入框下方选择 **Continue with SSO**，或者将模式切换为 Required。
  </Accordion>

  <Accordion title="“An error occurred during the authorization flow”（OIDC）">
    你的身份提供商拒绝了该请求。请检查该应用上是否已注册两个重定向 URI，以及是否已启用 **Authorization Code** 授权模式。
  </Accordion>

  <Accordion title="“We couldn't finish your single sign-on”">
    你的身份提供商返回的账户无法与你的组织匹配。请检查它释放的邮箱是否匹配你配置的某个 **Email domains**。如果匹配，请[联系 LI.FI 团队](https://li.fi/contact-us/)。
  </Accordion>

  <Accordion title="成员登录成功，但没有姓名或邮箱">
    对于 SAML，请检查属性声明以及 **Email attribute**、**First name attribute**、**Last name attribute** 的映射设置。对于 OIDC，请确保该应用已授予 `profile` 和 `email` scope。
  </Accordion>
</AccordionGroup>

## 后续步骤

<CardGroup cols={2}>
  <Card title="Partner Portal changelog" icon="list" href="/changelog/partner-portal">
    跟踪 Partner Portal 的新增功能与更新。
  </Card>

  <Card title="联系 LI.FI 团队" icon="envelope" href="https://li.fi/contact-us/">
    为你的组织申请 SSO，或获取设置方面的帮助。
  </Card>
</CardGroup>