完整文档索引见 llms.txt。在页面 URL 后附加 .md 即可获取 Markdown 版本；本页的 Markdown 版本可在此获取。

SAML SSO 设置

SAML SSO 设置相关操作

获取 SAML SSO 配置

获取当前 SAML SSO 配置，包括界面中提供的所有字段，以及服务提供方实体 ID 和 ACS 返回 URL。读取时会遮蔽签名私钥、签名证书和身份提供方元数据。需要 `saml:manage` 作用域，并获得 SAML 功能许可。

GET/settings/sso/saml

响应

状态码	说明
200	操作成功。
401	未授权
403	禁止访问

响应结构：200 · application/json

字段	类型	必填	说明
entityID	string	是	服务提供方实体 ID，即元数据 URL。 只读。
returnUrl	string	是	断言消费服务（ACS）返回 URL。 只读。
mapping	object	是	SAML 属性到 n8n 用户字段的映射。 展开字段 字段 类型 必填 说明 mapping.email string 是 映射到用户邮箱的 SAML 属性。 mapping.firstName string 是 映射到用户名字的 SAML 属性。 mapping.lastName string 是 映射到用户姓氏的 SAML 属性。 mapping.userPrincipalName string 是 映射到用户主体名称的 SAML 属性。 mapping.emailVerified string 是 表明身份提供方是否已验证用户邮箱的 SAML 属性；未使用时为空字符串。 mapping.n8nInstanceRole string 是 映射到 n8n 实例角色的 SAML 属性。 mapping.n8nProjectRoles array 是 映射到 n8n 项目角色的 SAML 属性，格式为 <projectId>:<role>。
metadata	string	是	XML 格式的身份提供方元数据。由于包含 IdP 证书，已设置时会在读取时遮蔽，绝不以明文返回。未设置时使用空字符串。
metadataUrl	string	是	获取身份提供方元数据的 URL；未设置时使用空字符串。
ignoreSSL	boolean	是	通过 URL 获取元数据时，是否忽略 SSL 证书错误。
loginBinding	string	是	SAML 登录请求的绑定方式。 可选值：redirect, post
loginEnabled	boolean	是	是否启用 SAML 登录。
loginLabel	string	是	SAML 登录按钮显示的标签。
authnRequestsSigned	boolean	是	是否对身份验证请求签名。
wantAssertionsSigned	boolean	是	是否要求断言带有签名。
wantMessageSigned	boolean	是	是否要求 SAML 消息带有签名。
emailVerifiedRequired	boolean	是	按邮箱将登录关联到现有用户之前，是否要求身份提供方断言用户邮箱已验证。关闭时，只有明确的否定断言会被拒绝。
signingPrivateKey	string	是	用于签署 SAML AuthnRequests 的 PEM 编码私钥。已设置时，读取会遮蔽，绝不以明文返回。未设置时使用空字符串。
signingCertificate	string	是	PEM 编码证书，包含与签名私钥匹配的公钥。已设置时，读取会遮蔽，绝不以明文返回。未设置时使用空字符串。
acsBinding	string	是	断言消费服务的绑定方式。 可选值：redirect, post
signatureConfig	object	是	SAML 请求与响应中的签名配置。 展开字段 字段 类型 必填 说明 signatureConfig.prefix string 是 signatureConfig.location object 是 展开字段 字段 类型 必填 说明 signatureConfig.location.reference string 是 signatureConfig.location.action string 是 可选值：before, after, prepend, append
relayState	string	是	SAML 请求的默认 relay state 值；未设置时使用空字符串。

下载完整 OpenAPI 定义（JSON）

设置 SAML SSO 配置

使用提供的完整对象替换 SAML SSO 配置。必须发送所有可写字段；未设置的值使用空字符串或空数组。若包含 GET 返回的只读 `entityID` / `returnUrl`，写入时会忽略，因此可以将 GET 响应作为 PUT 请求体提交。已遮蔽的密钥占位符会使已存储值保持不变。更新使用与界面相同的校验，并以相同方式生效。需要 `saml:manage` 作用域，并获得 SAML 功能许可。配置通过环境变量管理时，写入会以 409 拒绝，且不作任何更改。

PUT/settings/sso/saml

请求体

application/json

字段	类型	必填	说明
mapping	object	是	SAML 属性到 n8n 用户字段的映射；未使用的属性填写空字符串或空数组。 展开字段 字段 类型 必填 说明 mapping.email string 是 映射到用户邮箱的 SAML 属性。 mapping.firstName string 是 映射到用户名字的 SAML 属性。 mapping.lastName string 是 映射到用户姓氏的 SAML 属性。 mapping.userPrincipalName string 是 映射到用户主体名称的 SAML 属性。 mapping.emailVerified string 是 表明身份提供方是否已验证用户邮箱的 SAML 属性。接受 true 和 false，不区分大小写。未使用时填写空字符串。 mapping.n8nInstanceRole string 是 映射到 n8n 实例角色的 SAML 属性；未使用时填写空字符串。 mapping.n8nProjectRoles array 是 映射到 n8n 项目角色的 SAML 属性，格式为 <projectId>:<role>。未使用时填写空数组。
metadata	string	是	XML 格式的身份提供方元数据。使用空字符串可清除已存储元数据；未提供 URL 时，还会清除 metadataUrl。使用先前 GET 返回的遮蔽占位符，可保持现有值不变。
metadataUrl	string	是	获取身份提供方元数据的 URL；使用空字符串可清除已存储的 URL。
ignoreSSL	boolean	是	通过 URL 获取元数据时，是否忽略 SSL 证书错误。
loginBinding	string	是	SAML 登录请求的绑定方式。 可选值：redirect, post
loginEnabled	boolean	是	是否启用 SAML 登录。
loginLabel	string	是	SAML 登录按钮显示的标签。
authnRequestsSigned	boolean	是	是否对身份验证请求签名。
wantAssertionsSigned	boolean	是	是否要求断言带有签名。
wantMessageSigned	boolean	是	是否要求 SAML 消息带有签名。
emailVerifiedRequired	boolean	是	按邮箱将登录关联到现有用户之前，是否要求身份提供方断言用户邮箱已验证。关闭时，只有明确的否定断言会被拒绝。
signingPrivateKey	string	是	用于签署 SAML AuthnRequests 的 PEM 编码私钥。使用空字符串可清除现有密钥，使用先前 GET 返回的遮蔽占位符可保持不变。
signingCertificate	string	是	PEM 编码证书，包含与签名私钥匹配的公钥。未使用时，或要清除现有证书时，填写空字符串。
acsBinding	string	是	断言消费服务的绑定方式。 可选值：redirect, post
signatureConfig	object	是	SAML 请求与响应中的签名配置。 展开字段 字段 类型 必填 说明 signatureConfig.prefix string 是 signatureConfig.location object 是 展开字段 字段 类型 必填 说明 signatureConfig.location.reference string 是 signatureConfig.location.action string 是 可选值：before, after, prepend, append
relayState	string	是	SAML 请求的默认 relay state 值；未使用时填写空字符串。
entityID	string	否	服务提供方实体 ID。GET 为方便使用而返回此值；写入时忽略，因此可以将 GET 响应作为 PUT 请求体提交。
returnUrl	string	否	断言消费服务返回 URL。GET 为方便使用而返回此值；写入时忽略，因此可以将 GET 响应作为 PUT 请求体提交。

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
409	冲突
415	不支持的媒体类型。

响应结构：200 · application/json

字段	类型	必填	说明
entityID	string	是	服务提供方实体 ID，即元数据 URL。 只读。
returnUrl	string	是	断言消费服务（ACS）返回 URL。 只读。
mapping	object	是	SAML 属性到 n8n 用户字段的映射。 展开字段 字段 类型 必填 说明 mapping.email string 是 映射到用户邮箱的 SAML 属性。 mapping.firstName string 是 映射到用户名字的 SAML 属性。 mapping.lastName string 是 映射到用户姓氏的 SAML 属性。 mapping.userPrincipalName string 是 映射到用户主体名称的 SAML 属性。 mapping.emailVerified string 是 表明身份提供方是否已验证用户邮箱的 SAML 属性；未使用时为空字符串。 mapping.n8nInstanceRole string 是 映射到 n8n 实例角色的 SAML 属性。 mapping.n8nProjectRoles array 是 映射到 n8n 项目角色的 SAML 属性，格式为 <projectId>:<role>。
metadata	string	是	XML 格式的身份提供方元数据。由于包含 IdP 证书，已设置时会在读取时遮蔽，绝不以明文返回。未设置时使用空字符串。
metadataUrl	string	是	获取身份提供方元数据的 URL；未设置时使用空字符串。
ignoreSSL	boolean	是	通过 URL 获取元数据时，是否忽略 SSL 证书错误。
loginBinding	string	是	SAML 登录请求的绑定方式。 可选值：redirect, post
loginEnabled	boolean	是	是否启用 SAML 登录。
loginLabel	string	是	SAML 登录按钮显示的标签。
authnRequestsSigned	boolean	是	是否对身份验证请求签名。
wantAssertionsSigned	boolean	是	是否要求断言带有签名。
wantMessageSigned	boolean	是	是否要求 SAML 消息带有签名。
emailVerifiedRequired	boolean	是	按邮箱将登录关联到现有用户之前，是否要求身份提供方断言用户邮箱已验证。关闭时，只有明确的否定断言会被拒绝。
signingPrivateKey	string	是	用于签署 SAML AuthnRequests 的 PEM 编码私钥。已设置时，读取会遮蔽，绝不以明文返回。未设置时使用空字符串。
signingCertificate	string	是	PEM 编码证书，包含与签名私钥匹配的公钥。已设置时，读取会遮蔽，绝不以明文返回。未设置时使用空字符串。
acsBinding	string	是	断言消费服务的绑定方式。 可选值：redirect, post
signatureConfig	object	是	SAML 请求与响应中的签名配置。 展开字段 字段 类型 必填 说明 signatureConfig.prefix string 是 signatureConfig.location object 是 展开字段 字段 类型 必填 说明 signatureConfig.location.reference string 是 signatureConfig.location.action string 是 可选值：before, after, prepend, append
relayState	string	是	SAML 请求的默认 relay state 值；未设置时使用空字符串。

下载完整 OpenAPI 定义（JSON）