指南

通过 SAML 2.0 集成，轻松为您的组织启用集中式单点登录 (Single Sign-On)。您组织的成员可以使用他们的工作电子邮件登录 Ostorlab。

SAML Integration Overview

如需特定示例，请参阅我们的集成指南之一：

Azure Active Directory

Google Workspace

Okta

OneLogin

术语

IdP 代表身份提供商 (Identity Provider)。IdP 是充当用户目录的服务。
SP 代表服务提供商 (Service Provider)。服务提供商依靠身份提供商进行身份验证。
IdP Metadata XML 是您的 IdP 提供的 XML 配置文件。它包含有关您的用户目录的公共信息，服务提供商可以使用该信息来发出身份验证请求。

配置属性

使用 IdP 设置 SAML SSO 时，以下是您实际需要配置的仅有属性。

名称	其他名称	必需
Single sign on URL	AssertionConsumerService (ACS) URL	是
Entity ID	Metadata 或 Audience URL	是
Default relay state	Start 或 Application Start URL	否
Name identifier format	Name Identifier, Name, Name ID format	是

实体 ID

必需

Entity ID (SP) 是一个 URL，服务提供商在此处发布有关其 SAML 配置的公共信息。服务提供商发布的元数据文档显示其公共证书，该证书可用于验证从服务本身发起的身份验证请求的签名。

注意：IdP 也有一个 Entity ID。但是，IdP 的 Entity ID 用于唯一标识该 IdP 中的特定租户/组织。当您配置 SAML SSO 时，几乎总是要求您输入 SP Entity ID，这将特定于您在 Ostorlab 中的组织。

断言消费者服务 (ACS) URL / 单点登录 URL

必需

这是 IdP 可以 POST SAML 断言 (SAML assertions) 的 URL。

断言消费者服务绑定

必需

标识 ACS 支持的协议绑定。绑定描述了 IdP（或在某些情况下为浏览器）如何打包断言和任何包含内容以供 ACS 使用。

Name ID 格式

必需

Name ID format 是您的 SAML SSO 配置中最重要的方面之一。它定义了身份提供商如何识别下游服务上的用户。格式的值定义了用户主题 (Subject) 将使用什么值。

重要提示：一旦配置了您的 Name ID format 并且您的用户已开始使用 SSO，请勿更改名称标识符。这将阻止您的用户能够登录。

(默认) 中继状态

Relay State 是一个 URL，它本身作为身份提供商发起的 SSO 请求中的查询参数传递。这是一个可选属性。这也称为深度链接 (deep-linking)。这允许用户通过从身份提供商本身启动应用程序直接导航到下游服务。

使用方法：

配置您的 SAML 集成：

点击侧边栏按钮
点击 Integrations/API 展开
点击 Integrations
点击 SAML 集成

从 Saml 集成菜单中，选择配置 (configuration) 选项卡并填写以下值： SAML Configuration Tab

Idp Identifier : URI - IdP 实体的标识符：例如 https://your_domain.com/saml/metadata/connector_id
SAML 2.0 Endpoint : 身份验证请求消息 (Authentication Request Message) 将发送到的 IdP 目标 URL； 例如， https://your_domain.com/saml2/http-post/sso/connector_id
X.509 Certificate : IdP 的公共 X.509 证书。

在您的 SAML 标识符配置中，请确保为 Ostorlab 的服务提供商 (Service provider of Ostorlab) 使用以下设置：

Entity Id：https://api.ostorlab.co/saml/metadata/
AssertionConsumerService URL：https://api.ostorlab.co/saml/acs/?org=<organisation_prefix>

URL 中的 <organisation_prefix> 是您必须输入 Ostorlab 组织前缀的位置。您可以在组织的设置页面中找到组织的前缀。
Assertion Consumer Service Binding：urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
NameIDFormat：urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

对于现有帐户，用户必须将身份提供商列入白名单 (whitelist)，以允许使用 SSO 登录。要执行此操作：

转到帐户安全 (Account security) 菜单。
在 Single Sign-On 子菜单中，从受支持的身份提供商列表中选择组织。

没有现有帐户的新访问将自动配置具有对 SSO 组织的适当访问权限的新帐户。

故障排除

尝试保存 IdP 提供的元数据 XML 时出现验证错误

IdP 提供的元数据 XML 包含多个 XML 元素，其中 <IDPSSODescriptor> 是与 Ostorlab 相关的元素。在 IDPSSODescriptor 中，我们期望看到一个有效的 KeyDescriptor 公钥证书、一个 NameIDFormat、一个在 IdP 中标识您的组织的 Entity ID，以及一个 SSO 绑定 (SSO binding)。

失败通常是由于以下原因之一造成的：

XML 格式错误
IDPSSODescriptor 中的 KeyDescriptor 公钥证书已过期
IDPSSODescriptor 中缺少 KeyDescriptor 公钥证书
NameIDFormat 没有预期值或完全缺失。请参阅下一个故障排除主题以获取有关此操作的帮助。

提示：OneLogin 具有一套免费的 SAML 相关工具。

Name ID Format 无效

如 Name ID Format 部分所述，Ostorlab 期望您的 IdP 元数据 XML 中有特定值。使用 One Login 的 XML Pretty Print 来格式化您的 XML，并在 <IDPSSODescriptor> XML 元素下查找 <NameIDFormat>。

如果找不到名为 NameIDFormat 的元素，请紧接在 KeyDescriptor 的结束标签之后添加以下行：

<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>

这是一个示例元数据 XML。请注意，为简洁起见，删除了一些值。

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="...">
  <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      ....
    </md:KeyDescriptor>
    <!--
        在此示例中，所有元素的命名空间均为 `md`。这就是为什么 NameIDFormat 具有前缀 `md:` 的原因。
        如果您 XML 中的元素没有前缀，那么您可以跳过它。
    -->
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="..."/>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="..."/>
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

在 XML 中找不到 SSO 绑定。请联系您的 SSO 提供商。

当您尝试保存的元数据 XML 在 <IDPSSODescriptor> 下没有产生任何 <SingleSignOnService> 元素时，会发生此错误。Ostorlab 使用 <SingleSignOnService> 来确定 IDP 支持的身份验证机制。从 Wikipedia 了解有关 SAML 2.0 绑定 (SAML 2.0 Bindings) 的更多信息。您必须联系您的 IdP 支持人员或系统管理员以修复元数据 XML。

这是 HTTP-POST 的 SSO 绑定的示例：

<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="..."/>

注意：Location 属性对于您的 IDP 中的每个租户 (tenant) 都是唯一的。