Zum Hauptinhalt springen

DingTalk, WeCom, Lark, Infoflow und WeChat OAuth-Anmeldung mit Casdoor

· 11 Minuten Lektüre
Yang Luo
Yang Luo
Casdoor Maintainer

Casdoor verfügt über integrierte OAuth-Anbieter für DingTalk, WeCom (WeChat Work), Lark (Feishu), Baidu Infoflow und WeChat. Sie erstellen eine App in der Entwicklerkonsole jedes Anbieters, fügen deren Anmeldedaten in einen Casdoor-Anbieter ein und hinzufügen den Anbieter zu Ihrer Anwendung. Casdoor führt den Anbieter-Flow aus (QR-Scan auf dem Desktop oder Anmeldung innerhalb des eigenen Clients des Anbieters), ruft das erforderliche Unternehmens-Zugriffstoken ab, falls vom Anbieter benötigt, und ordnet die Benutzer-ID des Anbieters einem Casdoor-Benutzer zu. Ihre Anwendung kommuniziert nur über OIDC mit Casdoor und sieht weder einen DingTalk-Header, ein WeCom user_ticket noch eine WeChat unionid. Für DingTalk, WeCom und Lark kann ein Syncer auch das gesamte Organisationsverzeichnis vor der ersten Anmeldung importieren.

Auf einen Blick​

AnbieterZu erstellende AppWo Benutzer sich anmeldenID zur Verknüpfung des Casdoor-BenutzersE-Mail und TelefonVerzeichnis-Syncer
DingTalkInterne App (AppKey, AppSecret)DingTalk-Anmeldeseite, login.dingtalk.comopenId; unionid wird zum BenutzernamenAus dem Profil, ersetzt durch das Unternehmensverzeichnis; als verifiziert behandeltJa
WeComSelbst erstellte App (CorpID, Secret, AgentId) oder Drittanbieter-AppWeb-Anmeldung (QR oder Schnell-Anmeldung von WeCom Desktop) oder stille Anmeldung innerhalb von WeComuserid (intern), open_userid (Drittanbieter)E-Mail nur mit snsapi_privateinfo; Telefon nicht gelesenJa
Lark / FeishuEigene App (App ID, App Secret)Lark-Anmeldeseite, Feishu oder Lark Globalopen_id; Benutzername ist user_id, sonst union_id, sonst open_idJa, wenn die App Kontaktberechtigungen hatJa
Baidu InfoflowInterne App (CorpID, Secret, AgentID)Infoflow-Autorisierungsseiteuserid, auch der BenutzernameE-MailNein
WeChatWebsite-App auf der Open Platform plus ein Official AccountQR-Scan am PC; im WeChat-Browser über den Official Accountunionid, sonst openidWeder E-Mail noch TelefonNein

Die Einrichtungsschritte für jeden sind in den Docs beschrieben: DingTalk, WeCom, Lark, Infoflow und WeChat. Dieser Beitrag erklärt, was hinter jedem dieser Schritte passiert.

Was Ihre Anwendung sieht​

Jeder Anbieter in der Tabelle endet gleich. Casdoor tauscht den Code des Anbieters um, findet oder erstellt den Benutzer in der Organisation und gibt dann seinen eigenen Autorisierungscode an Ihre App aus. Ihre App löst ihn am Token-Endpoint von Casdoor ein und erhält ein Casdoor-ID-Token und Zugriffstoken, signiert mit dem Zertifikat der Anwendung. Die Claims stammen aus dem Casdoor-Benutzerdatensatz: Name, Anzeigename, E-Mail, Telefon, Avatar, Gruppen.

Ihr Backend-Code ist für alle fünf gleich. Jede OIDC-Bibliothek funktioniert; siehe die Referenz für OAuth 2.0 und OIDC und für eine vollständige Anleitung Spring Boot SSO mit OIDC. Wenn Sie später die eigene API des Anbieters benötigen, speichert Casdoor das Zugriffstoken des Anbieters beim Benutzer, wie in OAuth-Anbietern beschrieben.

DingTalk​

Erstellen Sie eine interne App auf der DingTalk Open Platform und kopieren Sie deren AppKey und AppSecret in die Client ID und das Client secret des Anbieters. Die Anmeldeseite leitet den Benutzer an https://login.dingtalk.com/oauth2/auth weiter mit scope=openid und prompt=login consent. Nach der Bestätigung des Benutzers macht Casdoor vier Aufrufe:

  1. POST https://api.dingtalk.com/v1.0/oauth2/userAccessToken wandelt den Code in ein Benutzer-Zugriffstoken um.
  2. GET https://api.dingtalk.com/v1.0/contact/users/me gibt die openId, unionId, Nickname, Avatar, E-Mail und Mobilnummer des Benutzers zurück. Dies erfordert die Berechtigung Contact.User.Read für die App.
  3. POST https://api.dingtalk.com/v1.0/oauth2/accessToken mit appKey und appSecret gibt das Unternehmens-(App-)Zugriffstoken zurück.
  4. Mit diesem Token bildet topapi/user/getbyunionid die unionid auf die unternehmensinterne userid ab, und topapi/v2/user/get liest den Verzeichniseintrag.

Wenn der Benutzer kein Mitglied der Organisation ist, der die App gehört, schlägt Schritt 4 mit dem DingTalk-Fehler 60121 fehl und die Anmeldung bricht ab. Wenn die Verzeichnissuche erfolgreich ist, ersetzen die E-Mail und Mobilnummer aus dem Verzeichnis die persönlichen Daten, unionid wird zum Benutzernamen und die Jobbezeichnung wird als zusätzlicher Claim beibehalten.

Das Unternehmens-Zugriffstoken und sein Header​

DingTalk hat zwei API-Generationen, die dasselbe Token an verschiedenen Orten entgegennehmen:

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>"}

Die neue API auf api.dingtalk.com liest das Token nur aus dem Header x-acs-dingtalk-access-token. Rufen Sie sie ohne diesen Header (oder mit Authorization: Bearer) auf, antwortet sie mit AuthenticationFailed.MissingParameter und nennt den Header. Die älteren Endpunkte auf oapi.dingtalk.com akzeptieren weiterhin einen access_token Query-Parameter. Casdoor verwendet beide: den Header für users/me, den Query-Parameter für die beiden topapi-Aufrufe, jeweils mit dem Unternehmens-Token von v1.0/oauth2/accessToken. DingTalk dokumentiert dieses Token als gültig für 7.200 Sekunden und empfiehlt Aufrufern, es pro App zu cachen. DingTalk markiert zudem den alten gettoken-Endpunkt für neue Apps als Legacy.

Casdoor zählt die von DingTalk zurückgegebenen E-Mail-Adressen und Telefonnummern als verifiziert, sodass die Standard-Bindungsregel (E-Mail, dann Telefon) eine DingTalk-Anmeldung an einen vorhandenen Benutzer anhängen kann. Siehe wie Casdoor Konten verknüpft.

WeCom (WeChat Work)​

Ein WeCom-Anbieter hat einen Sub type und eine Method:

  • Internal mit Normal leitet den Benutzer zur WeCom-Web-Anmeldung weiter, login.work.weixin.qq.com/wwlogin/sso/login mit login_type=CorpApp. WeCom zeigt einen QR-Code an oder ermöglicht eine One-Click-Schnellanmeldung, wenn die WeCom-Desktop-App ausgeführt und angemeldet ist.
  • Internal mit Silent verwendet open.weixin.qq.com/connect/oauth2/authorize mit der agentid der App. Dies ist die Option für Seiten, die innerhalb des WeCom-Clients geöffnet werden.
  • Third-party verwendet login_type=ServiceApp und das Secret des Diensteanbieters (get_provider_token), dann get_login_info, und verknüpft den Benutzer über open_userid.

Für interne Apps ruft Casdoor das Unternehmens-Token von cgi-bin/gettoken mit CorpID und dem App-Secret ab und tauscht anschließend den Code gegen die userid des Mitglieds aus. Ein Gast, der kein Mitglied ist, erhält stattdessen eine openid, und Casdoor lehnt die Anmeldung ab. Das Token ist ein Abfrageparameter bei jedem WeCom-Aufruf; WeCom gibt an, dass es normalerweise 7.200 Sekunden gültig ist und dass gettoken einer Ratenbegrenzung unterliegt.

Die E-Mail-Adresse ist der Punkt, der geplant werden muss. WeCom hat aufgehört, Avatar, Geschlecht, Mobilnummer und E-Mail über die Mitglieder-Lese-API (user/get) für selbst erstellte Apps zurückzugeben, die nach dem 20. Juni 2022 um 20:00 Uhr erstellt wurden. Um die E-Mail zu erhalten, setzen Sie den Scope des Providers auf snsapi_privateinfo. WeCom gibt dann ein user_ticket zurück, das Casdoor bei getuserdetail einlöst. WeCom verlangt, dass der Administrator die sensiblen Felder in den App-Einstellungen auswählt und das Mitglied zustimmt, und diese Felder werden niemals an Drittanbieter-Apps übermittelt. Casdoor liest die Telefonnummer nicht aus WeCom.

Lark and Feishu​

Erstellen Sie eine benutzerdefinierte App auf der Feishu Open Platform oder der Lark Global Platform und kopieren Sie die App ID und das App Secret. Aktivieren Sie Use global endpoint im Provider für Lark (open.larksuite.com); lassen Sie es für Feishu (open.feishu.cn) deaktiviert.

Casdoor erhält zunächst ein tenant_access_token von auth/v3/tenant_access_token/internal und sendet dann den Code an authen/v1/access_token mit diesem Token im Header Authorization: Bearer. Die Antwort enthält open_id, union_id, user_id, E-Mail, Unternehmens-E-Mail und Mobilnummer. Feishu gibt die sensiblen Daten nur zurück, wenn die App die entsprechende Berechtigung besitzt:

FieldFeishu permission
user_idcontact:user.employee_id:readonly
emailcontact:user.email:readonly
enterprise_emailcontact:user.employee:readonly
mobilecontact:user.phone:readonly

Ohne diese funktioniert die Anmeldung weiterhin: Der Benutzername fällt von user_id auf union_id und dann auf open_id zurück. Casdoor verwendet enterprise_email, wenn email leer ist, und betrachtet sowohl E-Mail als auch Telefon als verifiziert. Feishu listet den v1 access_token-Endpunkt nun als historische Version auf, aber er wird weiterhin bereitgestellt.

Baidu Infoflow​

Infoflow (如流) ist die Workplace-App von Baidu. Registrieren Sie eine App im Infoflow-Admin, geben Sie ihr Adressbuch-Berechtigungen und kopieren Sie CorpID, Secret und AgentID in den Provider mit dem Sub-Typ Internal. Die Anmeldeseite führt zu https://xpc.im.baidu.com/oauth2/authorize. Casdoor ruft dann qy.im.baidu.com/api/gettoken mit CorpID und Secret auf, tauscht den Code und die AgentID gegen die userid des Mitglieds bei api/user/getuserinfo aus und liest Name, Avatar und E-Mail von api/user/get. Die userid wird sowohl zur verknüpften ID als auch zum Benutzernamen, und die E-Mail zählt als verifiziert. Es gibt keinen Infoflow-Syncer, daher werden Benutzer beim ersten Anmelden erstellt.

WeChat-Anmeldung​

Die WeChat-Anmeldung besteht aus zwei Teilen, und normalerweise benötigen Sie beide:

  • Web-Sub-Typ: Eine Website-App auf der WeChat Open Platform. Die PC-Anmeldeseite zeigt einen QR-Code von open.weixin.qq.com/connect/qrconnect mit scope=snsapi_login; der Benutzer scannt ihn mit der WeChat-App.
  • Mobile-Sub-Typ oder das zweite Credential-Paar desselben Providers: Ein Official Account. Im WeChat-Browser ist ein QR-Code nutzlos, daher wechselt Casdoor zu connect/oauth2/authorize mit snsapi_userinfo und der AppID des Official Accounts. Wenn kein Official Account konfiguriert ist, weist Casdoor den Benutzer an, die Seite in einem externen Browser zu öffnen.

WeChat gibt keine E-Mail oder Telefonnummer zurück, nur openid, unionid, Nickname und Avatar. Casdoor verknüpft den Benutzer über unionid, wenn WeChat eines sendet, und greift auf openid zurück, und speichert außerdem die pro App gültige openid. WeChat gibt einem Benutzer denselben unionid über alle Apps und Official Accounts hinweg unter einem Open-Platform-Konto, daher sollten Sie Ihre Website-App und Ihren Official Account mit demselben Open-Platform-Konto verknüpfen. Andernfalls wird ein Benutzer, der auf einem PC scannt und sich später auf einem Telefon anmeldet, zu zwei Casdoor-Benutzern.

Importing the directory first​

Für DingTalk, WeCom und Lark kann ein Syncer Benutzer und Abteilungen zeitgesteuert abrufen, sodass Konten vorhanden sind, bevor sich jemand anmeldet, und Abteilungen zu Casdoor-Gruppen werden. Jeder verwendet ein Unternehmens-Token von der Verzeichnis-API des Anbieters: Der DingTalk Syncer durchläuft Abteilungen rekursiv, der WeCom Syncer greift auf user/list_id und user/get zurück für Apps, die nach dem 15. August 2022 erstellt wurden, und der Lark Syncer hat eine Einstellung Lark platform, um Feishu oder Lark global auszuwählen.

Der WeCom-Syncer schreibt die userid, über die der WeCom-Provider verknüpft, sodass synchronisierte Benutzer sich direkt anmelden können. Die DingTalk- und Lark-Syncer speichern das Verzeichnis-userid / user_id, während die Anmeldung über openId / open_id verknüpft. Ihre erste Anmeldung stimmt über die Bindungsregel per E-Mail oder Telefon überein, was funktioniert, weil beide Anbieter diese als verifiziert melden.

QR login and account recovery​

QR-Login verlagert das Passwortproblem auf das Telefon: Wenn ein Benutzer sein WeChat- oder DingTalk-Konto verliert, kann er nicht scannen. Da jede dieser Identitäten mit einem Casdoor-Benutzer verknüpft ist und nicht der Benutzer selbst ist, kann sich der Benutzer weiterhin mit einem Verifizierungscode anmelden oder sein Passwort über den Passwort-vergessen-Flow zurücksetzen, sofern die Anwendung einen E-Mail- oder SMS-Anbieter hat und eine Adresse im System hinterlegt ist. Bei DingTalk und Lark wird dies aus dem Verzeichnis ausgefüllt; bei WeChat sollte nach einer Telefonnummer bei der Registrierung gefragt werden. Um mehr als eine dieser Optionen auf der Seite anzuzeigen, siehe Anmeldemethoden.

Referenzen​