All Products
Search
Document Center

CDN:Configure remote authentication

Last Updated:Feb 02, 2024

Alibaba Cloud CDN supports the remote authentication feature. You can use this feature to redirect requests to a server for authentication. If a request passes the authentication, the request is redirected to points of presence (POPs). If a request fails the authentication, the request is rejected or requests from the client are throttled. This way, the resources on POPs are protected from unauthorized access.

Feature overview

Remote authentication is similar to URL signing. Both are used to protect resources from unauthorized access. Only authorized users can retrieve resources from POPs. Differences between URL signing and remote authentication:

  • URL signing: After you apply authentication rules that are created for a domain name to POPs, the POPs complete the authentication process.

  • Remote authentication: You can specify a self-managed authentication server. After POPs receive client requests, the requests are redirected to the specified authentication server.

The following figure shows how remote authentication works.远程鉴权交互图

No.

Description

1

A client sends a request to a POP. The request carries parameters that are used for authentication.

2

The POP receives the request, and then redirects the request to the authentication server. You can specify whether the request is processed by the POP before the request is redirected to the authentication server.

3

The authentication server checks the parameters in the request, and then returns the authentication result to the POP.

4

The POP performs the corresponding action based on the authentication result, and then returns data to the client.

Examples:

  • Example 1: The request passes the authentication. The POP returns the requested resources to the client.

  • Example 2: The request fails the authentication. The POP returns the HTTP 403 status code to the client.

  • Example 3: The request fails the authentication. The POP throttles requests that are sent from the client.

  • Example 4: The authentication process times out. The POP performs the specified action, such as allow or reject.

Procedure

  1. Log on to the Alibaba Cloud CDN console.

  2. In the left-side navigation pane, click Domain Names.

  3. On the Domain Names page, find the domain name that you want to manage and click Manage in the Actions column.

  4. In the left-side navigation tree of the domain name, click Access Control.

  5. Click the Remote Authentication tab.

  6. Turn on Remote Authentication and configure the parameters as prompted.

    Note

    After you enable remote authentication, all user requests are redirected to the authentication server. If a large number of requests are sent to POPs, make sure that the authentication server can handle traffic spikes without compromising the performance.

    Parameter

    Description

    Authentication Server Address

    The address of the authentication server. This address must be publicly accessible. Alibaba Cloud CDN checks the specified server address and the address format.

    • Supported formats

      HTTP and HTTPS addresses are supported. Examples:

      • http://example.com/auth

      • https://example.com/auth

      • http://192.0.2.1/auth

      • https://192.0.2.1/auth

    • Address requirements

      The server address cannot contain 127.0.0.1 or localhost. Otherwise, the server address is considered invalid.

    Request Method

    The request method that is supported by the authentication server. Valid values: GET, HEAD, and POST. Default value: GET.

    File Types

    • All: The authentication server checks all file types.

    • Specified: The authentication server checks only the specified file types.

      • You can specify one or more 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 Signing Parameters

    Parameters to Retain

    The URL parameters that you want the authentication server to check. Valid values: Retain All Parameters, Retain Specified Parameters, and Delete All URL Parameters.

    • If you specify multiple parameters that you want to retain, separate the parameters with vertical bars (|). Example: user|token.

    • Parameters are case-sensitive. For example, key and KEY are considered different parameters.

    Custom Parameters

    The parameters that you want to add to the URLs of requests before the requests are redirected to the authentication server. You can specify key-value pairs or select the variables that are provided by Alibaba Cloud CDN.

    • When you specify key-value pairs, take note of the following rules:

      • Separate key-value pairs 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 $http_host variable, host=$http_host is added to the URLs of requests before the requests are redirected to the authentication server. In this example, host is the value of the Host request header. For more information about the variables, see Variables.

    Parameters to Retain in Request Headers

    Request Headers to Retain

    The request headers that you want the authentication server to check. Valid values: Retain All Request Headers, Retain Specified Request Headers, and Delete All Request Headers.

    • If you specify multiple request headers that you want to retain, 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, POPs delete the Host header from requests. If you want to retain the Host header in requests, you can select Retain Specified Request Headers or configure Custom Parameters. The Host header in requests that are redirected to the authentication server specifies the accelerated domain name. Therefore, POPs automatically delete the Host header from requests. Otherwise, the authentication server may fail to identify these requests and return errors, such as the HTTP 404 status code, which indicates authentication failures.

    Custom Parameters

    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 the variables that are 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 $http_host variable, host=$http_host is added to the URLs of requests before the requests are redirected to the authentication server. In this example, host is the value of the Host request header. For more information about the variables, see Variables.

    HTTP Status Code to Return

    Passes Authentication

    The HTTP status code that is returned by the authentication server if a request passes the authentication.

    If you set the HTTP status code to 200, the authentication server returns the HTTP 200 status code to POPs for client requests that pass the authentication.

    If the HTTP status code that is returned by the authentication server does not indicate whether a request passes or fails the authentication, the POP allows the request. For example, if the HTTP status code specified for requests that pass the authentication is 200, but the authentication server returns the HTTP 201 status code for a request, the POP allows the request. This ensures that no request is blocked due to exceptions.

    Fails Authentication

    The HTTP status code that is returned by the authentication server if a request fails the authentication.

    If you set the HTTP status code to 403, the authentication server returns the HTTP 403 status code to POPs for client requests that fail the authentication.

    If the HTTP status code that is returned by the authentication server does not indicate whether a request passes or fails the authentication, the POP allows the request. For example, if the HTTP status code specified for requests that fail the authentication is 403, but the authentication server returns the HTTP 404 status code for a request, the POP allows the request. This ensures that no request is blocked due to exceptions.

    Allow Other Status Codes

    • Yes: If the HTTP status code that is returned by the authentication server does not indicate whether a request passes or fails the authentication, the POP allows the request. This ensures that no request is blocked due to exceptions.

      Note

      Examples:

      • If the HTTP status code specified for requests that pass the authentication is 200, but the authentication server returns the HTTP 201 status code for a request, the POP allows the request.

      • If the HTTP status code specified for requests that fail the authentication is 403, but the authentication server returns the HTTP 404 status code for a request, the POP allows the request.

    • No: If the HTTP status code that is returned by the authentication server does not indicate whether a request passes or fails the authentication, the POP rejects the request.

    Response if authentication Fails

    Custom HTTP Status Code

    The HTTP status code that is returned from POPs to clients after the POPs receive an HTTP status code indicating that the request fails the authentication from the authentication server.

    If you set Custom HTTP Status Code to 403, the POP returns the HTTP 403 status code to the user for requests that fail the authentication.

    Authentication Timeout Settings

    Timeout

    The timeout period starts when the POP redirects a request to the authentication server. The timeout period ends when the POP 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.

    Action After Timeout

    The action that you want the POPs to perform on a request when the authentication of the request times out. Valid values: Allow and Reject.

    • Allow: When the authentication of a request times out, the POP allows the request.

    • Reject: When the authentication of a request times out, the POP rejects the request, and then returns the HTTP status code that is specified in Custom HTTP Status Code to the client.

  7. Click OK.

    After remote authentication is configured, you can modify the settings of remote authentication or disable remote authentication on the Remote Authentication tab.

Variables

When you add custom parameters, you can select the variables that are provided by Alibaba Cloud CDN. The following table describes the variables.

Variable

Description

$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.

Related API operations

BatchSetCdnDomainConfig