Access control with signed URLs

Control who and for how long can access files in your project via signed URLs. When enabled, a user will require a token to access your content by the link like this:

https://cdn.yourdomain.com{path}?token=exp={timestamp}~hmac={token}

A signed URL is a URL that contains authentication information in its query string that provides limited permission and time to get the file.

How it works

Use cases:

End-users upload personal, medical, and other sensitive data.
Only an authorized client can access certain content.
Limit content access by time.

Prior to using signed URLs, set up a custom CNAME.

Example:

https://cdn.yourdomain.com{path}?token=exp={timestamp}~acl={acl}~hmac={token}

Where:

{path} is URL path part that contains file UUID and optionally any processing operations and filename. E.g.:
- /{uuid}/
- /{uuid}/-/preview/100x100/
- /{uuid}/lolcat.jpg
transformations + filename), which is a URL part.
{acl} is an optional Access Control List parameter. It supports * wildcard as a suffix.

ACL examples to access files with a token:

acl=/* — any file in a project.
acl=/{uuid}/ — original file with UUID.
acl=/{uuid}/* — original file or any variation of the original file.
acl=/{uuid}/-/resize/640x/ — modified file version.

Test environment

You can test signed URLs with in the test environment using the following credentials:

hostname: sectest.ucarecdn.com
secret: 73636b61519adede42191efe1e73f02a67c7b692e3765f90c250c230be095211

Note: don’t use it in production, this secret key is well known.

Token generation

Your backend app should take care of generating access tokens. To create tokens, you need to get the encryption key from our support.

You can start with ready-made solutions for popular languages:

Please note that we have limited support for this option.

Here non-official solutions:

C#
GoLang

You can use signed URLs into the Uploadcare PHP library.

After setting up signed URLs, specify the projects where you plan to store protected files. We will close public access to these projects.

Proxy backend example

The proxy backend is an API endpoint within your application’s backend. Its primary function is to receive a file URL, apply a signature for security, and respond with a redirect to the signed URL. This ensures secure access to files through your application.

The app needs to resolve the following tasks:

Accept escaped preview URL as a GET parameter.
Check user authorization.
Generate expiring access tokens for that URL.
Append access tokens to the URL.
Redirect to that URL.

Don’t forget to check user credentials on your backend. Make sure not to authenticate anonymous user requests. Otherwise using signed URLs don’t make any sense.

previewProxy option specifies the URL of a proxy backend. File Uploader uses this URL to generate secure previews of files by applying signed URLs. Here is a previewProxy example (Node JS + Express):

1 const express = require("express");
2 const cookieParser = require("cookie-parser");
3 const EdgeAuth = require("akamai-edgeauth");
4 
5 // User's custom CDN domain
6 const HOSTNAME = "https://files.acme.com";
7 // Encryption key for the above domain
8 const EA_ENCRYPTION_KEY = "your encryption key";
9 // token lifetime in seconds
10 const DURATION = 500;
11 
12 const ea = new EdgeAuth({
13 	key: EA_ENCRYPTION_KEY,
14 	windowSeconds: DURATION,
15 	tokenName: "token",
16 	escapeEarly: true,
17 });
18 
19 const app = express();
20 
21 app.use(express.urlencoded({ extended: false }));
22 app.use(cookieParser());
23 
24 app.get("/preview", (req, res) => {
25 	const user = req.cookies.user;
26 	if (!user) {
27 		return res.status(403).send("Authorization failed");
28 	}
29 	const { pathname } = new URL(req.query.url);
30 	const token = ea.generateURLToken(pathname);
31 	const signedURL = `${HOSTNAME}${pathname}?${ea.options.tokenName}=${token}`;
32 	res.redirect(signedURL);
33 });
34 
35 const listener = app.listen(3000, () => {
36 	console.log("Listening on port " + listener.address().port);
37 });

Billing

This feature is available on paid plans.