Authorized personnel only: Restricting access to assets with signed URLs

An illustration of an employee card, symbolizing restricted access to assets
April 15, 2021



As a global platform, Contentful excels at helping customers serve their content with very low latency — all around the world. We do this by integrating with CDN providers and caching customer content at the edge, where end users consume it. While this approach works great for public content, it lacks options for restricting access to cached assets. Sensitive quarterly earnings reports or Kim Kardashian wedding photos can only be seen by authorized people because CDNs generate long URLs full of random characters, making it impossible to guess your way to the right file.

As we support more and more customers who use Contentful to publish confidential information or distribute enterprise content, we knew we needed to go beyond "security by obscurity" to restrict private assets to authorized users. At the same time, we wanted to keep the scalability and performance offered by the CDN infrastructure.

What at first looked like an impossible dilemma eventually turned into an elegant implementation of an authorization mechanism that we call “embargoed assets.”

We announced embargoed assets today at Blueprints, the Contentful customer conference, and the feature is now available to our premium plan customers.

Using signed URLs to restrict access to assets

Embargoed assets makes it possible to restrict access to assets cached on the global CDN infrastructure. The new access mechanism relies on three crucial components:

  1. Replace regular asset URLs (\* with secure URLs (\*

  2. Define a security policy for accessing the secure URLs and let the customer determine the lifespan of access tokens

  3. Provide an endpoint for generating short-lived tokens used to sign the secure URLs

As a result, customers continue to benefit from the integration with global CDN infrastructure but access to their assets is now restricted by using an authentication mechanism that only returns assets to visitors signing their requests with valid signatures. This mechanism works for published assets accessible via the Content Delivery API (CDA), and draft assets accessible via the Content Preview API (CPA). Access tokens can be configured to expire in as little as 60 seconds or as long as 48 hours.

Customers are often forced to choose between performance and security. Luckily, this is not the case with the embargoed assets. A properly implemented request signing flow adds 20-40 milliseconds of latency, which is imperceptible to end users. Our implementation of embargoed assets enables you to integrate this feature with a wide range of authentication solutions, from out-of-the-box solutions provided by companies such as Okta, OneLogin and Microsoft, to in-house protocols. 

When to use embargoed assets 

By allowing customers to control who has access to the content authored through our content platform, customers can accomplish more tasks and implement brand new use cases on top of Contentful.

  • Intranets and extranets. Large organizations and manufacturers can build sites accessible only to internal employees or authorized partners. 

  • Paywalls and gated content. Media companies and service providers can now restrict content to users that have a subscription or are logged into their account.

  • Campaigns and product launches. Gaming studios and retailers can restrict access to campaign content (and avoid leaks) before the launch date.

Not all of these use cases have the same requirements, and we wanted to give our customers the flexibility of securing assets in a way that supports their specific use case. For example, if your organization focuses on preventing leaks while preparing for the launch, you can restrict access to draft assets while keeping published assets freely accessible. Alternatively, if you need to protect all of your assets, you can configure authentication logic to cover draft and published assets.

How to get started with embargoed assets

It's important to note that embargoed assets is not an out-of-the-box solution. Since the concept hinges on authorizing a specific subset of users to access your assets, you will have to integrate our URL-signing solution into your authorization workflow. Our infrastructure team has prepared a detailed tutorial covering this process step by step and answered most important questions in this FAQ section

To help you secure existing projects, we also designed the solution to work in several distinct modes, making it possible to thoroughly test asset URL-signing before deploying it to production. The preparation mode allows you to continue serving existing assets the usual way, while testing token generating and URL rewriting mechanisms.

Illustration of how embargoed assets work.

Embargoed assets are included on the Contentful Premium tier and can be activated on a per-space basis — you can choose to implement embargoed assets in a space powering your intranet, for example, while continuing to serve marketing assets, hosted in a marketing space, the regular way. To learn how to activate embargoed assets, head over to the tutorial. We can’t wait to see what it enables you to build! 

About the author

Don't miss the latest

Get updates in your inbox
Discover new insights from the Contentful developer community each month.
add-circle arrow-right remove style-two-pin-marker subtract-circle remove