企微中接入自建应用

瓦力同学
491 阅读5分钟

为何要在企微中接入自建应用

企微 应用可以很方便的通过用户企微手机号和公司自身的账户体系进行打通，方便在企微端嵌入公司自身的业务流程。

接入步骤

  1. 创建企微应用，配置可信域名、可信 IP、回调域
  2. 对接企微网页授权机制
  3. 企微账户跟公司账户系统打通

创建企微应用

首先使用企微管理员身份登录企微管理后台。

按转这个路径创建应用

应用管理-自建-创建应用

image.png

本文以自建 web 应用进行说明。

image 1.png

填写应用名称和描述，选择应用可见范围，这个可见范围代表的意思是，在公司的组织结构中哪些人员可以看到并使用这个应用。

配置企微应用

打开刚刚创建的应用

首先看到上面基础信息这块有三个地方需要重点注意

image 2.png

首先要获取 AgentId 和 Secret 这两个配置 这两个是企微自动生成。在后续的授权和获取 token 的时候需要用到。

应用主页需要进行配置，这个配置的作用是，用户在工作台点击这个应用的时候跳转的页面，可理解为网站首页。

接着配置开发者相关的配置。下面打勾的三个都是必须要配置的。

image 3.png

网页的授权以及JS-SDK

image 4.png

我们以如下场景介绍如何配置

image 5.png

前端域名 www.xxx.com 负责承载静态资源包括页面、样式、图片等。

服务域名 api.xxx.com 负责业务流程处理和数据交互。

可信域名

一般正常情况微信的授权回调会回调到服务端的接口，服务端的接口做处理。

在这种情况下授权回调域就要填写 api.xxx.com

配置这个可信域名的时候，微信要需要进行域名校验.

点击下面申请校验域名，会有校验域名提示步骤。

image 6.png

下载校验的文件，打开后其实就是一个字符串

image 7.png

企微要求在域名的根录下可以通过该文件名访问到这一个字符串。

现在有两种方式进行配置。

方式一:

将这个文件放到nginx所在服务器可访问的一个目录下，通过nginx 的配置返回该文件内容。

方式二：

直接通过后端的接口返回该字符串，这样也是需要 nginx 配合，直接将该文件的访问直接转发到服务端。

以 java 为例后端的接口如下

image 8.png

可调用JS-SDK、跳转小程序的可信域名

前端需要调用企微的 JS-SDK 相当的接口这里就需要配置前端相关的可信域名

最终配置如下

image 9.png

这里有个资质的问题需要注意，配置的域名需要跟当前企业的主体是同一个或者有关联关系。

企业可信IP

这个配置的含义是当服务端调用企微的接口的时候，出网ip需要在企微方配置可信域名，支持配置多个出网IP。授权过程需要根据 code 调用企微的接口获取用户的信息，跟企微有接口交互，所以这里需要配置。

应用授权

如下是企微官方给出的自建应用的Oauth2 的授权流程。是一个标准的 Oauth2 的流程。

image 10.png

官方企微的授权跳转链接构造如下：

open.weixin.qq.com/connect/oau…

授权链接的详解

  • appid:企微的企业 id，在企微后台-企业信息中可以查看
  • redirect_uri: 服务端接收企微回调 code 的接口，需要使用urlencode对链接进行处理
  • response_type:固定写 code，对应 Oauth2 的授权码方式
  • scope： 获取用户信息的范围, snsapi_base：静默授权，可获取成员的基础信息（UserId）；snsapi_privateinfo：手动授权，可获取成员的详细信息，包含头像、二维码等敏感信息（此时要求成员必须在应用可见范围内）。
  • agentid：自建应用的id,在应用信息里面可以查看
  • state：重定向回调服务端接口后会带上state参数

详细授权链接说明可以查看企微文档

developer.work.weixin.qq.com/document/pa…

微信授权和回调处理流程

假设我们构造的授权链接如下

open.weixin.qq.com/connect/oau… api.xxx.com/wechat/work…

为了方便讲解，redirect_uri用原始链接表示，实际使用需要对redirect_uri进行 urlencode后拼接到授权链接中。在该链接中把 state赋值为 agentId。

用户通过企微工作台进入到应用首页，前端需要根据当前用户的授权登录状态判断是否需要进行授权，如果需要进行授权，则拼接授权链接并跳转到授权链接，此时后企微会提示用户进行授权

image 11.png

用户点击同意后，企微服务器处理完成后会回调redirect_uri配置的链接地址。

即 api.xxx.com/wechat/work…

下面通过 java 的伪代码来演示授权处理的步骤


@Controller
@RequestMapping("/")
public class QyWechatController {

    @RequestMapping(value = "/wechat/work/auth/callback", method = RequestMethod.GET)
    @AutoLogger
    public void qyWechatCallback(@RequestParam("code") String code,@RequestParam("state") String state, HttpServletResponse response) throws IOException {

        if (StringUtils.isEmpty(code) || StringUtils.isEmpty(state)){
            response.sendRedirect("https://www.xxx.com/error?msg=授权信息错误");
        }

        // 根据agentId 去配置配置库中获取对应的  企微的 企业Id为corpid  和 应用secret
        // 这些配置是提前准备好的，放到一个地方(db、配置中心)方便查找

        // 企微的企业ID 和 应用的 secret 获取 access_token 文档 https://developer.work.weixin.qq.com/document/path/91039
        String accessToken = get_access_token(corpid,secret);

        // 根据accessToken和收到的code 获取 user_ticket 文档 https://developer.work.weixin.qq.com/document/path/96442
        // code 是一次性的用完后就失效了
        QyWechatUserInfo  qyUserInfo = getuserinfo(accessToken,code);

        // 用user_ticket 获取用户的敏感信息 例如手机号 文档  https://developer.work.weixin.qq.com/document/path/96443
        QyWechatUserDetail qyUserDetail =  getuserdetail(accessToken,qyUserInfo.getUserTicket());
        
        
        String phone = qyUserDetail.getMobile();

        // 使用获取到手机跟自身账户体系打通,调用自身业务系统的登录方法，获取到登录信息
        LoginUser loginUser = customLogin(phone);
        
        // 将登录信息放到链接上通过跳转返回给前端
        response.sendRedirect("https://www.xxx.com?userId=" + loginUser.getId() + "&accessToken=" + loginUser.getAccessToken());
    }
}

前端获取链接上的访问凭证设置到 header 中，后续访问带上访问凭证，业务系统根据 header 中的访问凭证就知道用户身份，进行业务处理。

avatar
文章
阅读
粉丝