OAuth验证接口

来自企业号开发者接口文档
跳转至: 导航搜索

OAuth2.0验证接口说明

企业应用中的URL链接(包括自定义菜单或者消息中的链接),可以通过OAuth2.0验证接口来获取成员的身份信息。


通过此接口获取成员身份会有一定的时间开销。对于频繁获取成员身份的场景,建议采用如下方案:

1、企业应用中的URL链接直接填写企业自己的页面地址

2、成员跳转到企业页面时,企业校验是否有代表成员身份的cookie,此cookie由企业生成

3、如果没有获取到cookie,重定向到OAuth验证链接,获取成员身份后,由企业生成代表成员身份的cookie

4、根据cookie获取成员身份,进入相应的页面


注意,此URL的域名,必须完全匹配企业应用设置项中的'可信域名'(如果你的redirect_uri有端口号,那'可信域名'也必须加上端口号),否则跳转时会提示redirect_uri参数错误。


企业获取code

企业如果需要员工在跳转到企业网页时带上员工的身份信息,需构造如下的链接:

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

员工点击后,页面将跳转至 redirect_uri?code=CODE&state=STATE,企业可根据code参数获得员工的userid。

  • 参数说明
参数 必须 说明
appid 企业的CorpID
redirect_uri 授权后重定向的回调链接地址,请使用urlencode对链接进行处理
response_type 返回类型,此时固定为:code
scope 应用授权作用域。

snsapi_base:静默授权,可获取成员的基础信息; snsapi_userinfo:静默授权,可获取成员的详细信息,但不包含手机、邮箱; snsapi_privateinfo:手动授权,可获取成员的详细信息,包含手机、邮箱。

agentid 企业应用的id。

当scope是snsapi_userinfo或snsapi_privateinfo时,该参数必填。 注意redirect_uri的域名必须与该应用的可信域名一致。

state 重定向后会带上state参数,企业可以填写a-zA-Z0-9的参数值,长度不可超过128个字节
#wechat_redirect 微信终端使用此参数判断是否需要带上身份信息


  • 权限说明

企业无限制;第三方使用snsapi_privateinfo的scope时,应用必须有’成员敏感信息授权’的权限。

根据code获取成员信息

  • 请求说明

Https请求方式:GET

https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo?access_token=ACCESS_TOKEN&code=CODE

  • 参数说明
参数 必须 说明
access_token 调用接口凭证
code 通过成员授权获取到的code,每次成员授权带上的code将不一样,code只能使用一次,10分钟未被使用自动过期
  • 权限说明

跳转的域名须完全匹配管理组中任一应用的可信域名。

  • 返回结果

a)企业成员授权时返回示例如下:

{
   "UserId":"USERID",
   "DeviceId":"DEVICEID"
   "user_ticket": "USER_TICKET",
   "expires_in":7200
}
参数 说明
UserId 成员UserID
DeviceId 手机设备号(由微信在安装时随机生成,删除重装会改变,升级不受影响,同一设备上不同的登录账号生成的deviceid也不同)
user_ticket 成员票据,最大为512字节。

scope为snsapi_userinfo或snsapi_privateinfo,且用户在应用可见范围之内时返回此参数。 后续利用该参数可以获取用户信息或敏感信息。

expires_in user_token的有效时间(秒),随user_ticket一起返回

b)非企业成员授权时返回示例如下:

{
   "OpenId":"OPENID",
   "DeviceId":"DEVICEID"
}
参数 说明
OpenId 非企业成员的标识,对当前企业号唯一
DeviceId 手机设备号(由微信在安装时随机生成,删除重装会改变,升级不受影响)

c)出错时返回示例如下:

{
   "errcode": "40029",
   "errmsg": "invalid code"
}


使用user_ticket获取成员详情

  • 请求说明

Https请求方式:POST

https://qyapi.weixin.qq.com/cgi-bin/user/getuserdetail?access_token=ACCESS_TOKEN

  • 请求示例
{
   "user_ticket": "USER_TICKET"
}
  • 参数说明
参数 必须 说明
access_token 调用接口凭证
user_ticket 成员票据
  • 权限说明

需要有对应应用的使用权限,且成员必须在授权应用的可见范围内。

  • 返回结果

{

  "userid":"lisi",
  "name":"李四",
  "department":[3],
  "position": "后台工程师",
  "mobile":"15050495892",
  "gender":1,
  "email":"xxx@xx.com",
  "avatar":"http://shp.qpic.cn/bizmp/xxxxxxxxxxx/0"

}

参数 说明
userid 成员UserID
name 成员姓名
gender 性别。0表示未定义,1表示男性,2表示女性
department 成员所属部门
position 职位信息
avatar 头像url。注:如果要获取小图将url最后的”/0”改成”/64”即可
mobile 成员手机号,仅在用户同意snsapi_privateinfo授权时返回
email 成员邮箱,仅在用户同意snsapi_privateinfo授权时返回