TopStack 文档

主题

单点登录 ​

平台支持符合OAuth2标准的开放授权功能。 您的Web应用接入开放授权后，用户就可以使用TopStack云组态平台的账户登录您的应用。 注意：本文中的www.topstack.com都需要替换成云组态平台的实际部署地址。

准备工作 ​

创建扩展应用，获得应用标识AppID和应用密钥AppKey。

账户认证 ​

您不需要开发账户登录界面。当用户访问您的某个需要认证的页面时，您只需将页面重定向到云组态平台的这个地址： http://www.topstack.com/login?type=oauth2&response_type=code&client_id={AppID}&redirect_uri={RedirectURI} 用户在上一步的界面登录云组态平台账户并点击授权访问后，浏览器会跳转到redirect_uri参数所指定的地址。

参数说明：

参数必填说明
response_type是固定为 code
client_id是填写 **扩展应用 **页面中获得的应用标识AppID
redirect_uri是填写认证回调地址

注意redirect_uri参数要根据URI标准进行转义。 例如，如果AppID是： cc2573ac909d4030a78db15b02bd2432 认证回调地址是： http://example.com/login_callback?theme=dark&level=1 则登录页面为： http://www.topstack.com/login?response_type=code&client_id=cc2573ac909d4030a78db15b02bd2432&redirect_uri=http%3A%2F%2Fexample.com%2Flogin_callback%3Ftheme%3Ddark%26level%3D1

关于redirect_uri的一些补充说明：

  1. redirect_uri自身虽然可以带有参数，但code、error、error_description三个参数在下一步有特定用途，因此不应使用。
  2. 根据OAuth2标准，redirect_uri应当是以http://或https://开头的绝对地址，不能是相对地址（形如/login_callback?theme=dark&level=1）；并且不能带有锚点（形如http://example.com/login_callback?theme=dark&level=1#id1）。

认证回调 ​

浏览器跳转到redirect_uri参数所指定的地址时，分为成功跳转和出错跳转两种情况。

例如，认证回调地址是： http://example.com/login_callback?theme=dark&level=1

成功跳转会附加一个code参数，形如： http://example.com/login_callback?theme=dark&level=1&code=ZTNKODYWNMYTZJCZOC0ZMDQYLTGYMJATOGFINME5YWEWMDIW

出错跳转会附加error、error_description两个参数，形如： http://example.com/login_callback?theme=dark&level=1&error=server_error&error_description=The+authorization+server+encountered+an+unexpected+condition+that+prevented+it+from+fulfilling+the+request

您需要根据这两种情况实现不同的行为。

对于出错跳转，通常是跳转或渲染一个页面，将错误信息告知用户，当然也可能是简单地返回HTTP 500错误。

对于成功跳转，您需要进一步调用此接口获取token（建议在服务器端调用）： http://www.topstack.com/oauth/token 请求方式为POST，请求体为form格式（application/x-www-form-urlencoded 或multipart/form-data），请求体参数如下：

参数必填说明
grant_type是固定为 authorization_code
code是填写传递给认证回调地址的code参数值
client_id是填写 **扩展应用 **页面中获得的应用标识AppID
client_secret是填写 **扩展应用 **页面中获得的应用密钥AppKey
redirect_uri是填写认证回调地址

这里的redirect_uri参数值必须与上一步传递给登录页面的redirect_uri参数值相同，否则获取token会失败。

接口将以JSON格式返回结果，如果获取token失败，会返回类似这样的结果：

json
{
	"error": "invalid_grant",
  "error_description": "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client"
}

您应当采用和错误跳转类似的方式处理此错误信息。

如果获取token成功，会返回类似这样的结果：

json
{
  "access_token": "YJUWY2FHNTKTYJMWNC0ZZMYZLTG5MZUTMDHKMWY1NTRJNTA4",
  "expires_in": 7200,
  "refresh_token": "MJNHNTY3YZMTM2Y5MY01MMJILWJINMUTNJE3ZTM4YMM3MZKX",
  "token_type": "Bearer"
}

注意：code的有效期非常短（目前是10分钟），获取token的操作应当尽快进行。获取token成功之后，code也会立即失效。

用户基本信息查询 ​

调用此接口可以查询用户基本信息： http://www.topstack.com/oauth/userinfo?access_token={access_token} 其中access_token参数值填写上一步中获取到的access_token值。

接口以JSON格式返回结果，类似于：

json
{
  "success": true,
  "data": {
    "id": "c524e3de97ev629b5i50",
    "username": "admin",
    "name": "管理员",
    "tel": "010-12345678",
    "mobile": "13012345678",
    "email": "admin@example.com",
    "projects": [
      {
        "id": "iotopo",
        "name": "默认项目"
      }
    ]
  }
}

返回结果中的id是账户唯一标识，表明云组态平台的用户身份已得到认证。此后您便可以将基于此id实现您应用内的身份认证功能。 data完整字段说明如下：

typescript
interface UserInfo {
	id: string;             // 唯一标识
  project_id?: string;    // 用户所属的项目，对于平台用户为空
  username: string;       // 登录名，在用户所属的项目下唯一，平台用户在平台侧唯一
  name: string;           // 姓名
  tel?: string;           // 联系电话
  mobile?: string;        // 手机号
  email?: string;         // 邮箱
  locked?: boolean;       // 用户是否被锁定
  is_superuser?: boolean;     // 是否为平台超级管理员
  is_administrator?: boolean; // 是否为平台普通管理员
  projects?: Array<{
    id: string;   // 项目标识
    name: string; // 项目名称
  }>; // 用户有权限访问的项目
}

如果access_token失效，接口会返回HTTP 400错误。 如果账户已在云组态平台内被删除，返回如下结果：

json
{
  "code": "not-found",
  "msg": "user does not exist"
}

刷新token ​

access_token的有效期是2小时，如果想在此之后继续使用access_token，需要在过期之前调用接口刷新。 请求地址（http://www.topstack.com/oauth/token）、方式（POST）和请求体格式（form）和获取token时相同，但参数不同：

参数必填说明
grant_type是固定为 refresh_token
refresh_token是填写获取token时的refresh_token值
client_id是填写 **应用管理 **页面中获得的应用标识AppID
client_secret是填写 **应用管理 **页面中获得的应用密钥AppKey

其返回形式也与获取token相同，但返回的access_token和refresh_token是刷新之后的值。刷新成功之后，之前的access_token和refresh_token即会失效。

单点登录 ​

点击云组态平台首页的应用图标，即会跳转到应用的跳转地址。此跳转地址没有任何限制。如果跳转地址是应用内一个需要认证的页面，并且此应用对接了开放授权，就可以实现在云组态平台单点登录、访问不同应用的效果。

常见问题 ​

Q：纯客户端/浏览器端应用，没有服务器端，可以接入开放授权吗？ A：可以。获取token时，client_secret参数（也即应用的AppKey）用于防止用户伪造code和回调地址，因此建议在服务器端获取token，安全性更高。如果没有服务器端，将AppKey保存在客户端/浏览器端，在客户端/浏览器端获取token也是可以的，不影响功能实现。

Q：应用有自己的账号系统，并希望区分通过云组态平台登录的账号和我应用内的账号，如何实现？ A：在您的数据库中，维护云组态平台的账号唯一标识id和您应用内的账号的唯一对应关系。在成功获取token和id后，查询此id是否已关联有您应用内的账号。如果没有，则自动在您应用内创建一个账号并与此id进行关联。

Q：应用有自己的账号系统，并希望用户能用云组态平台的账号登录到我应用内的现有账号，如何实现？ A：和上一问类似，但在获取到的id没有关联有您应用内的账号时，不自动创建您应用内的账号，而是提示用户云组态平台账号未绑定应用内账号。 您需要实现一个为您应用的现有账户绑定图扑物联平台账户的功能。用户登录您应用的账户后，点击您提供的“绑定云组态平台账户”链接，此链接会跳转到云组态平台的登录认证页面，和普通的授权对接流程一致，但使用不同的回调地址，在此回调中实现id和您应用的账户的关联。通过redirect_uri参数透传用户之前登录的您应用的账号的唯一标识。