feat: add feishu-auth plugin

[AlinsRan]

What does this PR do?

Adds a new feishu-auth plugin that authenticates browser-based API requests using the Feishu (Lark) OAuth 2.0 authorization code flow.

Problem

Teams using Feishu (Lark) as their enterprise collaboration platform need a way to protect internal APIs and developer portals so that only authenticated Feishu users can access them — without building a custom auth layer in each upstream service.

Solution

The feishu-auth plugin handles the complete OAuth 2.0 authorization code flow at the gateway level:

1. An unauthenticated request hits a protected Route.
2. The plugin redirects the user to redirect_uri (your app's OAuth entry point) with HTTP 302.
3. Your app sends the user to the Feishu authorization page. After the user consents, Feishu redirects back with an authorization code.
4. The plugin exchanges the code for an access token at access_token_url, then fetches user information from userinfo_url.
5. User info is stored in an encrypted server-side session cookie (feishu_session, powered by resty.session v4). Subsequent requests with a valid cookie skip the OAuth round-trip entirely.
6. Optionally, the plugin Base64-encodes the user info and forwards it to the upstream in the X-Userinfo header.

Configuration attributes

Name	Type	Required	Default	Description
app_id	string	Yes		Feishu App ID.
app_secret	string	Yes		Feishu App Secret. Stored encrypted.
secret	string	Yes		Session signing secret (8–32 chars). Stored encrypted.
auth_redirect_uri	string	Yes		Redirect URI registered in the Feishu app for the OAuth callback.
redirect_uri	string	Yes		URI to redirect to when no auth code is present (to start the OAuth flow).
secret_fallbacks	array of string	No		Previous secrets kept during key rotation. Each element is encrypted at rest.
code_query	string	No	"code"	Query parameter name carrying the authorization code.
code_header	string	No	"X-Feishu-Code"	HTTP header name carrying the authorization code.
access_token_url	string	No	Feishu v2 token endpoint	URL to exchange the authorization code for an access token.
userinfo_url	string	No	Feishu v1 userinfo endpoint	URL to retrieve user information.
set_userinfo_header	boolean	No	true	Forward Base64-encoded user info to upstream in X-Userinfo.
cookie_expires_in	integer	No	86400	Session cookie validity in seconds.
timeout	integer	No	6000	HTTP request timeout (ms) for Feishu endpoints.
ssl_verify	boolean	No	true	Verify TLS certificates when calling Feishu endpoints.

Usage examples

Prerequisites

1. Create a Feishu app at open.feishu.cn and obtain the App ID and App Secret.
2. Add your OAuth callback URL (e.g. https://your-domain.com/api/callback) to the app's Redirect URLs list.

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

Example 1: Basic setup

Protect a route so only authenticated Feishu users can access it. After login, the user's Feishu profile is forwarded to the upstream via X-Userinfo.

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PUT -d '
{
  "uri": "/api/*",
  "plugins": {
    "feishu-auth": {
      "app_id": "cli_xxxxxxxxxx",
      "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "secret": "my-session-secret-1",
      "auth_redirect_uri": "https://your-domain.com/api/callback",
      "redirect_uri": "https://your-domain.com/oauth/feishu"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": { "127.0.0.1:8080": 1 }
  }
}'

The first time a browser hits /api/*:

• The plugin returns 302 to https://your-domain.com/oauth/feishu.
• The user logs in via Feishu and is redirected back to https://your-domain.com/api/callback?code=<auth-code>.
• The plugin exchanges the code, stores the session, and the upstream receives an X-Userinfo header with the Base64-encoded Feishu user profile:

{
  "open_id": "ou_8fc70d9ea27111749a71eb",
  "name": "Alice",
  "en_name": "Alice",
  "avatar_url": "https://...",
  "tenant_key": "1224d18e8d"
}

Subsequent requests with the session cookie bypass the OAuth flow entirely.

Example 2: Receive the auth code via HTTP header (non-browser clients)

For API clients that handle OAuth externally and pass the auth code as a header:

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PUT -d '
{
  "uri": "/api/*",
  "plugins": {
    "feishu-auth": {
      "app_id": "cli_xxxxxxxxxx",
      "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "secret": "my-session-secret-1",
      "auth_redirect_uri": "https://your-domain.com/api/callback",
      "redirect_uri": "/login",
      "code_header": "X-Feishu-Code",
      "set_userinfo_header": false
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": { "127.0.0.1:8080": 1 }
  }
}'

The client then authenticates by passing the code in the header:

curl http://your-gateway/api/resource -H "X-Feishu-Code: <auth-code>"

Example 3: Session secret rotation with secret_fallbacks

Rotate the session signing secret without invalidating existing user sessions.

Step 1 — promote the new secret, keep the old one as a fallback:

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PATCH -d '
{
  "plugins": {
    "feishu-auth": {
      "secret": "my-session-secret-2",
      "secret_fallbacks": ["my-session-secret-1"]
    }
  }
}'

New sessions are signed with my-session-secret-2. Existing sessions signed with my-session-secret-1 are still accepted and automatically re-signed with the new secret on next access.

Step 2 — once old sessions have expired, remove the fallback:

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PATCH -d '
{
  "plugins": {
    "feishu-auth": {
      "secret_fallbacks": []
    }
  }
}'

Changes

File	Description
apisix/plugins/feishu-auth.lua	Plugin implementation
apisix/cli/config.lua	Register plugin in default list (priority 2420)
conf/config.yaml.example	Register plugin at priority 2420
t/plugin/feishu-auth.t	Unit tests with mocked Feishu server (no external deps)
t/admin/plugins.t	Add feishu-auth to plugin list assertion
docs/en/latest/plugins/feishu-auth.md	English documentation
docs/zh/latest/plugins/feishu-auth.md	Chinese documentation
docs/en/latest/config.json	Add to EN nav
docs/zh/latest/config.json	Add to ZH nav

Related

• Similar plugins: cas-auth, authz-casdoor
• Feishu OAuth 2.0 overview

[Copilot]

Pull request overview

Adds a new feishu-auth authentication plugin for APISIX that integrates Feishu/Lark OAuth 2.0 login, session-cookie caching, and optional upstream forwarding of authenticated user info.

Changes:

• Implements the feishu-auth plugin and registers it in default plugin lists.
• Adds mock Feishu token/userinfo helpers and plugin tests.
• Adds English/Chinese documentation and navigation entries.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
apisix/plugins/feishu-auth.lua	Implements Feishu OAuth token exchange, userinfo retrieval, session handling, and upstream header injection.
apisix/cli/config.lua	Adds feishu-auth to the built-in plugin list.
conf/config.yaml.example	Adds feishu-auth to the example enabled plugin list.
t/admin/plugins.t	Adds feishu-auth to the admin plugin-list expectations.
t/lib/server.lua	Adds mock Feishu token and userinfo endpoints for tests.
t/plugin/feishu-auth.t	Adds route setup and authentication/session behavior tests.
docs/en/latest/plugins/feishu-auth.md	Adds English plugin documentation.
docs/zh/latest/plugins/feishu-auth.md	Adds Chinese plugin documentation.
docs/en/latest/config.json	Adds the English docs navigation entry.
docs/zh/latest/config.json	Adds the Chinese docs navigation entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.