Skip to main content

Bring Your Own Bucket - CloudFlare

Pangea now offers a Bring your own Bucket (BYOB) method of storage for your applications, enabling you to use external storage pools (or buckets) with the Secure Share service. While Share gives you the option of hosting and managing your application’s files and folders from within Pangea, this method allows for greater flexibility based on your needs.

This guide will provide detailed steps for adding a CloudFlare R2 bucket to store the files that you use with the Secure Share service.

CloudFlare setup​

By the end of this guide, you will configure your CloudFlare and Pangea console settings for storage integration, create a sample validation file to be placed in your CloudFlare bucket, and test the setup by accessing the file for Secure Share from within your Pangea console. This guide assumes you already have:

CloudFlare console steps​

  1. Go to your CloudFlare console , then navigate to the R2 section of the menu on the left. Your R2 Overview page should appear.

CloudFlare R2

CloudFlare account ID​

  1. Obtain your Account ID from the top right corner of UI beneath Account details. There is an icon to the right of the ID you can select to copy the ID to your clipboard for convenience; paste it somewhere easily accessible as you will need this ID later.

  2. This Overview page shows all R2 storage buckets you can select for use with Secure Share. Follow the steps below to create a bucket, or if you intend to use an existing bucket for BYOB, please verify that its settings match the setup steps below and be sure to create an API token for this process.

Steps to create a CloudFlare bucket​

  • Select the Create bucket button on the Overview page. The “Create a bucket” form appears.

CF Create Bucket

  • Input a Bucket name (copy and paste this as you will need it later).
  • Leave the default settings for Location (Automatic) and Default Storage Class (Standard).
  • Select the Create bucket button at the bottom. Once created, you will see it appear in the Overview page under “Buckets”.

R2 API tokens​

  1. Navigate back to the R2 overview page by clicking R2 on the left-hand menu. From there, click the Manage R2 API Tokens link on the right under Account details to navigate to your account’s API Tokens page.

CF CORS

  1. Click the Create API token button. The Create API Token form appears.

CF Create Token

  • Token name
    • Input a name to identify the token.
  • Permissions
    • Grant Object Read & Write privileges.
  • Specify bucket(s)
    • Select Apply to specific buckets only and select your bucket from the field beneath it.
    • The field will show a dropdown list of selectable buckets when clicked, or you can search for it by typing its name.
  • TTL
    • Indicate the length of time for the token to remain active (Forever is recommend).
  • Client IP Address Filtering
  1. Click the Create API Token button; you will be taken to the next page, indicating your token was successfully created.

CloudFlare access key and access secret​

note

The token information isn’t viewable again after navigating away from this page, so be sure to copy the Access Key ID and Secret Access Key from the “Use the following credentials for S3 clients:” section. You will need these when configuring the bucket in your Pangea console.

  1. After copying and saving the Access Key ID and Secret Access Key for the Pangea bucket setup, click Finish. Verify that your new token appears in the list on the API Tokens page.

CF Token List

You have completed the CloudFlare setup; be sure to leave your CloudFlare console open in a tab as you move through the steps below, as there are additional settings to adjust. Before moving onto the Pangea steps, ensure you have the following copied down:

  • Bucket name
  • CloudFlare Account ID
  • Access Key ID
  • Secret Access Key

Pangea User Console steps​

Once you have completed the steps to configure the bucket for this process on the CloudFlare side, you will be able to designate the bucket as one of your storage options within your Pangea User Console. The steps below will walk you through this process.

  1. Log into your Pangea User Console .

  2. Navigate to Secure Share in the menu on the left, then click the General tab under Settings.

  3. Select the first option in the menu - Storage Pools. The modal that appears to the right will show available storage options to use with Secure Share, listing any you have already set up (e.g., the Pangea managed bucket below).

PUC Storage Pools

  1. Select the + Bucket button on the right; a pop-up will appear.

Select CF

  1. Select CloudFlare, then click Next.
  2. The modal will appear as shown below, where you will need to input the following:
  • Display name for the bucket
    • Your CloudFlare bucket name exactly as it appears in the list of R2 buckets
  • A bucket Prefix (we recommend to leave “pangea” for easy identification)
    • The folder Secure Share will utilize for everything it needs - Share will not reach outside of the designated folder for any purpose (thus, the folder contents should not be altered)
  • CloudFlare Account ID
  • (Optional) Jurisdiction

CF Step 1

  1. Once the fields are populated with your information, click Next to continue to the CORS policy setup.

CORS policy​

note

CORS: Things to Know

  • Cross-origin resource sharing (CORS) defines if and how client web applications from one domain have access to interact with resources in a different domain.
  • A CORS policy, like the one we create for this process, specifies which sites (origins) can do which operations (i.e., GET, PUT, POST, HEAD) to the bucket and its contents.
  • Secure Share uses the pangea.cloud domain, so to prevent errors when using presigned URLs for web app uploads, your bucket's CORS policy needs the proper Access-Control-Allow-* headers to define accessible Origins, Methods, and Headers for its contents.
  • The origins that will be able to access your bucket are driven by your policy’s "AllowedOrigins". A restrictive CORS policy should only allow:
    • All Pangea console and hosted share page locations
    • All Pangea Secure Share links
    • Any of your own application origins
    • Any sites your application may accept uploads from via presigned URLs (e.g. using Pangea’s Share file explorer control where customer-provided callbacks use presigned URLs for handling upload requests)
  • For an unrestricted CORS policy, or if you do not yet have a specific set of origins, you can use "AllowedOrigins" : ["*"] in your CORS policy.
  1. Navigate to the R2 Overview page of your CloudFlare console if not already there, then select your bucket from the list. Click the Settings tab.

CF R2 Settings

  • Scroll to the CORS Policy section, and click Add CORS policy (or Edit CORS policy if existing).

CloudFlare add CORS policy

  • Add the following to your bucket's CORS policy, then click Save:
[
    {
        "AllowedHeaders":[
            "content-length",
            "content-type"
        ],
        "AllowedMethods":[
            "POST",
            "GET",
            "PUT"
        ],
        "AllowedOrigins":[
            "https://console.pangea.cloud",
            "https://secure.share.aws.us.pangea.cloud"
        ],
        "ExposeHeaders":[

        ],
        "MaxAgeSeconds":0
    }
]
  • After saving the policy, you will be returned to the R2 page. The CORS policy section will now display your allowed origins, methods, and headers, as well as an Edit CORS policy button if any changes are needed.
  1. Once you have completed the form, click Next. A new set of information will appear below, walking you through the steps to set up the API for use with the service. This includes entering the Access Key ID and Access Secret you copied from your CloudFlare console.

CF Secrets

Once completed, click Next.

Validation info​

  1. Below this in the same modal, you will see a section titled “Validation info”, with a form to create a file in your bucket and validate the integration between your CloudFlare and Pangea consoles.

Your Validation File Name and Contents are available for manual copy-and-paste, however, the easiest and safest method for validating the file is running the customized CLI command we provide.

CloudFlare validation CLI steps (AWS)​

You can use the AWS CLI to run the command locally if already installed. If not, use the CloudShell CLI in your AWS console to create and place the validation file into your bucket with the following steps:

AWS CloudShell

  • Click the icon, then wait for the terminal to initialize.
  • Paste the code you copied from your PUC and hit enter. The command pasted from your clipboard should look similar to this:
echo -n “<YOUR VALIDATION CONTENTS>” | aws --endpoint-url https://<YOUR ACCOUNT ID>.r2.cloudflarestorage.com --region auto s3 cp - s3://<YOUR EXACT BUCKET NAME>/pangea/<YOUR VALIDATION FILE NAME>
  • Navigate back to your R2 bucket in CloudFlare and go to the Objects tab. You should see the newly created "pangea" folder with your validation file nested within it.

File successfully placed into CloudFlare bucket

CloudFlare validation manual steps​

  • Create the validation file using the exact validation file name and contents copied from your PUC Storage Pools UI. There are copy icons you can click for convenience.
  • Save the file locally under a prefix folder called pangea; this is important as a missing prefix may cause errors at the validation step.
  • Navigate to the R2 Overview page of your CloudFlare console, and select your bucket to open it.
  • Open your file explorer or finder to the pangea folder location you just created.
  • Drag-and-drop the pangea folder (which should have the validation file inside) into the CloudFlare R2 UI.
  • The folder should be in your bucket and the validation file should appear inside with its prefix as pangea/, as shown in the screenshot above.
  1. After using one of the above methods to place the verification file into your Cloudflare bucket, return to the PUC - Storage Pools setup screen and click the Verify button.
  • If successfully verified, you will see “Verified (timestamp from when you last verified)” to the left of the Close and Verify buttons. Select Close and return to the Storage pools screen, where you will see the bucket’s verification status along with any other storage pools you have.

If you encounter any errors and the bucket cannot be validated, please verify all of the steps in the UI were properly completed. Validation errors can occur due to any of numerous reasons, including:

  • Validation file doesn't exist or file name does not match exactly between PUC and CloudFlare
  • Validation file contents are incorrect
  • Access Key ID is incorrect
  • Secret Access Key is incorrect
  • Bucket name mismatch between PUC and CloudFlare
  • Bucket access settings or policy are not configured properly

Using the bucket​

You now have an external bucket integrated with Pangea as an external storage pool - congratulations! Use the screenshot and descriptions below to explore what the buttons in your PUC are used for.

Pangea User Console Storage Pool Icons

Enable your bucket (1)​

  • Storage pool buckets can be enabled or disabled.
  • Only enabled buckets are usable in your PUC or APIs.
  • To enable a bucket, select the toggle on the far right of the other icons.
    • Buckets must be verified before they can be enabled.
    • Enabled buckets will show a green toggle (1b).

Edit bucket details (2)​

  • Select the three-dot icon on the very right of the bucket row, then click Edit (pencil icon).
  • This can be used to make changes to the bucket name, policy, etc.
  • Be sure to re-verify and save changes if any changes are made.

Copy the bucket ID (3)​

  • Select the three-dot icon on the very right of the bucket's row, then select Copy ID (copy icon) from the dropdown.
  • Clipboard icon next to ID

Remove a bucket (4)​

  • Select the three-dot icon on the very right of the bucket row, then select Remove (trash icon).
  • A pop-up will display, prompting you to confirm bucket deletion by typing its exact (case-sensitive) name, then clicking Remove. The bucket should no longer appear in your list of “Storage Pools”.
  • Enabled buckets cannot be removed; you must first disable a bucket before the Remove menu item becomes enabled.
  • The Pangea bucket cannot be removed.
  • When a bucket is removed, all of its Secure Share content is also removed.

Set your default bucket (5)​

  • The Storage Pools feature allows you to set a default bucket for Secure Share, which will be used for your Share operations.
  • To select a default storage pool for Secure Share, click the Make default button in the Default column for any verified bucket; the button is grayed out (5b) until the bucket has been verified.
  • Secure Share APIs accept an optional bucket ID parameter; if the bucket ID parameter is not specified, the default bucket is used.

Advanced settings​

IP restrictions​

note

Important considerations before restricting IPs

One of the key values Secure Share provides is the ability to share files with anyone, anywhere in the world. Therefore, to utilize the service to its full potential for your application, we generally recommend that you do NOT use this IP filtering feature unless you have considered all of the following:

  • You are familiar with the implications of IP restriction
  • You have an organizational requirement to have all potential IP addresses (including end users to be shared with) previously defined or constrained to a corporate network/VPN
  • There is no potential for new internal or external users to utilize your application with an IP address that is unknown or outside of the defined list in the policy

Pangea IPs (CSP/Region IP):

  • AWS/US-WEST 54.176.53.52/32
  • AWS/US-EAST 3.223.13.213
  • AWS/EU 3.66.126.22/32
  • GCP/US 34.83.183.134/32
  • GCP/EU 35.241.162.165/32

To add IP restrictions in CloudFlare, they must be defined in the API token you created for the process. Follow the steps below to achieve this:

  • Navigate to your CloudFlare console.
  • Select R2 in the left-hand menu.
  • Select Manage R2 API Tokens in the top right.
  • Locate and select the three-dot icon on the right end of whichever token you created for use with BYOB.
  • Select Edit in the menu that appears.
  • At the bottom of the Edit API Token screen is a Client IP Address Filtering section, where you can use the Include and Exclude fields to indicate IP addresses to either be included or excluded from accessing your bucket. We have provided a list of Pangea addresses in the note above, which you will need to include based on your region if using restrictions.
  • When you are finished editing the token, select the Update API Token button.