Recently viewed X

Enabling URL token validation

Last updated April 26, 2018

Token validation allows you to create URLs that expire. Tokens are generated within your web application and appended to URLs in a query string. Requests are authenticated at Fastly's edge instead of your origin server. When Fastly receives a request for the URL, the token is validated before serving the content. After a configurable period of time, the token expires.

Adding custom VCL

/* make sure there is a token */if(req.url!~".+\?.*token=(\d{10,11})_([^&]+)"){error403;}/* extract token expiration and signature */setreq.http.X-Exp=re.group.1;setreq.http.X-Sig=re.group.2;/* validate signature */if(req.http.X-Sig==regsub(digest.hmac_sha1(digest.base64_decode("YOUR%SECRET%KEY%IN%BASE64%HERE"),req.url.pathreq.http.X-Exp),"^0x","")){/* check that expiration time has not elapsed */if(time.is_after(now,std.integer2time(std.atoi(req.http.X-Exp)))){error410;}}else{error403;}/* cleanup variables */unsetreq.http.X-Sig;unsetreq.http.X-Exp;

WARNING: You must replace YOUR%SECRET%KEY%IN%BASE64%HERE in the example VCL with your own randomly generated secret key. The example key will intentionally cause an error if you use it. Anyone who learns this key can bypass your token validation, so it's critical that you keep this key secret.

The key found in digest.hmac_sha1 can be any string. The one in this example was generated with the command openssl rand -base64 32.

A token is expected in the ?token= GET parameter. Tokens take the format [expiration]_[signature] and look like this:

What the custom VCL does

The custom VCL code checks for two things:

Is the current time greater than the expiration time specified in the token?

Does our signature match the signature of the token?

If the signature is invalid, Varnish returns a 403 response. If the signature is valid but the expiration time has elapsed, Varnish returns a 410 response. The different response codes are helpful for debugging.

Configuring your application

You'll need to write custom code in your application to generate tokens and authenticate with Varnish. We provide examples in our token functions repository on GitHub. Review the examples in the repository to learn how to generate custom tokens within your application.

Testing

To test your configuration, append a token generated by your application to a URL in a query string. For example:

If the token is valid, you will receive a normal response. If it is invalid, you will receive a 403 response.

Troubleshooting NUL bytes

You should verify that your secret key is devoid of NUL bytes. If the base64-decoded string contains a NUL byte (0x00), then that byte and any bytes following it will not be included in the response. See base64 decoding for more information.

Was this guide helpful?

Yes
No

Tell us what worked and what we could do better.

Do not use this form to send sensitive information. If you need assistance, contact support@fastly.com.