Getting started
Basics
Domains & Origins
Performance

Configuration
Basics
Conditions
Dictionaries
Domains & Origins
Request settings
Cache settings
Headers
Responses
Performance
Purging
Custom VCL
Image optimization
Video

Security
Access Control Lists
Monitoring and testing
Securing communications
Security measures
TLS
Web Application Firewall

Integrations
Logging endpoints
Non-Fastly services

Diagnostics
Streaming logs
Debugging techniques
Common errors

Account info
Account management
Billing
User access and control

Reference

    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 also use the API to create the Edge Dictionary and add dictionary items, and you can use custom VCL as shown below.

      1
      2
      3
      4
      
      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.

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

      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.

      1
      2
      3
      4
      5
      
      ##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.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      
      ## 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"
       "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
      
       <HTML>
       <HEAD>
       <TITLE>Error</TITLE>
       <META HTTP-EQUIV='Content-Type' CONTENT='text/html;'>
       </HEAD>
       <BODY><H1>401 Unauthorized (varnish)</H1></BODY>
       </HTML>
       "};
        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 allowlisting a set of IP addresses. To allowlist IP addresses with an ACL, add custom VCL to Fastly's boilerplate VCL.

    1
    2
    3
    4
    5
    6
    
    # Who is allowed access ...
    acl local {
        "localhost";
        "192.168.1.0"/24; /* and everyone on the local network */
        ! "192.168.1.23"; /* except for the dial-in router */
    }
    

    See our ACL guides for more information.

    Back to Top