跳到主要内容

参数​

请参阅 插件通用配置 了解所有插件可用的配置选项。

  • sp_issuer

    string

    必填

    服务提供商（SP）的实体 ID。请将其配置为与身份提供商（IdP）上的 SAML 客户端 ID 相同。

  • idp_uri

    string

    必填

    身份提供商（IdP）的 SAML 端点，插件会向该端点发送身份认证和注销请求。

  • idp_cert

    string

    必填

    身份提供商（IdP）的 PEM 格式 X.509 签名证书。插件使用该证书验证已签名的 SAML 响应。

  • login_callback_uri

    string

    必填

    身份认证后，身份提供商（IdP）向其发送 SAML 响应的 URI 路径。

    请配置受保护路由能够匹配的路径。例如，路由 URI 为 /anything/* 时可使用 /anything/login_callback。

  • logout_uri

    string

    必填

    触发 SAML 注销过程的 URI 路径。

    请配置受保护路由能够匹配的路径。例如，路由 URI 为 /anything/* 时可使用 /anything/logout。

  • logout_callback_uri

    string

    必填

    身份提供商（IdP）向其发送 SAML 注销响应的 URI 路径。

    请配置受保护路由能够匹配的路径。例如，路由 URI 为 /anything/* 时可使用 /anything/logout_callback。

  • logout_redirect_uri

    string

    必填

    单点注销完成后，插件将浏览器重定向到的 URI。

    如果用户应保持注销状态，请使用公开路由。重定向到受同一插件保护的路径会启动新的身份认证流程。

  • sp_cert

    string

    必填

    服务提供商（SP）的 PEM 格式 X.509 证书。身份提供商（IdP）使用该证书验证插件签名的请求。

  • sp_private_key

    string

    必填

    与 sp_cert 对应的 PEM 格式私钥。插件使用该私钥签署身份认证和注销请求。

    该值在存储到数据库前会使用 AES 加密。

  • secret

    string

    必填

    有效值：

    8 到 32 个字符

    用于派生 SAML 会话数据加密密钥的加密密钥。请在每个网关节点上配置相同的值，以确保会话在跨节点访问和重新加载后仍然有效。

    该值在存储到数据库前会使用 AES 加密。

    API7 企业版 3.9.3 和 APISIX 3.17.0 引入此配置。

  • auth_protocol_binding_method

    string

    默认值：HTTP-Redirect

    有效值：

    HTTP-Redirect 或 HTTP-POST

    身份认证请求使用的 SAML 绑定方式。API7 企业版 3.9.3 和 APISIX 3.17.0 引入此配置。

    设置为 HTTP-Redirect 时，插件通过浏览器重定向发送身份认证请求。

    设置为 HTTP-POST 时，插件通过 HTML 表单发送身份认证请求，并将会话 Cookie 属性设置为 SameSite=None 和 Secure。使用此绑定方式时请启用 HTTPS。

  • secret_fallbacks

    array[string]

    密钥轮换期间接受的旧会话密钥。请在 secret 中配置新值，并在旧会话过期前将上一个值保留在此处。

    该值在存储到数据库前会使用 AES 加密。

    API7 企业版 3.9.3 和 APISIX 3.17.0 引入此配置。

  • idp_issuers

    array[string]

    登录响应中可接受的颁发者（issuer）。响应中的每个断言都必须声明其中之一。

    未设置时，接受由 idp_cert 证书签名的任意颁发者。空列表不接受任何颁发者。

    该字段在 API7 企业版 3.9.21、3.10.8 和 APISIX 3.19.0 中引入。

  • sp_acs_url

    string

    有效值：

    以 http:// 或 https:// 开头的绝对 URL

    断言消费服务（ACS）的外部绝对 URL，即身份提供商（IdP）投递登录响应的地址，也就是 login_callback_uri 的公开 URL。

    插件会在身份认证请求中将该 URL 告知 IdP。断言的 Recipient 以及响应中存在的 Destination 必须与其一致。

    未设置时，该 URL 根据回调请求的 scheme 和 host 构建，并会参考 Forwarded、X-Forwarded-Proto 和 X-Forwarded-Host 请求头。如果网关位于终止 TLS 但不设置 X-Forwarded-Proto、会改写 host 或不规范化转发请求头的代理之后，请设置此参数。

    该字段在 API7 企业版 3.9.21、3.10.8 和 APISIX 3.19.0 中引入。

  • sp_audiences

    array[string]

    服务提供商（SP）接受的受众（audience）。携带 AudienceRestriction 的断言必须声明其中之一。不携带 AudienceRestriction 的断言不受限制。

    未设置时，唯一接受的受众为 sp_issuer 的值。

    该字段在 API7 企业版 3.9.21、3.10.8 和 APISIX 3.19.0 中引入。

  • clock_skew

    number

    默认值：60

    有效值：

    大于或等于 0

    校验断言的 NotBefore 和 NotOnOrAfter 条件时，允许与身份提供商（IdP）之间存在的时钟偏差，单位为秒。

    该字段在 API7 企业版 3.9.21、3.10.8 和 APISIX 3.19.0 中引入。

  • replay_dict

    string

    用于记录网关已接受断言的 lua_shared_dict 名称。记录仍有效时，字典中已经存在的断言会被拒绝。未设置时不记录断言。

    网关默认声明了 plugin-saml-auth-replay 共享字典（10m）用于此目的，其大小可在网关配置文件的 nginx_config.http.lua_shared_dict 下修改。

    记录按网关实例保存，不在实例之间共享。

    如果字典已满，登录仍可能成功，但不会记录其断言。请监控警告，并按预期登录量设置字典大小；这不能在集群范围内保证防止重放。

    该字段在 API7 企业版 3.9.21、3.10.8 和 APISIX 3.19.0 中引入。

  • replay_ttl

    number

    默认值：600

    有效值：

    大于或等于 1

    记录条件或可用 Subject Confirmation 中没有过期时间的断言的时长，单位为秒。其他断言会记录到无法再被接受的时间，再加上 clock_skew。保留时间上限为一天或 replay_ttl，取两者中较大的值。

    仅在设置了 replay_dict 时生效。

    该字段在 API7 企业版 3.9.21、3.10.8 和 APISIX 3.19.0 中引入。