feishu-auth

Authenticates users with a Feishu (Lark) account through OAuth.

Category AuthenticationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin feishu-authPriority 2420

What it does

feishu-auth lets staff sign in with their Feishu (Lark) account before their browser reaches the route's backend. The people live in Feishu, not on a consumer, and the gateway asks Feishu about them as the app under App ID and App secret. The Redirect URI is Feishu's own sign-in address, not an address of the gateway.

A browser without a session is answered 302 and sent to that sign-in address. Feishu sends it back with a code to a path the route serves, read from the query parameter under Code query or the header under Code header. Authentication explains callers who sign in at an identity provider.

When to use it

• Staff already sign in to Feishu at work, and an internal web application behind the gateway should accept the same account.
• A backend that has no sign-in of its own should be reached only by people who signed in with Feishu first.
• The backend needs to know who signed in, and reads the user's details from the header Set userinfo header adds.

Not for staff accounts kept in DingTalk — see dingtalk-auth (Authenticates users with a DingTalk account through OAuth), an OpenID Connect provider or bearer tokens on API calls — see openid-connect (Authenticates users against an OpenID Connect provider) or an API key a program sends on every call — see key-auth (Authenticates consumers with an API key sent in a header or query parameter).

Set it up

Let staff sign in with their Feishu account before they reach the service

A visitor without a session is sent to this address, Feishu's own sign-in page, which sends the browser back with the code to a path this route serves.

Under Basics set App ID to cli_a1b2c3d4e5f6, set App secret to <secret>, set Redirect URI to https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=cli_a1b2c3d4e5f6&redirect_uri=https%3A%2F%2Fapi.example.com%2Forders, set Auth redirect URI to https://api.example.com/orders and set Secret to <secret>. Under Behavior set Cookie expires in to 28800 seconds.

feishu-auth · as the console saves it

{
  "app_id": "cli_a1b2c3d4e5f6",
  "app_secret": "<secret>",
  "secret": "<secret>",
  "auth_redirect_uri": "https://api.example.com/orders",
  "redirect_uri": "https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=cli_a1b2c3d4e5f6&redirect_uri=https%3A%2F%2Fapi.example.com%2Forders",
  "cookie_expires_in": 28800
}

Things to know

• Redirect URI — A browser without a session is answered 302 with this address as its Location, followed by a &state= the gateway adds.
• Redirect URI — A request without an authorization code is redirected here, so write the provider's sign-in address. It never reaches the upstream.
• Auth redirect URI — Nothing is redirected here: this address only travels to the token endpoint, as the redirect the authorization code was issued for.
• Cookie expires in — Stored at zero, the session it opens has no lifetime limit at all and is closed only by its idling timeout.
• Secret — A secret shorter than 8 characters is refused when you save.
• Secret fallbacks — Each older secret follows the same lengths, and one longer than 32 characters is refused when you save.
• AdviceWhen you replace the Secret, keep the old one under Secret fallbacks until the sessions it signed have run out.
• On a consumer or a consumer group it runs only after the consumer has been identified by a credential; it does not identify the consumer itself.

Settings

The fields as the console shows them, section by section.

Basics

App IDapp_idstringRequired

at least 1 character

App secretapp_secretstringRequired

Stored on the engine and shown only to roles that manage this object.

at least 1 character

Redirect URIredirect_uristringRequired

at least 1 character

Auth redirect URIauth_redirect_uristringRequired

The redirect address registered in your Feishu app. It is sent with the code when the code is exchanged for a token.

SecretsecretstringRequired

The secret the session keys are derived from: a random value, the same on every node. Stored on the engine and shown only to roles that manage this object.

8 to 32 characters

Behavior

Set userinfo headerset_userinfo_headerbooleandefault true

Adds the signed-in user's details to the request as a header for the upstream.

Cookie expires incookie_expires_inintegerdefault 86400

How long the authorization cookie stays valid after it was created.

in seconds

Code headercode_headerstringdefault X-Feishu-Code

The request header the authorization code is read from.

at least 1 character

Code querycode_querystringdefault code

The query parameter the authorization code is read from.

at least 1 character

Timeouttimeoutintegerdefault 6000

at least 1 · in milliseconds

SSL verifyssl_verifybooleandefault true

Advanced

Access token URLaccess_token_urlstringdefault https://open.feishu.cn/open-apis/authen/v2/oauth/token

at least 1 character

Userinfo URLuserinfo_urlstringdefault https://open.feishu.cn/open-apis/authen/v1/user_info

at least 1 character

Secret fallbackssecret_fallbacksarray of strings

Older secrets a cookie may still be signed with while a new one rolls out. Stored on the engine and shown only to roles that manage this object.

each 8 to 32 characters

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.