实现自定义认证系统
如果系统提供的认证系统不能满足您的需求，您可以自己实现一个自定义认证服务。
基本概念
SCOW中使用identityId标识一个用户，并同时使用此identityId作为用户在集群上的登录名。
用户登录后，认证系统应负责给当前登录用户的当前会话赋予一个Token，SCOW将会在每次需要认证的请求时使用token请求认证系统以获取用户的身份。
一个认证服务本质是一个实现了以下HTTP API的HTTP服务器。
请注意
- 以
/public开头的API将会是用户可以直接访问的，其他的用户不可直接访问 - 所有响应和处于
body位置的参数均为json格式
必须实现的API
GET /public/auth
发起登录。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
callbackUrl | querystring | 字符串 | 是 | 登录完成后的回调地址。必须是一个合法的URL。 |
期望的响应
返回登录HTML或者重定向到实际的登录界面。
解释
此API用于进行实际的登录操作。用户点击登录后，系统将会重定向到这个URL。您可以选择自己实现一个登录页面，或者重定向到第三方登录认证的页面。
登录完成后，请返回一个重定向的请求到callbackUrl指定的URL，并附上querystring?token={您用来跟踪本用户的状态的token}。这些token的生成和保存您需要自己实现。后续的用户将会带着此token用于鉴权。
如果您在后端使用类似OAuth2的认证系统，这些认证系统登录完成后会给一个token用于跟踪用户状态并重定向到您指定的回调地址。对于这些系统，您应该自己实现一个单独的回调地址（且这些回调地址的URL必须以/public为前缀以使用户可以直接访问），在这些地址的处理函数中获取认证系统给予的token，并使用token进行后续的处理（例如生成自己的token，将这些token映射到用户等）。处理完成后，再回调到callbackUrl指定的URL。
GET /public/validateToken
验证token，返回对应的用户ID。SCOW将会在每次需要验证的请求发生时，使用登录时获取的token请求此API，所以请保证此API的性能。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
token | querystring | 字符串 | 是 | 用户的token |
期望的响应
200 OK
| 字段 | 类型 | 是否必须 | 解释 |
|---|---|---|---|
identityId | 字符串 | 是 | 此token对应的用户的用户ID |
400 Bad Request
| 字段 | 类型 | 是否必须 | 解释 |
|---|---|---|---|
code | 字符串常量INVALID_TOKEN | 是 | INVALID_TOKEN：token无效 |
DELETE /token
无效化一个token。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
token | query | 字符串 | 是 | token |
响应
| 状态码 | 内容 | 解释 |
|---|---|---|
204 | 无 | 操作完成。如果token不存在也应该返回这个状态码。 |
解释
此API用于无效化一个token。调用这个请求后，这个token将不应该继续能够通过GET /validateToken获得用户的信息。
GET /capabilities
返回认证系统支持的能力。
请求
无。
期望的响应
200 OK
| 字段 | 类型 | 是否必须 | 解释 |
|---|---|---|---|
createUser | boolean | 否 | 此认证系统是否支持创建用户 |
getUser | boolean | 否 | 此认证系统是否支持查询用户 |
checkPassword | boolean | 否 | 此认证系统是否支持验证用户密码 |
changePassword | boolean | 否 | 此认证系统是否支持修改用户密码 |
accountUserRelation | boolean | 否 | 此认证系统是否支持管理用户账户关系 |
解释
此API用于认证系统声明自己的支持的能力。系统的其他部分将会根据此API的返回值选择性地选择是否显示某些功能。例如，如果changePassword为false或者为undefined，那么前端系统将会不显 示修改密码的功能。
创建用户功能相关API
认证系统如果声明支持创建用户，则必须实现此部分的API。
POST /user
创建用户。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
identityId | body | 字符串 | 是 | 用户ID |
password | body | 字符串 | 是 | 密码 |
id | body | 整数 | 是 | 用户在数据库中的ID |
name | body | 字符串 | 是 | 用户姓名 |
mail | body | 字符串 | 是 | 用户邮箱 |
响应
| 状态码 | 内容 | 解释 |
|---|---|---|
204 | 无 | 创建完成 |
409 | 无 | 用户ID已经存在 |
501 | 无 | 不支持创建用 户功能 |
解释
此API用于在认证系统中创建用户。当前，系统只支持通过管理系统创建用户。管理系统首先在自己的数据库中创建用户，然后请求认证系统创建用户。请求参数中的id即是数据库中这个新的用户的自增ID。如果认证系统返回非成功的返回值，管理系统将会撤回在数据库中的项。
查询用户功能相关API
GET /user
获取已经存在的用户信息。目前只需要返回用户的ID。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
identityId | querystring | 字符串 | 是 | 用户的ID |
200 OK
| 字段 | 类型 | 是否必须 | 解释 |
|---|---|---|---|
user.identityId | 字符串 | 是 | 用户的ID。和请求的identityId一致 |
user.name | 字符串 | 否 | 用户的姓名。如果认证系统可以获取用户的姓名，则返回。如果不能获取，就不设置 |
user.mail | 字符串 | 否 | 用户的邮箱。如果认证系统可以获取用户的邮箱，则返回。如果不能获取，就不设置 |
404 Not Found
| 字段 | 类型 | 是否必须 | 解释 |
|---|---|---|---|
code | 字符串常量USER_NOT_FOUND | 是 | USER_NOT_FOUND：用户不存在 |
解释
此API可以获取用户的信息。此API也可以用于获取用户是否存在。
修改邮箱相关API
认证系统如果声明支持修改邮箱，则必须实现此部分的API。
PATCH /user/email
修改邮箱。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
identityId | body | 字符串 | 是 | 用户ID |
newEmail | body | 字符串 | 是 | 新邮箱 |
期望的响应
| 状态码 | 内容 | 解释 |
|---|---|---|
204 | 无 | 修改完成 |
404 | 无 | 用户未找到 |
501 | 无 | 不支持修改邮箱功能 |
解释
此API用于完成修改邮箱的功能。
验证密码相关API
GET /checkPassword
验证密码。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
identityId | query | 字符串 | 是 | 用户ID |
password | query | 字符串 | 是 | 密码 |
200 OK
| 字段 | 类型 | 是否必须 | 解释 |
|---|---|---|---|
success | 布尔值 | 是 | 验证结果 |
404 Not Found
| 字段 | 类型 | 是否必须 | 解释 |
|---|---|---|---|
code | 字符串常量USER_NOT_FOUND | 是 | USER_NOT_FOUND：用户不存在 |
501
表示此功能在当前服务器配置下不可用，返回null。
修改密码相关API
认证系统如果声明支持修改密码，则必须实现此部分的API。
PATCH /password
修改密码。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
identityId | body | 字符串 | 是 | 用户ID |
newPassword | body | 字符串 | 是 | 新密码 |
期望的响应
| 状态码 | 内容 | 解释 |
|---|---|---|
204 | 无 | 修改完成 |
404 | 无 | 用户未找到 |
501 | 无 | 不支持修改密码功能 |
解释
此API用于完成修改密码的功能。
用户账户关系相关API
认证系统如果声明支持管理用户账户关系，则必须实现此部分API。
POST /account
在认证系统中创建账户。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
accountName | body | 字符串 | 是 | 账户名 |
ownerUserId | body | 字符串 | 是 | 拥有者用户ID |
期望的响应
| 状态码 | 内容 | 解释 |
|---|---|---|
204 | 无 | 创建成功 |
POST /account/${accountName}/user
把用户加入账户中。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
accountName | path | 字符串 | 是 | 账户名 |
userId | body | 字符串 | 是 | 用户ID |
期望的响应
| 状态码 | 内容 | 解释 |
|---|---|---|
204 | 无 | 把用户加入账户成功 |
DELETE /account/${accountName}/user/${userId}
把用户从账户中删除。
请求
| 参数 | 位置 | 类型 | 是否必须 | 解释 |
|---|---|---|---|---|
accountName | path | 字符串 | 是 | 账户名 |
userId | path | 字符串 | 是 | 用户ID |
期望的响应
| 状态码 | 内容 | 解释 |
|---|---|---|
204 | 无 | 删除用户成功 |