Перейти до основного вмісту

Вхід через OAuth у DingTalk, WeCom, Lark, Infoflow та WeChat за допомогою Casdoor

· Читання за 10 хв
Yang Luo
Yang Luo
Casdoor Maintainer

Casdoor має вбудовані провайдери OAuth для DingTalk, WeCom (WeChat Work), Lark (Feishu), Baidu Infoflow та WeChat. Ви створюєте додаток у консолі розробника кожного постачальника, вставляєте його облікові дані у провайдер Casdoor і додаєте цей провайдер до свого додатка. Casdoor виконує потік постачальника (сканування QR-коду на десктопі або вхід всередині власного клієнта постачальника), отримує корпоративний токен доступу, якщо він потрібен постачальнику, та зіставляє ID користувача постачальника з користувачем Casdoor. Ваш додаток спілкується лише з Casdoor через OIDC і ніколи не бачить заголовок DingTalk, user_ticket WeCom чи unionid WeChat. Для DingTalk, WeCom та Lark синхронізатор також може імпортувати весь директорій організації перед першим входом.

Огляд​

ПровайдерСтворюваний додатокДе користувачі входятьID, який пов'язує користувача CasdoorЕлектронна пошта та телефонСинхронізатор директорії
DingTalkВнутрішній додаток (AppKey, AppSecret)Сторінка входу DingTalk, login.dingtalk.comopenId; unionid стає іменем користувачаЗ профілю, замінюється даними з корпоративного директорію; вважаються підтвердженимиТак
WeComСамостійно створений додаток (CorpID, Secret, AgentId) або стороннійВеб-вхід (QR-код або швидкий вхід із десктопного WeCom) або беззвучний вхід всередині WeComuserid (внутрішній), open_userid (сторонній)Електронна пошта лише з snsapi_privateinfo; телефон не зчитуєтьсяТак
Lark / FeishuКористувацький додаток (App ID, App Secret)Сторінка входу Lark, Feishu або глобальний Larkopen_id; ім'я користувача — це user_id, інакше union_id, інакше open_idТак, якщо додаток має дозволи на контактиТак
Baidu InfoflowВнутрішній додаток (CorpID, Secret, AgentID)Сторінка авторизації Infoflowuserid, також є іменем користувачаЕлектронна поштаНі
WeChatВеб-додаток на Open Platform плюс Official AccountСканирование QR-коду на ПК; всередині браузера WeChat через Official Accountunionid, інакше openidЖоднеНі

Кроки налаштування для кожного описано в документації: DingTalk, WeCom, Lark, Infoflow та WeChat. Цей пост пояснює, що відбувається за лаштунками кожного з них.

Що бачить ваш додаток​

Усі провайдери з таблиці завершуються однаково. Casdoor обмінює код постачальника, знаходить або створює користувача в організації, а потім видає власний код авторизації вашому додатку. Ваш додаток використовує його на ендпоінті токенів Casdoor і отримує ID-токен та токен доступу Casdoor, підписані сертифікатом додатка. Клейми беруться з записи користувача Casdoor: ім'я, відображуване ім'я, електронна пошта, телефон, аватар, групи.

Код вашого бекенду однаковий для всіх п'яти. Підійде будь-яка бібліотека OIDC; дивіться довідник OAuth 2.0 та OIDC та, для повного прикладу, SSO Spring Boot з OIDC. Якщо вам пізніше дійсно потрібен власний API постачальника, Casdoor зберігає токен доступу провайдера в користувачеві, як описано в провайдерах OAuth.

DingTalk​

Створіть внутрішній додаток на платформі DingTalk Open Platform і скопіюйте його AppKey та AppSecret у поля Client ID та Client secret провайдера. Сторінка входу надсилає користувача на https://login.dingtalk.com/oauth2/auth з scope=openid та prompt=login consent. Після того, як користувач підтвердить дію, Casdoor робить чотири виклики:

  1. POST https://api.dingtalk.com/v1.0/oauth2/userAccessToken перетворює код на токен доступу користувача.
  2. GET https://api.dingtalk.com/v1.0/contact/users/me повертає openId, unionId, нікнейм, аватар, електронну пошту та мобільний номер користувача. Це потребує дозволу Contact.User.Read у додатку.
  3. POST https://api.dingtalk.com/v1.0/oauth2/accessToken з appKey та appSecret повертає корпоративний (додатковий) токен доступу.
  4. З цим токеном topapi/user/getbyunionid зіставляє unionid з корпоративним userid, а topapi/v2/user/get читає запись з директорію.

Якщо користувач не є учасником організації, якій належить додаток, крок 4 завершується помилкою DingTalk 60121, і вхід зупиняється. Якщо пошук у директорії успішний, електронна пошта та мобільний номер з директорію замінюють особисті дані, unionid стає іменем користувача, а посада зберігається як додатковий клейм.

Корпоративний токен доступу та його заголовок​

DingTalk має два покоління API, які приймають той самий токен у різних місцях:

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

Нове API на api.dingtalk.com читає токен лише з заголовка x-acs-dingtalk-access-token. Викличте його без цього заголовка (або з Authorization: Bearer), і воно відповість AuthenticationFailed.MissingParameter, назвавши заголовок. Старіші ендпоінти oapi.dingtalk.com все ще приймають параметр запиту access_token. Casdoor використовує обидва варіанти: заголовок для users/me, параметр запиту для двох викликів topapi, з корпоративним токеном з v1.0/oauth2/accessToken в обох випадках. DingTalk документує цей токен як дійсний протягом 7,200 секунд і просить клієнтів кешувати його для кожного додатка. Також DingTalk позначає старий ендпоінт gettoken як застарілий для нових додатків.

Casdoor вважає електронну пошту та телефон, які повертає DingTalk, підтвердженими, тому правило автоматичного зв'язування за замовчуванням (спочатку електронна пошта, потім телефон) може прив'язати вхід через DingTalk до існуючого користувача. Дивіться як Casdoor пов'язує облікові записи.

WeCom (WeChat Work)​

Провайдер WeCom має поле Sub type та поле Method:

  • Internal з Normal перенаправляє користувача на веб-вхід WeCom login.work.weixin.qq.com/wwlogin/sso/login із параметром login_type=CorpApp. WeCom відображає QR-код або варіант швидкого входу в один клік, якщо десктопний додаток WeCom запущено та виконано вхід.
  • Internal з Silent використовує open.weixin.qq.com/connect/oauth2/authorize із agentid додатка. Це саме той варіант, який слід використовувати для сторінок, відкритих всередині клієнта WeCom.
  • Third-party використовує login_type=ServiceApp і секрет постачальника послуг (get_provider_token), потім викликає get_login_info і прив'язує користувача за допомогою open_userid.

Для внутрішніх додатків Casdoor отримує корпоративний токен від cgi-bin/gettoken, використовуючи CorpID і Secret додатка, а потім обмінює код на userid співробітника. Відвідувач, який не є співробітником, повертається з openid натомість, і Casdoor відхиляє спробу входу. Токен передається як параметр запиту для кожного виклику WeCom; WeCom зазначає, що зазвичай він дійсний протягом 7200 секунд, і що для gettoken діють обмеження частоти запитів.

Адреса електронної пошти — це те, про що варто подумати заздалегідь. WeCom припинила повертати аватар, стать, номер мобільного телефону та електронну адресу через API читання даних співробітника (user/get) для самостійно створених додатків, створених після 20:00 20 червня 2022 року. Щоб отримати електронну адресу, встановіть область (scope) провайдера на snsapi_privateinfo. Потім WeCom повертає user_ticket, який Casdoor обмінює через getuserdetail. WeCom вимагає, щоб адміністратор обрав конфіденційні поля в налаштуваннях додатка, а співробітник надав згоду, і ніколи не надає ці поля стороннім додаткам. Casdoor не зчитує номер телефону з WeCom.

Lark і Feishu​

Створіть користувацький додаток на Feishu Open Platform або глобальній платформі Lark і скопіюйте App ID та App Secret. Увімкніть Use global endpoint у провайдері для Lark (open.larksuite.com); залиште його вимкненим для Feishu (open.feishu.cn).

Спочатку Casdoor отримує tenant_access_token від auth/v3/tenant_access_token/internal, потім надсилає код на authen/v1/access_token із цим токеном у заголовку Authorization: Bearer. У відповіді містяться open_id, union_id, user_id, електронна адреса, корпоративна електронна адреса та номер мобільного телефону. Feishu повертає конфіденційні дані лише тоді, коли додаток має відповідне дозвіл:

ПолеДозвіл Feishu
user_idcontact:user.employee_id:readonly
emailcontact:user.email:readonly
enterprise_emailcontact:user.employee:readonly
mobilecontact:user.phone:readonly

Без них вхід все одно працює: ім'я користувача визначається послідовно з user_id, потім union_id, потім open_id. Casdoor використовує enterprise_email, якщо поле email порожнє, і вважає як електронну адресу, так і телефон підтвердженими. Feishu тепер позначає v1 ендпоінт access_token як історичну версію, але він досі обслуговується.

Baidu Infoflow​

Infoflow (如流) — це робочий додаток від Baidu. Зареєструйте додаток в адмінці Infoflow, надайте йому дозволи доступу до адресної книги та скопіюйте CorpID, Secret і AgentID у провайдер із підтипом Internal. Сторінка входу переходить на https://xpc.im.baidu.com/oauth2/authorize. Potim Casdoor викликає qy.im.baidu.com/api/gettoken із CorpID і Secret, обмінює код і AgentID на userid співробітника через api/user/getuserinfo і зчитує ім'я, аватар та електронну адресу з api/user/get. userid стає як прив'язаним ID, так і іменем користувача, а електронна адреса вважається підтвердженою. Синхронізатор Infoflow відсутній, тому користувачі створюються при першому вході.

Вхід через WeChat​

Вхід через WeChat складається з двох частин, і зазвичай потрібні обидві:

  • Підтип Web: веб-додаток на платформі WeChat Open Platform. На сторінці входу для ПК відображається QR-код від open.weixin.qq.com/connect/qrconnect із scope=snsapi_login; користувач сканує його за допомогою додатка WeChat.
  • Підтип Mobile, або друга пара облікових даних того самого провайдера: Офіційний акаунт (Official Account). У браузері WeChat QR-код безкорисний, тому Casdoor перемикається на connect/oauth2/authorize із snsapi_userinfo і AppID Офіційного акаунта. Якщо Офіційний акаунт не налаштовано, Casdoor повідомляє користувачеві відкрити сторінку в зовнішньому браузері.

WeChat не повертає електронну адресу чи телефон, лише openid, unionid, псевдонім та аватар. Casdoor прив'язує користувача за unionid, якщо WeChat його надсилає, з резервним варіантом openid, і також зберігає openid для конкретного додатка. WeChat надає користувачеві однаковий unionid для всіх додатків та Офіційних акаунтів в межах одного облікового запису Open Platform, тому прив'яжіть свій веб-додаток та Офіційний акаунт до одного облікового запису Open Platform. Інакше користувач, який відсканував QR-код на ПК і пізніше увійшов із телефона, стане двома різними користувачами Casdoor.

Імпорт директорії спочатку​

Для DingTalk, WeCom і Lark синхронізатор може періодично завантажувати користувачів і підрозділи, тому облікові записи існують до будь-якого входу, а підрозділи стають групами Casdoor. Кожен із них використовує корпоративний токен з API директорії постачальника: синхронізатор DingTalk рекурсивно проходить по підрозділах, синхронізатор WeCom використовує резервні варіанти user/list_id і user/get для додатків, створених після 15 серпня 2022 року, а синхронізатор Lark має налаштування Lark platform для вибору між Feishu та глобальною платформою Lark.

Синхронізатор WeCom записує userid, за яким провайдер WeCom виконує прив'язку, тому синхронізовані користувачі можуть входити напряму. Синхронізатори DingTalk і Lark зберігають userid / user_id з директорії, тоді як вхід прив'язується за openId / open_id. Їхній перший вхід зіставляється через правило прив'язки за електронною адресою або телефоном, що працює, оскільки обидва провайдери позначають ці дані як підтверджені.

QR-вхід і відновлення облікового запису​

Вхід за QR-кодом переносить проблему пароля на телефон: якщо користувач втрачає свій акаунт WeChat або DingTalk, він не зможе відсканувати код. Оскільки кожна з цих ідентичностей пов'язана з користувачем Casdoor, а не є самим користувачем, він все одно може увійти за допомогою коду підтвердження або скинути пароль через процес відновлення пароля, за умови, що у додатку налаштовано провайдера електронної пошти або SMS, а у профілі користувача зазначена адреса. DingTalk і Lark заповнюють її автоматично з каталогу; для WeChat запитуйте номер телефону під час реєстрації. Щоб показати кілька таких варіантів на сторінці, дивіться методи входу.

Посилання​