Zephr Classic User Guide

Trusted Referrers

53 views 0

Zephr provides the ability for 3rd party sites – Trusted Referrers – to create links to zephr-proxied pages that bypass any entitlement checks (specified in request or feature rules) and grant full access to that page for that session.

A trusted link looks like this:


This is a regular link with the addition of a btr=<some token> query parameter- this parameter (or btr token) must be generated for each link, server-side, by the referrer. Each such link will work only when clicked from a page on that referrer’s domain, this works because Zephr uses the Referer HTTP header to validate the btr token: if the link is copy-pasted, sent via email, or published on another site, the Referer HTTP header will be either unset or something different, and so Zephr will not be able to validate the btr token.

Creating a Trusted Referrer within Zephr

To begin setting up your Trusted Referrers, navigate to Entitlement Manager > Bypasses > Trusted Referrers within the Zephr Admin Console.

Under Configuration > Content Identifier Source choose between Path and Content Id Parameter and click Save.

Following this, you will need to create a secret for the Trusted Referrer you are setting up. For a 3rd party to create a trusted link into a Zephr-proxied site, they will need to be given this secret. Under the Trusted Referrers heading, click Add Trusted Referrer. Set the Referrer Domain for the 3rd party you with to use as a Trusted Referrer. This should be the domain through which traffic will be referred to Zephr. Take note of the Secret, then click Create Trusted Referrer.

Instructing a Trusted Referrer how to create Trusted Links

The Trusted Referrer will need to use server-side code to generate btr tokens in order to create trusted links to your site.

The btr token for a particular link is obtained by using MD5 to hash the path part of the link together with the Trusted Referrer’s Secret (set up above), separated by a pipe ‘|’ symbol. Fortunately this is trivial in most server-side languages.

For example, for the website trusted-forum.biz – which has been given Secret 89b4c0e4-e95f-4981-b872-b85ea5aec0ff -the following code snippets will all generate a valid link to http://your-website.com/stories/article228.html


public String createBTRToken(String path, String secret) {
    try {
        return DatatypeConverter.printHexBinary(MessageDigest.getInstance("MD5").digest((path + "|" + secret).getBytes(StandardCharsets.UTF_8);
    } catch (Exception e) {
        return "";
String trustedLink = "https://www.your-website.com/stories/article228.html?btr=" + createBTRToken("/stories/article228.html", "89b4c0e4-e95f-4981-b872-b85ea5aec0ff");


<?php echo 'https://www.your-website.com/stories/article228.html?btr=' . md5('/stories/article228.html|89b4c0e4-e95f-4981-b872-b85ea5aec0ff') ?>

Javascript (node.js server-side)

// assumes md5 was installed with npm install md5

var md5 = require('md5');

var trustedLink = 'https://www.your-website.com?btr=' + md5('/stories/article228.html' + | + '89b4c0e4-e95f-4981-b872-b85ea5aec0ff');

NOTE: It is important that the Trusted Referrer uses client-side javascript to generate Trusted Links – otherwise it will be possible for tech-savvy users to create their own trusted links and spoof the Referer header to gain free access to any content.