Amazon S3

6 minutes to read

The Design Editor allows your users to browse and select images from your Amazon S3 account.

To manage the Amazon S3 API, you can use the Google Drive web service. You can download this package from the My Account page. If you don't have a Customer's Canvas license, contact our support team.

To enable Amazon S3 as an external source for the Design Editor, you need to perform the following steps:

Configure Amazon S3 buckets.
Set up and run the Google Drive web service.
Configure the Design Editor.
Get an access token and load the Design Editor.

Now, let's look at how you can perform this.

Configuring Amazon S3 Buckets

This chapter describes how you can arrange S3 buckets, get access keys, and configure permissions in your AWS account.

First, navigate to the S3 service in the AWS console and create two S3 buckets: one for the assets and another for preview images. You can upload your assets into the first bucket and leave the second one empty.

Note

The preview images will be displayed in the Asset Manager. If you don't use a bucket for these images, they will be generated every time the user opens the Asset Manager.

After you have created your buckets, you must set up the CORS configuration.

Defining CORS Configuration

In the bucket list, click the name of your bucket for preview images, click Permissions, and click CORS configuration.

Defining CORS in Amazon S3.

In the configuration editor, define the following config and then click Save.

[
    {
        "AllowedHeaders": ["*"],
        "AllowedMethods": ["PUT","GET"],
        "AllowedOrigins": ["*"],
        "ExposeHeaders": []
    }
]

Getting the Access Keys

To get access tokens:

In the top toolbar, click your account name and then click My Security Credentials.
Create a group: click Groups, click Create new group, type in a group name, click Next step, select the amazonS3FullAcess policy, click Next step again, and click Create group.
Create a user: click Users, click Add user, type in a user name, click Programmatic access, click Next permissions, select a group created in the previous step, click Next twice, and click Create user.

If successful, you can see the user's Access key ID. To display the Secret access key, click Show.

Access keys for a new user in Amazon S3.

Now, you can specify these keys in the configuration of the Google Drive web service as S3.AccessKey and S3.Secret.

When you complete configuring the web service, you can enable an Amazon S3 source in the Asset Manager and browse assets from these buckets in the Design Editor.

Now, let's learn how you can set up the Google Drive web service to access the assets in Amazon S3.

Using the Google Drive Web Service

After you have created your Amazon S3 buckets, you can configure the web service that accesses assets in these buckets. This topic describes how you can configure the Google Drive web service (GDWS) to communicate between the Design Editor and Amazon S3.

Configuring the Web Service

Open the Web.config file and find the AppSettings section:

<configuration>
    <appSettings>
        <add key="ApiSecurityKey" value="UniqueSecurityKey" />
        <add key="CorsAllowOriginDomains" value="*" />
        ...
        <!-- Amazon S3 Configuration -->
        <add key="S3.BucketName" value="YourS3bucket"/>
        <add key="S3.Region" value="us-east-2"/>
        <add key="S3.PreviewBucketName" value="YourS3bucketForPreviews"/>
        <add key="S3.PreviewRegion" value="us-east-2"/>
        <add key="S3.Secret" value="UniqueUserSecret"/>
        <add key="S3.AccessKey" value="UserAccessKey"/>
        <add key="PreviewGeneratorServiceEndpoint" value="https://{YourDesignEditorInstance}/api/RemoteSource/GetPreview"/>
    </appSettings>
    ...
</configuration>

Here, you can specify the following parameters:

ApiSecurityKey - a secret key, which you send as X-GoogleDriveAPIKey in request headers to retrieve images.
CorsAllowOriginDomains - restricts the use of your Amazon S3 images to pages hosted only on listed domains. The "*" default value allows access from any domain.
S3.BucketName and S3.PreviewBucketName - the names of your S3 buckets - for assets and their previews.
S3.Region and S3.PreviewRegion - AWS Regions for your buckets.
S3.Secret - the user's Secret access key.
S3.AccessKey - the user's Access key ID.
PreviewGeneratorServiceEndpoint - an endpoint that GDWS calls to generate image previews. If you defined S3.PreviewBucketName and S3.PreviewRegion in this configuration, GDWS saves the preview images to this S3 bucket as soon as they are generated. In this case, the next time the Asset Manager requests them to display, they will be fetched from this bucket.

Running the Google Drive web service

To run this service, create a pool with the NetworkService identity and add a website to the Sites list in IIS Manager.

Configuring the Design Editor

To display Amazon S3 assets in the Asset Manager, you must configure this asset source in ~\Configuration\clientConfig.json and define the X-GoogleDriveAPIKey request header in ~\Configuration\AssetSourcesConfig.json.

This chapter describes how you can configure the Design Editor to access Amazon S3 assets.

Defining the Asset Source

Now that you have set up and run GDWS, you can define the Amazon S3 source as follows:

{
    "assetSources": {
        "[source]AmazonS3": {
            "type": "RemoteSource",
            "url": "https://gdws.example.com/"
        }
    },
    "widgets": {
        "AssetManager": {
            "tabs": [{
                "name": "Amazon",
                "assetSourceInstance": "[source]AmazonS3"
            }]
        }
    }
}

Here, we only specified the URL to the running instance of GDWS. To learn how to fine-tune this asset source, you can refer to the description of the Image manager.

In addition to the parameters responsible for displaying images, you must pass the user ID (representing a folder in your bucket) and a token in the editor's config. Now, let's see how you can generate and pass tokens.

Parameters of the Web API

The Design Editor uses the Web API to render print files. For the security policy, you must specify hi-res secret keys for remote sources in the ~\Configuration\AssetSourcesConfig.json file. This file looks as follows:

{
    "[source]AmazonS3": {
        "type": "RemoteSource",
        "hiResSecret": {
            "httpHeader": "X-GoogleDriveAPIKey",
            "secret": "UniqueSecurityKey"
        }
    }
}

Here, the object name "[source]AmazonS3" corresponds to the asset source name defined in clientConfig.json. The httpHeader is a parameter of your request payload. To render images hosted on Amazon S3, you need to pass the X-GoogleDriveAPIKey header. The value of the secret property corresponds to the ApiSecurityKey value specified in the Web.config file when setting up the web service supporting the Amazon API.

Now that you have configured the general parameters, you can move further and learn how to generate user-specific tokens and pass them into the editor.

Generating Tokens and Loading the Editor

In addition to general configuration parameters responsible for displaying images, you must pass user-specific parameters: the user ID (representing a folder in your Amazon S3 bucket) and a token within the editor's config.

To generate tokens, the Design Editor provides the following endpoint:

GET /api/users/{userId}/getToken

This method accepts the userId=[string] parameter. Here, you must pass a folder in your Amazon S3 bucket.

If successful, the token will appear in the response as follows:

"7FCE96562C0D5CEADDF02A73B4757495"

Now, you can use this token when loading the editor. The following example illustrates how you can generate a token and pass it into the Design Editor.

const userId = "JohnWood";
let response = await fetch(`https://localhost:44500/api/users/${userId}/getToken`, {
    headers: {
        'X-GoogleDriveAPIKey': 'UniqueSecurityKey'
    }
});
            
const token = await response.json();

let product = {
    "surfaces": [{
        "printAreas": [{ "designFile": "invitation" }]
    }]
};

let config = {
    "assetSources": {
        "[source]AmazonS3": {
            "requestParams": {
                "token": token,
                "userId": userId
            }
        }
    }
};

let editor = await CustomersCanvas.IframeApi.loadEditor(
            document.getElementById("editorFrame"), product, config);