项目的 SAML 2.0 单点登录

Supabase Auth 支持面向企业的单点登录（SSO），适用于任何兼容 SAML 2.0 协议的身份提供商。以下是部分支持的身份提供商列表：

🌐 Supabase Auth supports enterprise-level Single Sign-On (SSO) for any identity providers compatible with the SAML 2.0 protocol. This is a non-exclusive list of supported identity providers:

• Google 工作区（前称 G 套件）
• Okta，Auth0
• 微软活动目录、Azure 活动目录、Microsoft Entra
• PingIdentity
• OneLogin

如果你在使用不在此列表中的身份提供者软件时遇到问题，提交支持请求。

🌐 If you're having issues with identity provider software not on this list, open a support ticket.

先决条件 #

🌐 Prerequisites

本指南需要使用 Supabase CLI。确保你使用的是 v1.46.4 或更高版本。你可以使用 supabase -v 查看当前安装的版本。你可以使用 supabase sso 子命令 来管理你的项目配置。

🌐 This guide requires the use of the Supabase CLI. Make sure you're using version v1.46.4 or higher. You can use supabase -v to see the currently installed version. You can use the supabase sso subcommands to manage your project's configuration.

Supabase 项目默认禁用 SAML 2.0 支持。你可以在项目的 身份验证提供商 页面上进行配置。

🌐 SAML 2.0 support is disabled by default on Supabase projects. You can configure this on the Auth Providers page on your project.

请注意，SAML 2.0 支持仅在 Pro 及以上计划中提供。查看更多信息，请查阅定价页面。

🌐 Note that SAML 2.0 support is offered on plans Pro and above. Check the Pricing page for more information.

术语 #

🌐 Terminology

SAML 和 SSO 的缩略词数量常常令人眼花缭乱。这里有一个词汇表，你可以随时参考：

🌐 The number of SAML and SSO acronyms can often be overwhelming. Here's a glossary which you can refer back to at any time:

• 身份提供者、IdP 或 IDP 身份提供者是一种管理公司或组织用户账户的服务。它可以验证用户身份，并将这些信息与你的 Supabase 项目和其他应用交换。它作为用户身份和访问权限的唯一可信来源。常用的身份提供者包括：Microsoft Active Directory（Azure AD、Microsoft Entra）、Okta、Google Workspaces（G Suite）、PingIdentity、OneLogin 等等。还有自托管和本地部署的身份提供者，有时候只有通过公司 VPN 或在特定架构内才能访问。
• 服务提供商，SP 这是向身份提供者请求用户信息的软件。在 Supabase 中，这就是你项目的认证服务器。
• 声明 声明是由身份提供者发布的、包含有关用户信息的陈述。
• EntityID 一个全球唯一的 ID（通常是 URL），用来在全世界范围内识别身份提供者或服务提供者。
• NameID 一个独特的ID（通常是电子邮件地址），用于在身份提供者处识别用户。
• 元数据 一个描述身份提供者或服务提供者特性和配置的 XML 文档。它可以作为独立文档存在，也可以作为一个网址。通常（但不总是）EntityID 是你可以访问元数据的那个网址。
• 证书 Supabase Auth（服务提供商）会根据身份提供者附在声明上的签名来信任该声明。签名会根据元数据中存在的证书进行验证。
• 断言消费者服务（ACS）URL 这是最重要的 SAML URL 之一。它是 Supabase Auth 接收身份提供者断言的 URL。基本上，一旦身份提供者验证了用户的身份，它就会重定向到这个 URL，并且重定向请求中会包含断言。
• 绑定（重定向、POST 或工件） 这是对身份提供者与 Supabase Auth 之间通信方式的描述。使用重定向绑定时，通信通过 HTTP 301 重定向进行。当是 POST 时，它使用在页面上带有 <form> 元素的 POST 请求。使用工件时，它通过重定向或 POST 进行更安全的交换。
• RelayState Supabase Auth 用来保存验证用户身份请求信息的状态。

重要的 SAML 2.0 信息 #

🌐 Important SAML 2.0 information

下面是关于你项目的 SAML 2.0 配置信息，你可以将它分享给你正在尝试加入的公司或组织。

🌐 Below is information about your project's SAML 2.0 configuration which you can share with the company or organization that you're trying to on-board.

请注意，目前 Supabase Auth 不支持 SLO（单点注销），因为这是身份提供商很少支持的功能。不过，该 URL 已注册并将在功能可用时提供。SLO 是一种尽力而为的服务，所以我们建议考虑使用 会话时间限制或会话不活跃超时 来强制你的终端用户定期认证。

🌐 Note that SLO (Single Logout) is not supported at this time with Supabase Auth as it is a rarely supported feature by identity providers. However, the URL is registered and advertised for when this does become available. SLO is a best-effort service, so we recommend considering Session Timebox or Session Inactivity Timeout instead to force your end-users to authenticate regularly.

在元数据 URL 后添加 ?download=true 来下载元数据 XML 文件。这在身份提供者需要文件的情况下很有用。

🌐 Append ?download=true to the Metadata URL to download the Metadata XML file. This is useful in cases where the identity provider requires a file.

或者，你可以使用 supabase sso info --project-ref <your-project> 命令 来获取你项目的设置信息。

🌐 Alternatively, you can use the supabase sso info --project-ref <your-project> command to get setup information for your project.

用户账户和身份 #

🌐 User accounts and identities

通过单点登录（SSO）创建的用户账户和身份在以下方面与普通（邮箱、电话、密码、社交登录等）账户不同：

🌐 User accounts and identities created via SSO differ from regular (email, phone, password, social login...) accounts in these ways:

• 不进行身份关联。 每个通过 SSO 身份提供者验证的用户账户出于安全原因无法与现有用户账户进行身份关联。也就是说，如果用户 valid.email@supabase.io 用密码注册过，然后使用公司 SSO 登录你的项目，系统中就会出现两个 valid.email@supabase.io 用户账户。
• 电子邮件地址不一定是唯一的。 鉴于没有身份关联的情况，电子邮件地址不再是用户账号的唯一标识符。始终使用用户的 UUID 来正确引用用户账号。
• 会话可能有最长时长。 根据身份提供者的配置，通过 SSO 建立的登录会话可能会在一段时间后强制让用户退出。

行级安全 #

🌐 Row Level Security

你可以在行级安全策略中使用关于SSO身份提供者的信息。

🌐 You can use information about the SSO identity provider in Row Level Security policies.

这里有一些常用的语句，用来从用户的 JWT 中提取 SSO 相关信息：

🌐 Here are some commonly used statements to extract SSO related information from the user's JWT:

• auth.jwt()#>>'{amr,0,method}' 返回用来验证该用户身份的最后一个方法的名称。在 SAML 单点登录中，这是 sso/saml。
• auth.jwt()#>>'{amr,0,provider}' 返回用户用于登录的单点登录身份提供者的 UUID。
• auth.jwt()#>>'{user_metadata,iss}' 返回身份提供者的 SAML 2.0 EntityID

SSO 的一个常见用例是使用身份提供者的 UUID 作为用户所属组织的标识——通常称为租户。通过将身份提供者的 UUID 与你的租户关联，你可以使用限制性的 RLS 策略来缩小用户可以访问的操作和数据范围。

🌐 A common use case with SSO is to use the UUID of the identity provider as the identifier for the organization the user belongs to -- frequently known as a tenant. By associating the identity provider's UUID with your tenants, you can use restrictive RLS policies to scope down actions and data that a user is able to access.

例如，假设你有一张像这样的表格：

🌐 For example, say you have a table like:

1
create table organization_settings (
2
  -- the organization's unique ID
3
  id uuid not null primary key,
4
  -- the organization's SSO identity provider
5
  sso_provider_id uuid unique,
6
  -- name of the organization
7
  name text,
8
  -- billing plan (paid, Free, Enterprise)
9
  billing_plan text
10
);

你可以使用用户 JWT 中的信息来缩小用户可以查看的表格行范围，而无需进行任何额外的用户管理：

🌐 You can use the information present in the user's JWT to scope down which rows from this table the user can see, without doing any additional user management:

1
CREATE POLICY "View organization settings."
2
  ON organization_settings
3
  AS RESTRICTIVE
4
  USING (
5
    sso_provider_id = (select auth.jwt()#>>'{amr,0,provider}')
6
  );

管理 SAML 2.0 连接 #

🌐 Managing SAML 2.0 connections

一旦你通过控制台的 Auth Providers 页面在项目上启用了 SAML 2.0 支持，你就可以使用 Supabase CLI 来添加、更新、移除和查看身份提供者的信息。

🌐 Once you've enabled SAML 2.0 support on your project via the Auth Providers page in the dashboard, you can use the Supabase CLI to add, update, remove and view information about identity providers.

添加连接 #

🌐 Add a connection

要连接到 SAML 2.0 身份提供者 (IdP)，你需要：

🌐 To establish a connection to a SAML 2.0 Identity Provider (IdP) you will need:

• 一个 SAML 2.0 元数据 XML 文件，或者指向 XML 文件的 SAML 2.0 元数据 URL
• （可选）组织 IdP 使用的邮箱域名
• (可选) IdP 用户属性与 Supabase Auth 存储的声明之间的属性映射

你应该从你想要连接的组织的身份提供商（IdP）那里获取 SAML 2.0 元数据 XML 文件或 URL。大多数 SAML 2.0 身份提供商都支持元数据 URL 标准，如果有可用的 URL，我们建议使用它。

🌐 You should obtain the SAML 2.0 Metadata XML file or URL from the organization whose IdP you wish to connect. Most SAML 2.0 Identity Providers support the Metadata URL standard, and we recommend using a URL if this is available.

常用的支持元数据 URL 的 SAML 2.0 身份提供商：

🌐 Commonly used SAML 2.0 Identity Providers that support Metadata URLs:

• okta
• Azure AD（微软 Entra）
• PingIdentity

常用的仅支持元数据 XML 文件的 SAML 2.0 身份提供者：

🌐 Commonly used SAML 2.0 Identity Providers that only support Metadata XML files:

• 谷歌工作区（G 套件）
• 任何位于 VPN 后面的自托管或本地身份提供者

一旦你获得了 SAML 2.0 元数据 XML 文件或 URL，你就可以通过运行以下命令与项目的 Supabase Auth 服务器建立连接：

🌐 Once you've obtained the SAML 2.0 Metadata XML file or URL you can establish a connection with your project's Supabase Auth server by running:

1
supabase sso add --type saml --project-ref <your-project> \
2
  --metadata-url 'https://company.com/idp/saml/metadata' \
3
  --domains company.com

如果你想改用元数据 XML 文件，可以使用：

🌐 If you wish to use a Metadata XML file instead, you can use:

1
supabase sso add --type saml --project-ref <your-project> \
2
  --metadata-file /path/to/saml/metadata.xml \
3
  --domains company.com

这个命令会在你的项目身份验证服务器上注册一个新的身份提供者。成功后，你会看到提供者的详细信息，比如它的 SAML 信息和注册的域名。

🌐 This command will register a new identity provider with your project's Auth server. When successful, you will see the details of the provider such as it's SAML information and registered domains.

请注意，只有拥有项目写入权限的人才能注册、更新或删除身份提供者。

🌐 Note that only persons with write access to the project can register, update or remove identity providers.

一旦你添加了身份提供者，有权访问它的用户就可以登录你的应用。使用 SAML 2.0，有两种方式供用户登录你的项目：

🌐 Once you've added an identity provider, users who have access to it can sign in to your application. With SAML 2.0 there are two ways that users can sign in to your project:

• 通过从你应用的用户界面登录，通常称为服务提供商 (SP) 发起流程
• 点击公司内联网应用菜单或身份提供者页面上的图标，这通常被称为身份提供者发起（IdP）流程

要从你的应用的用户界面发起登录请求（即 SP 发起的流程），你可以使用：

🌐 To initiate a sign-in request from your application's user interface (i.e. the SP Initiated Flow), you can use:

1
supabase.auth.signInWithSSO({
2
  domain: 'company.com',
3
})

了解属性映射 #

🌐 Understanding attribute mappings

当用户使用 SAML 2.0 单点登录协议登录时，一个叫做 SAML 断言的 XML 文档会在身份提供者和 Supabase Auth 之间交换。

🌐 When a user signs in using the SAML 2.0 Single Sign-On protocol, an XML document called the SAML Assertion is exchanged between the identity provider and Supabase Auth.

这个声明包含关于用户身份和其他认证信息的信息，例如：

🌐 This assertion contains information about the user's identity and other authentication information, such as:

• 用户的唯一ID（在SAML中称作 NameID）
• 电子邮件地址
• 用户的名字
• 部门或组织
• 由身份提供者管理的用户目录中存在的其他属性

除了唯一的用户ID之外，SAML在声明中不要求任何其他属性。身份提供者可以配置为只与你的项目共享特定的用户信息。

🌐 With exception of the unique user ID, SAML does not require any other attributes in the assertion. Identity providers can be configured so that only select user information is shared with your project.

你的项目可以配置为识别这些属性，并使用 JSON 结构将它们映射到你项目的数据库中。这个过程叫做属性映射，并且会根据身份提供者的配置而有所不同。

🌐 Your project can be configured to recognize these attributes and map them into your project's database using a JSON structure. This process is called attribute mapping, and varies according to the configuration of the identity provider.

例如，下面的 JSON 结构配置了 email 和 first_name 用户身份属性的属性映射。

🌐 For example, the following JSON structure configures attribute mapping for the email and first_name user identity properties.

1
{
2
  "keys": {
3
    "email": {
4
      "name": "mail"
5
    },
6
    "first_name": {
7
      "name": "givenName"
8
    }
9
  }
10
}

在使用 Supabase CLI 创建或更新身份提供者时，你可以通过 --attribute-mapping-file /path/to/attribute/mapping.json 标志将这个 JSON 作为文件包含进去。

🌐 When creating or updating an identity provider with the Supabase CLI you can include this JSON as a file with the --attribute-mapping-file /path/to/attribute/mapping.json flag.

例如，要更改现有提供者的属性映射，你可以使用：

🌐 For example, to change the attribute mappings to an existing provider you can use:

1
supabase sso update <provider-uuid> --project-ref <your-project> \
2
  --attribute-mapping-file /path/to/attribute/mapping.json

假设有一个包含以下属性的 SAML 2.0 声明：

🌐 Given a SAML 2.0 assertion that includes these attributes:

1
<saml:AttributeStatement>
2
  <!-- will be mapped to the email key -->
3
  <saml:Attribute
4
    Name="mail"
5
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
6
    >
7
    <saml:AttributeValue xsi:type="xs:string">
8
      valid.email@supabase.io
9
    </saml:AttributeValue>
10
  </saml:Attribute>
11
12
  <!-- will be mapped to the first_name key -->
13
  <saml:Attribute
14
    Name="givenName"
15
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
16
    >
17
    <saml:AttributeValue xsi:type="xs:string">
18
      Jane Doe
19
    </saml:AttributeValue>
20
  </saml:Attribute>
21
</saml:AttributeStatement>

将在数据库和 JWT 中导致用户身份出现以下声明：

🌐 Will result in the following claims in the user's identity in the database and JWT:

1
{
2
  "email": "valid.email@supabase.io",
3
  "custom_claims": {
4
    "first_name": "Jane Doe"
5
  }
6
}

如果你只需要访问用户的邮箱，Supabase Auth 不需要指定属性映射。它会尝试在断言中找到指定的邮箱属性。其他所有属性不会自动包含，而那些才是你需要映射的。

🌐 Supabase Auth does not require specifying attribute mappings if you only need access to the user's email. It will attempt to find an email attribute specified in the assertion. All other properties will not be automatically included, and it is those you need to map.

目前不可能有没有电子邮件地址的用户，所以没有电子邮件地址的 SAML 断言会被拒绝。

🌐 At this time it is not possible to have users without an email address, so SAML assertions without one will be rejected.

大多数 SAML 2.0 身份提供者使用轻量级目录访问协议（LDAP）属性名称。不过，由于这些属性的多样性和复杂性，身份提供者的运算符可以自定义发送到 Supabase Auth 断言中的 Name 和属性值。请参考身份提供者的文档，并联系运算符了解你的项目中映射了哪些属性。

🌐 Most SAML 2.0 identity providers use Lightweight Directory Access Protocol (LDAP) attribute names. However, due to their variability and complexity operators of identity providers are able to customize both the Name and attribute value that is sent to Supabase Auth in an assertion. Refer to the identity provider's documentation and contact the operator for details on what attributes are mapped for your project.

访问存储的属性

存储的属性一旦映射，就会显示在用户的访问令牌（JWT）中。如果你需要在数据库中查询这些值，可以在 auth.identities 表的 identity_data JSON 列中找到它们。为 SSO 提供商创建的身份在 provider 列中有 sso:<uuid-of-provider>，而 id 列包含用户账户的唯一 NameID。

🌐 The stored attributes, once mapped, show up in the access token (a JWT) of the user. If you need to look these values up in the database, you can find them in the auth.identities table under the identity_data JSON column. Identities created for SSO providers have sso:<uuid-of-provider> in the provider column, while id contains the unique NameID of the user account.

此外，你也可以在 auth.users 里的 raw_user_meta_data 找到相同的身份数据。

🌐 Furthermore, you can find the same identity data under raw_user_meta_data inside auth.users.

高级属性映射

如果 SAML 断言包含某个键的多个值，比如用户可以访问的组，系统只会选取第一个值。要更改此行为，需要将该键标记为数组。例如这个属性映射：

🌐 If the SAML assertion contains multiple values for a key, such as the groups that the user has access to, only the first one will be picked up. To change this behavior, mark the key as an array. For example this attribute mapping:

1
{
2
  "keys": {
3
    "groups": {
4
      "name": "groups",
5
      "array": true
6
    }
7
  }
8
}

将导致以下索赔：

🌐 Will result in the following claims:

1
{
2
  "groups": ["group-a", "group-b", "group-c"]
3
}

你也可以为 SAML 声明中可能缺失的键指定一个默认值。

🌐 You can also specify a default value for a key that may be missing in the SAML assertion.

1
{
2
  "keys": {
3
    "custom_claim": {
4
      "name": "custom_claim",
5
      "default": 123
6
    }
7
  }
8
}

有些 SAML 断言可能会为不同的用户以不同的名称暴露相同的属性。在这种情况下，你可以不指定单个名称来查找值，而是可以指定多个名称。这些名称将按顺序查找，直到找到值为止：

🌐 Some SAML Assertions may expose the same attribute under different names for different users. In this case instead of specifying a single name to look up the value, you can specify multiple names. These will be looked at in-order until a value is found:

1
{
2
  "keys": {
3
    "custom_claim": {
4
      "names": ["first-look-for-this-attribute", "then-this-one"]
5
    }
6
  }
7
}

删除连接 #

🌐 Remove a connection

一旦与身份提供者建立了连接，你可以通过运行以下命令来移除它：

🌐 Once a connection to an identity provider is established, you can remove it by running:

1
supabase sso remove <provider-id> --project-ref <your-project>

如果成功，被移除的身份提供者的详细信息将会显示出来。来自该身份提供者的所有用户账户将会立即登出。用户信息仍会保留在系统中，但即使你再次添加该连接，这些账户以后将无法再访问。

🌐 If successful, the details of the removed identity provider will be shown. All user accounts from that identity provider will be immediately logged out. User information will remain in the system, but it will no longer be possible for any of those accounts to be accessed in the future, even if you add the connection again.

可以通过运行以下命令显示所有已注册的身份提供者 列表:

🌐 A list of all registered identity providers can be displayed by running:

1
supabase sso list --project-ref <your-project>

更新连接 #

🌐 Update a connection

你可能想更新关于与 SAML 2.0 身份提供者连接的设置。

🌐 You may wish to update settings about a connection to a SAML 2.0 identity provider.

通常在以下情况下这是必要的：

🌐 Commonly this is necessary when:

• 加密密钥已轮换或已过期
• 元数据 URL 已更改，但身份提供者相同
• 其他 SAML 2.0 元数据属性有所更改，但它仍然是同一个身份提供者
• 你正在更新域或属性映射

你可以使用此命令来更新身份提供者的配置：

🌐 You can use this command to update the configuration of an identity provider:

1
supabase sso update <provider-id> --project-ref <your-project>

使用 --help 查看所有可用的标志。

🌐 Use --help to see all available flags.

无法更改身份提供者的唯一 SAML 标识符，也就是 EntityID。其他所有内容都可以更新。如果你的身份提供者的 SAML EntityID 已经更改，它会被视为新的身份提供者，你将需要像注册新连接一样重新注册它。

🌐 It is not possible to change the unique SAML identifier of the identity provider, known as EntityID. Everything else can be updated. If the SAML EntityID of your identity provider has changed, it is regarded as a new identity provider and you will have to register it like a new connection.

正在获取连接信息 #

🌐 Retrieving information about a connection

你总是可以使用以下方法获取所有已注册提供者的列表:

🌐 You can always obtain a list of all registered providers using:

1
supabase sso list --project-ref <your-project>

这个列表只会包含每个提供者的基本信息。要查看关于提供者的所有信息，你可以使用：

🌐 This list will only include basic information about each provider. To see all of the information about a provider you can use:

1
supabase sso show <provider-id> --project-ref <your-project>

如果需要，你可以使用 -o json 标志将信息以 JSON 格式输出。其他格式可能也受支持，使用 --help 查看所有可用选项。

🌐 You can use the -o json flag to output the information as JSON, should you need to. Other formats may be supported, use --help to see all available options.

价格 #

🌐 Pricing

$0.015 每个SSO MAU。只有超过订阅计划配额的使用才会收费。

有关费用如何计算的详细说明，请参阅管理每月活跃 SSO 用户使用情况。

🌐 For a detailed breakdown of how charges are calculated, refer to Manage Monthly Active SSO Users usage.

常见问题 #

🌐 Frequently asked questions

将你的应用发布到身份提供商的市场上 #

🌐 Publishing your application to an identity provider's marketplace

许多基于云的身份提供商都提供了一个市场，你可以在其中注册你的应用，以便客户轻松上手。当你使用 Supabase Auth 的 SAML 2.0 支持时，你可以将你的项目注册到任何一个这样的市场。

🌐 Many cloud-based identity providers offer a marketplace where you can register your application for easy on-boarding with customers. When you use Supabase Auth's SAML 2.0 support you can register your project in any one of these marketplaces.

请查阅每个基于云的身份提供商的相关文档，了解如何操作。一些常见的市场有：

🌐 Refer to the relevant documentation for each cloud-based identity provider on how you can do this. Some common marketplaces are:

• Okta 集成网络
• Azure Active Directory 应用图库
• Google 工作区预集成 SAML 应用目录

为什么有些用户会收到：SAML 断言不包含电子邮件地址？ #

🌐 Why do some users get: SAML assertion does not contain email address?

身份提供商不一定要返回用户的邮箱地址，尽管他们通常会这么做。Supabase Auth 要求必须有邮箱地址。

🌐 Identity providers do not have to send back and email address for the user, though they often do. Supabase Auth requires that an email address is present.

以下按出现顺序检查的常用 SAML 属性名列表，用于在断言中查找电子邮件地址：

🌐 The following list of commonly used SAML attribute names is inspected, in order of appearance, to discover the email address in the assertion:

• urn:oid:0.9.2342.19200300.100.1.3
• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
• http://schemas.xmlsoap.org/claims/EmailAddress
• mail
• email

最后，如果没有这样的属性，它将使用 SAML NameID 值，但仅当格式被标示为 urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress 时才会使用。

🌐 Finally if there is no such attribute, it will use the SAML NameID value but only if the format is advertised as urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

如果你遇到这个问题，很可能是身份提供方那边的配置错误。告诉你公司里的联系人，把用户的电子邮件地址映射到上面列出的某个属性名，通常是 email。

🌐 Should you run into this problem, it is most likely a misconfiguration issue on the identity provider side. Instruct your contact at the company to map the user's email address to one of the above listed attribute names, typically email.

访问项目中用于 SAML 的私钥 #

🌐 Accessing the private key used for SAML in your project

目前无法提取你项目的 Supabase Auth 服务器使用的 RSA 私钥。这样做是为了尽可能保证私钥的安全，因为 SAML 没有提供一个在不影响服务的情况下轻松更换密钥的方法。（出于这个原因，请尽量使用 SAML 2.0 元数据 URL！）

🌐 At this time it is not possible to extract the RSA private key used by your project's Supabase Auth server. This is done to keep the private key as secure as possible, given that SAML does not offer an easy way to rotate keys without disrupting service. (Use a SAML 2.0 Metadata URL whenever possible for this reason!)

如果你真的需要访问密钥，提交支持请求，我们会尽力为你提供帮助。

🌐 If you really need access to the key, open a support ticket and we'll try to support you as best as possible.

多租户 SSO 支持 SAML 吗？ #

🌐 Is multi-tenant SSO with SAML supported?

是的，Supabase 支持使用 SAML 2.0 实现多租户单点登录（SSO）。虽然仪表板上只显示一个 SAML 字段，但你可以使用 Supabase CLI 设置多个 SAML 连接。 每个连接都会分配一个唯一的 sso_provider_id，这个值会包含在用户的 JWT 中，并可以在行级安全（RLS）策略中使用。你还可以为每个连接配置自定义属性映射，以包含特定租户的信息，比如角色。 这种设置允许你在一个应用内为多个客户或组织实现多租户 SSO。例如，如果你的应用有多个客户使用不同的 Azure Active Directory，你可以为每个客户创建单独的 SAML 连接，并使用 sso_provider_id 来管理访问权限并应用相应的安全策略。

🌐 Yes, Supabase supports multi-tenant Single Sign-On (SSO) using SAML 2.0. While the dashboard displays only one SAML field, you can set up multiple SAML connections using the Supabase CLI. Each connection is assigned a unique sso_provider_id, which is included in the user's JWT and can be used in Row Level Security (RLS) policies. You can configure custom attribute mappings for each connection to include tenant-specific information, such as roles. This setup allows you to implement multi-tenant SSO for multiple clients or organizations within a single application. For example, if you have an app with multiple clients using different Azure Active Directories, you can create separate SAML connections for each and use the sso_provider_id to manage access and apply appropriate security policies.

多子域名的 SAML 单点登录支持吗？ #

🌐 Is multi-subdomain SSO with SAML supported?

是的，也称为同一站点内的跨源认证。要在 IdP 发回 SAML 响应后重定向到非站点 URL的地址，可以在signInWithSSO中添加redirectTo选项。

🌐 Yes, also referred to as cross-origin authentication within the same site. To redirect to a URL other than the Site URL, following the SAML response from the IdP, the redirectTo option can be added to signInWithSSO.

1
const { data, error } = await supabase.auth.signInWithSSO({
2
  domain: 'company.com',
3
  options: {
4
    redirectTo: `https://app.company.com/callback`,
5
  },
6
})

当重定向到站点 URL 以外的 URL 时，需要一个 /callback 端点来处理来自 IdP 的授权代码，并将其换成会话。这假设 Supabase SSR 客户端 已经配置好了。

🌐 When redirecting to a URL other than the Site URL, a /callback endpoint is necessary to process the auth code from the IdP and exchange it for a session. This assumes the Supabase SSR client has already been configured.

1
import { error, redirect } from '@sveltejs/kit'
2
3
import type { RequestHandler } from './$types'
4
5
export const GET: RequestHandler = async ({ url, locals }) => {
6
  const code = url.searchParams.get('code')
7
8
  if (!code) {
9
    error(400, 'No authorization code provided')
10
  }
11
12
  const { error: tokenExchangeError } = await locals.supabase.auth.exchangeCodeForSession(code)
13
14
  if (tokenExchangeError) {
15
    error(400, 'Failed to exchange authorization code for session')
16
  }
17
18
  redirect(303, '/')
19
}

为什么 IdP 发起的 SAML 流程不能和 PKCE 一起用，有什么替代方案？ #

🌐 Why doesn't IdP-initiated SAML flow work with PKCE, and what's the alternative?

传统的 IdP 发起的 SAML 流程不兼容 PKCE（代码交换验证），因为 PKCE 需要 code_challenge 和 code_verifier，而它们是在你的应用发起认证流程时生成的。在 IdP 发起的流程中，Supabase 会收到一个没有这些信息的非请求响应，导致代码交换步骤失败。

🌐 Traditional IdP-initiated SAML flows aren't compatible with PKCE (Proof Key for Code Exchange) because PKCE requires a code_challenge and code_verifier that are generated when your application initiates the authentication flow. In IdP-initiated flows, Supabase receives an unsolicited response without this information, causing the code exchange step to fail.

为了在保持 PKCE 安全性的同时实现相同的用户体验，你可以采用“书签应用”方法：

🌐 To achieve the same user experience while maintaining PKCE security, you can implement a "bookmark app" approach:

在你的应用中创建一个端点（例如，https://your-app.com/auth/saml-init），使用 signInWithSSO 发起 SAML 流程。然后在你的 IdP 中创建一个书签或关联应用，指向这个端点。当用户访问这个书签应用时，就会触发一个安全的 SP 发起流程。

🌐 Create an endpoint in your application (for example, https://your-app.com/auth/saml-init) that initiates the SAML flow using signInWithSSO. Then create a bookmark or linked application in your IdP that points to this endpoint. When users access the bookmark app, it triggers a secure SP-initiated flow.

这种方法支持自定义 SAML 声明，并让你可以在应用里的任何地方嵌入链接。

🌐 This approach supports custom SAML assertions and lets you embed the link anywhere in your application.