# Feishu Auth 配置选项

feishu-auth 插件支持飞书 OAuth 2.0 身份认证，允许客户端在访问上游资源前通过飞书账号完成认证，增强 API 安全性。<!-- --> <!-- -->配置涵盖插件参数。

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

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

* app\_id

  string

  必填

  ***

  飞书应用 ID（client ID）。

* app\_secret

  string

  必填

  ***

  飞书应用密钥（client secret）。

  该密钥在存入数据库之前会通过 AES 加密。你也可以将其保存在环境变量中并通过 `env://` 前缀引用，或保存在 HashiCorp Vault 的 [KV secrets engine](https://developer.hashicorp.com/vault/docs/secrets/kv) 等密钥管理服务中，通过 `secret://` 前缀引用。更多信息请参阅 [密钥](https://docs.apiseven.com/apisix/key-concepts/secrets.md)。

* auth\_redirect\_uri

  string

  必填

  ***

  在飞书注册的 OAuth 回调重定向 URI，需与你在飞书应用设置中配置的重定向 URI 一致。飞书完成认证后会携带授权码重定向到该地址。

* redirect\_uri

  string

  必填

  ***

  用户被重定向进行身份认证的 URI。请勿在 URI 中预设 `state`；插件会生成随机 `state`，保存到会话并自动追加到该 URI。使用查询参数返回授权码时，回调必须携带相同的 `state`，否则插件返回 `401 Invalid state`；通过 `code_header` 提供授权码时不校验 `state`。详见 [构造授权链接](https://open.feishu.cn/document/sso/web-application-end-user-consent/guide#9948213f)。

* secret

  string

  必填

  有效值：

  8 到 32 个字符

  ***

  用于会话密钥派生和 Cookie 加密的密钥。该密钥应为强随机字符串以保障安全。

  该值在存入数据库之前会通过 AES 加密。

* secret\_fallbacks

  array\[string]

  ***

  用于密钥轮换期间会话校验的备用密钥列表，使主密钥更新后由旧密钥创建的现有会话仍然有效。

* code\_header

  string

  默认值：`X-Feishu-Code`

  ***

  用于提取授权码的请求头名称。若请求头与查询参数同时提供，请求头优先。

* code\_query

  string

  默认值：`code`

  ***

  用于提取授权码的查询参数名称。当飞书在查询字符串中通过授权码回跳时使用。

* access\_token\_url

  string

  默认值：`https://open.feishu.cn/open-apis/authen/v2/oauth/token`

  ***

  用于使用授权码换取访问 Token 的飞书 OAuth Token 端点 URL。

* userinfo\_url

  string

  默认值：`https://open.feishu.cn/open-apis/authen/v1/user_info`

  ***

  用于使用访问 Token 获取用户信息的飞书用户信息端点 URL。

* set\_userinfo\_header

  boolean

  默认值：`true`

  ***

  如果为 `true`，则在转发到上游服务的请求中设置 `X-Userinfo` 请求头，其中包含 Base64 编码的飞书用户信息。

* timeout

  integer

  默认值：`6000`

  ***

  调用飞书 API 时 HTTP 请求的超时时间（毫秒），同时适用于 Token 交换和用户信息获取请求。

* ssl\_verify

  boolean

  默认值：`true`

  ***

  如果为 `true`，则在调用飞书 API 时验证 SSL 证书。

* cookie\_expires\_in

  integer

  默认值：`86400`

  ***

  会话 Cookie 的过期时间（秒）。Cookie 在该时长内保持有效。
