URL authentication
URL authentication: add an expiry time and signature to download or playback links; the node returns content only when the signature checks out.
What it does
URL authentication puts an expiry time and a signature into the link. When a request arrives, the node recomputes the signature with the policy's key and returns the content only if it matches and has not expired; otherwise it answers 403. An expired link stops working, and a link cannot be edited to point at another path.
When to use it
- Paid downloads, course videos or installers: your business server generates a signed link for a logged-in user.
- A link is valid for only minutes or hours.
- Bind a link to the client IP that requested it, so it cannot be forwarded to someone else.
- Limit how many times one signature can be used.
Where to configure it
In the console: "URL authentication" under site management. Create a policy and bind it to a site. Once saved, the policy is delivered to the nodes with the site configuration.
Settings
| Setting | Description |
|---|---|
| Bound site | The site the policy applies to |
| Name | Up to 128 characters |
| Algorithm | HMAC-SHA256 |
| Signature parameter | Query parameter name that carries the signature |
| Expiry parameter | Query parameter name that carries the expiry time |
| Key ID parameter | Query parameter name that carries the key ID |
| Clock skew limit | 0 to 300 seconds, tolerated when checking the expiry time |
| Signature validity limit | 1 to 86400 seconds; the expiry time cannot be further away than this |
| Signature use limit | 0 to 1000000; 0 means unlimited |
| Excluded parameters | Other query parameters left out of the signature, one per line |
| Trusted proxy CIDRs | When the client reaches you through these proxies the real IP is read from the forwarding header, one per line |
| Bind client IP | The client IP is included in the signature |
| Enable policy | Can be enabled or disabled at any time |
Parameter names may use letters, digits, dot, underscore, tilde and hyphen, up to 64 characters.
How the signature is computed
Compute HMAC-SHA256 over the following text and write the lowercase hexadecimal result into the signature parameter:
CDNCA-URL-AUTH/1
tenant_id=<tenant ID>
site_id=<site ID>
method=<request method>
path=<path>
query=<remaining query parameters, sorted>
expires=<expiry as Unix seconds>
key_id=<key ID>
client_ip=<client IP, empty when IP binding is off>Every value is percent-encoded. From the query, drop the signature, expiry and key ID parameters and the excluded parameters, then sort by name and value and encode. A link looks like /video/a.mp4?expires=1767225600&kid=k1&sign=<signature>; the parameter names are the ones set in the policy.
Key management
- The key is shown once when the policy is created. After you close the dialog it cannot be viewed again, so save it in your credential manager right away.
- "Rotate key": the current key enters a smooth rotation window in which both old and new keys pass; the new key is likewise shown once.
- "Revoke previous key": requests signed with the previous key stop working immediately.
- When a policy is disabled, the site no longer requires signatures.
FAQ
A request returns 403
Common causes: the signature, expiry or key ID parameter is missing; the link has expired, or its expiry is further away than the signature validity limit; the method, path or query differs from what was signed; IP binding is on and the request comes from another IP; the signature use limit has been exceeded.
A request returns 503
The node does not yet have the key for this policy version, or the state that counts signature uses is briefly unavailable. It can appear shortly after a policy is created or its key rotated, and clears as the configuration is delivered.
The signature does not match
Check each item under "How the signature is computed": path and query values are percent-encoded, signature-related parameters are removed from the query and the rest sorted by name, the expiry is Unix seconds, and the method matches the request.
Clients come through a proxy
List the proxies' ranges under "Trusted proxy CIDRs" so the node reads the real client IP from the forwarding header for the signature.