Basic authentication

  Last updated August 02, 2018

Basic authentication is a simple way of protecting a website at the edge. Users enter a username and password combination to access pages protected by basic authentication. You can use basic authentication to restrict access to low-risk assets like testing and staging environments. Basic authentication can be implemented using custom VCL or VCL Snippets.

Follow the steps below to set up basic authentication for your service:

  1. Create an Edge Dictionary with a list of Base64-encoded usernames and passwords — you can include the usernames in plaintext for reference. You can use the API to create the Edge Dictionary and add dictionary items, or you can use custom VCL as shown below.

    table customer_keys {
      "Basic am9lOjQzNEAvMzkyIzgyPzk2": "joe",
      "Basic bWlrZTo4MjM0MzNzWjQ0SDZlNw==": "mike"

    The first value in the key pair is the username and password Base64-encoded. You can generate this in a terminal application as shown below. In this example, the username is joe, and the password is 434@/392#82?96.

    $ echo -ne joe:434@/392#82?96 | base64

    The result (am9lOjQzNEAvMzkyIzgyPzk2) is the second half of the first key pair (Basic am9lOjQzNEAvMzkyIzgyPzk2).

  2. In vcl_recv, create a table lookup to authorize customer credentials against those in the table.

    ##table lookup from customer_keys dictionary, plus part in vcl_error
    if(! table.lookup(customer_keys, req.http.Authorization) ) {
      error 401 "Restricted";
  3. In vcl_error, create your Custom 401 Restricted HTML page.

    ## Start 401 custom code
    if (obj.status == 401) {
      set obj.http.Content-Type = "text/html; charset=utf-8";
      set obj.http.WWW-Authenticate = "Basic realm=Secured";
      synthetic {"
     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
     <META HTTP-EQUIV='Content-Type' CONTENT='text/html;'>
     <BODY><H1>401 Unauthorized (varnish)</H1></BODY>
      return (deliver);
    } # End custom 401 code

Using basic authentication with GCS

To use basic authentication with Google Cloud Storage (GCS) as a origin server, add a request header to delete the http.Authorization header and prevent it from being sent to GCS. That header causes GCS to respond with a "Not Authorized" message instead of your request.

Security considerations

There are several security considerations you should take into account before using basic authentication:

Using access control lists

As an alternative to basic authentication, you can use access control lists (ACLs) to restrict access to your assets by whitelisting a set of IP addresses. To whitelist IP addresses with an ACL, add custom VCL to Fastly's boilerplate VCL.

# Who is allowed access ...
acl local {
    ""/24; /* and everyone on the local network */
    ! ""; /* except for the dial-in router */

See our ACL guides for more information.

Back to Top