configure remote authentication - CDN - Alibaba Cloud Documentation Center

If you have your own authentication server, you can configure remote authentication to forward user requests to the specified authentication server for verification.

Feature overview

Remote authentication and URL signing both aim to protect resources by ensuring only authorized users have access. Unauthorized users will be denied access. The technical implementation of these two features differs as follows:

URL signing: Authentication rules created for a domain name are applied to CDN edge nodes, which complete the authentication process.
Remote authentication: CDN edge nodes receive client requests and redirect them to your specified authentication server for verification.

The data interaction process of the remote authentication feature is as follows: Remote Authentication Interaction Diagram

Ordinal number	Interaction description
①	A client sends a resource access request to a CDN edge node. The request carries parameters that are used for authentication. Example: Original request URL: `https://example.com/123/test.txt?key=xxxxxxxxxx` Header carried in the original request: `test=123`
②	The CDN edge node receives the request and redirects it to the authentication server. You can specify whether the request is processed by the CDN edge node before it is redirected to the authentication server. Example: Authentication server address: `https://192.0.2.1/auth` The remote authentication feature in the CDN console is set to: Retain all request parameters and Retain all request headers The request URL forwarded by the CDN to the authentication server is: `https://192.0.2.1/auth?key=xxxxxxxxxx` The request forwarded by the CDN to the authentication server includes the header: `test=123`
③	The authentication server checks the parameters in the request and returns the authentication result to the CDN edge node.
④	The CDN edge node performs the specified action based on the authentication result and returns data to the client. Examples of authentication results are as follows: Example 1: The request passes the authentication. The CDN edge node returns the requested resources to the client. Example 2: The request fails the authentication. The CDN edge node returns the HTTP 403 status code to the client. Example 3: The request fails the authentication. The CDN edge node throttles requests sent from the client. Example 4: The authentication process times out. The CDN edge node performs the specified action, such as allow or reject.

Notes

After you configure remote authentication, requests that fail the authentication can still reach the CDN edge nodes, but they will be rejected by the CDN edge nodes and the HTTP 403 status code will be returned. The CDN logs will still record the client request.
Because remote authentication routes user requests to the designated authentication server for verification, intercepting malicious requests at the CDN/ edge nodes incurs a small amount of traffic fees. Additionally, if the client employs the HTTPS protocol, fees for HTTPS requests will apply due to the resource consumption at the CDN/ edge nodes when intercepting these requests.

Procedure

Log on to the Alibaba Cloud CDN console.
In the left-side navigation pane, click Domain Names.
On the Domain Names page, find the domain name that you want to manage and click Manage in the Actions column.
In the left-side navigation tree of the domain name, click Access Control.

Click the Remote Authentication tab.

Turn on the Remote Authentication switch and follow the prompts to configure the remote authentication information.

Note

After enabling remote authentication, ensure your authentication server can handle traffic spikes without compromising performance.

Parameter		Description
Authentication Server Address		The address of the authentication server. The system checks the specified server address and the format of the address. Format requirements The authentication address supports HTTP and HTTPS protocols. Examples: http://example.com/auth https://example.com/auth http://192.0.2.1/auth https://192.0.2.1/auth Value requirements The value cannot contain 127.0.0.1 or localhost because these local addresses are invalid.
Request Method		The request method that is supported by the authentication server. The supported request methods are GET, HEAD, and POST. The default request method is GET.
Authentication File Type		All File Types: All file types are authenticated. Specified File Types: Only specified file types are authenticated. When you specify file types, separate multiple file types with vertical bars (\|). Example: mp4\|flv. File types are case-sensitive. For example, .jpg and JPG are considered different file types.
URL Authentication Parameters	Retain Parameter Settings	Specify the URL parameters that you want the authentication server to check. You can select Retain All Parameters, Retain Specified Parameters, or Delete All URL Parameters. If you specify multiple parameters, separate the parameters with vertical bars (\|). Example: user\|token. Parameters are case-sensitive. For example, key and KEY are considered different parameters.
URL Authentication Parameters	Add Custom Parameters	Specify the parameters that you want to add to the URLs of requests before they are redirected to the authentication server. You can specify key-value pairs or select variables provided by Alibaba Cloud CDN. When you specify key-value pairs, take note of the following rules: Separate multiple parameters with vertical bars (\|). Example: token=$arg_token\|vendor=ali_cdn. Values are case-sensitive. For example, key and KEY are considered different values. If you use preset variables, the values of the variables are added to requests that are sent to the POP before the requests are redirected to the authentication server. For example, if you select the variable $http_host, the URL of the client request will include host=$http_host, where host indicates the value of the host header in the client request. For more information about variable names and meanings, see Variable names.
Request Header Authentication Parameters	Retain Request Header Settings	Specify the request headers that you want the authentication server to check. You can select Retain All Parameters, Retain Specified Parameters, or Delete All Request Header Parameters. If you specify multiple request headers, separate the request headers with vertical bars (\|). Example: user_agent\|referer\|cookies. Request headers are not case-sensitive. For example, http_remote_addr and HTTP_Remote_Addr are considered the same request header. Note If you select Retain All Request Headers, CDN edge nodes delete the Host header from requests by default. If you want to retain the Host header in requests, you can select Retain Specified Request Header or configure the Custom Parameters parameter. CDN edge nodes delete the Host header from requests by default because the Host header in requests that are redirected to the authentication server specifies the accelerated domain name. The authentication server may fail to identify these requests and cause errors such as the HTTP 404 status code, which indicates authentication failures.
Request Header Authentication Parameters	Add Custom Parameters	Specify the parameters that you want to add to request headers before the requests are redirected to the authentication server. You can specify key-value pairs or select variables provided by Alibaba Cloud CDN. When you specify key-value pairs, take note of the following rules: Separate multiple request headers with vertical bars (\|). Example: User-Agent=$http_user_agent\|vendor=ali_cdn. Request headers are not case-sensitive. For example, http_remote_addr and HTTP_Remote_Addr are considered the same request header. If you use preset variables, the values of the variables are added to requests that are sent to the POP before the requests are redirected to the authentication server. For example, if you select the variable $http_host, the URL of the client request will include host=$http_host, where host indicates the value of the host header in the client request. For more information about variable names and meanings, see Variable names.
Status Codes For Authentication Results	Status Codes For Successful Authentication	Description When the authentication server successfully authenticates a request, it returns specific HTTP status codes to the CDN. You can configure multiple status codes. Separate multiple status codes with commas. Example If you set the status codes for successful authentication to `200,206`, the authentication is considered successful when the authentication server returns `200` or `206`. Exception handling mechanism To prevent all user requests from being blocked due to exceptions, if the status code returned by the authentication server is neither a success status code nor a failure status code, the CDN edge node will allow the request by default.
	Status Codes For Failed Authentication	Description When the authentication server fails to authenticate a request, it returns specific HTTP status codes to the CDN. You can configure multiple status codes. Separate multiple status codes with commas. Example If you set the status codes for failed authentication to `400,403`, the authentication is considered failed when the authentication server returns `400` or `403`. Exception handling mechanism To prevent all user requests from being blocked due to exceptions, if the status code returned by the authentication server is neither a success status code nor a failure status code, the CDN edge node will allow the request by default.
	Allow Other Status Codes	Yes: To prevent all user requests from being blocked due to exceptions, if the status code returned by the authentication server is neither a success status code nor a failure status code, the CDN edge node will allow the request by default. Note Example: If the status code for successful authentication is set to 200 and the authentication server returns 201, the request is allowed. If the status code for failed authentication is set to 403 and the authentication server returns 404, the request is allowed. No: If the status code returned by the authentication server is neither a success status code nor a failure status code, the CDN edge node will reject the request.
Actions Performed By The CDN After Failed Authentication	Custom Status Code For Response	The HTTP status code that is returned from CDN edge nodes to clients after the edge nodes receive an HTTP status code indicating that the request fails the authentication from the authentication server. For example, if you set the custom status code for response to 403, the CDN edge node returns the HTTP 403 status code to the client for requests that fail the authentication.
Authentication Timeout Configuration	Authentication Timeout Period	The timeout period starts when a CDN edge node redirects a request to the authentication server. The timeout period ends when the CDN edge node receives the authentication result from the authentication server. The timeout period is measured in milliseconds. You can set the timeout period to up to 3,000 milliseconds.
Authentication Timeout Configuration	Actions Performed After Authentication Timeout	Specify the action that you want the CDN edge nodes to perform on a request if the authentication on the request times out. The supported actions are Allow and Reject. The differences are as follows: Allow: The authentication process times out. The CDN edge node allows the request. Reject: Authentication timeout. The CDN rejects the user's request and returns the configured Custom Response Status Code to the user.

Click OK to finalize the configuration.

Once you have successfully configured the remote authentication feature, you can alter the existing configuration or deactivate the remote authentication on the Remote Authentication tab.

Variable names

When adding custom parameters, select from the variables provided by Alibaba Cloud CDN. The following table describes these variables.

Variable name	Variable meaning
$http_host	The value of the Host header.
$http_user_agent	The value of the User-Agent header.
$http_referer	The value of the Referer header.
$http_content_type	The value of the Content-Type header.
$http_x_forward_for	The value of the X-Forwarded-For header.
$remote_addr	The client IP address.
$scheme	The protocol of the request.
$server_protocol	The protocol version of the request.
$uri	The original URI of the request.
$args	The query string of the request URL. The query string does not include the question mark (?).
$request_method	The request method.
$request_uri	The content of uri+'?'+args.

FAQ

Related API operations

BatchSetCdnDomainConfig