Integration of Amazon S3

Integration of Amazon S3

The following tutorial describes how to use Amazon S3 as a Cloud Storage for the webQsee Cloud Gallery.
These are complete step-by-step instructions that include the creation of user groups and permission policies on the Cloud Storage.

Enforcing User Rights

webQsee honors the privacy of your Cloud Gallery items. The browser extension talks direktly to the Cloud Storage without any of our servers in between. User rights of items on the Cloud Storage are on the one hand enforced in the browser extension (client-side).
On the other hand, they are enforced on the Cloud Storage as well (server-side), if you set it up like shown in this tutorial.

If you are a single user that wants to use the Cloud Gallery just for himself, then the simplified S3 integration tutorial might be suited better for you.

The user rights that are enforced by the Cloud Storage itself are quite simple:
Admins can read, delete and modify anything, while normal users can read anything, but can only delete and modify items they created themselves.
A special case are private items, they can only be read and modified by the creator, and be deleted by the creator or and admin.

While there are two types of admins in webQsee (content admin, super admin), there is only one admin group on the Cloud Storage that covers both types of webQsee admins.

Getting Started

If you are already using Amazon S3 with a webQsee Cloud Gallery and would like to set up an additional Cloud Gallery for another webQsee team, using the existing S3 Bucket + Policies + Groups (or at least the existing Policies + Groups), then there are also separate tutorials for that.

In this tutorial we assume that you do not yet have an Amazon AWS account, so we show you how to get started with a free one. You can skip these steps if you already have an AWS account that is ready for an additional S3 bucket.

Create a free Amazon AWS account

Navigate to https://aws.amazon.com/free and create an account. Please note that the free accounts only stay free under certain conditions. If you exceed certain usage limits, you will have to pay for your AWS account. Those limits are documented on Amazon's AWS website.

After selecting the support plan (preferably the free one if you are new to AWS), click the button "Sign in to the Console" or use the link https://console.aws.amazon.com/console/home

Sign in to the AWS Console

Sign in at https://console.aws.amazon.com/console/home as "Root user" using the credentials of your new AWS account.
If you already had an existing AWS account, sign in with an account that has sufficient rights for managing S3 storages and users.
Verify, that that you have been logged in correctly and that you have access to the AWS Management Console.

Setting up user groups and rights

Soon we will create an Amazon S3 Bucket to be used as a storage for the raw data of the webQsee Cloud Gallery.
But first, we will create appropriate user groups, so that we can enforce some user rights for the webQsee users that will use the Cloud Storage. For example webQsee admins (content admins and user admins) will be able to delete all items on the storage, while regular members of the webQsee team will only be able to delete items that they created themselves.

Open the IAM management page: https://console.aws.amazon.com/iam/home

Then navigate to "Policies" and click "Create policy".

Creating the Policy for webQsee admins

Change from "Visual editor" to "JSON" and replace the code you see there by the following JSON:

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:AbortMultipartUpload"
],
"Resource": [
"arn:aws:s3:::webqsee/webqsee/*/items-root/shared/*",
"arn:aws:s3:::webqsee/webqsee/*/items-root/protected/*",
"arn:aws:s3:::webqsee/webqsee/*/items-root/private/${aws:PrincipalTag/webqsee-user-id}/*"
],
"Effect": "Allow"
},
{
"Action": [
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::webqsee/webqsee/*/items-root/private/*"
],
"Effect": "Allow"
},
{
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::webqsee"
],
"Condition": {
"StringLike": {
"s3:prefix": [
"webqsee/*/items-root/",
"webqsee/*/items-root/*"
]
}
},
"Effect": "Allow"
}
]
}

Please note that in in all occurrences of arn:aws:s3:::webqsee the "webqsee" will be the name of the S3 bucket that we are going to create as well.
If you are using an AWS account that already contains a bucket named "webqsee" and you would like to create a different bucket for this tutorial, then change all occurrences of arn:aws:s3:::webqsee to arn:aws:s3:::custombucketname

When you have pasted the JSON into the editor, continue by clicking "Review policy". As policy name insert webqsee-admin

(In case you are using an AWS account that already has a policy with this name, define an alternative name for the policy.)

Click "Create policy" after entering the policy name. You should see a success message, telling you that the policy has been created.

Creating the Policy for regular webQsee team members

In the overview page for the policies, click "Create policy" again and switch to the JSON tab again, then replace the code you see there by the following JSON:

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:AbortMultipartUpload"
],
"Resource": [
"arn:aws:s3:::webqsee/webqsee/*/items-root/shared/*",
"arn:aws:s3:::webqsee/webqsee/*/items-root/protected/${aws:PrincipalTag/webqsee-user-id}/*",
"arn:aws:s3:::webqsee/webqsee/*/items-root/private/${aws:PrincipalTag/webqsee-user-id}/*"
],
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::webqsee/webqsee/*/items-root/protected/*"
],
"Effect": "Allow"
},
{
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::webqsee"
],
"Condition": {
"StringLike": {
"s3:prefix": [
"webqsee/*/items-root/shared/",
"webqsee/*/items-root/shared/*",
"webqsee/*/items-root/protected/",
"webqsee/*/items-root/protected/*",
"webqsee/*/items-root/private/${aws:PrincipalTag/webqsee-user-id}/",
"webqsee/*/items-root/private/${aws:PrincipalTag/webqsee-user-id}/*"
]
}
},
"Effect": "Allow"
}
]
}

Please note that in in all occurrences of arn:aws:s3:::webqsee the "webqsee" will be the name of the S3 bucket that we are going to create as well.
If you are using an AWS account that already contains a bucket named "webqsee" and you would like to create a different bucket for this tutorial, then change all occurrences of arn:aws:s3:::webqsee to arn:aws:s3:::custombucketname

When you have pasted the JSON into the editor, continue by clicking "Review policy". As policy name insert webqsee-user

(In case you are using an AWS account that already has a policy with this name, define an alternative name for the policy.)

Click "Create policy" after entering the policy name. You should see a success message, telling you that the policy has been created.

Creating the Group for webQsee admins

In the IAM Console, open "Groups", then click "Create New Group".

When asked to set a group name, enter webqsee-admin and click "Next Step" afterwards.

(If you are using a AWS account that already has a group of this name, choose an alternative name.)

In the next step, called "Attach Policy", search for the Admin-Policy you created before and check it. Then click "Next Step".

Review the changes, then click "Create Group".

After creating the group, you should see the newly created groups in the overview table of the groups page.

Creating the Group for regular webQsee team members

Click the button "Create New Group" again and this time enter webqsee-user as a group name, then click "Next Step".

(If you are using an AWS account that already has a group called "webqsee-user", choose an alternative name.)

In the next step, called "Attach Policy", search for the Regular-User-Policy you created before and check it. Then click "Next Step".

Review the changes, then click "Create Group".

After creating the group, you should see the new group in the overview table of the Groups page. You should see both new Groups there.

Creating Users

Each member of your webQsee team, that wants to use the Cloud Gallery, needs a user on Amazon AWS as well. In the following example, we will create an admin user for you (the person that is working through this tutorial). Any other users that you might need, you must also create.

First, navigate to the "Users" overview page of the IAM console and click "Add user":

Set an appropriate user name. In this example we use my-webqsee-admin-user, but you should probably choose a different name.
Make sure to enable the checkbox for programmatic access! Click the "Next" button after setting a name and enabling the checkbox.

In the next step, search for the admin group you created previously and check this group.
Make sure to only select ONE group when adding new users! If you want to add a regular team member, check the group for the regular user. And in case of admins only the admin group, not both!

After checking the appropriate group, click the "Next" button.
On the next screen, add a new tag with the key webqsee-user-id and in the value of this tag, you need to insert the user-id of your webQsee user!
You own webQsee user id can be found in the "Current User and Team"-Tab of the webQsee browser extension's main window and the user id of other team members can be found in the "Team Management" Sub-tab of the "Current User and Team"-Tab (rightmost column of the top table there).

Click "Next" after setting your user id. Then review the changes and click "Create user" afterwards.

In the final screen, that confirms the creation of the user, it is important that you copy the Access key ID and the Secret access key and store it somewhere safe. You will need these credentials later to sign into the Cloud Storage in the webQsee browser extension.

Click the "Close" button after you copied the Access key ID and the Secret access key and stored them in a secure location.

Now that we have set up users and rights, we can finally create the new S3 bucket.

Open the S3 Console located under https://s3.console.aws.amazon.com/s3/home and click the "Create bucket" button there.

In the general configuration of the bucket, set the bucket name to the name used in the policies earlier. If you did not change the bucket name in the policies, then it should be webqsee

In the region setting you choose a region that works best for you or just keep the preselected region.
Write down the hyphen-separated last part of the region name somewhere, you will need it later! In our example it would be eu-central-1

Enable the checkbox for blocking all public access:

Set Bucket Versioning to disabled, skip adding tags, skip advanced settings and if you want to use server-side encryption to increase the security of the data in your bucket, you can enable it. If you enable server-side encryption, choose the key type "Amazon S3 key". This is the most simple variant and requires no additional setup steps. This is also the only variant that has been tested in combination with webQsee.

Click the button "Create bucket" after you are finished with entering the settings as described. You should then see a success message.

Now click on the name of the new bucket in order to open its details page. There click on the tab "Permissions".

Scroll down the permissions-page until you reach the point Cross-origin resource sharing (CORS).
There you click "Edit" and then paste the following code (replacing any existing code):

[
{
"AllowedHeaders": [
"*"
],
"AllowedMethods": [
"PUT",
"POST",
"GET",
"DELETE",
"HEAD"
],
"AllowedOrigins": [
"*"
],
"ExposeHeaders": [
"ETag"
],
"MaxAgeSeconds": 3600
}
]

Click "Save changes" after you pasted these settings.

You should see a success message after saving the CORS settings.

We are now done preparing the Cloud Storage and can connect it to our webQsee Cloud Gallery.

Open the webQsee Gallery and switch to the tab "Cloud Gallery". Then click "Edit Settings".

In the configuration window, you need to provide the following team-wide settings:

  1. The Storage Type, choose S3 compatible storarge, KEY-Auth (there is only one available at the moment anyway)
  2. The name of the bucket that you created in this tutorial, should be webqsee unless you gave it a different name
  3. The connections settings, that in case of original Amazon S3 should not need more information than the region of the bucket.
    During the bucket setup, you should have noted down the bucket region, if not take a look at the bucket overview page. In our case the bucket region is eu-central-1
{
"region": "eu-central-1"
}

The team-wide settings only need to be provided once and will be shared with all members of the webQsee team.

Then you need to provide the following personal settings:

  1. Access Key Id: The access key id you noted down previously for your AWS IAM user that you created in this tutorial.
  2. Secret Access Key: The secret access key you noted down previously for your AWS IAM user that you created in this tutorial.

The personal settings need to be provided by each webQsee member of your team that wants to use the Cloud Gallery.
This means that each user of your team needs to be provided with his own Access Key Id and a Secret Access Key (= you need to create additional users in the IAM console, just like you created your own user).

After entering all required settings, click the "Save" button.

After saving, you should see a success message in the top right corner of the page and the warning, that the storage configuration is incomplete, should be gone.

Congratulations! Cloud Storage setup is now complete! You can switch to the Local Gallery and upload items to the Cloud Gallery, using your brand-new storage.

Keep in mind, that you need to create storage-users for the other members of your webQsee team as well. One storage-user per webQsee team member. You can do that in Amazon's IAM Console, as shown above, where you created your own user.
If you create a storage-user for a regular team-member, assign the group for regular users and if you create a storage-user for a webqsee admin (content admin or super admin), assign the group for admins. Do NOT assign both groups!

Feel free to contact us if you have any troubles setting up the cloud storage.

If a team member leaves your team at some point in the future, you should also delete his Cloud Storage user, so he loses complete access to your Cloud Storage. Also, if you promote / demote a team member to / from admin, you need to change the user group for his Cloud Storage user as well.