Pular para o conteúdo principal

Login OAuth com Casdoor via DingTalk, WeCom, Lark, Infoflow e WeChat

· Leitura de 12 min
Yang Luo
Yang Luo
Casdoor Maintainer

O Casdoor possui provedores OAuth integrados para DingTalk, WeCom (WeChat Work), Lark (Feishu), Baidu Infoflow e WeChat. Você cria um aplicativo no console de desenvolvedor de cada fornecedor, cola suas credenciais em um provedor do Casdoor e adiciona o provedor à sua aplicação. O Casdoor executa o fluxo do fornecedor (escaneamento de QR code no desktop ou login dentro do próprio cliente do fornecedor), obtém o token de acesso corporativo onde o fornecedor exige um, e mapeia o ID de usuário do fornecedor para um usuário do Casdoor. Sua aplicação apenas conversa via OIDC com o Casdoor e nunca vê um cabeçalho do DingTalk, um user_ticket do WeCom ou um unionid do WeChat. Para DingTalk, WeCom e Lark, um sincronizador também pode importar todo o diretório da organização antes do primeiro login.

Visão geral​

ProvedorAplicativo que você criaOnde os usuários fazem loginID que vincula o usuário do CasdoorE-mail e telefoneSincronizador de diretório
DingTalkAplicativo interno (AppKey, AppSecret)Página de login do DingTalk, login.dingtalk.comopenId; unionid torna-se o nome de usuárioDo perfil, substituído pelo diretório corporativo; tratado como verificadoSim
WeComAplicativo autoconstruído (CorpID, Secret, AgentId) ou de terceirosLogin na web (QR code ou login rápido do desktop WeCom) ou login silencioso dentro do WeComuserid (interno), open_userid (terceiros)E-mail apenas com snsapi_privateinfo; telefone não lidoSim
Lark / FeishuAplicativo personalizado (App ID, App Secret)Página de login do Lark, Feishu ou Lark globalopen_id; o nome de usuário é user_id, senão union_id, senão open_idSim, se o aplicativo tiver as permissões de contatoSim
Baidu InfoflowAplicativo interno (CorpID, Secret, AgentID)Página de autorização do Infoflowuserid, também o nome de usuárioE-mailNão
WeChatAplicativo de site na Open Platform, além de uma Official AccountEscaneamento de QR code no PC; dentro do navegador WeChat através da Official Accountunionid, senão openidNenhumNão

As etapas de configuração para cada um estão na documentação: DingTalk, WeCom, Lark, Infoflow e WeChat. Este post explica o que acontece por trás de cada um.

O que sua aplicação vê​

Todos os provedores na tabela terminam da mesma forma. O Casdoor troca o código do fornecedor, encontra ou cria o usuário na organização e então emite seu próprio código de autorização para sua aplicação. Sua aplicação resgata esse código no endpoint de token do Casdoor e recebe um token de ID do Casdoor e um token de acesso, assinados com o certificado da aplicação. As claims vêm do registro do usuário do Casdoor: nome, nome de exibição, e-mail, telefone, avatar, grupos.

Seu código backend é o mesmo para todos os cinco. Qualquer biblioteca OIDC funciona; veja a referência de OAuth 2.0 e OIDC e, para um passo a passo completo, SSO Spring Boot com OIDC. Se você precisar da API própria do fornecedor mais tarde, o Casdoor armazena o token de acesso do provedor no usuário, conforme descrito em Provedores OAuth.

DingTalk​

Crie um aplicativo interno na DingTalk Open Platform e copie seu AppKey e AppSecret para o Client ID e Client secret do provedor. A página de login envia o usuário para https://login.dingtalk.com/oauth2/auth com scope=openid e prompt=login consent. Depois que o usuário confirma, o Casdoor faz quatro chamadas:

  1. POST https://api.dingtalk.com/v1.0/oauth2/userAccessToken transforma o código em um token de acesso de usuário.
  2. GET https://api.dingtalk.com/v1.0/contact/users/me retorna o openId, unionId, apelido, avatar, e-mail e celular do usuário. Isso requer a permissão Contact.User.Read no aplicativo.
  3. POST https://api.dingtalk.com/v1.0/oauth2/accessToken com appKey e appSecret retorna o token de acesso corporativo (do app).
  4. Com esse token, topapi/user/getbyunionid mapeia o unionid para o userid corporativo, e topapi/v2/user/get lê o registro do diretório.

Se o usuário não for membro da organização que possui o aplicativo, a etapa 4 falha com o erro 60121 do DingTalk e o login é interrompido. Se a busca no diretório for bem-sucedida, o e-mail e o celular do diretório substituem os pessoais, o unionid torna-se o nome de usuário e o cargo é mantido como uma claim extra.

O token de acesso corporativo e seu cabeçalho​

O DingTalk tem duas gerações de API que aceitam o mesmo token em lugares diferentes:

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

A nova API em api.dingtalk.com lê o token apenas do cabeçalho x-acs-dingtalk-access-token. Chame-a sem esse cabeçalho (ou com Authorization: Bearer) e ela responderá AuthenticationFailed.MissingParameter, nomeando o cabeçalho. Os endpoints mais antigos de oapi.dingtalk.com ainda aceitam um parâmetro de consulta access_token. O Casdoor usa ambos: o cabeçalho para users/me, o parâmetro de consulta para as duas chamadas topapi, com o token corporativo de v1.0/oauth2/accessToken nos dois lugares. O DingTalk documenta que esse token é válido por 7.200 segundos e pede que os chamadores o armazenem em cache por aplicativo. O DingTalk também marca o endpoint antigo gettoken como legado para novos aplicativos.

O Casdoor conta o e-mail e o telefone retornados pelo DingTalk como verificados, então a regra padrão de vínculo (e-mail, depois telefone) pode anexar um login do DingTalk a um usuário existente. Veja como o Casdoor vincula contas.

WeCom (WeChat Work)​

Um provedor WeCom tem um Sub type e um Method:

  • Internal com Normal envia o usuário para o login web da WeCom, login.work.weixin.qq.com/wwlogin/sso/login com login_type=CorpApp. A WeCom exibe um código QR ou um login rápido com um clique quando o aplicativo desktop da WeCom está em execução e conectado.
  • Internal com Silent usa open.weixin.qq.com/connect/oauth2/authorize com o agentid do aplicativo. Esta é a opção a ser usada para páginas abertas dentro do cliente WeCom.
  • Third-party usa login_type=ServiceApp e o segredo do provedor de serviços (get_provider_token), depois get_login_info, e vincula o usuário pelo open_userid.

Para aplicativos internos, o Casdoor obtém o token corporativo de cgi-bin/gettoken com o CorpID e o Secret do aplicativo, depois troca o código pelo userid do membro. Um visitante que não é membro retorna com um openid em vez disso, e o Casdoor rejeita o login. O token é um parâmetro de consulta em cada chamada à WeCom; a WeCom diz que ele normalmente dura 7.200 segundos e que gettoken tem limite de taxa.

O endereço de e-mail é a parte a ser planejada. A WeCom deixou de retornar avatar, gênero, celular e e-mail da API de leitura de membros (user/get) para aplicativos autoconstruídos criados após as 20:00 do dia 20-06-2022. Para obter o e-mail, defina o escopo do provedor como snsapi_privateinfo. A WeCom então retorna um user_ticket, que o Casdoor resgata em getuserdetail. A WeCom exige que o administrador selecione os campos sensíveis nas configurações do aplicativo e que o membro consinta, e nunca fornece esses campos para aplicativos de terceiros. O Casdoor não lê o número de telefone da WeCom.

Lark e Feishu​

Crie um aplicativo personalizado na Feishu Open Platform ou na plataforma global Lark e copie o App ID e o App Secret. Ative Use global endpoint no provedor para Lark (open.larksuite.com); deixe desativado para Feishu (open.feishu.cn).

O Casdoor primeiro obtém um tenant_access_token de auth/v3/tenant_access_token/internal, depois envia o código para authen/v1/access_token com esse token em um cabeçalho Authorization: Bearer. A resposta contém open_id, union_id, user_id, e-mail, e-mail corporativo e celular. A Feishu retorna os dados sensíveis apenas quando o aplicativo possui a permissão correspondente:

CampoPermissão da Feishu
user_idcontact:user.employee_id:readonly
emailcontact:user.email:readonly
enterprise_emailcontact:user.employee:readonly
mobilecontact:user.phone:readonly

Sem elas, o login ainda funciona: o nome de usuário recua de user_id para union_id para open_id. O Casdoor usa enterprise_email quando email está vazio e trata tanto o e-mail quanto o telefone como verificados. A Feishu agora lista o endpoint access_token da v1 como uma versão histórica, mas ele ainda é servido.

Baidu Infoflow​

Infoflow (如流) é o aplicativo corporativo da Baidu. Registre um aplicativo no admin do Infoflow, conceda-lhe permissões de diretório de endereços e copie o CorpID, Secret e AgentID para o provedor com o subtipo Internal. A página de login vai para https://xpc.im.baidu.com/oauth2/authorize. O Casdoor então chama qy.im.baidu.com/api/gettoken com o CorpID e Secret, troca o código e o AgentID pelo userid do membro em api/user/getuserinfo, e lê nome, avatar e e-mail de api/user/get. O userid se torna tanto o ID vinculado quanto o nome de usuário, e o e-mail conta como verificado. Não há sincronizador do Infoflow, então os usuários são criados no primeiro login.

Início de sessão WeChat​

O login do WeChat tem duas partes, e você geralmente precisa de ambas:

  • Subtipo Web: um aplicativo de site na WeChat Open Platform. A página de login para PC mostra um código QR de open.weixin.qq.com/connect/qrconnect com scope=snsapi_login; o usuário o escaneia com o aplicativo WeChat.
  • Subtipo Mobile, ou o segundo par de credenciais do mesmo provedor: uma Official Account. Dentro do navegador do WeChat, um código QR é inútil, então o Casdoor muda para connect/oauth2/authorize com snsapi_userinfo e o AppID da Official Account. Se nenhuma Official Account estiver configurada, o Casdoor informa ao usuário para abrir a página em um navegador externo.

O WeChat não retorna e-mail ou telefone, apenas openid, unionid, apelido e avatar. O Casdoor vincula o usuário pelo unionid quando o WeChat envia um, recuando para openid, e também armazena o openid específico do aplicativo. O WeChat fornece ao usuário o mesmo unionid em todos os aplicativos e Official Accounts sob uma única conta da Open Platform, então vincule seu aplicativo de site e sua Official Account à mesma conta da Open Platform. Caso contrário, um usuário que escaneia no PC e depois faz login no celular se torna dois usuários do Casdoor.

Importando o diretório primeiro​

Para DingTalk, WeCom e Lark, um syncer pode puxar usuários e departamentos em um cronograma, para que as contas existam antes que alguém faça login e os departamentos se tornem grupos do Casdoor. Cada um usa um token corporativo da API de diretório do fornecedor: o DingTalk syncer percorre os departamentos recursivamente, o WeCom syncer recua para user/list_id e user/get para aplicativos criados após 15-08-2022, e o Lark syncer tem uma configuração Lark platform para escolher Feishu ou Lark global.

O syncer da WeCom escreve o userid pelo qual o provedor da WeCom vincula, então os usuários sincronizados fazem login diretamente. Os syncers do DingTalk e da Lark armazenam o userid / user_id do diretório, enquanto o login vincula por openId / open_id. Seu primeiro login corresponde através da regra de vinculação por e-mail ou telefone, o que funciona porque ambos os provedores relatam esses como verificados.

Login via QR code e recuperação de conta​

O login por QR transfere o problema da senha para o celular: se um usuário perder sua conta WeChat ou DingTalk, ele não poderá escanear. Como cada uma dessas identidades está vinculada a um usuário Casdoor, em vez de ser o próprio usuário, ele ainda pode fazer login com um código de verificação ou redefinir a senha através do fluxo de esquecimento de senha, desde que a aplicação tenha um provedor de e-mail ou SMS e o usuário tenha um endereço cadastrado. O DingTalk e o Lark preenchem isso automaticamente pelo diretório; para o WeChat, solicite um número de telefone no cadastro. Para exibir mais de uma dessas opções na página, consulte métodos de login.

Referências​