OAuth2简介
OAuth2的设计背景,在于允许用户在不告知第三方自己的帐号密码情况下,通过授权方式,让第三方服务可以获取自己的资源信息。企业微信提供了OAuth的授权登录方式,可以让从企业微信终端打开的网页获取成员的身份信息,从而免去登录的环节。企业应用中的URL链接(包括自定义菜单或者消息中的链接),均可通过OAuth2.0验证接口来获取成员的UserId身份信息。
企业微信OAuth2接入流程
使用OAuth2前须知
关于网页授权的可信域名
REDIRECT_URL中的域名,需要先配置至应用的“可信域名”,否则跳转时会提示“redirect_uri参数错误”。
要求配置的可信域名,必须与访问链接的域名完全一致。举个例子:
- 假定重定向访问的链接是:http://mail.qq.com:8080/cgi-bin/helloworld:
配置域名 | 是否正确 | 原因 |
---|---|---|
mail.qq.com:8080 | 配置域名与访问域名完全一致 | |
email.qq.com | 配置域名必须与访问域名完全一致 | |
support.mail.qq.com | 配置域名必须与访问域名完全一致 | |
*.qq.com | 不支持泛域名设置 | |
mail.qq.com | 配置域名必须与访问域名完全一致,包括端口号 |
- 假定配置的可信域名是 mail.qq.com:
访问链接 | 是否正确 | 原因 |
---|---|---|
https://mail.qq.com/cgi-bin/helloworld | 配置域名与访问域名完全一致 | |
http://mail.qq.com/cgi-bin/redirect | 配置域名与访问域名完全一致,与协议头/链接路径无关 | |
https://exmail.qq.com/cgi-bin/helloworld | 配置域名必须与访问域名完全一致 |
关于UserID机制
UserId用于在一个企业内唯一标识一个用户,通过网页授权接口可以获取到当前用户的UserId信息,如果需要获取用户的更多信息可以调用 通讯录管理 - 成员接口 来获取。
静默授权与手动授权
-
- 静默授权:用户点击链接后,页面直接302跳转至 redirect_uri?code=CODE&state=STATE
- 手动授权:用户点击链接后,会弹出一个中间页,让用户选择是否授权,用户确认授权后再302跳转至 redirect_uri?code=CODE&state=STATE
缓存方案建议
通过OAuth2.0验证接口获取成员身份会有一定的时间开销。对于频繁获取成员身份的场景,建议采用如下方案:
1、企业应用中的URL链接直接填写企业自己的页面地址
2、成员操作跳转到步骤1的企业页面时,企业后台校验是否有标识成员身份的cookie信息,此cookie由企业生成
3、如果没有匹配的cookie,则重定向到OAuth验证链接,获取成员的身份信息后,由企业后台植入标识成员身份的cookie信息
4、根据cookie获取成员身份后,再进入相应的页面
构造网页授权链接
构造第三方应用oauth2链接
如果第三方应用需要在打开的网页里面携带用户的身份信息,第一步需要构造如下的链接来获取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
参数 | 必须 | 说明 |
---|---|---|
appid | 是 | 企业的CorpID |
redirect_uri | 是 | 授权后重定向的回调链接地址,请使用urlencode对链接进行处理 |
response_type | 是 | 返回类型,此时固定为:code |
scope | 是 | 应用授权作用域。 snsapi_base:静默授权,可获取成员的的基础信息(UserId与DeviceId); snsapi_userinfo:静默授权,可获取成员的详细信息,但不包含手机、邮箱; snsapi_privateinfo:手动授权,可获取成员的详细信息,包含手机、邮箱 注意:企业自建应用可以根据userid获取成员详情,无需使用snsapi_userinfo和snsapi_privateinfo两种scope。更多说明见scope |
agentid | 否 | 企业应用的id。 当scope是snsapi_userinfo或snsapi_privateinfo时,该参数必填 注意redirect_uri的域名必须与该应用的可信域名一致。 |
state | 否 | 重定向后会带上state参数,企业可以填写a-zA-Z0-9的参数值,长度不可超过128个字节 |
#wechat_redirect | 是 | 终端使用此参数判断是否需要带上身份信息 |
员工点击后,页面将跳转至 redirect_uri?code=CODE&state=STATE,企业可根据code参数获得员工的userid。code长度最大为512字节。
scope的特殊情况
-
- scope为snsapi_userinfo或snsapi_privateinfo时,必须填agentid参数,否则系统会视为snsapi_base,不会返回敏感信息。
- 第三方服务商配置scope为snsapi_privateinfo时,agentid所对应的应用必须有“成员敏感信息授权”的权限。“成员敏感信息授权”的开启方法为:登录服务商管理后台->标准应用服务->本地应用->进入应用->点击基本信息栏“编辑”按钮->勾选”成员敏感信息”
- 企业自建应用调用读取成员接口没有字段限制,可以获取包括敏感字段在内的所有信息。因此,只有第三方应用才有必要使用snsapi_userinfo或snsapi_privateinfo的scope。
获取访问用户身份
请求方式: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
}
参数 | 说明 |
---|---|
errcode | 返回码 |
errmsg | 对返回码的文本描述内容 |
CorpId | 用户所属企业的corpid |
UserId | 用户在企业内的UserID,如果该企业与第三方应用有授权关系时,返回明文UserId,否则返回密文UserId |
DeviceId | 手机设备号(由企业微信在安装时随机生成,删除重装会改变,升级不受影响) |
user_ticket | 成员票据,最大为512字节。 scope为snsapi_userinfo或snsapi_privateinfo,且用户在应用可见范围之内时返回此参数。 后续利用该参数可以获取用户信息或敏感信息,参见“第三方使用user_ticket获取成员详情”。 |
expires_in | user_ticket的有效时间(秒),随user_ticket一起返回 |
b) 若用户不属于任何企业,返回示例如下:
{
"errcode": 0,
"errmsg": "ok",
"OpenId":"OPENID",
"DeviceId":"DEVICEID"
}
参数 | 说明 |
---|---|
errcode | 返回码 |
errmsg | 对返回码的文本描述内容 |
OpenId | 非企业成员的标识,对当前服务商唯一 |
DeviceId | 手机设备号(由企业微信在安装时随机生成,删除重装会改变,升级不受影响) |
获取访问用户敏感信息
请求方式: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"
}
参数说明:
参数 | 说明 |
---|---|
errcode | 返回码 |
errmsg | 对返回码的文本描述内容 |
corpid | 用户所属企业的corpid |
userid | 成员UserID |
name | 成员姓名 |
mobile | 成员手机号,仅在用户同意snsapi_privateinfo授权时返回 |
gender | 性别。0表示未定义,1表示男性,2表示女性 |
成员邮箱,仅在用户同意snsapi_privateinfo授权时返回 | |
avatar | 头像url。注:如果要获取小图将url最后的”/0”改成”/100”即可。仅在用户同意snsapi_privateinfo授权时返回 |
qr_code | 员工个人二维码(扫描可添加为外部联系人),仅在用户同意snsapi_privateinfo授权时返回 |