# SAML Auth 配置选项

saml-auth 插件通过 Keycloak 等身份提供商，为 APISIX 和 API7 网关路由提供 SAML 2.0 单点登录和单点注销。<!-- --> <!-- -->配置涵盖插件参数。

## 参数[​](#参数 "参数的直接链接")

请参阅 [插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md) 了解所有插件可用的配置选项。

* 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`

  ***

  服务提供商为身份提供商的身份认证响应请求使用的绑定方式。插件会将此值作为 `ProtocolBinding` 放入 SAML `AuthnRequest`。初始身份认证请求始终通过 HTTP 重定向发送给身份提供商，并携带 `SAMLRequest` 查询参数；选择 `HTTP-POST` 不会将初始请求改成表单提交。API7 企业版 3.9.3 和 APISIX 3.17.0 引入此配置。

  设置为 `HTTP-Redirect` 时，身份提供商通过 GET 请求将身份认证响应返回到回调地址。插件不会针对这种绑定方式显式配置会话 Cookie 属性。

  设置为 `HTTP-POST` 时，身份提供商通过 POST 请求将身份认证响应返回到回调地址。插件会设置会话 Cookie 属性 `SameSite=None` 和 `Secure`，以支持跨站 POST。使用此绑定方式时请启用 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 中引入。
