接入指南

第三方应用是指非云网的应用或服务,用户中心为第三方开发者提供了基于OAuth2.0标准协议的授权登录服务。

OAuth2.0

OAuth2.0是客户端和认证服务器之间一种授权协议。云网的OAuth2.0接口是基于OAuth2.0协议标准构建的授权登录服务,用于第三方应用使用云网账号,实现单点登录功能。

在云网用户授权登录已接入云网的第三方应用后,第三方可以获取到用户的接口调用票据(access_token),并利用该票据获取云网用户基本信息。

接入流程

用户中心提供了集成OAuth2.0的demo示例(立即下载

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 授权接口返回的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直接从授权服务器获取,方便使用。
  • 请求示例:https://auth.ms.casicloud.com/1/oauth/authorize?client_id=&ts=&sign=

    请求参数说明

    参数名 是否必须 类型 参数描述
    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