24 hours Hot-line
CORAOOL
Current Path：Home » Documents » API Docs » The text

自定义用户登录/认证集成方案

Coraool2025-05-23API Docs/Help Center阅读(79)

1. 文档目的

本文主要介绍如何在Coraool Montipora产品中集成自定义的用户认证功能，以便可以在您完整的在自主品牌域名下为您的用户提供完整用户产品功能。认证授信的过程发生在您的客户与您的认证服务器之间，Coraool本身不会收集和人用户信息，仅保存必要的Session状态和用户标识，以便数据源、活动策略等集成服务的透传和使用。

1.1 集成配置交互流程

如果您的认证服务器已经实现了下文集成方案中的任意一种，那么仅需要您的产品经理或者工作人员根据上图在Coraool Montipora完成集成配置即可使用。

1.2 集成效果案例-H5

上图为从用户角度使用过程的访问路径，基本保持和您现有的产品体验一致。

  • 访问页面：在您绑定的品牌域名下，可参考 “CORAOOL自定义域名文档”
  • 点击链接时，下一个访问页面需要认证，那么会自动跳转到您配置的认证服务器地址。
  • 用户输入认证信息，完成认证成功后，就会调回到之前的访问页面

2. 集成方式介绍

支持的集成方式集成方需要提供内容简易程度描述说明优点缺点备注
Callback提供已有的登录中心URL认证成功后调回指定页面白名单活动站点的回调地址简单经典应用，弱信息分享（一般仅在有限内容，协议本身仅需要标记用户唯一ID），在复杂性和安全性的平衡方案。Callback的标准仅在框架层，具体数据需要集成双方约定和映射。系统耦合性低，无强依赖绑定实现代价小，异构系统兼容性高灵活性高，业务可以较快的根据扩展字段，新增需要的数据字段，比如用户标签、状态等等标准宽容性大，不同场景集成时需要一定的定制化适配有被DNS/HTTP劫持的安全风险数据传输大小受HTTP GET的限制，2MB左右大致约定到实现1天左右
Callback加密提供已有的登录中心URL认证成功后调回指定页面白名单活动站点的回调地址授权的数据密钥，单独生成简单+在Callback的基础上，对回调携带数据加密后传输，防止DNS/HTTP流量劫持共计，密钥可以根据强度分为静态、动态等实施方式。同上加强安全性，减少泄露风险大致约到实现2天左右
OAuth 2.0OAuth Authentication URLOAuth Token URLOAuth OPENID URLAK / SK授权码，单独生成中等如您已经有该标准协议的实现则无需任何改动一种用于授权用户的开放标准协议，允许第三方应用在用户授权的前提下，访问用户在另一个服务上的受保护数据，而无需共享用户凭据，比如用户名和密码。一般互联网企业均有提供，例如Facebook，Google，AWS等行业标准实现，通用性强安全性良好，基本可以做到无共享用户凭据虽然是行业成熟方案，但重新0-1实现的代价大，需要对协议有一定的经验和调优能力交互复杂，认证过程需要有多次调用，对性能有一定的要求如果是新标准实现，那么大概从设计到实施需要1-2周左右，如果集成方已经实现标准协议，则为0实施代价，在CORAOOL产品上完成配置即可
定制化如果当前已经有其他标准协议的用户认证实现和流程根据实际情况可以讨论，建议使用行业成熟的已有协议比如SSO / SAML / OPENID等，降低理解的成本和实施周期

2.1 集成方式：Callback / Callback加密

2.2 集成方式：OAuth 2.0

3. API Integration Developer Guide

3.1 集成方式：Callback/Callback加密

3.1.1 Service Provider

提供您的Authentication Service服务地址和使用方式。

名称说明
URL认证服务的地址，通常可直接访问带有页面，例如https://login.demo.com
Provider待集成方
SchemaHTTPS
Others如果有访问控制，需要将auth.coroaolapis.com域名加为白名单如果有跨域限制，需要将auth.coroaolapis.com域名授权为可访问这里的回调地址Prefix为 https://auth.coraoolapis.com/v1/callback

3.1.2 Authorize API集成

3.1.2.1 API定义说明
名称说明
URLhttps://auth.coroaolapis.com/v1/callback/authorize
ProviderCORAOOL
SchemaHTTPS
ProtocolGET，数据传输方式
Request Content-Typex-www-form-urlencoded
3.1.2.2 跳转入参说明

跳转您的认证中心URL地址时传入参数列表，具体如下：

名称类型长度是否必须说明
client_idstring256是授权给CORAOOL的唯一应用ID，由集成方生成或双方约定
sign_keystring256是授权给CORAOOL的签名key，由集成方生成或双方约定
signstring256是请求签名，双方使用sign_key对应的secret来做HMAC签名签名方式为对整个完整的URL和Request Body做HMAC(date + sign_secret, sha256)的单次签名，其中date为HTTP header中的标准字段Date。如果放在HTTP Header参数中，则命名为X-Sign
redirect_uristring4096是跳转地址，认证成功后重定向用户访问该地址，前缀为https://auth.coroaolapis.com/v1/callback/authorize
statestring256可选透传字段，即入参值是什么，回调时原样带上，一般用于CSRF等防劫持场景功能
secretstring256可选如果启用了加密方式的Callback协议，这里传入的是双方约定的加密方式名称，密钥将在后台配置，具体加密是分别实现。比如：secret=AES256，表示使用AES256加密secret=BASE64，表示使用BASE64加密如果需要进一步为了不让第三方理解加密方式，也可以配置成不可识别的其他名称
3.1.2.3 返回结果说明

您的认证服务认证成功后重定向调整到请求中的redirect_uri，需要携带追加的参数列表，具体如下：

名称类型长度是否必须说明
sign_keystring256是同上文
signstring256是同上文
tokenstring256是认证有效凭证，一段时间内有效
expires_atnumber10是凭证过期时间，UNIX Timestamp精确到毫秒，例如1678886400
openidstring256是用户唯一标识
nicknamestring256可选用户昵称，一般用于提升用户体验，快速的给用户一个对应带有称谓的提示和展示
statestring256可选透传参数
extstring2M可选结果值，JSON格式value值需要进行url编码（UTF-8）

例如，生成跳转您的认证中心连接如下：

https://login.demo.com?client_id=9f5a97d56&sign_key=c283360a802ea55&state=4c1ba88fea2d056f5d6f9b967557165502&secret=default&redirect_uri=https%3A%2F%2Fauth.coraoolapis.com%2Fv1%2Fcallback%2Fauthorize%3Fredirect_uri%3Dhttp%253A%252F%252Fsite.demo.com%252F%253Fstate%253D4c1ba88fea2d056f5d6f9b967557165502&sign=a090ee6898574fdd3e6637f1125dc009

其中的redirect_uri参数字段值为如下：

redirect_uri=https%3A%2F%2Fauth.coraoolapis.com%2Fv1%2Fcallback%2Fauthorize%3Fredirect_uri%3Dhttp%253A%252F%252Fsite.demo.com%252F%253Fstate%253D4c1ba88fea2d056f5d6f9b967557165502

URLDecoded解码为：
https://auth.coraoolapis.com/v1/callback/authorize?redirect_uri=http%3A%2F%2Fsite.demo.com%2F%3Fstate%3D4c1ba88fea2d056f5d6f9b967557165502

那么重定向时生成的链接如下：

https//auth.coraoolapis.com/v1/callback/authorize？redirect_uri=http%3A%2F%2Fsite.demo.com%2F%3Fstate%3D4c1ba88fea2d056f5d6f9b967557165502&token=0ac11827b12a8a0f0d&expires_at=1678886400&openid=4d62adb3aeafb&nickname=helloworld&state=4c1ba88fea2d056f5d6f9b967557165502&ext=%7B%22key%22%3A%20%22value%22%7D&sign_key=c283360a802ea55&sign=d63bead6eab2046216b76bb256f39003

最终根据协议完成双边解析后，跳转到用户访问的页面：

http://site.demo.com/?state=4c1ba88fea2d056f5d6f9b967557165502
3.1.2.4 返回异常结果说明

返回异常结果，redirect携带参数

名称类型长度是否必须说明
sign_keystring256是同上文
signstring256是同上文
errorstring200是错误码
error_messagestring2048可选错误描述，value部分会进行url编码（UTF-8）
statestring256可选同上文
错误码等级说明
0成功
100100WARN缺少client_id
100101WARN缺少参数或参数中有格式非法字段。
100201ERRORclient_id已经过期或者不可用
100202ERRORredirect_uri未在授权名单
100203ERROR无法识别的secret方式
100204ERRORtoken失效，请重新认证

那么这时重定向时生成的链接如下：

https//auth.coraoolapis.com/v1/callback/authorize?redirect_uri=http%3A%2F%2Fsite.demo.com%2F%3Fstate%3D4c1ba88fea2d056f5d6f9b967557165502&error=100100&error_message=argument%20is%20ilegal&state=4c1ba88fea2d056f5d6f9b967557165502&sign_key=c283360a802ea55&sign=d63bead6eab2046216b76bb256f39003

最终根据协议完成双边解析后，跳转到用户访问的页面：

http://site.demo.com/?error=100100&error_message=argument%20is%20ilegal
如果站点配置了自定义的错误页面，则不会跳回到上面的地址，而是将会被重定向到预先配置的错误页面：
http://site.demo.com/error/page?error=100100&error_message=argument%20is%20ilegal

3.1.3 Expiration API (Optional)

当登录的用户在其他地方被登出时，同步将用户也在本系统中踢下线。该API集成可选，主要用户高用户体验同步保障的场景，否则仍保证最终一致性，当用户在访问需要授权的资源，仍会通过认证系统判断要求重新认证。

3.1.3.1 API定义说明
名称说明
URLhttps://auth.coroaolapis.com/v1/callback/logout
ProviderCORAOOL
SchemaHTTPS
ProtocolGET / POST，数据传输方式
Request Content-Typex-www-form-urlencoded
Response Content-Typeapplication/json
3.1.3.2 参数说明
名称类型长度是否必须说明
client_idstring256是同上文
sign_keystring256是同上文
signstring256是同上文
openidstring256是同上文
secretstring256可选同上文
statestring256可选同上文

由集成方不定时主动发起请求通知，GET调用的示例方式如下：

curl -X GET https//auth.coraoolapis.com/v1/callback/logout?client_id=9f5a97d56&openid=4d62adb3aeafb&secret=default&state=4c1ba88fea2d056f5d6f9b967557165502&sign_key=c283360a802ea55&sign=d63bead6eab2046216b76bb256f39003

同时也支持POST方式调用，此时签名的字段需要调整到HTTP Header，字段名为X-Sign

curl -X POST https//auth.coraoolapis.com/v1/callback/logout -H "X-Signature:d63bead6eab2046216b76bb256f39003" -d '{
    "client_id":"9f5a97d56",
    "openid":"4d62adb3aeafb",
    "secret":"default",
    "state":"4c1ba88fea2d056f5d6f9b967557165502",
    "sign_key:"c283360a802ea55",
}'
3.1.3.3 返回结果说明
名称类型长度是否必须说明
codestring256是状态码，0表示成功，其他错误见异常列表
messagestring256可选提示文案或错误消息
openidsarray2048可选处理失败的openid列表

API的返回结果以JSON格式返回，正常结果处理返回结构如下：

{
    "code": status        // number, 0表示成功，其他表示异常，见3.1.2.4中的说明
    "message": ""         // string, API返回消息，一般用于用户的提示，默认为空
}

异常结果处理返回结果如下

{
    "code": status                // number, 0表示成功，其他表示异常，见3.1.2.4中的说明
    "message": "Error Message"    // string, API返回消息，一般用于用户的提示，默认为空
    "openids" : []                // array, 处理失败的openid列表，支持批处理
}

3.2 集成方式：OAuth 2.0

3.2.1 Service Provider

提供您的OAuth2.0 Service服务地址和使用方式，本文档中的字段命名基本采用了当前主流的实现标准如Google / AWS等。如果您的实现非文档中的字段名，可以通过配置后台做相应的字段映射。

名称说明
URL认证服务的地址，例如https://site.com/api/oauth2/
Provider待集成方
SchemaHTTPS
Others如果有访问控制，需要将auth.coroaolapis.com域名加为白名单如果有跨域限制，需要将auth.coroaolapis.com域名授权为可访问这里的回调地址Prefix为 https://auth.coraoolapis.com/v1/oauth2/

3.2.2 Authorize API集成

3.2.2.1 API定义说明
名称说明
URL认证服务的地址，例如https://site.com/api/oauth2/authorize
Provider待集成方
SchemaHTTPS
ProtocolGET，数据传输方式
Request Content-Typex-www-form-urlencoded
3.2.2.3 跳转入参说明
名称是否必须说明
client_id是授权给CORAOOL的唯一应用ID，由集成方生成或双方约定
return_uri是跳转地址，认证成功后重定向用户访问该地址
response_type是默认值code，授权类型。
scope否默认openid，请求用户授权时向用户显示的可进行授权的列表，如果有多项则用,作为分隔，例如openid, user_profile
state否透传字段，即入参值是什么，回调时原样带上，一般用于CSRF等防劫持场景功能
3.2.2.4 返回结果
名称是否必须说明
code是授权码，如果用户认证成功，该code将用于下一步的正式认证码Access_Token的生成
state否同上文

这里以待集成的认证中心地址是https://login.demo.com为例，那么生成的待认证地址为，需要认证时用户将自动跳转到该动态生成的地址：

https://login.demo.com?client_id=YOUR_CLIENT_ID&response_type=code&state=4c1ba88fea2d056f5d6f9b967557165502&redirect_uri=https%3A%2F%2Fauth.coraoolapis.com%2Fv1%2Foauth2%2Fauthorize%3Fredirect_uri%3Dhttp%253A%252F%252Fsite.demo.com%252F%253Fstate%253D4c1ba88fea2d056f5d6f9b967557165502

其中redirect_uri字段的值经过URLEncode编码（UTF-8)，这里解析后的原值是
https://auth.coraoolapis.com/v1/oauth2/authorize?redirect_uri=http%3A%2F%2Fsite.demo.com%2F%3Fstate%3D4c1ba88fea2d056f5d6f9b967557165502

进一步的，用户认证成功后待集成的认证中心，应该返回并重定向到redirect_uri的地址，并在后面追加上返回结果code等参数，例如：

https://auth.coraoolapis.com/v1/oauth2/authorize?redirect_uri=http%3A%2F%2Fsite.demo.com%2F%3Fstate%3D4c1ba88fea2d056f5d6f9b967557165502&state=4c1ba88fea2d056f5d6f9b967557165502&code=13cdd9ca2eee617c90
3.2.2.5 返回异常结果说明
名称类型长度是否必须说明
errorstring200是错误码
error_descriptionstring2048可选错误描述，value部分会进行url编码（UTF-8）
statestring256可选同上文

错误码定义

错误码等级说明
0成功
100100WARN缺少client_id
100101WARN缺少参数或参数中有格式非法字段。
100201ERRORclient_id已经过期或者不可用
100202ERRORredirect_uri未在授权名单
100203ERROR无法识别的secret方式
100204ERRORtoken失效，请重新认证

如果异常情况那么，也将重定向到redirect_uri指定的地址，并携带上error、error_message等参数，例如根据上述的认证中心那么，跳转的连接形式如下：

https//auth.coraoolapis.com/v1/oauth2/authorize?redirect_uri=http%3A%2F%2Fsite.demo.com%2F%3Fstate%3D4c1ba88fea2d056f5d6f9b967557165502&error=100100&error_description=argument%20is%20ilegal&state=4c1ba88fea2d056f5d6f9b967557165502

3.2.3 Access Token API集成

3.2.3.1 API定义说明
名称说明
URL认证服务的地址，例如https://site.com/api/oauth2/token
Provider待集成方
SchemaHTTPS
ProtocolPOST，数据传输方式
Request Content-Typex-www-form-urlencoded
Response Content-Typeapplication/json
3.2.3.2 参数说明
名称是否必须说明
code是授权码，该Authorize API中获取得到
client_id是同上文
client_secret是授权给CORAOOL的认证密钥，由集成方生成或双方约定
grant_type是根据OAuth 2.0协议， 这里为固定值authorization_code
redirect_uri是作用同上文，必须保持和前面传入Authorize API中的参数一直
scope可选同上文
3.2.3.3 返回结果说明
名称是否必须说明
token_type是用户认证凭证类型，这里为协议固定值bearer，强制全小写
access_token是授权码，如果用户认证成功，该code将用于下一步的用户认证凭证Access_Token的生成
expires_in是access_token 的有效期（秒）
refresh_token可选用于续期 access_token
id_token可选OIDC 中返回的用户身份 JWT（仅限支持 OIDC 的平台）
scope可选同上文

这里继续以待之前的案例为例，生成的请求参数类型为x-www-form-urlencoded：

grant_type=authorization_code&
code=13cdd9ca2eee617c90&
client_id=CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https://auth.coraoolapis.com/v1/callback/authorize?redirect_uri=http%3A%2F%2Fsite.demo.com%2F%3Fstate%3D4c1ba88fea2d056f5d6f9b967557165502

发送POST请求到待集成的认证中心

curl -X POST https://site.com/api/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=13cdd9ca2eee617c90" \
  -d "redirect_uri=https%3A%2F%2Fauth.coraoolapis.com%2Fv1%2Fcallback%2Fauthorize%3Fredirect_uri%3Dhttp%253A%252F%252Fsite.demo.com%252F%253Fstate%253D4c1ba88fea2d056f5d6f9b967557165502" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET"

如果请求成功那么将会返回一下JSON结构

{
  "access_token": "ya29.a0AfH6SM...",
  "expires_in": 3600,
  "refresh_token": "1//04i9xyz...",
  "scope": "openid email profile",
  "token_type": "bearer",
  "id_token": "eyJhbGciOiJSUzI1..."
}
3.2.3.4 返回异常结果说明
名称类型长度是否必须说明
errorstring200是错误码
error_descriptionstring2048可选错误描述

返回格式为JSON格式，且HTTP Response Code为400，错误码和Authorize中说明的异常错误表使用同一个

{
  "error": "100100",
  "error_description": "The authorization code is invalid or expired"
}

3.2.4 Refresh Access Token API集

3.2.4.1 API定义说明
名称说明
URL认证服务的地址，例如https://site.com/api/oauth2/token
Provider待集成方
SchemaHTTPS
ProtocolPOST，数据传输方式
Request Content-Typex-www-form-urlencoded
Response Content-Typeapplication/json
3.2.4.2 参数说明
名称是否必须说明
client_id是同上文
client_secret是授权给CORAOOL的认证密钥，由集成方生成或双方约定
grant_type是根据OAuth 2.0协议， 这里为固定值refresh_token
refresh_token是上一次授权时获得到access_token
scope可选同上文
3.2.4.3 返回结果说明
名称是否必须说明
token_type是用户认证凭证类型，这里为协议固定值bearer，强制全小写
access_token是授权码，如果用户认证成功，该code将用于下一步的用户认证凭证Access_Token的生成
expires_in是access_token 的有效期（秒）
id_token可选同上文
scope可选同上文

这里继续以待之前的案例为例，生成的请求参数类型为x-www-form-urlencoded：

grant_type=refresh_token&
code=13cdd9ca2eee617c90&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

发送POST请求到待集成的认证中心

curl -X POST https://site.com/api/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=1//04i9xyz..." \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET"

如果请求成功那么将会返回一下JSON结构

{
  "access_token": "ya29.a0AfH6SM...",
  "id_token": "eyJhbGciOiJSUzI1..."
  "scope": "openid email profile",
  "expires_in": 3600,
  "token_type": "bearer"
}
3.2.4.4 返回异常结果说明

同Access Token API中说明的格式和内容定义

3.4 (Demo) Example Service API Integrated with Authentication Token

集成用户认证后，出了页面使用认证状态外，另一个常用场景就是部分Service API也需要携带认证信息返回对应的用户结果，在数据源中提供了几种方式

3.4.1 Request Header参数模式

本文档支持使用X-Access-Token作为用户登录凭证的携带字段，也可以根据实际场景修改使用其他自定义命名的Request Header，将在API请求时携带token用户凭证参数

curl -X POST https://api.demo.com/api_name -H "X-Access-Token=2ee2de233f043228b241dc5"

3.4.2 Cookies模式

也可以使用传统的HTTP Cookies携带，注意开启HTTP-Only、Secure、以及SameSite=Strict提高安全性，这里使用标准命名access_token，可以根据实际场景需要修改

curl -X POST https://api.demo.com/api_name -b "access_token=eyJhbGciOi...; param=xxx"
Share to
1
1 Likes
Prev page
Next page

Recomm

Comments (0)

Contact
Always Still with YouCopyCopiedcontact-img