企业微信-第三方应用网页授权登陆

1、构造第三方应用网页授权链接

如果第三方应用需要在打开的网页里面携带用户的身份信息，第一步需要构造如下的链接来获取 code：

https://open.weixin.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect

参数	必须	说明
appid	是	第三方应用 id（即 ww 或 wx 开头的 suite_id）。注意与企业的网页授权登录不同
redirect_uri	是	授权后重定向的回调链接地址，请使用 urlencode 对链接进行处理 ，注意域名需要设置为第三方应用的可信域名
response_type	是	返回类型，此时固定为：code
scope	是	应用授权作用域。snsapi_base：静默授权，可获取成员的基础信息（UserId与DeviceId）；snsapi_userinfo：静默授权，可获取成员的详细信息，但不包含手机、邮箱等敏感信息；snsapi_privateinfo：手动授权，可获取成员的详细信息，包含手机、邮箱等敏感信息。
state	否	重定向后会带上 state 参数，企业可以填写 a-zA-Z0-9 的参数值，长度不可超过 128 个字节
#wechat_redirect	是	终端使用此参数判断是否需要带上身份信息

 企业员工点击后，页面将跳转至 redirect_uri?code=CODE&state=STATE，第三方应用可根据 code 参数获得企业员工的 corpid 与 userid。code 长度最大为 512 字节。

2、获取访问用户身份

请求方式：GET（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/service/getuserinfo3rd?access_token=SUITE_ACCESS_TOKEN&code=CODE

参数	必须	说明
access_token	是	第三方应用的 suite_access_token，参见“获取第三方应用凭证”
code	是	通过成员授权获取到的 code，最大为 512 字节。每次成员授权带上的 code 将不一样，code 只能使用一次，5 分钟未被使用自动过期。

权限说明：
跳转的域名须完全匹配access_token对应第三方应用的可信域名，否则会返回50001错误。

返回结果：
a) 当用户属于某个企业，返回示例如下：

{
   "errcode": 0,
   "errmsg": "ok",
   "CorpId":"CORPID",
   "UserId":"USERID",
   "DeviceId":"DEVICEID",
   "user_ticket": "USER_TICKET"， //用于获取用户敏感信息
   "expires_in":7200
}

获取访问用户身份，需要先获取到 suite_access_token，获取suite_access_token需要先获取到suite_ticket。

获取企业后台推送的suite_ticket

企业微信服务器会定时（每十分钟）推送 ticket。ticket 会实时变更，并用于后续接口的调用。
请求方式：POST（HTTPS）
请求地址：https://api.ninesix.cc/worktile?msg_signature=87276aaf15a13e1eb2ebb6d93732ca668c3ddef8&timestamp=1551850300&nonce=1551051655

请求体参数说明：

参数	说明
SuiteId	第三方应用的SuiteId
InfoType	"suite_ticket",字符串
TimeStamp	时间戳
SuiteTicket	Ticket内容，最长为512字节

在发生授权、通讯录变更、ticket 变化等事件时，企业微信服务器会向应用的“指令回调 URL”推送相应的事件消息，nodejs 接收到的是 xml，解析后拿到 encrypt 字段，然后使用上面配置通用开发参数的 url 时用的解密方式，就可以得到 suite_ticket。

app.post('/worktile', function (req, res) {
  const str = req.body.xml.encrypt || req.body.xml.Encrypt || '';
  if (str) {
    const xmlResult = checkSignature(req, res, str);//先解码得到xml格式的返回结果
    parseString(xmlResult, { trim: true, explicitArray: false }, (err, result) => {
      if (result && result.xml) {
        console.log('result', result.xml);        
      }
    }) //将xml解析成json格式
  }
  console.log('req.body', req.body);
  console.log('req.query', req.query);

  res.send('success');

});

将得到的 req.body.SuiteTicket保存起来，即为suite_ticket。suite_ticket 实际有效期为 30 分钟，可以容错连续两次获取 suite_ticket 失败的情况，但是请永远使用最新接收到的 suite_ticket。

获取第三方应用的 suite_access_token

请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/service/get_suite_token

参数	是否必须	说明
suite_id	是	以 ww 或 wx 开头应用 id（对应于旧的以 tj 开头的套件 id）
suite_secret	是	应用 secret
suite_ticket	是	企业微信后台推送的 ticket

由于第三方服务商可能托管了大量的企业，其安全问题造成的影响会更加严重，故 API 中除了合法来源 IP 校验之外，还额外增加了 suite_ticket 作为安全凭证。
通过本接口获取的 suite_access_token 有效期为 2 小时，开发者需要进行缓存，不可频繁获取。 

获取到 suite_access_token就可以按照第一步访问用户身份，获取到user_ticket，来获取用户的敏感信息来。

2、获取用户敏感信息

请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/service/getuserdetail3rd?access_token=SUITE_ACCESS_TOKEN

请求包体：

{
   "user_ticket": "USER_TICKET"
}

参数说明：

参数	必须	说明
access_token	是	第三方应用的suite_access_token，参见“获取第三方应用凭证”
user_ticket	是	成员票据

 返回结果

{
   "errcode": 0,
   "errmsg": "ok",
   "corpid": "wwxxxxxxyyyyy",
   "userid": "lisi",
   "name": "李四",
   "mobile": "15913215421",
   "gender": "1",
   "email": "xxx@xx.com",
   "avatar": "http://shp.qpic.cn/bizmp/xxxxxxxxxxx/0",
   "qr_code": "https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=vcfc13b01dfs78e981c"
}

3、用户授权成功

授权成功，就可以正常登陆第三方应用来了。

首页

任务详情页

worktile还增加了项目模块，更多，更好的功能，欢迎体验。

4、给用户发消息

当给我们分配了任务，有日程邀请我们参加，添加了我们关注某个项目等等时，需要我们收到企业微信推送给我们的消息，我们点击就可以定位到第三方应用，直接查看。

目前企业微信可以给推送文本、图片、视频、文件、图文等类型。

请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN

参数	是否必须	说明
access_token	是	企业应用调用接口凭证
agentId	是	企业应用的ID

推送的时候需要 access_token 和 应用的 agentId。第三方服务商，可通过接口 获取企业授权信息 获取该参数值，其实可以直接通过 获取企业永久授权码直接取到这两个值。

获取永久授权码

API用于使用临时授权码换取授权方的永久授权码，并换取授权信息、企业access_token，临时授权码一次有效。建议第三方以userid为主键，来建立自己的管理员账号。

请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/service/get_permanent_code?suite_access_token=SUITE_ACCESS_TOKEN

请求包体：

{
"auth_code": "auth_code_value"
}

参数说明：

参数	是否必须	说明
auth_code	是	临时授权码，会在授权成功时附加在redirect_uri中跳转回第三方服务商网站，或通过回调推送给服务商。长度为64至512个字节

注意：临时授权码和预授权码并不是一个，测试的时候一直拿预授权码来获取永久授权码，导致一直提示invalid auth_code.

在我们安装测试应用成功之后，企业微信会 post 一条请求给指令回调 URL，通过上面的解密方式，可以解析到 xml 中的 auth_code，通过这种方式可以获取到临时授权码。

然后通过https://qyapi.weixin.qq.com/cgi-bin/service/get_permanent_code?suite_access_token=SUITE_ACCESS_TOKEN和 auth_code 可以获取到 access_token 和 agentId，返回的 agent 是一个数组，但仅旧的多应用套件授权时会返回多个agent，对新的单应用授权，永远只返回一个 agent。取agent[0].agentid.

再通过 access_token 和 agentId 就可以愉快的给用户发送消息了。

注意：当点击链接时，可以跳到指定任务或者日程等，只不过返回时还是在企业微信的消息模块，并不能自动打开第三方应用，客服回复不支持这么做。 

注意事项

• 本文更新于 2019 年 3 月 6 日，api 可能有时效性，如有差异，以 官方 api 为准。
• 完整 demo