Backblaze B2 Cloud Storage

      Last updated September 15, 2020

    Backblaze B2 Cloud Storage (B2) public and private buckets can be used as origins with Fastly.

    Before you begin

    Before you begin the setup and configuration steps required to use B2 as an origin, keep in mind the following:

    Using Backblaze B2 as an origin

    To use B2 as an origin, follow the steps below.

    Creating a new bucket

    Data in B2 is stored in buckets. Follow these steps to create a new bucket via the B2 web interface.

    1. Log in to your Backblaze account. Your Backblaze account settings page appears.
    2. Click the Buckets link. The B2 Cloud Storage Buckets page appears.
    3. Click the Create a Bucket link. The Create a Bucket window appears.

      Backblaze B2 New Bucket window

    4. In the Bucket Unique Name field, enter a unique bucket name. Each bucket name must be at least 6 alphanumeric characters and can only use hyphens (-) as separators, not spaces.
    5. Click the Create a Bucket button. The new bucket appears in the list of buckets on the B2 Cloud Storage Buckets page.
    6. Upload a file to the new bucket you just created.

    Uploading files to a new bucket

    Once you've created a new bucket in which to store your data, follow these steps to upload files to it via the B2 web interface.

    1. Click the Buckets link in the B2 web interface. The B2 Cloud Storage Buckets page appears.
    2. Find the bucket details for the bucket you just created.
    3. Click the Upload/Download button. The Browse Files page appears.
    4. Click the Upload button. The upload window appears.
    5. Either drag and drop any file into the window or click to use the file selection tools to find a file to be uploaded. The name and type of file at this stage doesn't matter. Any file will work. Once uploaded, the name of the file appears in the list of files for the bucket.
    6. Find your bucket's assigned hostname so you can set up a Fastly service that interacts with B2.

    Finding your bucket's assigned hostname

    To set up a Fastly service that interacts with your B2, you will need to know the hostname Backblaze assigned to the bucket you created and uploaded files to.

    Find your hostname in one of the following ways:

    Creating a Backblaze application key for private buckets

    Your Backblaze master application key controls access to all buckets and files on your Backblaze account. If you plan to use a Backblaze B2 private bucket with Fastly, you should create an application key specific to the bucket.

    Via the web interface

    To create an application key via the B2 web interface:

    1. Click the App Keys link. The Application Keys page appears.
    2. Click the Add a New Application Key button. The Add Application Key window appears.

      Backblaze B2 New Application Key

    3. Fill out the fields of the Add Application Key controls as follows:
      • In the Name of Key field, enter the name of your private bucket key. Key names are alphanumeric and can only use hyphens (-) as separators, not spaces.
      • From the Allow access to Bucket(s) menu, select the name of your private bucket.
      • From the Type of Access controls, select Read Only.
      • Leave the remaining optional controls and fields blank.
    4. Click the Create New Key button. A success message and your new application key appear.

      Backblaze B2 Created Application Key

    5. Immediately note the keyID and the applicationKey from the success message. You'll use this information when you implement header-based authentication with private objects.

    Via the command line

    To create an application key from the command line, run the create-key command as follows:

    1
    
    b2 create-key --bucket <bucketName> <keyName> shareFiles,listBuckets
    

    where <bucketName> <keyName> represents the name of the bucket and key you created. For example:

    1
    
    b2 create-key --bucket this-is-an-example-bucket Fastly-Private-Bucket-Key shareFiles,listBuckets
    

    The keyID and the applicationKey are the two values returned.

    Creating a new service

    To create a new Fastly service, you must first create a new domain and then create a new host and edit it to accept traffic for B2. Instructions to do this appear in our guide to creating a new service. While completing these instructions, keep the following in mind:

    1. When you create the new host, enter the B2 bucket's hostname in the Hosts field on the Origins page.
    2. When you edit the host details on the Edit this host page, confirm the Transport Layer Security (TLS) area information for your host. Specifically, make sure you:
      • secure the connection between Fastly and your origin.
      • enter your bucket's hostname in the Certificate hostname field.
      • select the checkbox to match the SNI hostname to the Certificate hostname (it appears under the SNI hostname field).
    3. Also when you edit the host, optionally enable shielding by choosing the appropriate shielding location from the Shielding menu. When using B2 Cloud Storage, this means you must choose a shielding location closest to the most appropriate Backblaze datacenter. For the datacenters closest to:
      • Sacramento, California (in the US West region), choose San Jose (SJC) from the Shielding menu.
      • Phoenix, Arizona (in the US West region), choose Palo Alto (PAO) from the Shielding menu.
      • Amsterdam, Netherlands (in the EU central region), choose Amsterdam (AMS) from the Shielding menu.
    4. Decide whether or not you should specify an override host in the Advanced options area:
      • If you're using the S3 Compatible API, skip this step and don't specify an override host.
      • If you're not using the S3 Compatible API, in the Override host field in the Advanced options, enter an appropriate address for your host (e.g., s3-uswest-000.backblazeb2.com or f000.backblazeb2.com).

    Using the S3 Compatible API

    Using the S3 Compatible API with public objects

    To use the S3 Compatible API with public objects, you will need to make sure the Host header contains the name of your B2 Bucket. There are two ways to do this, both of which require you to get your region name which will be the 2nd part of your S3 Endpoint. So if your S3 Endpoint is s3.us-west-000.backblazeb2.com, this means your region will be us-west-000.

    1. In the Origin you created set the Override host field in the Advanced options to <bucket>.s3.<region>.backblazeb2.com (e.g., testing.s3.uswest-000.backblazeb2.com)
    2. Create a VCL Snippet. When you create the snippet, select within subroutine to specify its placement and choose miss as the subroutine type. Then, populate the VCL field with the following code. Be sure to change specific values as noted to ones relevant to your own B2 bucket - in this case var.b2Bucket would be "testing" and var.b2Region would be "uswest-000".

      1
      2
      3
      4
      5
      6
      7
      8
      
       declare local var.b2Bucket STRING;
       declare local var.b2Region STRING;
       set var.b2Bucket = "YOUR_B2_BUCKET_NAME";   # Change this value to your own data
       set var.b2Region = "YOUR_B2_BUCKET_REGION"; # Change this value to your own data
      
       if (req.method == "GET" && !req.backend.is_shield) {
         set bereq.http.host = var.b2Bucket ".s3." var.b2Region ".backblazeb2.com";
       }
      

    Using the S3 Compatible API with private objects

    To use a Backblaze B2 private bucket with Fastly, you must implement version 4 of Amazon’s header-based authentication. You can do this using custom VCL.

    Start by obtaining the following information from Backblaze (see Creating a Backblaze application key for private buckets):

    Item Description
    Bucket name The name of your Backblaze B2 bucket. When you download items from your bucket, this is the string listed in the URL path or hostname of each object.
    Region The Backblaze region code of the location where your bucket resides (e.g., uswest-000).
    Access key The Backblaze keyID for the App Key that has at least read permission on the bucket.
    Secret key The Backblaze applicationKey paired with the access key above.

    Once you have this information, you can configure your Fastly service to authenticate against your B2 bucket using header authentication by calculating the appropriate header value in VCL.

    Start by creating a regular VCL snippet. Give it a meaningful name, such as AWS protected origin. When you create the snippet, select within subroutine to specify its placement and choose miss as the subroutine type. Then, populate the VCL field with the following code (be sure to change specific values as noted to ones relevant to your own AWS bucket):

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    
    declare local var.b2AccessKey STRING;
    declare local var.b2SecretKey STRING;
    declare local var.b2Bucket STRING;
    declare local var.b2Region STRING;
    declare local var.canonicalHeaders STRING;
    declare local var.signedHeaders STRING;
    declare local var.canonicalRequest STRING;
    declare local var.canonicalQuery STRING;
    declare local var.stringToSign STRING;
    declare local var.dateStamp STRING;
    declare local var.signature STRING;
    declare local var.scope STRING;
    
    set var.b2AccessKey = "YOUR_B2_ACCESS_KEY";   # Change this value to your own data
    set var.b2SecretKey = "YOUR_B2_SECRET_KEY";   # Change this value to your own data
    set var.b2Bucket = "YOUR_B2_BUCKET_NAME";     # Change this value to your own data
    set var.b2Region = "YOUR_B2_BUCKET_REGION";   # Change this value to your own data
    
    if (req.method == "GET" && !req.backend.is_shield) {
    
      set bereq.http.x-amz-content-sha256 = digest.hash_sha256("");
      set bereq.http.x-amz-date = strftime({"%Y%m%dT%H%M%SZ"}, now);
      set bereq.http.host = var.b2Bucket ".s3." var.b2Region ".backblazeb2.com";
      set bereq.url = querystring.remove(bereq.url);
      set bereq.url = regsuball(urlencode(urldecode(bereq.url.path)), {"%2F"}, "/");
      set var.dateStamp = strftime({"%Y%m%d"}, now);
      set var.canonicalHeaders = ""
        "host:" bereq.http.host LF
        "x-amz-content-sha256:" bereq.http.x-amz-content-sha256 LF
        "x-amz-date:" bereq.http.x-amz-date LF
      ;
      set var.canonicalQuery = "";
      set var.signedHeaders = "host;x-amz-content-sha256;x-amz-date";
      set var.canonicalRequest = ""
        "GET" LF
        bereq.url.path LF
        var.canonicalQuery LF
        var.canonicalHeaders LF
        var.signedHeaders LF
        digest.hash_sha256("")
      ;
    
      set var.scope = var.dateStamp "/" var.awsRegion "/s3/aws4_request";
    
      set var.stringToSign = ""
        "AWS4-HMAC-SHA256" LF
        bereq.http.x-amz-date LF
        var.scope LF
        regsub(digest.hash_sha256(var.canonicalRequest),"^0x", "")
      ;
    
      set var.signature = digest.awsv4_hmac(
        var.awsSecretKey,
        var.dateStamp,
        var.awsRegion,
        "s3",
        var.stringToSign
      );
    
      set bereq.http.Authorization = "AWS4-HMAC-SHA256 "
        "Credential=" var.awsAccessKey "/" var.scope ", "
        "SignedHeaders=" var.signedHeaders ", "
        "Signature=" + regsub(var.signature,"^0x", "")
      ;
      unset bereq.http.Accept;
      unset bereq.http.Accept-Language;
      unset bereq.http.User-Agent;
      unset bereq.http.Fastly-Client-IP;
    }
    

    Using the B2 API

    Public Objects

    You'll need to make sure the URL contains your bucket name. There are two ways to do this.

    Private Objects

    1. To use a Backblaze B2 private bucket with Fastly, you must obtain an Authorization Token. This must be obtained via the command line.

    2. You'll now need to authorize the command line tool with the application key you obtained.
      1
      
      b2 authorize-account <keyID> <applicationKey>
      
    3. You will now need to get an authorization token for the private bucket.
      1
      
      b2 get-download-auth <bucket>
      

      e.g

      1
      
      b2 get-download-auth testing
      

      This will create a token that is valid for 86400 seconds (i.e 1 day), the default. You can optionally change the expiration time from anywhere between 1s and 604,800 seconds (i.e 1 week).

      1
      
      b2 get-download-auth --duration 604800 testing
      

      Take note of the generated token.

    Passing a generated token to Backblaze

    There are two ways you can pass the generated token to Backblaze. The first is using an Authorization header. This is the recommended method.

    1. Click the Create header button again to create another new header. The Create a header page appears.

      creating an authorization header via the header page

    2. Fill out the Create a header fields as follows:
      • In the Name field, enter Authorization.
      • From the Type menu, select Request, and from the Action menu, select Set.
      • In the Destination field, enter http.Authorization.
      • From the Ignore if set menu, select No.
      • In the Priority field, enter 20.
    3. In the Source field, enter the Authorization Token generated in the command line tool, surrounded by quotes. For example, if the token generated was DEC0DEC0C0A, then the Source field would be "DEC0DEC0C0A"
    4. Click the Create button. A new Authorization header appears on the Content page.
    5. Click the Activate button to deploy your configuration changes.

    Alternatively, the second way is to pass an Authorization query parameter.

    1. Click the Create header button again to create another new header. The Create a header page appears.

      creating an authorization header via the header page

    2. Fill out the Create a header fields as follows:
      • In the Name field, enter Authorization.
      • From the Type menu, select Request, and from the Action menu, select Set.
      • In the Destination field, enter url.
      • From the Ignore if set menu, select No.
      • In the Priority field, enter 20.
    3. In the Source field, enter the header authorization information using the following format:

      1
      
      querystring.set(req.url, "Authorization", "<Authorization Token>")
      

      Using the previous example, that would be:

      1
      
      querystring.set(req.url, "Authorization", "DEC0DEC0C0A")
      
    4. Click the Create button. A new Authorization header appears on the Content page.
    5. Click the Activate button to deploy your configuration changes.
    This article describes an integration with a service provided by a third party. Please see our note on integrations.
    Back to Top