Configure URL signing - Edge Security Acceleration - Alibaba Cloud Documentation Center

This topic describes how to implement three authentication methods for Edge Security Acceleration (ESA) using Edge Function templates. It covers the signature algorithm, URL format, parameters, and server-side validation logic for each method. These methods secure resources for use cases like protected file access or authenticated API requests. The provided code examples and parameter descriptions help you configure and debug the implementation.

How it works

URL signing protects your origin resources by blocking requests that fail authentication.

Authentication methods

ESA provides three authentication methods: A, B, and C. Each method verifies a request by comparing an MD5 hash from the URL with a hash computed at a point of presence (POP). If the hashes match, the POP processes the request and serves the resource. If they do not match, the request is denied.

Method A

Signed URL format: http://DomainName/Filename?auth_key={timestamp}-{rand}-{uid}-{md5hash}. For a description of these parameters, see Parameters.

Example code

import { createHash } from "node:crypto";

async function handleRequest(request) {
  const url = new URL(request.url);
  const path = url.pathname;
  const delta = 3600;

  const authKeyTypeA = url.searchParams.get('auth_key');

  const privateKey = 'your_secret_key'
  const currentTimestamp = Math.floor(Date.now() / 1000);

  if (!authKeyTypeA) {
    return new Response('Unauthorized', { status: 401 });
  }

  const [timestamp, rand, uid, signature] = authKeyTypeA.split('-');

  if (currentTimestamp > parseInt(timestamp)+ delta) {
    return new Response('Link expired', { status: 403 });
  }

  const signString = [path, timestamp, rand, uid, privateKey].join('-');

  const md5 = createHash('md5').update(signString).digest('hex');

  if (md5 !== signature) {
    return new Response('Unauthorized', { status: 401 });
  }

  // If the resource is on another domain, fetch it and return the response
  // const yourUrl = `https://your-dcdn-domain.com${path}${url.search}`
  // const cdnResponse = await fetch(yourUrl, request)
  // return new Response(cdnResponse.body, cdnResponse)

  // In most cases, one origin fetch is sufficient
  return fetch(request.url)
}

export default {
  async fetch(request) {
    return handleRequest(request)
  }
}

Test and verify
- Use a Command Line Interface (CLI) to test a URL that should pass authentication: curl -I http://esa.aliyun.top/video/test.mp4?auth_key=1743388566-61b20a42d14f403ba3790d1b82502027-1-ee1c2c463a41ef4d72fcff5987f1e08c. A 200 HTTP response code indicates that authentication is successful.
- Use a CLI to test a URL that should fail authentication: curl -I http://esa.aliyun.top/test.mp4. A 401 HTTP response code indicates that authentication has failed.

Method B

Signed URL format: http://DomainName/{timestamp}/{md5hash}/FileName. For a description of these parameters, see Parameters.

Example code

import { createHash } from "node:crypto";

function handleRequest(request) {
  const url = new URL(request.url);
  const path = url.pathname;
  const parts = path.split('/');
  const delta = 3600;
  const privateKey = 'your_secret_key'
  const currentTimestamp = Math.floor(Date.now() / 1000);
  const timestamp = parts[1];
  const signature = parts[2];

  if (!timestamp || !signature) {
    return new Response('Unauthorized', { status: 401 });
  }

  const filePath = '/' + parts.slice(3).join('/');
  const signString = [privateKey, timestamp, filePath].join('');
  const md5 = createHash('md5').update(signString).digest('hex');

  if (md5 !== signature) {
    return new Response('Unauthorized', { status: 401 });
  }

  if (currentTimestamp > parseInt(timestamp)+ delta) {
    return new Response('Link expired', { status: 403 });
  }

  // If the resource is on another domain, fetch it and return the response
  // const yourUrl = `https://your-dcdn-domain.com${path}${url.search}`
  // const cdnResponse = await fetch(yourUrl, request)
  // return new Response(cdnResponse.body, cdnResponse)

  // For Authentication Method B, reconstruct the original file path for the origin fetch.
  return fetch(url.origin + filePath)
}

export default {
  async fetch(request) {
    return handleRequest(request)
  }
}

Test and verify
- Use a CLI to test a URL that should pass authentication: curl -I http://esa.aliyun.top/1743391454/f1415e282ae5ae650455e7b525231eff/test.mp4. A `200` HTTP response code indicates that authentication is successful.
- Use a CLI to test a URL that should fail authentication: http://esa.aliyun.top/test.mp4. A `401` HTTP response code indicates that authentication has failed.

Method C

Signed URL format: http://DomainName/{md5hash}/{timestamp}/FileName. For a description of these parameters, see Parameters.

Example code

import { createHash } from "node:crypto";

function handleRequest(request) {
  const url = new URL(request.url);
  const path = url.pathname;
  const parts = path.split('/');
  const delta = 3600;
  const privateKey = 'your_secret_key'
  const currentTimestamp = Math.floor(Date.now() / 1000);
  const signature = parts[1];
  const hexTime = parts[2];
  const timestamp = parseInt(hexTime, 16);

  if (!hexTime || !signature) {
    return new Response('Unauthorized', { status: 401 });
  }

  const filePath = '/' + parts.slice(3).join('/');
  const signString = [privateKey, filePath, hexTime].join('-');
  const md5 = createHash('md5').update(signString).digest('hex');

  if (md5 !== signature) {
    return new Response('Unauthorized', { status: 401 });
  }

  if (currentTimestamp > parseInt(timestamp)+ delta) {
    return new Response('Link expired', { status: 403 });
  }

  // If the resource is on another domain, fetch it and return the response
  // const yourUrl = `https://your-dcdn-domain.com${path}${url.search}`
  // const cdnResponse = await fetch(yourUrl, request)
  // return new Response(cdnResponse.body, cdnResponse)

  // For Authentication Method C, reconstruct the original file path for the origin fetch.
  return fetch(url.origin + filePath)
}

export default {
  async fetch(request) {
    return handleRequest(request)
  }
}

Test and verify
- Use a CLI to test a URL that should pass authentication: curl -I http://esa.aliyun.top/e59c904c85f19a48413b6283fc9d2f5a/1743400480/test.mp4. A `200` HTTP response code indicates that authentication is successful.
- Use a CLI to test a URL that should fail authentication: http://esa.aliyun.top/test.mp4. A `401` HTTP response code indicates that authentication has failed.

Parameters

DomainName: The DNS record for your ESA site.
timestamp: The time when the signed URL is generated, expressed as a Unix timestamp (the number of seconds since the Unix epoch). This value, along with the configured TTL, determines the URL's expiration time. For Authentication Method C, the timestamp is represented as a hexadecimal string.
Note
A signed URL expires at the timestamp plus a configured validity period. The validity period is typically set in ESA. The example code uses a fixed value for this period, set in the `delta` variable.
FileName: The path to the requested file on the origin server. The path must start with a forward slash (/).
md5hash: A 32-character validation string generated using the MD5 algorithm. The string consists of digits from 0 to 9 and lowercase letters from a to z.
The md5hash value is calculated as follows:
- Authentication Method A: getMd5(FileName + "-" + timestamp + "-" + rand + "-" + uid + "-" + your_secret_key).
- Authentication Method B: getMd5(your_secret_key + timestamp + FileName).
- Authentication Method C: getMd5(your_secret_key + "-" + FileName + "-" + timestamp).
Note
You must implement the getMd5 function manually.
rand: A random string used to make each signed URL unique. Use a universally unique identifier (UUID) without hyphens for this value. For example: 477b3bbc253f467b8def6711128c7bec.
uid: The User ID (UID), which you can set based on your business requirements.
auth_key: The authentication information for the request, which consists of timestamp, rand, uid, and md5hash.