云客服登录开发指南

前期准备

网站应用须在云客服后台创建客户端应用,方可利用云客服授权联合登录系统,整个流程基于标准的OAUTH2.0协议。

设置 > OAUTH客户端

授权步骤

1. 第三方发起云客服授权登录请求,用户允许授权第三方应用后,云客服重定向到第三方网站,URL附上临时授权码code参数;

2. 第三方通过code加上client_id等参数,请求access_token;

3. 第三方通过access_token,获取用户基本数据资源或帮助用户实现基本操作。

access_token 获取时序图:

第一步:获取 code 临时授权码

临时授权码有效期为 10 分钟,可凭借此授权码向云客服请求 access_token。

https://{yourdomain}.kf5.com/authorize/start?response_type=code&client_id={client_id}&state={state}&redirect_uri=https%3A%2F%2Fclient.abc.com%2Fcb

假设回调 redirect_uri 为:

https://client.abc.com/cb

请求参数

参数是否必须说明
response_type填写 code
client_idclient 注册时分配的『客户端唯一标识』
scopeclient 授权域,拥有多个授权域用『逗号』(,)分隔,目前仅支持 user:read
redirect_uri默认使用 client 注册时使用的『跳转地址』,必须 urlencode 处理
state用于 client 对保持上下文

正确响应

成功将返回临时授权码,从回调接口中通过 code 参数获得。

                https://client.abc.com/cb?state={state}&code={code}

错误响应

失败后可以通过 error 以及 error_description 了解本次授权失败的原因。

                https://client.abc.com/cb?state={state}&error=invalid_request&error_description=invalid_request

第二步:授权码 code 请求 access_token

通过第一步获取的 code,请求 access_token,会同时返回 refresh_token,请妥善保管。

    POST /oauth/token HTTP/1.1
Host: {youdoamin}.kf5.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

认证方式

BASIC AUTH 认证,username 和 password 分别为 client 注册时生成的『OAUTH客户端唯一标识』和『通信秘钥』。

请求参数

参数是否必须说明
grant_type填写 authorization_code
code临时授权码

正确响应

                    {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTMxMDgsInVpZCI6Ijc0NCIsInNjb3BlcyI6InJlYWQsdGlja2V0OndyaXRlIiwiaWQiOiIxMDAwMDExIn0.BFy35PGyQr0OS7ZxPYFiI_VkiYj7fjkweF1bCIETGkE",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTY3MDgsImlkIjoiMTAwMDAxMSJ9.UpnsxNRe-AO9nUcfQiwXU1nVaDjoAMOLYzkqbq_tqpI"
}

响应参数

参数说明
access_token用户资源访问票据
token_typetoken类型,固定为 bearer
expires_inaccess_token有效期,2 小时
refresh_token刷新码,有效期为 30 天

错误响应

                    {
    "error":"invalid_grant",
    "error_description":"The Authorization code is invalid"
}

用 refresh_token 刷新 access_token

access_token 过期后,用 refresh_token 刷新 access_token。

                    POST /oauth/token/refresh HTTP/1.1
Host: {youdoamin}.kf5.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTY3MDgsImlkIjoiMTAwMDAxMSJ9.UpnsxNRe-AO9nUcfQiwXU1nVaDjoAMOLYzkqbq_tqpI

请求参数

参数是否必须说明
grant_type填写 authorization_code
refresh_token刷新码,有效期为 30 天

正确响应

                    {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTMxMDgsInVpZCI6Ijc0NCIsInNjb3BlcyI6InJlYWQsdGlja2V0OndyaXRlIiwiaWQiOiIxMDAwMDExIn0.BFy35PGyQr0OS7ZxPYFiI_VkiYj7fjkweF1bCIETGkE",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTY3MDgsImlkIjoiMTAwMDAxMSJ9.UpnsxNRe-AO9nUcfQiwXU1nVaDjoAMOLYzkqbq_tqpI"
}

错误响应

                    {
    "error":"invalid_grant",
    "error_description":"refresh token is invalid"
}

第三步:用 access_token 调用资源接口

用 access_token 调用资源接口,调用成功的前提是,access_token 有效,且接口对应的 授权域 包含在 access_token 的授权域中。

支持接口如下:

授权域(scope)接口说明
user:read/oauth/resource/userinfo用于获取用户个人信息

client 授权域

协议规范中叫 scope,用于 OAUTH 授权访问时的权限控制。user:read 为基础授权域,若授权时仅指定了其他授权域将自动包含该域,目前仅支持 user:read。

OAUTH 授权错误汇总

错误可能原因
invalid_request参数缺失、包含了无效的参数值
unauthorized_clientclient未被授权
access_denied用户或授权服务器拒绝了这次请求
unsupported_response_type错误的 response_type
invalid_scope无效、未知或非法的授权范围
invalid_clientclient认证失败,比如未知的 client,未包含认证头,或不支持的认证方法
invalid_grant授权码、资源票据或刷新 token 无效
unsupported_grant_type不支持的 grant_type 类型
server_error授权服务器异常
temporarily_unavailable授权服务器临时性无法处理当前请求,原因包括临时性的负载高峰或维护