Configuring a private S3 bucket
Save your screenshots, PDFs and other renders to a private S3 bucket from Urlbox
This guide will walkthough the process of configuring a private S3 bucket which means Urlbox can only store your renders but cannot access them.
The process of configuring a private S3 bucket and credentials can be quite complicated, so we've put together this guide to help you through the process.
It consists of the following steps:
- Creating a new private S3 bucket with the correct settings
- Creating a new IAM user
- Create a new IAM user group
- Adding the IAM user to the group
- Creating a policy on the group to allow upload access to the bucket
- Generating an access key and secret key for the IAM user
- Adding the credentials to your project in Urlbox
Configuring S3
Over in your AWS account, you should create an S3 bucket and an IAM user that has the minimal settings allowed for Urlbox to save to your bucket only. In private bucket mode, Urlbox will not be able to serve the renders from your bucket.
Creating an S3 Bucket
From the AWS console, navigate to the S3 service and click the Create Bucket button.
Fill in the required fields, such as the bucket name, and desired region where you want the bucket to be located.
For this example, we'll use the bucket name private-render-demo and the region eu-west-2.
Object Ownership, ACLs and Public Access Settings
You can leave ACL's disabled as Urlbox will not be using them in private bucket mode.
You can also leave the public access settings as the default - Block all public access.
Next click the Create bucket button to create your S3 bucket.
Creating an IAM User with access to the bucket
From the AWS console, navigate to the IAM service and click the Users link in the left hand menu. Then click the Create User button.
Name the user something like urlbox-s3-private and click next.
On the next screen, select the Add User to Group option, and then click the Create Group button.
Enter a name for the group you want to add the user to, something like urlbox should make sense and then create the user group.
Back on the create user wizard, click next and then create user.
Adding a bucket policy to the user group
The only permissions that Urlbox needs to save renders to your private bucket is the s3:PutObject permission.
Now go back to the user group you created, and ensure that the IAM user you created is a part of the group.
Next it's time to add a policy to the group, so that the user can access the bucket you created.
Click the Permissions tab, and then click the Add permissions dropdown and then Create inline policy.
In the policy editor that pops up, switch to JSON view and paste the following JSON policy in:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1505247412000",
"Effect": "Allow",
"Action": ["s3:PutObject"],
"Resource": ["arn:aws:s3:::private-render-demo/*"]
}
]
}You'll need to replace the private-render-demo part of the Resource key with the name of your bucket.
Alternatively, if you'd like this policy to apply to all buckets, you can set the Resource to arn:aws:s3:::*/*.
These are the minimum permissions required for Urlbox to save renders to your bucket. They won't allow Urlbox to access the renders or serve them.
Once you've pasted in the policy, click the Review Policy button, and then give the policy a name, something like urlbox-s3-policy should make sense.
Generating an access key and secret key for the IAM user
Now that the user has been created, and has the correct permissions, we need to generate an access key and secret key for the user.
Open the user again in the IAM console, and click the Security credentials tab. Scroll down to the Access keys section.
Then click the Create access key button. You will want to tell AWS that the purpose of this access key is for a third party service.
It will recommend that you use IAM roles in order to provide short term credentials to a third party, however because we have locked down the access that this user has to the least privileges required by urlbox, it is safe to use the access key and secret key directly.
If you do want to use IAM roles with Urlbox, you will need to figure out a way to refresh them each time they expire, and update the project settings with the fresh credentials.
Now you have created the access keys, it's time to copy them to your clipboard and make sure you don't lose them, as you won't be able to see them again.
Adding the S3 config to your project
Now we can go back to the Urlbox dashboard.
From within the project settings page, scroll down to the S3 Configuration section and click the Add S3 Config button.
We can copy the access key and secret key from our IAM user into the S3 config form.
Also add the region as eu-west-2 and the bucket name as private-render-demo (or whatever you named your bucket).
Crucially, you need to enable the Private Bucket option, to tell Urlbox that it will not be able to serve the renders from your bucket.
Then click Save S3 Config, and if everything is configured correctly, the form should disappear and you should see a success message.
When you click Save S3 Config on the form, Urlbox will attempt to upload a file to your bucket at urlbox_test/deleteme.txt to ensure that the credentials are correct.
Because Urlbox does not have delete credentials on your bucket, this file will remain in your bucket and you can delete it once the bucket is configured correctly.
Debugging Errors
If you see an error message when you click Save S3 Config, it means that Urlbox was unable to upload the test file to your bucket. This could be for a number of reasons:
- The bucket name is incorrect
- The bucket does not exist
- Bucket does not have the correct public settings
- Bucket does not have the correct ACL settings
- The IAM user does not have the correct permissions
Please check all of the above and follow the steps in this guide to ensure that the S3 bucket is configured correctly. Please reach out to support if you are still having issues.
Start saving screenshots to your private S3 bucket
Now that your private S3 bucket is configured correctly, you can start saving screenshots and other renders to it.
When using the Urlbox API, a successful response will still return a renderUrl pointing to the file in your private bucket, however accessing this link will likely give an access denied error becuase the bucket is private.
When using render links with a private bucket, because Urlbox has only been granted write permissions, it is not possible to serve the images directly, so Urlbox will return a JSON response instead of the usual binary response.
You can do this by setting the use_s3 option to true in your API request.
For more options on how to configure how renders are saved to your S3 bucket, please see the saving to s3 guide.
