Customized Authentication Solution

1. Document Purpose

This article mainly introduces how to integrate custom user authentication functions in Coraool Montipora products, so that you can provide your users with complete user product functions under your own brand domain name. The authentication and authorization process occurs between your customers and your authentication server. Coraool itself does not collect and use user information, but only saves the necessary session status and user identification for the transparent transmission and use of integrated services such as data sources and activity strategies.

1.1 Configuration Process

If your authentication server has implemented any of the following integration solutions, your product manager or staff only needs to complete the integration configuration in Coraool Montipora according to the above figure.

1.2 User Journey – H5

The above figure shows the access path from the user’s perspective, which is basically consistent with your existing product experience.

• Access page: Under the brand domain name you have bound, you can refer to the “CORAOOL Custom Domain Name Documentation”
• When you click a link, if the next page you visit requires authentication, you will be automatically redirected to the authentication server address you configured.
• The user enters the authentication information, and after successful authentication, the page will be returned to the previous access page.

2. Solution Introduction

Supported integration methods	The integrator needs to provide content	Ease of use	Description	advantage	shortcoming	Remark
Callback	Provide the existing login center URL and call back to the specified page after successful authentication. The callback address of the whitelisted active site	Simple	Classic applications, weak information sharing (generally only limited content, the protocol itself only needs to mark the user’s unique ID), a balance between complexity and security. The Callback standard is only at the framework layer, and specific data needs to be integrated with the agreement and mapping of both parties.	The system has low coupling, no strong dependency, low implementation cost, high compatibility with heterogeneous systems, and high flexibility. Businesses can quickly add required data fields based on extended fields, such as user tags, status, etc.	The standard is very tolerant, and some customization is required for integration in different scenarios. There is a security risk of being hijacked by DNS/HTTP. The data transmission size is limited by HTTP GET, about 2MB.	It takes about 1 day to achieve the goal.
Callback encryption	Provide the existing login center URL to call back to the specified page after successful authentication. The data key for the callback address authorization of the whitelisted active site is generated separately	Simple+	Based on the Callback, the data carried in the callback is encrypted before transmission to prevent DNS/HTTP traffic hijacking. The key can be divided into static and dynamic implementation methods according to the strength.	Same as above to enhance security and reduce the risk of leakage		It takes about 2 days to achieve
OAuth 2.0	OAuth Authentication URLOAuth Token URLOAuth OPENID URLAK / SK authorization code, generated separately	Medium If you already have an implementation of this standard protocol, no changes are required	An open standard protocol for authorizing users, allowing third-party applications to access the user’s protected data on another service under the premise of user authorization without sharing user credentials, such as username and password. It is generally provided by Internet companies, such as Facebook, Google, AWS, etc.	Industry standard implementation, strong versatility and good security, basically no shared user credentials	Although it is a mature solution in the industry, the cost of re-implementing it from 0-1 is high, and requires certain experience and tuning capabilities in the protocol. The interaction is complex, and the authentication process requires multiple calls, which has certain performance requirements.	If it is a new standard implementation, it will take about 1-2 weeks from design to implementation. If the integrator has already implemented the standard protocol, the implementation cost is 0 and the configuration can be completed on the CORAOOL product.
Customization	If there are already user authentication implementations and processes of other standard protocols, we can discuss it based on the actual situation. It is recommended to use mature industry protocols such as SSO/SAML/OPENID to reduce the cost of understanding and implementation cycle.

2.1 Authentication Solution 1: Callback / Callback encryption

2.2 Authentication Solution 2: OAuth 2.0

3. API Integration Developer Guide

3.1 Authentication Solution 1: Callback/Callback encryption

3.1.1 Service Provider

Provide your Authentication Service service address and usage method.

name	illustrate
URL	The address of the authentication service, usually you can directly access the page with it, such as https://login.demo.com
Provider	To be integrated
Schema	HTTPS
Others	If there is access control, the auth.coroaolapis.com domain name needs to be added to the whitelist. If there is a cross-domain restriction, the auth.coroaolapis.com domain name needs to be authorized to access the callback address here. The prefix is ​​https://auth.coraoolapis.com/v1/callback

3.1.2 Authorize API

3.1.2.1 API Definition

name	illustrate
URL	https://auth.coroaolapis.com/v1/callback/authorize
Provider	CORAOOL
Schema	HTTPS
Protocol	GET, data transmission method
Request Content-Type	x-www-form-urlencoded

3.1.2.2 Redirect Parameters Specification

When redirecting to your authentication center URL, pass in a parameter list, as follows:

name	type	length	Is it necessary	illustrate
client_id	string	256	yes	A unique application ID authorized to CORAOOL, generated by the integrator or agreed upon by both parties
sign_key	string	256	yes	The signature key authorized to CORAOOL is generated by the integrator or agreed upon by both parties.
sign	string	256	yes	Request signature, both parties use the secret corresponding to sign_key to do HMAC signature. The signature method is a single signature of the entire URL and Request Body HMAC(date + sign_secret, sha256), where date is a standard field in the HTTP header Date. If placed in the HTTP Header parameter, it is namedX-Sign
redirect_uri	string	4096	yes	Redirect address. After successful authentication, the user is redirected to this address. The prefix is ​​https://auth.coroaolapis.com/v1/callback/authorize
state	string	256	Optional	The transparent field, that is, what the input parameter value is, is brought as it is during the callback, generally used for anti-hijacking scenarios such as CSRF
secret	string	256	Optional	If the encryption callback protocol is enabled, the encryption method name agreed upon by both parties is passed in here. The key will be configured in the background, and the specific encryption is implemented separately. For example: secret=AES256 means using AES256 encryption. secret=BASE64 means using BASE64 encryption. If you need to further prevent the third party from understanding the encryption method, you can also configure it to other unrecognizable names.

3.1.2.3 API Response Specification

After your authentication service successfully authenticates, the redirection is adjusted to the redirect_uri in the request, and an additional parameter list is required, as follows:

name	type	length	Is it necessary	illustrate
sign_key	string	256	yes	Same as above
sign	string	256	yes	Same as above
token	string	256	yes	Valid certification, valid for a period of time
expires_at	number	10	yes	Credential expiration time, UNIX Timestamp accurate to milliseconds, for example 1678886400
OpenID	string	256	yes	User unique identifier
nickname	string	256	Optional	User nicknames are generally used to improve user experience and quickly give users a prompt and display with a corresponding title.
state	string	256	Optional	Transparent transmission parameters
ext	string	2M	Optional	Result value, JSON format value needs to be URL encoded (UTF-8)

For example, generate a link to redirect your authentication center as follows:

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

The redirect_uri parameter field value is as follows:

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

Then the link generated during redirection is as follows:

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

After completing the bilateral analysis according to the agreement, jump to the page visited by the user:

http://site.demo.com/?state=4c1ba88fea2d056f5d6f9b967557165502

3.1.2.4 Exception API Response Specification

Returns abnormal results, redirect carries parameters

name	type	length	Is it necessary	illustrate
sign_key	string	256	yes	Same as above
sign	string	256	yes	Same as above
error	string	200	yes	Error Code
error_message	string	2048	Optional	Error description, the value part will be url encoded (UTF-8)
state	string	256	Optional	Same as above

Error Code	grade	illustrate
0		success
100100	WARN	Missing client_id
100101	WARN	The parameter is missing or contains an invalid field format.
100201	ERROR	client_id has expired or is unavailable
100202	ERROR	redirect_uri is not in the authorized list
100203	ERROR	Unrecognized secret method
100204	ERROR	The token is invalid. Please re-authenticate.

Then the link generated during redirection is as follows:

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

After completing the bilateral analysis according to the agreement, jump to the page visited by the user:

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)

When the logged-in user is logged out elsewhere, the user will be kicked off the system as well. This API integration is optional and is mainly used in scenarios where users need to ensure high user experience synchronization. Otherwise, the final consistency is still guaranteed. When the user accesses resources that require authorization, the authentication system will still determine and require re-authentication.

3.1.3.1 API Definition

name	illustrate
URL	https://auth.coroaolapis.com/v1/callback/logout
Provider	CORAOOL
Schema	HTTPS
Protocol	GET / POST, data transmission method
Request Content-Type	x-www-form-urlencoded
Response Content-Type	application/json

3.1.3.2 API Parameter Specification

name	type	length	Is it necessary	illustrate
client_id	string	256	yes	Same as above
sign_key	string	256	yes	Same as above
sign	string	256	yes	Same as above
OpenID	string	256	yes	Same as above
secret	string	256	Optional	Same as above
state	string	256	Optional	Same as above

The integrator initiates the request notification from time to time. The example of GET call is as follows:

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

It also supports POST method calls. In this case, the signature field needs to be adjusted to the HTTP Header. The field name isX-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 API Response Specification

name	type	length	Is it necessary	illustrate
code	string	256	yes	Status code, 0 means success, other errors see exception list
message	string	256	Optional	Prompt text or error message
openids	array	2048	Optional	Processing failed openid list

The API returns the result in JSON format. The normal result processing return structure is as follows:

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

The abnormal result processing returns the following results

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

3.2 Authentication Solution 2: OAuth 2.0

3.2.1 Service Provider

Provide your OAuth2.0 Service address and usage. The field names in this document basically adopt the current mainstream implementation standards such as Google / AWS, etc. If your implementation is not the field name in the document, you can do the corresponding field mapping by configuring the backend.

name	illustrate
URL	The address of the authentication service, such as https://site.com/api/oauth2/
Provider	To be integrated
Schema	HTTPS
Others	If there is access control, the auth.coroaolapis.com domain name needs to be added to the whitelist. If there is a cross-domain restriction, the auth.coroaolapis.com domain name needs to be authorized to access the callback address here. The prefix is ​​https://auth.coraoolapis.com/v1/oauth2/

3.2.2 Authorize API

3.2.2.1 API Definition

name	illustrate
URL	The address of the authentication service, such as https://site.com/api/oauth2/authorize
Provider	To be integrated
Schema	HTTPS
Protocol	GET, data transmission method
Request Content-Type	x-www-form-urlencoded

3.2.2.3 Redirect Parameters Specification

name	Is it necessary	illustrate
client_id	yes	A unique application ID authorized to CORAOOL, generated by the integrator or agreed upon by both parties
return_uri	yes	Jump address, redirect the user to access this address after successful authentication
response_type	yes	The default value is code, the authorization type.
scope	no	The default is openid. When requesting user authorization, the list of available authorizations is displayed to the user. If there are multiple items, it is used ,as a separator, for exampleopenid, user_profile
state	no	The transparent field, that is, what the input parameter value is, is brought as it is during the callback, generally used for anti-hijacking scenarios such as CSRF

3.2.2.4 API Response Specification

name	Is it necessary	illustrate
code	yes	Authorization code. If the user authentication is successful, the code will be used to Access_Tokengenerate the formal authentication code in the next step.
state	no	Same as above

Here, the address of the authentication center to be integrated is taken https://login.demo.comas an example, then the generated address to be authenticated is, and the user will automatically jump to the dynamically generated address when authentication is required:

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

Furthermore, after the user is successfully authenticated, the authentication center to be integrated should return and redirect to redirect_urithe address, and append the return result codeand other parameters to the end, for example:

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 API Exception Response Specification

name	type	length	Is it necessary	illustrate
error	string	200	yes	Error Code
error_description	string	2048	Optional	Error description, the value part will be url encoded (UTF-8)
state	string	256	Optional	Same as above

Error code definition

Error Code	grade	illustrate
0		success
100100	WARN	Missing client_id
100101	WARN	The parameter is missing or contains an invalid field format.
100201	ERROR	client_id has expired or is unavailable
100202	ERROR	redirect_uri is not in the authorized list
100203	ERROR	Unrecognized secret method
100204	ERROR	The token is invalid. Please re-authenticate.

If there is an abnormal situation, it will also be redirected to redirect_urithe specified address and carry parameters such as above error. error_messageFor example, according to the above-mentioned authentication center, the jump connection form is as follows:

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 Definition

name	illustrate
URL	The address of the authentication service, for example https://site.com/api/oauth2/token
Provider	To be integrated
Schema	HTTPS
Protocol	POST, data transmission method
Request Content-Type	x-www-form-urlencoded
Response Content-Type	application/json

3.2.3.2 API Parameter Specification

name	Is it necessary	illustrate
code	yes	Authorization code, Authorize APIobtained from
client_id	yes	Same as above
client_secret	yes	The authentication key authorized to CORAOOL is generated by the integrator or agreed upon by both parties.
grant_type	yes	According to the OAuth 2.0 protocol, this is a fixed valueauthorization_code
redirect_uri	yes	The function is the same as above, and Authorize APIthe parameters passed in must be kept consistent
scope	Optional	Same as above

3.2.3.3 API Response Specification

name	Is it necessary	illustrate
token_type	yes	User authentication credential type, here is the protocol fixed value bearer, forced to be all lowercase
access_token	yes	Authorization code. If the user authentication is successful, the code will be used to Access_Tokengenerate the user authentication credentials in the next step.
expires_in	yes	Access_token validity period (seconds)
refresh_token	Optional	Used to renew access_token
id_token	Optional	User identity JWT returned in OIDC (only for platforms that support OIDC)
scope	Optional	Same as above

Here we continue to take the previous case as an example, the generated request parameter type is 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

Send POSTa request to the authentication center to be integrated

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"

If the request is successful, the following JSON structure will be returned

{
  "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 Exception API Response Specification

name	type	length	Is it necessary	illustrate
error	string	200	yes	Error Code
error_description	string	2048	Optional	Error description

The return format is JSON, and the HTTP Response Code is 400. The error code uses the same exception error table as described in Authorize.

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

3.2.4 Refresh Access Token API

3.2.4.1 API Definition

name	illustrate
URL	The address of the authentication service, for example https://site.com/api/oauth2/token
Provider	To be integrated
Schema	HTTPS
Protocol	POST, data transmission method
Request Content-Type	x-www-form-urlencoded
Response Content-Type	application/json

3.2.4.2 API Parameter Specification

name	Is it necessary	illustrate
client_id	yes	Same as above
client_secret	yes	The authentication key authorized to CORAOOL is generated by the integrator or agreed upon by both parties.
grant_type	yes	According to the OAuth 2.0 protocol, this is a fixed valuerefresh_token
refresh_token	yes	The last authorization was obtainedaccess_token
scope	Optional	Same as above

3.2.4.3 API Response Specification

name	Is it necessary	illustrate
token_type	yes	User authentication credential type, here is the protocol fixed value bearer, forced to be all lowercase
access_token	yes	Authorization code. If the user authentication is successful, the code will be used to Access_Tokengenerate the user authentication credentials in the next step.
expires_in	yes	Access_token validity period (seconds)
id_token	Optional	Same as above
scope	Optional	Same as above

Here we continue to take the previous case as an example, the generated request parameter type is x-www-form-urlencoded:

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

Send POSTa request to the authentication center to be integrated

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"

If the request is successful, the following JSON structure will be returned

{
  "access_token": "ya29.a0AfH6SM...",
  "id_token": "eyJhbGciOiJSUzI1..."
  "scope": "openid email profile",
  "expires_in": 3600,
  "token_type": "bearer"
}

3.2.4.4 Exception API Response Specification

Same format and content definition as described in Access Token API

3.4 (Demo) Example Service API Integrated with Authentication Token

After integrating user authentication, in addition to the page using the authentication status, another common scenario is that some Service APIs also need to carry authentication information to return the corresponding user results. Several methods are provided in the data source

3.4.1 Request Header Parameter Mode

This document supports the use of fields as user login credentials. You can also modify and use other custom-named Request Headers according to actual scenarios to carry user credential parameters X-Access-Tokenwhen making API requests.token

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

3.4.2 Cookies Mode

You can also use traditional HTTP Cookies to carry, pay attention to opening HTTP-Only, Secureand SameSite=Strictimprove security. Here we use standard naming access_token, which can be modified according to actual needs.

curl -X POST https://api.demo.com/api_name -b "access_token=eyJhbGciOi...; param=xxx"