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:
A signed URL is a URL that contains authentication information in its query string that provides limited permission and time to get the file.
Use cases
When to use signed URLs:
- End-users upload personal, medical, and other sensitive data.
- Only an authorized client can access certain content.
- Limit content access by time.
How it works
Signed URLs only work on paid plans. Contact us to enable the this feature. Please specify if you need to upload files larger than 1 GB in your request.
Prior to using signed URLs, set up a custom CNAME.
Example:
Where:
{uuid}
is a UUID of any file in your Uploadcare project or a URI (UUID + 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 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.
We recommend that you start with ready-made solutions for popular languages:
Here non-official solutions:
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 of 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.
Here is a previewProxy
example (Node JS + Express):
Show image previews in jQuery File Uploader
After uploading, the uploading widget loads image previews from the CDN:
With this feature turned on, the uploading widget can’t show previews because signed URLs include a token part. To work that around, you can load images through a proxy backend, where it can hook up the token info:
Here are two options that can help you show image previews:
previewProxy
. It proxies the data related to image previews.previewUrlCallback
. It works if you need to send extra data like JWT tokens.
Option previewProxy
Implementing the previewProxy
option works best for these cases:
- Your application uses cookie-based authorization.
- Your proxy backend and your app are located in the same domain (otherwise, cookies won’t be sent).
- You don’t need any other image-related data beside URLs.
To use previewProxy
option, specify your proxy backend endpoint URL, and
you’re good to go:
It’ll let the uploading widget load image previews via the following URL:
It appends a query parameter with image preview URL to previewProxy
:
By default, the uploader uses url
as the query parameter name, but you
can have a custom naming as well:
Option previewUrlCallback
This option provides you with explicit control over the uploading widget preview
URLs. In code, previewUrlCallback
is a function with a signature:
Example:
Note, previewUrlCallback
overrides previewProxy
, and the latter option will
be ignored.