# 1.1 网页授权登录
第三方应用可以使用此接口构造勤策oAuth2授权登录回调接口,完成系统对接自动登录
# 1.1.1 获取授权令牌AccessToken
为了安全考虑,开发者请勿将access_token返回给前端,需要开发者保存在后台,所有访问勤策api的请求由后台发起
获取access_token是调用勤策API接口的第一步,相当于创建了一个登录凭证,其它的业务API接口,都需要依赖于access_token来鉴权调用者身份。 因此开发者,在获取企业及用户信息,以及其他授权的业务操作前,要明确access_token的颁发来源,使用正确的access_token。
企业接入申请是由企业管理员向客户经理提出开通申请,勤策审核通过后向企业提供参数app_id、app_secret、tenant_id用于接口调用。
请求方式: POST(HTTPS)
请求地址: https://sso.qince.com/service/oauth/token
请求示例:
{
"app_id":"app1029034344",
"app_secret":"NX09FRERZAFERERT96KL=",
"tenant_id":"6692513571099135446"
}
参数说明:
参数 | 是否必须 | 说明 |
---|---|---|
app_id | 是 | 服务商应用的唯一标识,用于接口区分不同应用 |
app_secret | 是 | 应用的凭证密钥,相当于登录密码,开发者应保管好该字段值,避免在公开场合暴露(比如在网页参数) |
tenant_id | 是 | 企业ID,是企业在勤策的租户唯一标识 |
响应示例:
{
"return_code":0,
"return_msg":"success",
"return_data": {
"access_token":"2019040189580858920907506625723500936366986112",
"expires_in":7200
}
}
参数说明:
参数 | 说明 |
---|---|
return_code | 出错返回码。0:表示成功,非0:表示调用失败 |
return_msg | 返回码提示语 |
access_token | 获取到的凭证,最长为512字节 |
expires_in | 凭证的有效时间(秒) |
注意事项: 开发者需要缓存access_token,用于后续接口的调用(注意:不能频繁调用gettoken接口,否则会受到频率拦截)。当access_token失效或过期时,需要重新获取。
access_token的有效期通过返回的expires_in来传达,正常情况下为7200秒(2小时),每次调用获取都会返回新的access_token。 access_token至少保留512字节的存储空间。 勤策可能会出于运营需要,提前使access_token失效,开发者应实现access_token失效时重新获取的逻辑。
# 1.1.2 获取用户临时授权令牌code
# 1.1.2.1 通过网页授权菜单获取code
当外部系统链接URL需要作为菜单嵌入勤策手机APP或WEB系统时,由于在勤策已经登录,用户打开菜单时直接生成授权code并作为参数跳转到第三方服务地址REDIRECT_URI。可适用于在勤策APP、WEB或企业微信中配置菜单入口,以及勤策订货APP、WEB和公众号入口。
网页授权菜单配置流程
请求方式: GET(HTTPS)
请求地址: RREDIRECT_URI?code=XXXX&state=STATE&tenant_id=TENANT_ID&app_id=APP_ID
点击授权菜单成功跳转地址:
HTTP/1.1 302 Found
Location: REDIRECT_URI?code=XXXX&state=1234&tenant_id=111222333444&app_id=app12344455566
参数说明:
参数 | 说明 |
---|---|
code | 用户访问授权码。用户打开菜单时直接生成授权code并作为参数跳转到第三方服务地址REDIRECT_URI,最大为512字节。每次成员授权带上的code将不一样,code只能使用一次,5分钟未被使用自动过期。 |
redirect_uri | 企业在勤策配置的重定向URI,代表当授权完成之后,返回的路径 |
state | 由于后续步骤验证时用的随机字符串,最长为64字节 |
tenant_id | 企业在勤策的租户唯一标识 |
app_id | 应用的唯一标识,用于接口区分不同应用 |
点击授权菜单失败跳转地址:
HTTP/1.1 302 Found
Location: https://cloud.waiqin365.com/oauth2/authorize_error.jsp?error=access_denied&state=1342&app_id=app12344455566
参数说明:
参数 | 说明 |
---|---|
redirect_uri | 重定向URI,代表当授权完成之后,返回的路径 |
error | 错误码: invalid_request-请求错误 unauthorized_client-访问未授权链接 access_denied-服务器拒绝访问 unsupported_response_type-不支持响应类型 invalid_scope-请求授权信息失败 server_error-服务器错误 |
state | 由于后续步骤验证时用的随机字符串,最长为64字节 |
app_id | 应用的唯一标识,用于接口区分不同应用 |
# 1.1.2.2 构造独立授权oAuth2链接
当需要在独立系统(非勤策手机APP/WEB/企业微信/服务号/小程序)中使用勤策用户帐号授权时,可根据需要生成授权链接地址,当用户访问此授权链接地址时会提示用户使用勤策帐号登录并“授权”获取用户信息,授权完成后将带授权参数code跳转到REDIRECT_URI。适用于独立的H5、WEB页面使用勤策帐号统一授权登录第三方H5、WEB的场景。
请求方式: GET(HTTPS)
请求地址: https://cloud.waiqin365.com/service/oauth/authorize?response_type=code&app_id=APP_ID&redirect_uri=REDIRECT_URI&scope=user&state=STATE&tenant_id=TENANT_ID
GET /service/oauth/authorize?response_type=code&app_id=app1234455555&state=1342&tenant_id=1112222334444&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: cloud.waiqin365.com
参数说明:
参数 | 是否必须 | 说明 |
---|---|---|
response_type | 是 | 用户访问模式。code:授权码模式 |
app_id | 是 | 应用ID |
redirect_uri | 是 | 重定向URI,代表当授权完成之后,返回的路径。参数需要UrlEncode编码 |
scope | 是 | 当前需要访问的授权信息 |
tenant_id | 是 | 企业ID |
state | 是 | 由于后续步骤验证时用的随机字符串,最长64字节 |
客户端授权页面: 用户首次打开应用的授权链接时需要用户授权,授权界面如下:
授权成功后跳转地址:
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=XXXX&state=1342&tenant_id=YYYY&app_id=app1234444444
参数说明:
参数 | 说明 |
---|---|
redirect_uri | 重定向URI,代表当授权完成之后,返回的路径 |
code | 用户授权码 |
state | 由于后续步骤验证时用的随机字符串,最长64字节 |
tenant_id | 企业唯一ID |
app_id | 应用ID |
授权失败后跳转地址:
HTTP/1.1 302 Found
Location: https://cloud.waiqin365.com/oauth2/authorize_error.jsp?error=access_denied&state=1342&app_id=app1234444444
参数说明:
参数 | 说明 |
---|---|
redirect_uri | 重定向URI,代表当授权完成之后,返回的路径 |
error | 错误码: invalid_request-请求错误 unauthorized_client-访问未授权链接 access_denied-服务器拒绝访问 unsupported_response_type-不支持响应类型 invalid_scope-请求授权信息失败 server_error-服务器错误 |
state | 由于后续步骤验证时用的随机字符串,最长64字节 |
app_id | 应用ID |
# 1.1.2.3 通过第三方应用APP唤起勤策APP授权获取code
当第三方APP需要使用勤策用户授权登录时,由第三方APP直接打开勤策客户端包名或类名,由勤策用户登录授权完成后返回授权码参数code到第三方APP。适用于第三方应用APP使用勤策帐号统一授权登录第三方APP的场景。
请求方式: 直接打开客户端类名
请求地址: 第三方应用包名或类名
请求参数说明:
参数 | 是否必须 | 说明 |
---|---|---|
app_id | 是 | 应用ID |
scope | 是 | 唤起APP要申请的权限编码:user-用户信息 custom-客户信息 all-所有权限 |
响应参数说明:
参数 | 是否必须 | 说明 |
---|---|---|
code | 是 | 用户访问授权码。用户打开菜单时直接生成授权code并作为参数跳转到第三方服务地址REDIRECT_URI,最大为512字节。每次成员授权带上的code将不一样,code只能使用一次,5分钟未被使用自动过期 |
state | 是 | 由于后续步骤验证时用的随机字符串,最长为64字节 |
expires_in | 是 | 令牌有效时间,单位秒 |
# 1.1.3 获取访问用户信息
第三方应用可以使用此接口获取当前授权的企业用户基本信息
请求方式: POST(HTTPS)
请求地址: https://sso.qince.com/service/oauth/userinfo?access_token=2019040189580858920907506625723500936366986112&code=2019040409119168303823765016020d9cd24aa343ecb0c4047ba67a5e24
参数说明:
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 应用授权AccessToken,生成方法详见 [1.1.1 获取授权令牌AccessToken](https://api.waiqin365.com/PROVIDER/oauth/oauth2.html#1.1.1 获取授权令牌AccessToken) |
code | 是 | 用户访问授权码。用户打开菜单时直接生成授权code并作为参数跳转到第三方服务地址REDIRECT_URI,最大为512字节。每次成员授权带上的code将不一样,code只能使用一次,5分钟未被使用自动过期 |
响应示例:
{
"return_code":0,
"return_msg":"success",
"return_data": {
"tenant_id":"7102807924041722259",
"id":"7102807924041722259",
"name":"张三",
"user_type": "1",
"status":"1",
"depart_id":"5222557594701155252",
"depart_name":"经营部",
"full_depart_name":"/总公司/华中大区/销售部/经营部",
"thrid_id":"244d5c86d3c342f992ced55729fb6f05"
}
}
参数说明:
参数 | 说明 |
---|---|
return_code | 响应码 |
return_msg | 对返回码的文本描述内容 |
tenant_id | 企业ID |
id | 企业用户唯一ID,最长为32字节 |
name | 用户名称,最长为100字节 |
user_type | 用户类型。1:用户,2:客户,3:客户联系人 |
status | 用户状态。1:正常,2:停用,0:销户 |
depart_id | 用户所在部门ID |
depart_name | 用户所在部门名称 |
full_depart_name | 用户所在部门全路径 |
thrid_id | 来源第三方的唯一ID,最长为100字节 |