Zephr User Guide


74 views 0

Bypasses in Zephr allow you to offer extra access to users without the need for them to have the product grant used within your decision or rule.

It does this by allowing your user to bypass the product check being used within your rule. In this instance, every product check made for the user will return true, regardless of that user’s product grants. For example, if you have a rule requiring a user to have an Article product in order to view content, users meeting the criteria of one of the bypasses will be able to view content that requires the Article product for access, regardless of not having the product granted.

Available bypasses within Zephr include Trusted Referrers, and IP Whitelisting. We cover both below.

Configuring Bypasses

To begin using Bypasses you will first need to set the Current Identifier Source.

To set this, navigate to the B2B module, select Bypasses, and scroll down to the Configuration section.

Select between Path, and Content ID Parameter.

Setting Current Identifier Source for Zephr Bypasses

Once selected, continue setting up your Bypasses as below.

Trusted Referrers

Trusted Referrers allows 3rd party sites to create links to Zephr-proxied pages that bypass product checks specified in your 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=<token> query parameter – this parameter (or btr token) must be generated for each link, server-side, by the referrer. Each 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 different, 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 the B2B module in your Zephr Admin Console, select Bypasses, then scroll to Truster Referrers.

Click Add A Trusted Referrer. Set the Referrer Domain for the 3rd party you wish to use as a Trusted Referrer. This should be the domain through which traffic will be referred to Zephr. Take note of the Secret, as 3rd parties will need to use this secret to create a trusted link into a Zephr-proxied site.

Trusted Referrer Set Up within Zephr Bypasses

Once complete, click Add.

You will see your new Trusted Referrer in the list of Trusted Referrers on the Bypasses page. Once complete, click Save.

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 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.

IP Whitelist

The Zephr  IP Whitelist feature allows you to set a series of IP addresses to bypass the product grant checks that take place within your Rules.

This means users coming to your site from the IP addresses you have listed will not require any of the product grants checked for within your Zephr Rules. This is helpful for granting access to users on scale – for example, providing free access to your content for guests using your company wifi, or staff within your company offices.

The IP Whitelist can be set up by navigating to the B2B module in your Zephr Admin Console, selecting Bypasses, then scrolling to IP Whitelist.

Simply add the IP Addresses to the IP Whitelist field as a newline delimited list (a new line for each IP) and click Save.

Zephr accepts IPv4 and IPv6 addresses or CIDR blocks.