SAML（Security Assertion Markup Language，安全断言标记语言）是一种基于 XML 的标准，用于在不同的安全域之间交换身份验证和授权数据。它允许用户使用单一的凭据（如用户名和密码）访问多个相关的应用程序，而无需在每个应用程序中单独进行登录，这就是所谓的单点登录（SSO，Single Sign-On）。

SAML 的基本原理涉及三个主要角色：

身份提供者（IdP, Identity Provider）：负责验证用户的身份，并向服务提供者发送包含用户身份信息的断言。
服务提供者（SP, Service Provider）：依赖身份提供者进行用户身份验证，接收断言并根据断言中的信息决定是否授权用户访问其服务。
用户：请求访问服务提供者资源的个体。

当用户尝试访问服务提供者的资源时，服务提供者会将用户重定向到身份提供者进行身份验证。用户在身份提供者处完成登录后，身份提供者会生成一个包含用户身份信息的 SAML 断言，并将其发送回服务提供者。服务提供者验证断言的有效性后，允许用户访问其资源。

SSO方式比较

SSO接入方式	适应版本	配置方式	IdP发起登录	SP 发起登录	多个IdP	域名安全
整个站点	私有化/企业	管理后台	支持	支持	不支持	不支持
每个空间站	SaaS	空间站-安全设置	不支持	支持	支持	支持

站点级 SAML 配置（私有化部署版本）

在私有化部署版本中，站点级 SAML 配置允许管理员在整个站点范围内设置 SAML 单点登录。这意味着所有的空间站租户都可以继承这些配置，除非租户级有自己的特定配置覆盖。这种配置方式适用于希望在整个企业范围内统一管理 SAML 设置的场景。

适用场景:

基于数据安全考虑, 你使用的是私有化版本或企业版.
您希望Bika在您企业里仅限企业员工使用, 并且您也有员工统一登录系统, 只需通过登录验证即可使用Bika.
您想完全控制企业与Bika的通讯录数据同步,不想在Bika界面上再维护一套额外的通讯录结构.
您想自由实现Bika与内部其他系统的交互.

空间站租户级 SAML 配置

空间站租户级 SAML 配置允许每个租户根据自己的需求定制 SAML 设置。这在企业内部不同部门或业务单元有不同的身份验证要求时非常有用。租户级配置会覆盖站点级的通用配置，以满足租户的特定需求。

适用场景:

您期望在 Bika.ai 开启发起登录, 而不是直接访问您的IdP登录页面
您期望贵司内的员工都能使用公司IdP的员工邮箱账号登录使用 Bika.ai

配置站点级 SAML 配置

步骤1: 获取Bika的SP元数据文件

使用管理员账号密码登录bika站长管理后台: https://{您部署地址}/bika-admin

管理后台

未登录前提下在登录页点击“使用账户名继续”, 如何登录请参考“站长管理后台”章节

左边菜单点击“SSO配置”

点击以下“here”即可访问, 您也可以直接访问: https://{您部署地址}/api/site-admin/saml/metadata

步骤2: 配置企业IdP

当您在IdP方已完成配置, 将您的IdP必要信息填入“SSO配置”

EntityId: IdP标识, 必填
Sign-in URL: IdP的登录地址, 必填
X509 Certificate: IdP的SAML断言签名证书, 给SP端解析回调, 必填

步骤3: 配置身份匹配规则

当IdP方登录成功后SAML回调到SP方, NameID作为识别IdP方的员工唯一性, 规则介绍

Match Against: NameID的匹配规则,
- User Id: NameID与Bika系统的用户ID字段匹配
- Email Address: NameID与Bika系统的用户邮箱字段作为匹配
Action if User not match: 如果匹配不到用户, 您期望SP如何处理
- Create User: Bika将根据NameID数据格式自动创建用户
- Reject to redirect sign-in page: Bika不会创建用户, 直接拒绝并返回到IdP登录页重新登录

步骤4: 登录验证

以上配置后, 打开“Trun On”, 点击保存, 退出站长管理后台,重新进入系统

登录页会出现“Continue with Sign Sign On”按钮, 点击登录验证流程

配置Okta作为IdP(示例)

以下为您详细介绍以 Okta 作为 IDP（身份提供商）时，接入我们产品实现 SSO（单点登录）的配置流程。

一、Okta（IDP）端配置

登录 Okta 管理控制台：使用具有管理员权限的 Okta 账号登录到 Okta 管理控制台。
创建应用集成：
- 在管理控制台首页，点击 “Applications”（应用程序）选项卡。
- 点击 “Create App Integration”（添加应用程序）按钮。
- 选择“SAML 2.0” 作为连接类型，然后点击 “Next”（创建）。
配置 SAML 应用设置：
- General Settings（常规设置）：
  - 在 “App Name”（应用名称）字段，输入一个易于识别的名称，如我们产品的名称“Bika”。
  - 可选择上传产品图标，以便在 Okta 界面中更好区分。
- SAML Settings（SAML 设置）：
  - Single Sign On URL（单点登录 URL）：从SP元数据里获取产品的 SAML SP 单点登录回调 URL，将其填入此处。此 URL 用于 Okta 将用户认证信息发送回我们的产品。
  - Audience URI (SP Entity ID)（受众 URI（SP 实体 ID））：同样从SP元数据的 SAML SP EntityID字段值，填入该字段。这是产品在 SAML 通信中的唯一标识符。
  - Signature Certificate (签名证书): 从SP元数据里 X509Certificate 字段里复制该值并保存成 bika-sp.cert 证书文件, 然后上传验证。
  - Response: 由IDP 进行数字签名,设置为Signed。
打开Okta应用获取IdP配置:
- Issuer（颁发者）：在 “Sign On” 选项卡下，找到 “Issuer” 字段，此值即为 Okta 作为 IDP 的唯一标识，填入SSO配置的Entity Id
- Sign on URL：在 “Sign On” 选项卡下，找到 “Single Sign On URL”，复制该网址，这是用户登录时将跳转的 Okta 认证页面链接, 填入SSO配置的Sign-in URL
- Certificate（证书）：在 “Sign On” 选项卡中，点击 “Signing Certificate”后面的“Copy”复制证书内容, 粘贴到SSO配置的X509 Certificate。

点击确认：点击 “确认” 按钮，完成 IDP 信息配置。

二、用户登录验证

点击登录：在产品登录页面，点击 “登录” 按钮，系统将自动跳转到 Okta 的企业 SSO 登录界面。

完成登录：用户在此页面使用 Okta 账号及密码进行登录，登录成功后，将自动跳转回产品应用，用户即可顺利访问产品内的相关资源和服务，完成 SSO 单点登录流程。

通过以上详细的配置流程，企业能够便捷地将 Okta 作为 IDP 接入我们的产品，实现高效、安全的 SSO 单点登录功能，提升企业员工的办公体验和工作效率。

通过站点级 OpenAPI （site-admin OpenAPI)，预先写入企业自己的用户、空间站、通讯录组织结构、角色

完成上述操作后，企业内部的站点登录信息已成功打通。在这种情况下，通常用户登录时，系统会自动创建一个与企业绑定的账号。然而，在某些场景下，您可能有进一步的需求。

例如，您希望用户登录后，默认直接跳转到预先设置好的公司全员空间站，而非新注册用户默认分配的个人专属空间站。

API调用请查阅《使用站点级OpenAPI》章节

注册 outgoing-webhooks 事件，当企业员工变化，通知到 Bika.ai 的私有化部署版本，重写写入企业自己的用户、空间站、通讯录组织结构、角色

配置 Webhook：在企业的身份管理系统（如 Active Directory、Okta 等）中配置 outgoing-webhooks，当员工信息发生变化（如创建、更新、删除）时，向 Bika.ai 的私有化部署版本发送 HTTP POST 请求。
处理 Webhook 事件：
- 在私有化部署版本中，创建一个 Webhook 处理程序，监听来自企业身份管理系统的请求。
- 解析请求体中的员工变化信息，并根据这些信息调用站点级 OpenAPI 的相应端点，更新用户、空间站、通讯录组织结构和角色信息。
CallbackURL(Post) 请求体:

{
    "eventType": "BEFORE_MEMBER_JOINED",
    "member": {
        "spaceId": "join space id",
        "userId": "bika user id",
        "teamId": "want to joined team Id",
        "roleIds": "the role id list",
        "joinInfo": {
            "joinType": "LINK_INVITATION or EMAIL_INVITATION",
            "inviteToken": "when join type is LINK_INVITATION",
            "inviterUserId": "when join type is LINK_INVITATION",
            "email": "when join is EMAIL_INVITATION ",
            "emailInvitationId": "when join is EMAIL_INVITATION "
        }
    }
}

SaaS 版 SAML 配置

本功能正在施工中

SaaS 版配置流程