企业微信三方应用服务商获取通讯录及扫码登录(测试应用)

编程语言 2022-05-13 02:39:53 阅读次数: 0

一、前言

公司作为企业微信第三方应用服务商，想要获取到授权企业的通讯录信息中的用户信息和部门信息，以及授权企业的成员可以扫码进行登录。

二、流程梳理

1.后台配置

image.png
红色箭头标记的是最基本的需要的东西。
可信域名：设置可信域名后支持应用的OAuth2授权、JSSDK调用、通讯录名称转义等大部分操作都必须在这个域名下发起才能成功。
指令回调URL:系统将会把此应用的授权变更事件、ticket参数、通讯录变更信息等推送给此URL
TOKEN:主要是用来进行校验回调请求的合法性。
EncodingAESKey：回调消息加解密参数，是AES密钥的Base64编码，用于解密回调消息内容对应的密文。后续所有托管的企业产生的回调消息都使用该值来解密。
这里的TOKEN和EncodingAESKey主要是用来校验数据回调URL和指令回调URL是否能够被企业微信服务器调用成功。
校验URL
企业微信验证URL是否能够被调用是GET请求，各项信息的通知是相同URL下的POST请求。也就是需要用配置的URL 写一个GET用来校验,一个POST请求接受信息。 校验信息

router.GET("/wx/cmdback", func(c *gin.Context) {
   /*
      数据回调验证
   */
   //企业微信加密签名
   msgSignature := cast.ToString(c.Query("msg_signature"))
   //时间戳
   timestamp := cast.ToInt64(c.Query("timestamp"))
   //随机数
   nonce := cast.ToString(c.Query("nonce"))
   //加密字符串
   echostr, err := url.PathUnescape(c.Query("echostr"))
   if err != nil {
      fmt.Println("url解码失败")
      return
   }
   //企业微信api 详情可以看企业微信文档
   wxcpt := wxbizmsgcrypt.NewWXBizMsgCrypt(model.Token, model.EncodingAesKey, model.CorpId, wxbizmsgcrypt.XmlType)
   echoStr, cryptErr := wxcpt.VerifyURL(msgSignature, cast.ToString(timestamp), nonce, echostr)
   if nil != cryptErr {
      fmt.Println("verifyUrl fail", cryptErr)
      return
   }
   fmt.Println("verifyUrl success echoStr")
   c.String(util.Success, string(echoStr))//返回解密出来的字符串给企业微信校验

})
复制代码

接收信息

router.POST("/wx/cmdback", func(c *gin.Context) {
   /*
      指令回调URL： 微信服务器推送suite_ticket以及安装应用时推送auth_code时。
   */
   //企业微信加密签名
   msgSignature := cast.ToString(c.Query("msg_signature"))
   //时间戳
   timestamp := cast.ToString(c.Query("timestamp"))
   //随机数
   nonce := cast.ToString(c.Query("nonce"))
   // post请求的密文数据
   defer c.Request.Body.Close()
   con, _ := ioutil.ReadAll(c.Request.Body) //获取post的数据

   // 访问应用和企业回调传不同的ID
   wxcpt := wxbizmsgcrypt.NewWXBizMsgCrypt(model.Token, model.EncodingAesKey, model.SuitId, wxbizmsgcrypt.XmlType)
   msg, cryptErr := wxcpt.DecryptMsg(msgSignature, timestamp, nonce, con)
   if nil != cryptErr {
      fmt.Println("DecryptMsg fail", cryptErr)
      return
   }
   fmt.Println(string(msg))

   var content MsgContent
   xml.Unmarshal(msg, &content)
   var changeContent ChangeContent
   xml.Unmarshal(msg, &changeContent)
   fmt.Println(changeContent)
   
   //业务逻辑，根据信息需要进行的业务逻辑
   
   '''
 
   
   c.String(util.Success, "success")//需要返回"success"不然企业微信认为此次请求错误
})
复制代码

2.安装应用

未命名文件 (3).png

  1. 企业首先需要安装第三方应用和授权，企业有两种方式进行安装授权。从第三方服务商发起授权比应用商店授权相比，无非是需要第三方服务商自己生成跳转到微信授权网站的链接。
  • 从第三方服务商

(1) 获取第三方应用凭证（suite_access_token）

企业微信服务器会定时（每十分钟）推送ticket。ticket会实时变更，并用于后续接口的调用。

请求地址： qyapi.weixin.qq.com/cgi-bin/ser…

请求包体：

{
	"suite_id":"wwddddccc7775555aaa" ,
	"suite_secret": "ldAE_H9anCRN21GKXVfdAAAAAAAAAAAAAAAAAA", 
	"suite_ticket": "Cfp0_givEagXcYJIztF6sfbdmIZCmpaR8ZBsvJEFFNBrWmnD5-CGYJ3_NhYexMyw" 
}
复制代码

参数说明：

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

代码实现：

func GetSuiteAccessToken(ticket string) {
  result, err := util.Post(util.PostSuiteAccessToken, util.WxSuite{SuiteId: model.SuitId, SuiteTicket: ticket, SuiteSecret: model.SuitSecret})
  if err != nil {
     fmt.Println("Post Suite Token Fail")
  }
  var wxRspSuiteToken util.WxRspSuiteToken
  err = json.Unmarshal([]byte(result), &wxRspSuiteToken)
  if err != nil {
     fmt.Println(err)
  }
  if wxRspSuiteToken.ErrCode == 0 {
     model.GetRedis().Set("suiteAccessToken", wxRspSuiteToken.SuiteAccessToken, time.Minute*30)
     fmt.Println("获取成功，suiteAccessToken==>", cast.ToString(wxRspSuiteToken.SuiteAccessToken))
  } else {
     fmt.Println("errCode==>", wxRspSuiteToken.ErrCode)
     fmt.Println("errMsg==>", wxRspSuiteToken.ErrMsg)
  }
}
复制代码

获取到的suite_access_token有效期为2小时，应当进行缓存，接下来各项操作需要携带。

(2) 获取预授权码

请求方式： GET（HTTPS）
请求地址：  qyapi.weixin.qq.com/cgi-bin/ser…

扫描二维码关注公众号，回复： 14137186 查看本文章

参数说明：

参数 是否必须 说明
suite_access_token 是 第三方应用access_token,最长为512字节

返回结果：

{
	"errcode":0 ,
	"errmsg":"ok" ,
	"pre_auth_code":"Cx_Dk6qiBE0Dmx4EmlT3oRfArPvwSQ-oa3NL_fwHM7VI08r52wazoZX2Rhpz1dEw",
	"expires_in":1200
}
复制代码

代码实现：

/*
   预授权码
*/
func GetAuthCode(suiteAccessToken string) string {
   data, err := util.Get(util.GetAuthCode + "?suite_access_token=" + suiteAccessToken)
   if err != nil {
      fmt.Println("预授权码wx请求失败")
      return ""
   }
   var rsp util.WxRspAuthorizationCode
   err = json.Unmarshal(data, &rsp)
   if err != nil {
      fmt.Println("预授权码解析失败")
      return ""
   }
   if rsp.ErrCode != 0 {
      fmt.Println("ErrorCode==>", rsp.ErrCode)
      fmt.Println("ErrMsg==>", rsp.ErrMsg)
      return ""
   }
   return rsp.PreAuthCode

}
复制代码

*注意：因为是测试应用，还未进行发布，所以要对预授权设置授权，让其支持测试，正式应用不需要此操作。

设置授权配置

该接口可对某次授权进行配置。可支持测试模式（应用未发布时）。

请求方式： POST（HTTPS）
请求地址：  qyapi.weixin.qq.com/cgi-bin/ser…

请求包体：

{
	"pre_auth_code":"xxxxx",
	"session_info":
	{
		"appid":[1,2,3],
		"auth_type":1
	}
}
复制代码

参数说明：

参数 是否必须 说明
suite_access_token 是 第三方应用access_token
pre_auth_code 是 预授权码
session_info 是 本次授权过程中需要用到的会话信息
appid 否 允许进行授权的应用id，如1、2、3， 不填或者填空数组都表示允许授权套件内所有应用（仅旧的多应用套件可传此参数，新开发者可忽略）
auth_type 否 授权类型：0 正式授权， 1 测试授权。 默认值为0。注意，请确保应用在正式发布后的授权类型为“正式授权”

返回结果：

{
	"errcode": 0,
	"errmsg": "ok"
}
复制代码

代码实现：

PreAuthCode := GetAuthCode(suiteAccessToken)
//应用未发布时。测试
req := map[string]interface{}{
   "pre_auth_code": PreAuthCode,
   "session_info": map[string]interface{}{
      "auth_type": 1,
   },
}
util.Post("https://qyapi.weixin.qq.com/cgi-bin/service/set_session_info"+"?suite_access_token="+suiteAccessToken, &req)
复制代码

(3) 获取永久授权码

该API用于使用临时授权码换取授权方的永久授权码，并换取授权信息、企业access_token，临时授权码一次有效。

请求方式： POST（HTTPS）
请求地址：  qyapi.weixin.qq.com/cgi-bin/ser…

请求包体：

{
	"auth_code": "auth_code_value"
}
复制代码

代码实现：

/*
   永久授权码
*/
func GetPermanentCode(suiteAccessToken string, authCode string) (string, util.AuthCorpInfo) {
   post, err := util.Post(util.PostPermanentCode+"?suite_access_token="+suiteAccessToken, util.WxAuthCode{AuthCode: authCode})
   if err != nil {
      fmt.Println("Post PermanentCode Fail")
      return "", util.AuthCorpInfo{}
   }
   var wxAuthCode util.WxRspAuthCode
   err = json.Unmarshal([]byte(post), &wxAuthCode)
   if err != nil {
      fmt.Println("解析失败")
      return "", util.AuthCorpInfo{}
   }
   if wxAuthCode.ErrCode != 0 {
      fmt.Println(wxAuthCode.ErrCode)
      fmt.Println(wxAuthCode.ErrMsg)
      return "", util.AuthCorpInfo{}
   } else {
      return wxAuthCode.PermanentCode, wxAuthCode.AuthCorpInfo
   }
}
复制代码

当企业成功安装应用后，企业微信会通过第三方应用后台配置的数据回调URL，将企业的各项信息返回，开发者可以根据自己需要存储信息，最重要的存储授权企业的id（corp_id）和永久授权码(permanent_code)，后面需要根据指定企业的id，取到相应的永久授权码，从而获取到能获取到指定企业的access_token。

3.获取通讯录信息

未命名文件 (3).png
*注意：在企业安装应用时，在同意安装页面记得需要可见范围范围，不然获取不到整个企业的部门和成员信息

(1)获取企业凭证（access_token）

第三方服务商在取得企业的永久授权码后，通过此接口可以获取到企业的access_token。 获取后可通过通讯录、应用、消息等企业接口来运营这些应用。
此处获得的企业access_token与企业获取access_token拿到的token，本质上是一样的，只不过获取方式不同。获取之后，就跟普通企业一样使用token调用API接口。
*注意：因权限问题获取的信息可能不同。如三方无法直接获取用户名称等

请求方式： POST（HTTPS）
请求地址：  qyapi.weixin.qq.com/cgi-bin/ser…

请求包体：

 {
 	"auth_corpid": "auth_corpid_value",
 	"permanent_code": "code_value"
 }
复制代码

参数说明：

参数 是否必须 说明
auth_corpid 是 授权方corpid
permanent_code 是 永久授权码，通过get_permanent_code获取

返回结果：

{
	"errcode":0 ,
	"errmsg":"ok" ,
	"access_token": "xxxxxx", 
	"expires_in": 7200
}
复制代码

参数说明：

参数 说明
access_token 授权方（企业）access_token,最长为512字节
expires_in 授权方（企业）access_token超时时间

代码实现：

/*
   第三方应用获取指定企业凭证
 */
func GetAccessToken(companyId int) string {
   var company model.Company
   model.GetDB().Where("company_id = ?", companyId).First(&company)
   if company.CompanyId == 0 {
      fmt.Println("公司匹配失败")
   }
   preCode := company.PermanentCode
   CorpId := company.CorPid
   suitToken := model.GetRedis().Get("suiteAccessToken").Val()
   wxReq := util.WxReqDepartment{AuthCorpid: CorpId, PermanentCode: preCode}
   data, err := util.Post(util.PostAccessToken+"?suite_access_token="+suitToken, wxReq)
   if err != nil {
      fmt.Println(err)
   }
   var wxAccessToken util.WxRspAccessToken
   json.Unmarshal([]byte(data), &wxAccessToken)
   fmt.Println(wxAccessToken)
   if wxAccessToken.ErrCode != 0 {
      fmt.Println(wxAccessToken.ErrMsg)
      return ""
   } else {
      fmt.Println("获取成功,AccessToken==>", wxAccessToken.AccessToken)
      return wxAccessToken.AccessToken
   }
}
复制代码

拿到access_token需要先缓存起来，因为企业微信做了频率校验，超过次数将无法获取access_token，token有效期为两个小时，两个小时内获取到的access_token是一样的。有了token就可以访问通讯录的各项信息。

(2)获取部门成员详情

请求方式： GET（HTTPS）
请求地址： qyapi.weixin.qq.com/cgi-bin/use…

参数说明：

参数 必须 说明
access_token 是 调用接口凭证
department_id 是 获取的部门id
fetch_child 否 1/0：是否递归获取子部门下面的成员

权限说明：

应用须拥有指定部门的查看权限。
返回结果：

{
	"errcode": 0,
	"errmsg": "ok",
        "userlist": [
        {
            "userid": "userid",
            "name": "name",
            "department": [
                1
            ],
            "gender": "0",
            "avatar": "https://rescdn.qqmail.com/node/wwmng/wwmng/style/images/independent/DefaultAvatar$73ba92b5.png",
            "status": 1,
            "order": [
                0
            ],
            "main_department": 1,
            "is_leader_in_dept": [],
            "thumb_avatar": "https://rescdn.qqmail.com/node/wwmng/wwmng/style/images/independent/DefaultAvatar$73ba92b5.png",
            "open_userid": "",
            "direct_leader": []
        },
       
    ]
}
复制代码

第三方应用能拿到企业成员的信息不多，详情可以参照企业微信文档developer.work.weixin.qq.com/document/pa…

(3)获取部门列表

请求方式： GET（HTTPS）
请求地址： qyapi.weixin.qq.com/cgi-bin/dep…

参数说明 ：

参数 必须 说明
access_token 是 调用接口凭证
id 否 部门id。获取指定部门及其下的子部门（以及子部门的子部门等等，递归）。 如果不填，默认获取全量组织架构

权限说明：

只能拉取token对应的应用的权限范围内的部门列表

返回结果：

{
   "errcode": 0,
   "errmsg": "ok",
   "department": [
       {
           "id": 2,
           "name": "广州研发中心",
		   "name_en": "RDGZ",
		   "department_leader":["zhangsan","lisi"],
           "parentid": 1,
           "order": 10
       },
       {
           "id": 3,
           "name": "邮箱产品部",
		   "name_en": "mail",
		   "department_leader":["lisi","wangwu"],
           "parentid": 2,
           "order": 40
       }
   ]
}
复制代码

(4)通讯录转义

当第三方拉取到信息时会发现，部门名和成员名都等于部门id和成员id，无法显示真实的名称，主要是因为企业微信为了保护隐私，第三方将不再直接获取到授权企业的通讯录数据（接口将不再返回人名与部门名）。 所以开发者如果需要展示名称就需要对名称进行转义，有两种方法可以进行转义。

通讯录组件转换名称

这种方法主要是前端实现，后端只需要返回前端需要的相关配置信息。
详情参照企业微信文档 developer.work.weixin.qq.com/document/pa…

通讯录ID转义

需要前后端配合实现,详情参照企业微信文档 developer.work.weixin.qq.com/document/pa…

实现流程

未命名文件 (3).png 实现步骤
1.需要先创建一个文件（txt,csv,xls,xlsx,doc,docx）,并替换模板，效果如下图所示：

QQ图片20220512122236.png
要获取部门名称同理,模板如下：
$departmentName=DEPARTMENT_ID$
$userName=USERID$
将你要查的id替换大写英文的部分，只能转义同一公司的id，不然不会进行转义。
2.上传文件到企业微信，这里是在后端进行上传。

client := http.Client{}
bodyBuf := &bytes.Buffer{}
bodyWrite := multipart.NewWriter(bodyBuf)
//上传给企业微信
//创建请求并设置内容类型
fileWrite, err := bodyWrite.CreateFormFile("media", "file.xlsx")
_, err = io.Copy(fileWrite, excel)
if err != nil {
   log.Println("err")
}
bodyWrite.Close() //要关闭，会将w.w.boundary刷写到w.writer中
// 创建请求
contentType := bodyWrite.FormDataContentType()
req, err := http.NewRequest(http.MethodPost, util.PostMediaFile+"?provider_access_token="+token+"&type=file", bodyBuf)
if err != nil {
   log.Println("err")
}
// 设置头
req.Header.Set("Content-Type", contentType)
resp, err := client.Do(req)
if err != nil {
   log.Println("err")
}
defer resp.Body.Close()
var data1 util.WxRspUploadFile
all, err := ioutil.ReadAll(resp.Body)
if err == nil {
    //解析response
   json.Unmarshal(all, &data1)
}


//返回
{
    "errcode": 0,
    "errmsg": "ok. Warning: wrong json format. ",
    "type": "file",
    "media_id": "3zwYR2FyKTQZuuCvvVyrCGb9j8yNrUqjwqA97cXHQBoZF46rDsIWX4l4fzZCBDYzp",
    "created_at": "1652335969"
}
复制代码

素材上传得到media_id，该media_id仅三天内有效
media_id在同一企业内应用之间可以共享

3.异步通讯录id转译

post, err := util.Post(util.PostTransId+"?provider_access_token="+token,
   map[string]interface{}{
      "auth_corpid":      "ww*******",//授权企业corpid ，也就是需要转义的用户、部门id的所属企业的corpid，安装应用时进行了存储。
      "media_id_list":    []string{data1.MediaId},//上一步上传文件得到的媒体id（media_id）,可以上传多个。
      "output_file_name": "trans_id",//输出的文件名
      //"output_file_format": "xlsx"//输出格式，若不指定，则输出格式跟输入格式相同。
   })
fmt.Println(post)
if err != nil {
   fmt.Println(err)
}

var data2 util.WxRspTranId
json.Unmarshal([]byte(post), &data2)
fmt.Println(data2.JobId)



//结果
{
    "errcode": 0,
    "errmsg": "ok",
    "jobid": "Xq24rw360-NyvhqHnK9ztC_Nr4zeHPyqMbJF-SjwGL0"
}
复制代码

注：若生成的文件不需要压缩，则 media_id_list列表只能指定一项，同时 output_file_name 不需要传值

4.获取异步任务的结果

get, err := util.Get(util.GetJobResult + "?provider_access_token=" + token + "&jobid=" + data2.JobId + "&debug=1")
var data3 util.WxRspJobResult
json.Unmarshal(get, &data3)
result := cast.ToString(data3.Result["contact_id_translate"].(map[string]interface{})["url"])
fmt.Println(result)


//结果
{
    "errcode": 0,
    "errmsg": "ok",
    "status": 3,
    "type": "contact_id_translate",
    "result": {
        "contact_id_translate": {
            "url": "https://open.work.weixin.qq.com/wwopen/openData/getTranslateContactOpenData?dataid=j9otnBMVKUDSf4xrAxxxxxxxxxxxxxxxxxxxxxx"
        }
    }
}
复制代码

注：返回的url参数，开发者在使用时以a标签引用，download属性不可指定（浏览器兼容性问题）

5.下载转义后文件，这是最后也是最麻烦的一步，能够下载的条件是：
1.当前浏览器页面进行了授权登录，存在登录态。
可以通过open.work.weixin.qq.com/wwopen/open… 来检查当前登录态。 QQ图片20220512144056.png
2.需要在配置好的可信域名下进行访问。(不是直接在浏览器中输入打开链接)
满足这两个条件后才会下载id转义后的文件。

4.扫码登录

这里主要讲从第三方进行单点登录，需要构造登录链接以及登录成功回调url大致流程如图所示：

未命名文件 (3).png\

(1)构造链接

1、用户进入服务商网站。
2、服务商网站引导用户进入登录授权页。
服务商可以在自己的网站首页中放置“企业微信登录”的入口，引导用户进入登录授权页。网址为:

https://open.work.weixin.qq.com/wwopen/sso/3rd_qrConnect?appid=ww100000a5f2191&redirect_uri=http%3A%2F%2Fwww.oa.com&state=web_login@gyoss9&usertype=admin
复制代码

3、用户确认并同意授权。
用户进入登录授权页后，需要确认并同意将自己的企业微信和登录账号信息授权给企业或服务商，完成授权流程。
4、授权后回调URI，得到授权码和过期时间。 登录授权发起域名和授权成功回调域名需要在服务商后台进行配置，只能在该域名下才能发起授权和完成授权回调。

image.png

参数 是否必须 说明
appid 是 服务商的CorpID
redirect_uri 是 授权登录之后目的跳转网址，需要做urlencode处理。所在域名需要与授权完成回调域名一致
state 否 用于企业或服务商自行校验session，防止跨域攻击
usertype 否 支持登录的类型。admin代表管理员登录（使用微信扫码）,member代表成员登录（使用企业微信扫码），默认为admin
lang 否 自定义语言，支持zh、en；lang为空则从Headers读取Accept-Language，默认值为zh

代码实现

encode := url.QueryEscape("http://qr-login.xxxxxxxx/wx/returnLogin")//回调地址，需要做urlencode处理
redirect := "https://open.work.weixin.qq.com/wwopen/sso/3rd_qrConnect?appid=" + model.CorpId + "&redirect_uri=" + encode + "&state=" + key + "&usertype=member"
//这里是后端直接跳转到扫码页面
c.Header("Content-Type", "text/html")
c.String(200, "<script type="text/javascript"> window.location.href = ""+redirect+""</script>")
复制代码

(2)获取登录用户信息

1.先获取服务商凭证（provider_access_token）,需要先从服务商后台拿到CorpID和ProviderSecret

QQ图片20220512155333.png
2.第三方可通过如下接口，获取登录用户的信息。建议用户以返回信息中的corpid及userid为主键匹配用户。

请求方式： POST（HTTPS）
请求地址：  qyapi.weixin.qq.com/cgi-bin/ser…

请求包体：

 {
    "auth_code":"xxxxx" //扫码登录成功回调url携带参数
 }
复制代码

参数说明：

参数 是否必须 说明
access_token 是 授权登录服务商的网站时，使用应用提供商的provider_access_token，获取方法参见服务商的凭证
auth_code 是 oauth2.0授权企业微信管理员登录产生的code，最长为512字节。只能使用一次，5分钟未被使用自动过期

代码实现

data, err := util.Post(util.GetLoginInfo+"?access_token="+corpToken, map[string]interface{}{
   "auth_code": authCode,
})
fmt.Println(data)
if err != nil {
   fmt.Println("post获取用户信息失败")
   return
}
var result util.WxRspLoginInfo
json.Unmarshal([]byte(data), &result)
if result.ErrCode != 0 {
   fmt.Println("获取用户信息失败")
   return
}
复制代码

返回结果中可以获取到成员id就可以进行身份校验。

猜你喜欢

转载自juejin.im/post/7096772149037236232
今日推荐
面壁智能发布 Eurux-8x22B 开源大模型 —— 堪称「理科状元」
开源日报 | 谷歌扶持鸿蒙上位；开源Rabbit R1；Docker加持的安卓手机；微软的焦虑和野心；海尔电器把开放平台关了
中国码农的“35岁魔咒”
蘭雅 CorelDRAW 插件 2024.5.1 国际劳动节版，免费下载
Arc Browser for Windows 1.0 正式 GA
90后程序员开发视频搬运软件、不到一年获利超 700 万，结局很刑！
周排行
OOP第二次作业
java web 乱码问题
android 禁止scrollview 因控件变化自动滚动到底的方法
mysql服务解压版的安装(5.7)
centos7 nginx+tomcat配置https 安装免费SSL Let’s Encrypt
使用Mosquitto遗嘱机制实现感知客户端上下线功能的方法
面向对象之------多态与多态性
开发Teams Tabs应用程序
C# 希尔排序
第2章 Jupyter Notebooks
每日归档
更多
2024-05-06(40)
2024-05-05(0)
2024-05-04(7)
2024-05-03(19)
2024-05-02(0)
2024-05-01(4)
2024-04-30(1)
2024-04-29(40)
2024-04-28(0)
2024-04-27(56)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022