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授权时返回 |