Passer au contenu principal

Connexion OAuth avec Casdoor via DingTalk, WeCom, Lark, Infoflow et WeChat

· Lecture de 11 minutes
Yang Luo
Yang Luo
Casdoor Maintainer

Casdoor intègre des fournisseurs OAuth pour DingTalk, WeCom (WeChat Work), Lark (Feishu), Baidu Infoflow et WeChat. Vous créez une application dans la console développeur de chaque éditeur, collez ses identifiants dans un fournisseur Casdoor, puis ajoutez ce fournisseur à votre application. Casdoor exécute le flux de l'éditeur (scan de QR code sur ordinateur, ou connexion au sein du client même de l'éditeur), récupère le jeton d'accès d'entreprise lorsque l'éditeur l'exige, et associe l'identifiant utilisateur de l'éditeur à un utilisateur Casdoor. Votre application ne communique qu'en OIDC avec Casdoor et ne voit jamais un en-tête DingTalk, un user_ticket WeCom ni un unionid WeChat. Pour DingTalk, WeCom et Lark, un synchroniseur peut également importer tout l'annuaire de l'organisation avant la première connexion.

En un coup d'œil​

FournisseurApplication crééeOù les utilisateurs se connectentIdentifiant reliant l'utilisateur CasdoorE-mail et téléphoneSynchroniseur d'annuaire
DingTalkApplication interne (AppKey, AppSecret)Page de connexion DingTalk, login.dingtalk.comopenId ; unionid devient le nom d'utilisateurIssus du profil, remplacés par ceux de l'annuaire d'entreprise ; considérés comme vérifiésOui
WeComApplication auto-hébergée (CorpID, Secret, AgentId), ou tierceConnexion web (QR, ou connexion rapide depuis le bureau WeCom) ou connexion silencieuse dans WeComuserid (interne), open_userid (tierce)E-mail uniquement avec snsapi_privateinfo ; téléphone non luOui
Lark / FeishuApplication personnalisée (App ID, App Secret)Page de connexion Lark, Feishu ou Lark globalopen_id ; le nom d'utilisateur est user_id, sinon union_id, sinon open_idOui, si l'application dispose des permissions de contactOui
Baidu InfoflowApplication interne (CorpID, Secret, AgentID)Page d'autorisation Infoflowuserid, qui sert aussi de nom d'utilisateurE-mailNon
WeChatApplication site web sur la plateforme ouverte, plus un compte officielScan de QR code sur PC ; dans le navigateur WeChat via le compte officielunionid, sinon openidNi l'un ni l'autreNon

Les étapes de configuration sont détaillées dans la documentation : DingTalk, WeCom, Lark, Infoflow et WeChat. Cet article explique ce qui se passe en coulisses pour chacun.

Ce que voit votre application​

Chaque fournisseur du tableau se termine de la même manière. Casdoor échange le code de l'éditeur, trouve ou crée l'utilisateur dans l'organisation, puis émet son propre code d'autorisation vers votre application. Votre application l'échange sur le point d'accès aux jetons de Casdoor et obtient un jeton d'identité et un jeton d'accès Casdoor, signés avec le certificat de l'application. Les claims proviennent de l'enregistrement utilisateur Casdoor : nom, affichage du nom, e-mail, téléphone, avatar, groupes.

Le code de votre backend est le même pour les cinq fournisseurs. Toute bibliothèque OIDC fonctionne ; consultez la référence OAuth 2.0 et OIDC et, pour un guide complet, SSO Spring Boot avec OIDC. Si vous avez besoin ultérieurement de l'API propre à l'éditeur, Casdoor stocke le jeton d'accès du fournisseur sur l'utilisateur, comme décrit dans Fournisseurs OAuth.

DingTalk​

Créez une application interne sur la plateforme ouverte DingTalk et copiez son AppKey et son AppSecret dans les champs Client ID et Client secret du fournisseur. La page de connexion redirige l'utilisateur vers https://login.dingtalk.com/oauth2/auth avec scope=openid et prompt=login consent. Après confirmation par l'utilisateur, Casdoor effectue quatre appels :

  1. POST https://api.dingtalk.com/v1.0/oauth2/userAccessToken convertit le code en jeton d'accès utilisateur.
  2. GET https://api.dingtalk.com/v1.0/contact/users/me renvoie l'openId, l'unionId, le pseudo, l'avatar, l'e-mail et le numéro de mobile de l'utilisateur. Cela nécessite la permission Contact.User.Read sur l'application.
  3. POST https://api.dingtalk.com/v1.0/oauth2/accessToken avec appKey et appSecret renvoie le jeton d'accès d'entreprise (application).
  4. Avec ce jeton, topapi/user/getbyunionid associe l'unionid à l'userid d'entreprise, et topapi/v2/user/get lit l'enregistrement dans l'annuaire.

Si l'utilisateur n'est pas membre de l'organisation propriétaire de l'application, l'étape 4 échoue avec l'erreur DingTalk 60121 et la connexion s'arrête. Si la recherche dans l'annuaire réussit, l'e-mail et le numéro de mobile de l'annuaire remplacent les informations personnelles, l'unionid devient le nom d'utilisateur, et le poste est conservé comme claim supplémentaire.

Le jeton d'accès d'entreprise et son en-tête​

DingTalk propose deux générations d'API qui acceptent le même jeton mais à des endroits différents :

GET https://api.dingtalk.com/v1.0/contact/users/me
x-acs-dingtalk-access-token: <token>
POST https://oapi.dingtalk.com/topapi/v2/user/get?access_token=<token>
Content-Type: application/json

{"userid": "<userid>"}

La nouvelle API sur api.dingtalk.com lit le jeton uniquement depuis l'en-tête x-acs-dingtalk-access-token. Appelez-la sans cet en-tête (ou avec Authorization: Bearer) et elle répond AuthenticationFailed.MissingParameter, en nommant l'en-tête requis. Les points d'accès plus anciens sur oapi.dingtalk.com acceptent encore un paramètre de requête access_token. Casdoor utilise les deux : l'en-tête pour users/me, le paramètre de requête pour les deux appels topapi, avec le jeton d'entreprise issu de v1.0/oauth2/accessToken dans les deux cas. DingTalk documente ce jeton comme valide pendant 7 200 secondes et demande aux appelants de le mettre en cache par application. DingTalk marque également l'ancien point d'accès gettoken comme obsolète pour les nouvelles applications.

Casdoor considère comme vérifiés l'e-mail et le téléphone renvoyés par DingTalk, afin que la règle de liaison par défaut (e-mail, puis téléphone) puisse associer une connexion DingTalk à un utilisateur existant. Voir comment Casdoor lie les comptes.

WeCom (WeChat Work)​

Un fournisseur WeCom possède un champ Sub type et un champ Method :

  • Internal avec Normal renvoie l'utilisateur vers la connexion web de WeCom, login.work.weixin.qq.com/wwlogin/sso/login avec login_type=CorpApp. WeCom affiche un code QR, ou une connexion rapide en un clic lorsque le bureau WeCom est ouvert et connecté.
  • Internal avec Silent utilise open.weixin.qq.com/connect/oauth2/authorize avec l'agentid de l'application. C'est l'option à utiliser pour les pages ouvertes dans le client WeCom.
  • Third-party utilise login_type=ServiceApp et le secret du fournisseur de services (get_provider_token), puis get_login_info, et lie l'utilisateur via open_userid.

Pour les applications internes, Casdoor obtient le jeton d'entreprise depuis cgi-bin/gettoken avec le CorpID et le Secret de l'application, puis échange le code contre le userid du membre. Un visiteur qui n'est pas membre revient avec un openid à la place, et Casdoor rejette la connexion. Le jeton est un paramètre de requête sur chaque appel WeCom ; WeCom indique qu'il dure normalement 7 200 secondes et que gettoken est limité par débit.

L'adresse e-mail est l'élément à prévoir. WeCom a cessé de renvoyer l'avatar, le genre, le mobile et l'e-mail depuis l'API de lecture des membres (user/get) pour les applications auto-construites créées après 20:00 le 2022-06-20. Pour obtenir l'e-mail, définissez la portée du fournisseur sur snsapi_privateinfo. WeCom renvoie alors un user_ticket, que Casdoor échange auprès de getuserdetail. WeCom exige que l'administrateur sélectionne les champs sensibles dans les paramètres de l'application et que le membre donne son consentement, et ne fournit jamais ces champs aux applications tierces. Casdoor ne lit pas le numéro de téléphone depuis WeCom.

Lark et Feishu​

Créez une application personnalisée sur la Feishu Open Platform ou la plateforme globale Lark et copiez l'App ID et l'App Secret. Activez Use global endpoint dans le fournisseur pour Lark (open.larksuite.com) ; laissez-le désactivé pour Feishu (open.feishu.cn).

Casdoor obtient d'abord un tenant_access_token depuis auth/v3/tenant_access_token/internal, puis poste le code sur authen/v1/access_token avec ce jeton dans un en-tête Authorization: Bearer. La réponse contient open_id, union_id, user_id, l'e-mail, l'e-mail professionnel et le mobile. Feishu ne renvoie les données sensibles que si l'application possède la permission correspondante :

ChampPermission Feishu
user_idcontact:user.employee_id:readonly
emailcontact:user.email:readonly
enterprise_emailcontact:user.employee:readonly
mobilecontact:user.phone:readonly

Sans eux, la connexion fonctionne toujours : le nom d'utilisateur se replie de user_id vers union_id puis open_id. Casdoor utilise enterprise_email lorsque email est vide et considère l'e-mail et le téléphone comme vérifiés. Feishu liste désormais l'endpoint access_token v1 comme version historique, mais il est toujours servi.

Baidu Infoflow​

Infoflow (如流) est l'application professionnelle de Baidu. Enregistrez une application dans l'administration Infoflow, donnez-lui des permissions d'annuaire, et copiez le CorpID, le Secret et l'AgentID dans le fournisseur avec le sous-type Internal. La page de connexion pointe vers https://xpc.im.baidu.com/oauth2/authorize. Casdoor appelle ensuite qy.im.baidu.com/api/gettoken avec le CorpID et le Secret, échange le code et l'AgentID contre le userid du membre sur api/user/getuserinfo, et lit le nom, l'avatar et l'e-mail depuis api/user/get. Le userid devient à la fois l'ID lié et le nom d'utilisateur, et l'e-mail est considéré comme vérifié. Il n'y a pas de synchroniseur Infoflow, donc les utilisateurs sont créés lors de la première connexion.

WeChat​

La connexion WeChat comporte deux volets, et vous avez généralement besoin des deux :

  • Sous-type Web : une application de site web sur la WeChat Open Platform. La page de connexion PC affiche un code QR depuis open.weixin.qq.com/connect/qrconnect avec scope=snsapi_login ; l'utilisateur le scanne avec l'application WeChat.
  • Sous-type Mobile, ou la deuxième paire d'identifiants du même fournisseur : un Compte Officiel. Dans le navigateur WeChat, un code QR est inutile, donc Casdoor bascule sur connect/oauth2/authorize avec snsapi_userinfo et l'AppID du Compte Officiel. Si aucun Compte Officiel n'est configuré, Casdoor demande à l'utilisateur d'ouvrir la page dans un navigateur externe.

WeChat ne renvoie ni e-mail ni téléphone, seulement openid, unionid, surnom et avatar. Casdoor lie l'utilisateur via unionid lorsque WeChat en envoie un, se repliant sur openid, et stocke également l'openid spécifique à l'application. WeChat donne à un utilisateur le même unionid pour toutes les applications et Comptes Officiels sous un seul compte Open Platform, donc liez votre application de site web et votre Compte Officiel au même compte Open Platform. Sinon, un utilisateur qui scanne sur un PC puis se connecte sur un téléphone deviendra deux utilisateurs Casdoor.

Importer l'annuaire d'abord​

Pour DingTalk, WeCom et Lark, un synchroniseur peut importer les utilisateurs et les départements selon un calendrier, afin que les comptes existent avant que quiconque se connecte et que les départements deviennent des groupes Casdoor. Chacun utilise un jeton d'entreprise provenant de l'API d'annuaire du fournisseur : le synchroniseur DingTalk parcourt les départements récursivement, le synchroniseur WeCom se replie sur user/list_id et user/get pour les applications créées après le 2022-08-15, et le synchroniseur Lark dispose d'un paramètre Lark platform pour choisir entre Feishu ou Lark global.

Le synchroniseur WeCom écrit le userid par lequel le fournisseur WeCom effectue la liaison, afin que les utilisateurs synchronisés se connectent directement. Les synchroniseurs DingTalk et Lark stockent le userid / user_id de l'annuaire, tandis que la connexion lie via openId / open_id. Leur première connexion correspond via la règle de liaison sur l'e-mail ou le téléphone à la place, ce qui fonctionne parce que les deux fournisseurs signalent ceux-ci comme vérifiés.

Connexion QR et récupération de compte​

La connexion par QR code déplace le problème du mot de passe vers le téléphone : si un utilisateur perd son compte WeChat ou DingTalk, il ne peut pas scanner. Comme chacune de ces identités est liée à un utilisateur Casdoor plutôt que d'être l'utilisateur lui-même, ce dernier peut toujours se connecter avec un code de vérification ou réinitialiser son mot de passe via le flux de récupération de mot de passe, tant que l'application dispose d'un fournisseur d'e-mails ou de SMS et que l'utilisateur a une adresse enregistrée. DingTalk et Lark remplissent cette information depuis l'annuaire ; pour WeChat, demandez un numéro de téléphone lors de l'inscription. Pour afficher plusieurs de ces options sur la page, consultez les méthodes de connexion.

Références​