feishu-auth

Description

The feishu-auth Plugin authenticates requests using the Feishu (Lark) OAuth 2.0 authorization flow. Users are redirected to the Feishu login page when unauthenticated. After a successful login, Feishu user information is stored in an encrypted session cookie and optionally forwarded to upstream services via the X-Userinfo header.

Attributes

Name	Type	Required	Default	Description
app_id	string	True		Feishu application App ID.
app_secret	string	True		Feishu application App Secret.
secret	string	True		Secret used for signing the session cookie (8–32 characters). Must remain stable across restarts.
auth_redirect_uri	string	True		Redirect URI registered in the Feishu application for the OAuth flow.
redirect_uri	string	True		URI to redirect the user to when no authorization code is present (i.e. to start the OAuth flow).
code_header	string	False	"X-Feishu-Code"	HTTP header name to extract the Feishu authorization code from.
code_query	string	False	"code"	Query parameter name to extract the Feishu authorization code from.
access_token_url	string	False	"https://open.feishu.cn/open-apis/authen/v2/oauth/token"	URL to exchange the authorization code for an access token.
userinfo_url	string	False	"https://open.feishu.cn/open-apis/authen/v1/user_info"	URL to retrieve user information using the access token.
set_userinfo_header	boolean	False	true	When enabled, sets the X-Userinfo request header with Base64-encoded Feishu user information.
cookie_expires_in	integer	False	86400	Validity duration (in seconds) for the session cookie.
secret_fallbacks	array	False		List of fallback secrets used during key rotation.
timeout	integer	False	6000	Timeout (in milliseconds) for HTTP requests to Feishu endpoints.
ssl_verify	boolean	False	true	When enabled, verifies the SSL certificate when connecting to Feishu endpoints.

note

The fields app_secret, secret, and secret_fallbacks are encrypted and stored in etcd. See encrypted storage fields for more information.

Enable Plugin

You can enable the Plugin on a specific Route as shown below:

note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

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

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/api/*",
    "plugins": {
        "feishu-auth": {
            "app_id": "cli_xxxxxxxxxx",
            "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "secret": "my-session-secret",
            "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
        }
    }
}'

How It Works

The authentication flow proceeds as follows:

1. A user visits a Route protected by feishu-auth.
2. If no valid session cookie exists and no authorization code is present, the plugin generates a random state, stores it in the session cookie, and redirects the user to redirect_uri with HTTP 302, appending state to the query string. Your application should then redirect the user to the Feishu OAuth authorization page, passing state through so that Feishu returns it on the callback.
3. After the user authorizes, Feishu redirects back to auth_redirect_uri with an authorization code. The plugin extracts the code either from the code_query query parameter or the code_header HTTP header.
4. A code taken from the query string must arrive with the state bound to the session, otherwise the plugin responds with HTTP 401. This ties the code to the browser that started the flow. A code taken from the code_header HTTP header is exempt, since such requests come from non-browser clients.
5. The plugin exchanges the code for an access token at access_token_url, then fetches user information from userinfo_url.
6. User information is stored in an encrypted session cookie (feishu_session). Subsequent requests with a valid cookie bypass the OAuth flow.
7. If set_userinfo_header is true, the plugin encodes the user information as Base64 JSON and sets it in the X-Userinfo request header before forwarding to the upstream.

Delete Plugin

To remove the feishu-auth Plugin, delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/api/*",
    "plugins": {},
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:8080": 1
        }
    }
}'