Introduction

This guide provides an overview and examples of how you can protect against DNS bypass attempts. Implementing the x-ch-no-bypass header is not required for any of CrowdHandler's integrations, however, doing so will provide an additional layer of user verification and is therefore recommended.

Which integration types is this article relevant for?

Akamai

Cloudflare

Cloudfront

DNS

What do we mean by DNS bypass attempts?

Integrating CrowdHandler on your CDN of choice makes bypassing CrowdHandler checks difficult, however savvy users that are able to track down network information associated with your web infrastructure may be able to route their traffic around your CDN endpoint, bypassing all of the protection that it offers, including your CrowdHandler integration.

How it works

When configured, your CrowdHandler integration will attach a header named "x-ch-no-bypass" to all requests forwarded to your application. The value of the header will be your secure no-bypass token. With a minimal amount of code required, you can configure your web application to check that requests are sent with this header and token, ensuring that only user's that have been checked by CrowdHandler are allowed onto your application.

Where can I find my token?

If you are using the DNS integration, the token can be found in the CrowdHandler administration console on the domain settings screen of the web application you will be protecting. The token value will be stored in the No-Bypass Token field. 

For other CDN integrations (akamai, cloudflare and cloudfront), the respective installation guides will instruct you on how to set up your no-bypass token. 

Integration Examples

Validating for the presence and value of the x-ch-no-bypass request header can easily be done in most programming languages and web servers. Below are some implementation examples for various, popular languages and web servers. 

Apache

RewriteEngine On

# block if request header x-ch-no-bypass value isn't matched
RewriteCond %{HTTP:x-ch-no-bypass} !^(YOURTOKENVALUE)$
RewriteRule ^ - [F]

Nginx

location / {

    if ($http_x_ch_no_bypass != "YOURTOKENVALUE") {
        return 403;
    }

    proxy_pass http://app:3000/;
}

Express.js

app.get('/', (req, res) => {
    if (req.header('x-ch-no-bypass') !== "YOURTOKENVALUE") {
        res.status(403).send("Sorry! You can't see that.")
    }
    res.sendFile(__dirname + "/views/index.html");
})

PHP

function getRequestHeaders() {
    $headers = array();
    foreach($_SERVER as $key => $value) {
        if (substr($key, 0, 5) <> 'HTTP_') {
            continue;
        }

        $header = str_replace(' ', '-', ucwords(str_replace('_', ' ', strtolower(substr($key, 5)))));
        $headers[$header] = $value;
    }
    return $headers;
}

$headers = getRequestHeaders();

if($headers['X-Ch-No-Bypass'] != "YOURTOKENVALUE") {
    header("HTTP/1.1 403 Forbidden" );
    exit;
}

Python (Django)

from django.http import HttpResponseForbidden
from django.http import HttpResponse

def index(request):
    chBypassKey = request.META.get('HTTP_X_CH_NO_BYPASS')
    if (chBypassKey) != "YOURTOKENVALUE" :
        return HttpResponseForbidden()
    else :
        return HttpResponse("Hello world!")