1. Project Overview

The expected outcome of this small project is to allow Directus to support logging in with DingTalk accounts. After understanding the OAuth2 protocol (see the previous blog post, reference 1), we have enough knowledge to implement this. Directus natively supports GitHub login, so the approach is to start with GitHub. Follow these steps:

  • Configure Directus to use GitHub account login to get familiar with Directus’s standard OAuth support
  • Configure Directus to use DingTalk account login; since DingTalk’s protocol implementation differs from RFC6749/GitHub, we may need to handle issues as they arise
  • Deploy Directus to the server environment and verify on both DingTalk PC and mobile versions

2. Environment Configuration

Use ngrok locally to expose a service to receive OAuth server redirects.

ngrok http 8055

Get https://445a-240e-47c-30b0-3b10-600e-ea25-cde5-2334.ngrok.io/ as the public domain to access the local port 8055 where directus is running.

3. Directus GitHub Login

Configure parameters according to reference material 2. In the following configuration, for each new GitHub authorized user, Directus will automatically create a Directus user using the user’s email during the login process and assign it the role AUTH_GITHUB_DEFAULT_ROLE_ID.

A A A A A A A A A A # # U U U U U U U U U U T T T T T T T T T T A A H H H H H H H H H H U U _ _ _ _ _ _ _ _ _ _ T T P G G G G G G G G G H H R I I I I I I I I I _ _ O T T T T T T T T T G G V H H H H H H H H H I I I U U U U U U U U U T T D B B B B B B B B B H H E _ _ _ _ _ _ _ _ _ U U R D C C A A P A D I B B S R L L U C R L E C _ _ = I I I T C O L F O E I " V E E H E F O A N M D g E N N O S I W U = A E i R T T R S L _ L " I N t = _ _ I _ E P T g L T h " I S Z U _ U _ i _ I u o D E E R U B R t K F b a = C _ L R L O h E I " u " R U = L I L u Y E t 7 E R " = C E b = R h e T L h " _ _ " " _ 2 . = = t h R I e K " . " " t t E D m E . d h p t G = a Y . 5 t s p I " i = a . t : s S 0 l " e . p / : T f " e " . s / / R 5 m . : g / A f a . i a T 1 i . t p I b l . g h i O 5 " d i u . N a 9 t b g = - " h . i " 1 u c t t 0 b o h r 6 . m u u f c b e - l . " 4 m c e g o c l i m 7 o n - g u a i o s 8 n a e b / u r 8 o t " - a h 6 u / f t a 1 h c 1 / c 4 a e 8 u s 2 t s a h _ 0 o t 6 r o 0 i k f z e " e n " "

After restarting Directus to apply the configuration, you can see the GitHub option on the login page. picture 1

After selecting and authorizing, you can successfully log in to Directus. Check that the newly generated user and permissions in Directus are normal. picture 2

4. Attempting Directus DingTalk Login

First, try to configure it similar to GitHub.

A A A A A A A A A A # # U U U U U U U U U U A A T T T T T T T T T T U U H H H H H H H H H H T T _ _ _ _ _ _ _ _ _ _ H H P D D D D D D D D D _ _ R I I I I I I I I I D D O N N N N N N N N N I I V G G G G G G G G G N N I T T T T T T T T T G G D A A A A A A A A A T T E L L L L L L L L L A A R K K K K K K K K K L L S _ _ _ _ _ _ _ _ _ K K = D C C A A P A D I _ _ " R L L U C R L E C E I g I I I T C O L F O M D i V E E H E F O A N A E t E N N O S I W U = I N h R T T R S L _ L " L T u = _ _ I _ E P T a _ I b " I S Z U _ U _ l K F , o D E E R U B R i E I a = C _ L R L O p Y E d u " R U = L I L a = R i t d E R " = C E y " _ n h i T L h " _ _ " e K g 2 n = = t h R I m E t " g " " t t E D a Y a . c h p t G = i = l . 6 t s p I " l " k . r t : s S 0 " e " t C p / : T f m x T s / / R 5 a t . : a / A f i " . p a T 1 l . / i p I b " h l . i O 5 4 o d . N a o g i d = - h i n i " 1 K n g n t 0 l . t g r 6 q d a t u f 5 i l a e - o n k l " 4 z g . k e " t c . c a o c 7 l m - k m a . v / 8 c 1 v b o . 1 8 m 0 . - / 0 6 o / f a a c 1 u u o 1 t t n 4 h h t 8 2 2 a 2 / / c a a u t 0 u s / 6 t e u 0 h r s f " A e " c r c s e / s m s e T " o k e n "

picture 3

Clicking Log In with DingTalk authorizes normally, but after authorization it redirects to:

/ a d m i n / l o g i n ? r e a s o n = I N V A L I D _ U S E R

Suspect that the URL redirected back from DingTalk doesn’t have a code parameter (refer to the previous article about protocol analysis - DingTalk uses authCode parameter). First, I opened an issue in the community to see if anyone else has encountered this.

At the same time, I made a temporary patch to the oauth2 driver. When there’s an authCode, assign it to code.

    try {
        res.clearCookie(`oauth2.${providerName}`);

        if ( req.query.authCode) {
            req.query.code = req.query.authCode
        }

        if (!req.query.code || !req.query.state) {
            logger.warn(`[OAuth2] Couldn't extract OAuth2 code or state from query: ${JSON.stringify(req.query)}`);
        }

        authResponse = await authenticationService.login(providerName, {
            code: req.query.code,
            codeVerifier: verifier,
            state: req.query.state,
        });
    } catch (error: any) {
        ...

After restarting directus again, the patch seemed to work. This time it redirected to:

/ a d m i n / l o g i n ? r e a s o n = S E R V I C E _ U N A V A I L A B L E

The first step of the OAuth2 protocol (getting the code) has passed. Is SERVICE_UNAVAILABLE a problem with getting the token or getting the profile?

I noticed that in the request to get the token from DingTalk, the parameter names are clientId, clientSecret. While GitHub uses client_id, client_secret. Additionally, DingTalk requires an extra grantType.

{ } " " " " c c c g l l o r i i d a e e e n n n " t t t T I S : y d e p " c " e r 6 " : e b t 4 : " " 2 d 7 " i : e a n 8 u g " b t y f h y o a o o u b r u r 8 i r 3 z s e a i e 9 t d c 3 i " r b o , e e n t d _ " d c , 1 o 3 d f e 1 " 6 a 4 3 0 7 0 2 " ,

Configure clientId, clientSecret, and grantType as parameters in the directus request.

A U T H _ D I N G T A L K _ P A R A M S = " { \ " c l i e n t I d \ " : \ " d i n . . . t x t \ " , \ " c l i e n t S e c r e t \ " : \ " d 5 6 . . . . 5 8 b d 9 \ " , \ " g r a n t T y p e \ " : \ " a u t h o r i z a t i o n _ c o d e \ " } "

Still getting SERVICE_UNAVAILABLE. After checking the driver, the problem is in the following:

    try {
        tokenSet = await this.client.oauthCallback(
            this.redirectUrl,
            { code: payload.code, state: payload.state },
            { code_verifier: payload.codeVerifier, state: generators.codeChallenge(payload.codeVerifier) }
        );
        userInfo = await this.client.userinfo(tokenSet.access_token!);
    } catch (e) {
        throw handleError(e);
    }

The above code throws an exception because the HTTP response is 400. It should be that the DingTalk OAuth server doesn’t recognize the message sent by Directus.

The context of the above code execution:

  • In the oauth2 driver, the express route is configured to handle the code redirected from DingTalk. During processing, the user needs to be authenticated (successful authentication completes login and issues JWT token);
  • User authentication is independent of the driver, handled by a general AuthenticationService.login service, which calls the driver’s getUserID method to get userId;
  • For the oauth2 driver, no username/password is passed from the web page. Its only input is the code redirected from DingTalk. It needs to convert the code to a token through the OAuth interface, then read the user information to know the userID.

The OAuth2 Driver uses openid-client to communicate with the server. The client is also initialized in the driver:

    const issuer = new Issuer({
        authorization_endpoint: authorizeUrl,
        token_endpoint: accessUrl,
        userinfo_endpoint: profileUrl,
        issuer: additionalConfig.provider,
    });

    this.client = new issuer.Client({
        client_id: clientId,
        client_secret: clientSecret,
        redirect_uris: [this.redirectUrl],
        response_types: ['code'],
    });

So the problem becomes compatibility between openid-client and DingTalk. More specifically, how to use the oauthCallback function to get tokens from DingTalk.

Looking at the implementation of openid-client, when interacting with OAuth servers, the POST form data uses parameter names hardcoded according to RFC6749. These inevitably don’t match DingTalk’s requirements. Using openid-client cannot be compatible with DingTalk. I discussed the research results in detail with the Directus OAuth Driver author in Integrating Dingtalk as OAuth2 server.

5. Conclusion

The original plan cannot be achieved. The reason is that DingTalk’s OAuth implementation is not compatible with the standard. Directus uses a third-party OAuth library to communicate with OAuth servers. The standard openid-client cannot communicate with DingTalk’s OAuth server that speaks a different “dialect”.

Two solutions are considered:

  1. Inherit from Directus’s standard oauth2 driver and implement a DingTalk dialect version of the oauth2-dingtalk driver, or
  2. Implement a proxy to translate DingTalk’s OAuth dialect to the standard OAuth2 protocol

I prefer solution 2, which is equivalent to creating a protocol wrapper for DingTalk, converting parameter formats according to the standard. This way, other systems that need to integrate DingTalk login in the future can also use it.

I will add more notes after completion.

6. Additional Notes

Refer to apiproxy which implemented password-free DingTalk login using solution 2 above.

7. References