dingtalk-auth

Authenticates users with a DingTalk account through OAuth.

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

What it does

dingtalk-auth lets staff sign in with their DingTalk account before their browser reaches the route's backend. The people live in DingTalk, not on a consumer, and the gateway asks DingTalk about them as the application under App key and App secret. The Redirect URI is DingTalk'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. DingTalk 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 DingTalk 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 DingTalk 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 Feishu — see feishu-auth (Authenticates users with a Feishu (Lark) 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 DingTalk account before they reach the service

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

Under Basics set App key to dingoa1b2c3d4e5f6, set App secret to <secret>, set Redirect URI to https://login.dingtalk.com/oauth2/auth?response_type=code&scope=openid&prompt=consent&client_id=dingoa1b2c3d4e5f6&redirect_uri=https%3A%2F%2Fapi.example.com%2Forders and set Secret to <secret>. Under Behavior set Cookie expires in to 28800 seconds.

dingtalk-auth · as the console saves it

{
  "app_key": "dingoa1b2c3d4e5f6",
  "app_secret": "<secret>",
  "secret": "<secret>",
  "redirect_uri": "https://login.dingtalk.com/oauth2/auth?response_type=code&scope=openid&prompt=consent&client_id=dingoa1b2c3d4e5f6&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.
• Secret — A secret shorter than 8 characters is refused when you save.
• Secret — A secret longer than 32 characters is refused when you save.
• Secret fallbacks — Each older secret follows the same lengths, and one shorter than 8 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 keyapp_keystringRequired

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

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.

at least 1 · in seconds

Code headercode_headerstringdefault X-DingTalk-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://api.dingtalk.com/v1.0/oauth2/accessToken

at least 1 character

Userinfo URLuserinfo_urlstringdefault https://oapi.dingtalk.com/topapi/v2/user/getuserinfo

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.