接入指南

第三方应用是指非云网的应用或服务,根据不同业务场景,为开发者提供OAuth2.0授权登录和用户绑定两种服务。

OAuth2.0

OAuth2.0是客户端和认证服务器之间一种授权协议。

云网OAuth2.0是基于OAuth2.0协议标准构建的授权登录系统,用于第三方应用对接云网用户账号,实现单点登录功能。在云网用户授权登录已接入云网的第三方应用后,第三方可以获取到用户的接口调用票据(access_token),并利用该票据获取云网用户基本开放信息

接入流程

云网OAuth2.0授权登录目前支持code和token两种模式,默认是code模式:

  • 第一种模式: code模式,它适用于后台开发者使用,以code换取access_token进行授权认证,较为安全。
  • 请求授权

    第三方发起云网授权登录请求,用户在云网系统登录成功后会重定向到第三方网站,并且带上授权临时票据code参数。

    请求示例:https://auth.ms.casicloud.com/1/oauth/authorize?client_id=&ts=&sign=

    请求参数说明

    参数名 是否必须 类型 参数描述
    client_id string 分配的clientId
    redirect_uri string 回调地址
    response_type string 返回类型,值为code
    state string client端的状态值。用于第三方应用防止CSRF攻击,成功授权后回调时会原样带回。

    返回参数说明:

    参数名 类型 参数描述
    code string 返回的code,用来获取access_token
    scope string 授权作用域
    state string 请求参数里的state值
    注:code有效期为5分钟,且只能使用一次。

    返回示例说明

    用户允许授权后,将会重定向到redirect_uri的网址上,并且带上code。如果请求参数中传入了state参数,返回值会带上原始state值,如: redirect_uri?code=CODE&state=STATE

    获取授权

    通过code参数加上client_id、sign等公共参数,可通过获取授权API换取access_token。

    请求示例:https://auth.ms.casicloud.com/1/oauth/token?client_id=&ts=&sign=&grant_type=&code=&redirect_uri=

    请求参数说明

    参数名 是否必须 类型 参数描述
    grant_type string 授权方式,值为authorization_code
    code string authorize接口返回的code
    redirect_uri string 回调地址

    返回参数说明:

    参数名 类型 参数描述
    access_token string 分配的access token,有效期8小时
    expires_in long access token的有效期,单位为秒
    refresh_token string 分配的refresh token,用于刷新access token,有效期30天
    scope string 授权作用域
    user_open_id string 用户openid
    client_id string 分配的client_id

    返回参数示例

    {
    "code" : 200,
    "data" : {
    	"access_token" : "access_token",
    	"expires_in" : 28800,
    	"refresh_token" : "refresh_token",
    	"scope" : "base",
    	"user_open_id":"user_open_id",
    	"client_id" : "client_id"
    	},
    "msg" : ""
    }
    

    用户信息获取

    通过access_token进行接口调用,获取用户基本信息。

    请求示例:https://auth.ms.casicloud.com/1/oauth/user_info?client_id=&ts=&sign=&access_token=

    请求参数说明

    参数名 是否必须 类型 参数描述
    access_token string 授权票据,token接口返回的值

    返回参数根据授权作用域(scope)不同,返回参数有所不同,可分为两种

    返回成功示例1(单点登录信息):

    {
    "code" : 200,
    "data" : {
    	"user_open_id" : "fc8568a6f1cf4b5297ad64d0bef81a6c",
    	"user_name" : "张三",
    	"org_open_id" : "98139c8bb5a711e8908a0cda411db1fc",
    	"org_name" : "北京测试有限公司"
    },
    "msg" : ""
    }
    

    返回成功示例2(用户集成信息):

    {
      "partner_account": "test_account",
      "partner_connecter": "张三",
      "partner_email": "partner@163.com",
      "partner_fullname": "张三",
      "partner_mobile": "18800020002",
      "partner_name": "第三方测试有限公司",
      "partner_org_id": "21315431",
      "partner_user_id": "464984131564",
      "system_id": 100,
      "yw_org_id": 5100941,
      "yw_org_open_id": "98139c8bb5a711e8908a0cda411db1fc",
      "yw_user_id": 1393817040,
      "yw_user_open_id": "fc8568a6f1cf4b5297ad64d0bef81a6c"
    }
    
  • 第二种模式: token模式,它适用于前端开发者使用,access_token直接从授权服务器获取,方便使用。
  • 请求参数说明

    参数名 是否必须 类型 参数描述
    client_id string 分配的clientId
    redirect_uri string 回调地址
    response_type string 返回类型,值为token
    state string client端的状态值。用于第三方应用防止CSRF攻击,成功授权后回调时会原样带回。

    返回参数说明:

    参数名 类型 参数描述
    access_token string 返回的access_token
    expires_in long access token的有效期,单位为秒
    scope string 授权作用域
    state string 请求参数里的state值

    返回示例说明

    如果用户成功登录并授权,则会跳转到指定的回调地址,并在URL后加“#”号,带上Access Token以及expires_in等参数。如果请求参数中传入了state参数,这里会带上原始state值。如果redirect_uri地址后已经有“#”号,则加“&”号,带上相应的返回参数。如:

    redirect_uri?#access_token=ACCESS_TOKEN&expires_in=EXPIRES_IN&state=STATE

用户绑定

为了更方便用户访问第三方系统,在相同子系统下,使云网用户与第三方用户进行绑定。

绑定后云网用户可直接访问第三方系统。

应用场景:在未登录第三方系统情况下,登录云网平台可直接访问第三方系统。

接入流程

  • 第三方系统需给云网平台提供获取用户信息接口(通过用户唯一标识获取,如:手机号或邮箱等)。
  • 云网平台拿到第三方用户信息后,实现云网用户与第三方用户的绑定操作。
  • 绑定成功后,通过调用用户中心OAuth2.0的请求授权接口,跳转到第三方平台,附带授权code码。
  • 第三方系统拿到授权code码后,调用用户中心OAuth2.0的获取授权接口,获取授权凭据access_token。
  • 第三方系统拿到授权凭据access_token后,调用用户中心OAuth2.0的获取用户信息接口,获取用户绑定信息,绑定信息包含云网用户信息和第三方用户信息。
  • 第三方系统拿到用户信息后,即可实现单点登录。
  • 其中绑定分为两种:云网用户存进行绑定、云网用户不存在先注册在绑定。

    接口名称:用户及企业绑定

    请求示例:https://uc.ms.casicloud.com/1/synchronize/binding?client_id=&ts=&sign=

    请求参数说明:

    参数名 是否必须 类型 参数描述
    system_id long 子系统ID
    yw_user_id long 云网用户ID
    yw_user_open_id string 云网用户openId
    partner_user_id string 第三方用户ID
    partner_fullname string 第三方用户姓名
    partner_account string 第三方用户账号
    partner_mobile string 第三方用户手机号
    partner_email string 第三方用户邮箱
    1、入参说明:yw_user_id、yw_user_open_id至少填一项,partner_account、partner_mobile、partner_email至少填一项
    2、绑定说明: 同一个子系统,若第三方用户与云网的用户已经存在绑定关系,则该第三方用户不允许再与云网其他用户做绑定,同时该云网用户也不允许再与此系统下的其他第三方用户做绑定。

    Post请求示例:

    {
      "yw_user_id": 1,
      "partner_connecter": "张三",
      "partner_fullname": "张三",
      "partner_mobile": "18800020002",
      "partner_user_id": "464984131564",
      "system_id": 100
    }
    

    返回成功示例:

    {
    "code": 200,
    "data":{
    "bind_user":{
    	"partner_user_id": "464984131564",
    	"partner_fullname": "张三",
    	"partner_account": null,
    	"partner_mobile": "18800020002",
    	"partner_email": null,
    	"system_id": 100,
    	"yw_user_open_id": "8e27d584b59b11e8ae08fa163e098ba6",
    	"yw_fullname": "张三"
    	},
    "bind_org": null
    	},
    "msg": ""
    }
    

    返回失败示例:

    {
    "code": 1309,
    "data": null,
    "msg": "所提供的云网账号已与该系统其他账号绑定"
    }