Token Authentication for Cached Private Content and APIs

While working to make the Internet a better place, we also want to make it easier for our customers to have control of their content and APIs, and who has access to them. Using Cloudflare’s Token Authentication features, customers can implement access control via URL tokens or HTTP request headers without having to build complex back-end systems.

Cloudflare will check these tokens at the edge before any request is relayed to an origin or served from cache. If the token is not valid the request is blocked. Since Cloudflare handles all the token validation, the origin server does not need to have complex authentication logic. In addition, a malicious user who attempts to forge tokens will be blocked from ever reaching the origin.

CC BY 2.0 image by zeevveez

Leveraging our edge network of over 100 data centers, customers can use token authentication to perform access control checks on content and APIs, as well as allowing Cloudflare to cache private content and only serve it to users with a valid token tied specifically to that cached asset.

Performing access control on the edge has many benefits. Brute force attempts and other attacks on private assets don't ever reach an origin server, preventing origin CPU and bandwidth from being wasted on malicious requests.

By performing authentication on the edge it's possible to cache protected content, giving users faster access to private content because there’s no round trip to the origin for authentication. At the same time web application owners are assured that only valid, authenticated users have access to the cache content.

By validating that an API request is from a valid client, Cloudflare is able to eliminate forged requests coming from bots, attackers or non-authenticated users.

Many Internet applications are not built with access control features for assets, especially static assets like images, PDFs, zip files, apps, eBooks, and other downloadable content. Building an access control layer for these can be difficult and expensive.

We’ve worked with many customers to solve problems such as:

• A website provides downloadable static content to registered users; however, users tend to share/publish links to that content on social media platforms;

• A website provides downloadable static content, but crawlers and scrapers are constantly trying to find/leech/look for available links;

• An access control system is in place, but the customer would like to cache content at the edge for a better user experience and reduced bandwidth bills;

• A website would like to generate links with an expiry time;

• Access to specific resources hosted outside of the main application needs to be limited and restricted.

Today most applications are client software that connect to HTTP based APIs on the Internet. Protecting those APIs from malicious use is important as it’s possible to write client software, such as bots, that talks directly to the APIs bypassing the original application. This can lead to abuse and unwanted load on API servers.

Cloudflare’s token authentication can be used to validate that an API request is coming from a valid user, client or a mobile device on the edge. Cloudflare will filter out non-authenticated or forged requests and not pass them on to the origin API server.

Along with Cloudflare’s Rate Limiting and WAF, a mobile application with an Internet API can be protected at the edge, far from the origin API server.

Token Authentication leverages tokens to verify that a user has access to a specific resource. The token can be sent as a URL parameter or in an HTTP header.

The token is an HMAC generated from the following:

• A secret shared between Cloudflare and the web application or mobile app;

• The path to the resource or API;

• A Unix epoch timestamp;

• Potential optional additional parameters (e.g. IP address, cookie value, username);

The Cloudflare edge validates the token and allow access or not based on the result. The generated HMAC can also be configured to expire after a certain time (e.g. 10 minutes), or so that the expiry is controlled directly from the origin server. In the latter case, the generated URLs would simply include an absolute future Unix timestamp.

In the simplest implementations, tokens can be used to protect static private content. The code required in the back end application would be as follows (in PHP):

<?php
// Generate valid URL token
$secret = "thisisasharedsecret";
$time   = time();
$token  = $time . "-" . urlencode(base64_encode(hash_hmac("sha256", "/download/private.jpg$time", $secret, true)));
$url    = "http://www.domain.com/download/private.jpg?verify=" . $token;
?>

The code above, given a shared secret:

• Generates the current timestamp;

• Generates the token by concatenating the timestamp with the cryptographic hash separated by a dash -;

• The cryptographic hash is a SHA256 based HMAC generated from the relative path to the restricted asset concatenated with the timestamp. The key of the hash is the shared secret;

• The hash is base64 encoded, and subsequently, URL encoded;

• Finally, the URL to the private asset is generated by simply adding the resulting token to the query string. The token HTTP GET parameter name is customizable.

Once deployed, the authentication rules are available under the Web Application Firewall Custom User Rule Set Package. From here the rules can be configured on simulate, challenge or block or deactivated completely:

Once active and in the event a user were to try to access a restricted resource without a valid token, Cloudflare would present the default WAF Block page shown below:

The block page can be fully customized to match the customer branding as necessary.

In more advanced implementations tokens can also be used to perform API authentication:

• User requests access using a standard authentication method (e.g. username and password);

• The origin server validates access and provides a token to the client. The token is specific to the user;

• Client stores the token and includes it in any subsequent request to API endpoints;

• The Cloudflare edge validates the token on every request. If the token is missing or the token is not valid the request is denied;

• The token can be configured to expire after a certain time, forcing the client to re-authenticate with the origin server if necessary.

Using tokens for API endpoints provides many benefits:

• No session information is stored so it is much easier to scale applications;

• Tokens help to prevent CSFR attacks as the token is required on every request;

• Ability to provide selective access to third party applications;

• Lower load on API servers.

Allowing access to API servers only from Cloudflare IP ranges will ensure that users cannot bypass the token authentication.

Additionally, for API endpoints, Cloudflare can be configured to generate custom JSON responses compatible with the API specification.

Most mobile applications leverage HTTP based API endpoints to provide dynamic functionality to the end user. The shared secret used to generate the token can be embedded and encrypted within native mobile applications, improving protection of mobile app API endpoints and ensuring only requests from legitimate clients are allowed to access the underlying API.

Token Authentication is available for all paid plans if you are able to follow the default Cloudflare parameter format and expiry times are known beforehand. Our support team is able to provide implementation details on request.

If this is not possible, or if you are looking for additional logic and/or custom behavior, please contact us and enquire about our Enterprise Plan and reference Token Authentication.