跳到主要内容

实现自定义认证系统

如果系统提供的认证系统不能满足您的需求,您可以自己实现一个自定义认证服务。

基本概念

OpenSCOW中使用identityId标识一个用户,并同时使用此identityId作为用户在集群上的登录名。

用户登录后,认证系统应负责给当前登录用户的当前会话赋予一个Token,OpenSCOW将会在每次需要认证的请求时使用token请求认证系统以获取用户的身份。

一个认证服务本质是一个实现了以下HTTP API的HTTP服务器。

请注意

  • /public开头的API将会是用户可以直接访问的,其他的用户不可直接访问
  • 所有响应和处于body位置的参数均为json格式

必须实现的API

GET /public/auth

发起登录。

请求

参数位置类型是否必须解释
callbackUrlquerystring字符串登录完成后的回调地址。必须是一个合法的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。OpenSCOW将会在每次需要验证的请求发生时,使用登录时获取的token请求此API,所以请保证此API的性能。

请求

参数位置类型是否必须解释
tokenquerystring字符串用户的token

期望的响应

200 OK
字段类型是否必须解释
identityId字符串此token对应的用户的用户ID
400 Bad Request
字段类型是否必须解释
code字符串常量INVALID_TOKENINVALID_TOKEN:token无效

DELETE /token

无效化一个token。

请求

参数位置类型是否必须解释
tokenquery字符串token

响应

状态码内容解释
204操作完成。如果token不存在也应该返回这个状态码。

解释

此API用于无效化一个token。调用这个请求后,这个token将不应该继续能够通过GET /validateToken获得用户的信息。

GET /capabilities

返回认证系统支持的能力。

请求

无。

期望的响应

200 OK
字段类型是否必须解释
createUserboolean此认证系统是否支持创建用户
getUserboolean此认证系统是否支持查询用户
checkPasswordboolean此认证系统是否支持验证用户密码
changePasswordboolean此认证系统是否支持修改用户密码
accountUserRelationboolean此认证系统是否支持管理用户账户关系

解释

此API用于认证系统声明自己的支持的能力。系统的其他部分将会根据此API的返回值选择性地选择是否显示某些功能。例如,如果changePasswordfalse或者为undefined,那么前端系统将会不显示修改密码的功能。

创建用户功能相关API

认证系统如果声明支持创建用户,则必须实现此部分的API。

POST /user

创建用户。

请求

参数位置类型是否必须解释
identityIdbody字符串用户ID
passwordbody字符串密码
idbody整数用户在数据库中的ID
namebody字符串用户姓名
mailbody字符串用户邮箱

响应

状态码内容解释
204创建完成
409用户ID已经存在
501不支持创建用户功能

解释

此API用于在认证系统中创建用户。当前,系统只支持通过管理系统创建用户。管理系统首先在自己的数据库中创建用户,然后请求认证系统创建用户。请求参数中的id即是数据库中这个新的用户的自增ID。如果认证系统返回非成功的返回值,管理系统将会撤回在数据库中的项。

查询用户功能相关API

GET /user

获取已经存在的用户信息。目前只需要返回用户的ID。

请求

参数位置类型是否必须解释
identityIdquerystring字符串用户的ID
200 OK
字段类型是否必须解释
user.identityId字符串用户的ID。和请求的identityId一致
user.name字符串用户的姓名。如果认证系统可以获取用户的姓名,则返回。如果不能获取,就不设置
user.mail字符串用户的邮箱。如果认证系统可以获取用户的邮箱,则返回。如果不能获取,就不设置
404 Not Found
字段类型是否必须解释
code字符串常量USER_NOT_FOUNDUSER_NOT_FOUND:用户不存在

解释

此API可以获取用户的信息。此API也可以用于获取用户是否存在。

修改邮箱相关API

认证系统如果声明支持修改邮箱,则必须实现此部分的API。

PATCH /user/email

修改邮箱。

请求

参数位置类型是否必须解释
identityIdbody字符串用户ID
newEmailbody字符串新邮箱

期望的响应

状态码内容解释
204修改完成
404用户未找到
501不支持修改邮箱功能

解释

此API用于完成修改邮箱的功能。

验证密码相关API

GET /checkPassword

验证密码。

请求

参数位置类型是否必须解释
identityIdquery字符串用户ID
passwordquery字符串密码
200 OK
字段类型是否必须解释
success布尔值验证结果
404 Not Found
字段类型是否必须解释
code字符串常量USER_NOT_FOUNDUSER_NOT_FOUND:用户不存在
501

表示此功能在当前服务器配置下不可用,返回null。

修改密码相关API

认证系统如果声明支持修改密码,则必须实现此部分的API。

PATCH /password

修改密码。

请求

参数位置类型是否必须解释
identityIdbody字符串用户ID
newPasswordbody字符串新密码

期望的响应

状态码内容解释
204修改完成
404用户未找到
501不支持修改密码功能

解释

此API用于完成修改密码的功能。

用户账户关系相关API

认证系统如果声明支持管理用户账户关系,则必须实现此部分API。

POST /account

在认证系统中创建账户。

请求

参数位置类型是否必须解释
accountNamebody字符串账户名
ownerUserIdbody字符串拥有者用户ID

期望的响应

状态码内容解释
204创建成功

POST /account/${accountName}/user

把用户加入账户中。

请求

参数位置类型是否必须解释
accountNamepath字符串账户名
userIdbody字符串用户ID

期望的响应

状态码内容解释
204把用户加入账户成功

DELETE /account/${accountName}/user/${userId}

把用户从账户中删除。

请求

参数位置类型是否必须解释
accountNamepath字符串账户名
userIdpath字符串用户ID

期望的响应

状态码内容解释
204删除用户成功