Simple Email Service (SES)¶

Verify email addresses¶

SES requires that any email addresses used to send emails are verified. To verify email addresses, follow AWS documentation, ensuring that the region you verify the address within matches the AWS region selected within the Skuid authentication provider.

Creating an AWS authentication provider¶

Before configuring data sources within Skuid, you need to decide how you’ll authenticate to your AWS services using an IAM role. We recommend consulting your AWS administrator prior to making this decision.

Assume Role [[]]

This authentication method allows you to use the ARN of an assumable role instead of hard-coded AWS access keys. When a Skuid user makes a request using this authentication method, Skuid makes a secure server-side request to assume the configured role. If this request is successful, Skuid receives temporary access credentials, which Skuid caches until the credentials expire after 60 minutes.

Requests made through an assumed role are traceable via the AWS console. From there, you can see both the Skuid site and Skuid user who initiated the request, which provides AWS administrators full visibility into who requested access credentials and from what Skuid site.

Due to this method’s security and ease-of-management after initial setup, we typically recommend it over the access keys method. However, it does require some technical knowledge to configure. Be sure to read all of the instructions below.

Before you begin

Skuid can only access roles that have a defined path containing the string /skuid-assumable-role/ . This is different from the role’s name. Role paths can only be set when first created, so it isn’t possible to update an existing role with a new path.

In order to create a role with a path, you’ll need to use either the AWS IAM API or the AWS CLI.

The instructions below assume you are using AWS CLI (version 2) and that you’ve already configured an access key ID and secret access key for use with the CLI. Ensure these credentials have the iam:CreateRole permission. Command line examples are also tailored for Linux or macOS operating systems; commands for command line programs on Windows may differ.

Finally, because IAM roles require a trust relationship policy upon creation, you’ll need to save the JSON that Skuid provides when creating an authentication provider. Because of this you’ll need to navigate between your browser window, your computer’s file explorer, as well as the command line.

In Skuid

1. From the Skuid navigation bar, navigate to Data Sources > Authentication Providers.
2. Click Create.
3. Configure the authentication provider’s basic properties:
   • Name: Enter a name, such as AWSAuth.
   • Authentication Method: AWS: Assume Role with ARN
4. In the Trust Relationship Policy, click Copy to Clipboard.

This copied policy will enable your role to grant proper access to your Skuid site.

Note

If you want this role to be assumable by multiple Skuid sites—for example a staging site and a production site, make the sts:ExternalId property’s value into an array of Skuid site Ids.

For example, change this key/value:

"sts:ExternalId": "09583eba-de0e-49d3-ae42-61b3927a61b1"

Into this:

"sts:ExternalId": [
   "09583eba-de0e-49d3-ae42-61b3927a61b1",
   "e354e60f-5a80-4024-b01a-4cae13d0948c"
]

Site IDs are accessible from Settings > Site > Profile.

On your local machine

1. With the policy copied to your clipboard, paste the policy into a text editor.
2. Save the file to an easily accessible directory (for example, your desktop) on your machine with a recognizable name and the JSON file extension, like trust-policy.json

In a command line interface

With the trust policy saved to your machine, you can now use the AWS CLI to create an assumable role.

1. Open your command line program of choice and navigate to the directory containing your policy JSON file. For example, if you saved the file on your desktop:

   1	cd ~/Desktop

2. Use the AWS CLI’s iam create-role command to create the role with the proper path value and trust relationship policy:

   1	aws iam create-role --role-name Skuid-S3-Access --path /skuid-assumable-role/ --assume-role-policy-document file://trust-policy.json

   Note

   While role-name can vary from this example, the path must contain /skuid-assumable-role/

   The CLI creates the role, outputting its ARN and other related metadata. Because of the configured path, your ARN should look similar to this: arn:aws:iam::1234567891011:role/skuid-assumable-role/Skuid-S3-Access.

3. Copy this created ARN, either from the command line output or the AWS console.

In Skuid

1. Return to the authentication provider window.
2. Paste the copied ARN into the AWS Role ARN to assume field.
3. Click Save.

Access Keys [[]]

This authentication method utilizes an Amazon Web Service (AWS) IAM role’s access keys to authenticate to an AWS system.

If you are not the manager of your AWS services, follow along with Amazon’s steps for creating access keys with your IT administrator. You’ll need to do the following:

In AWS

1. Create a new group and select the appropriate policies for that group.
   • These should align with your intended Skuid use. Ensure your access policies match the services (S3, DynamoDB, or SNS) you’ll be using.
2. Create a new user in AWS Identity and Access Management (IAM) within the newly created group.
3. Retrieve the access credentials generated for that user:
   • The secret access key is only displayed once, immediately after the access key is generated, and cannot be found later. Be sure to copy it to a safe place.

In Skuid

With your access credentials handy, you can now use them to configure a Skuid authentication provider that will work with all AWS data sources.

1. Navigate to Configure > Data Sources > Authentication Providers.
2. Click New Authentication Provider.
3. Configure the authentication provider’s basic properties:
   • Name: Enter a name, such as AWSAuth.
   • Authentication Method: AWS: Access Keys
4. Enter your IAM role’s credential information:
   • AWS Access Key Id: The access key ID to use when authenticating.
   • AWS Secret Access Key: The secret access key to use when authenticating.
5. Click Save.

Adding AWS access permissions¶

After choosing an authentication method for your role, you must grant the role a certain set of IAM permissions to access AWS resources. Add each of these permissions to the role used to authenticate Skuid.

• ses:SendEmail

You can add these permissions using the AWS Console or the AWS CLI. You may use any managed policy that includes these permissions, or create a custom inline policy. For more information about these access options, refer to AWS documentation.

Creating an SES data source¶

1. Navigate to Data Sources > Data Sources.
2. Click Create.
3. Select Amazon SES for Type.
4. Enter an appropriate value for Name, such as AWS-ServiceName.
5. Click Next.
6. Select the previously configured AWS authentication provider.
7. Select the AWS Region where the resources you need within Skuid reside. See AWS documentation on regions for more information.
8. Click Save.

After creation, leave Use proxy disabled. The proxy does not currently support Amazon SES data sources.

Data source actions¶

The SES data source is used exclusively to send emails through its one data source action, which can be selected anywhere the Action Framework is accessible, such as Button Set components or as row actions on Tables.

• Send Email: Sends an email through SES. Each of its properties is compatible with merge syntax.

  • To: The email address or addresses that will receive the email. Can accept multiple addresses delimited by a comma.
  • Cc: The email address that will also receive the email as a carbon copy (Cc), meaning other recipients of the email will see that other addresses received the email. Can accept multiple addresses delimited by a comma.
  • Bcc: The email address that will also receive the email as a blind carbon copy (Bcc), which will hide that the Bcc addresses received the email from other recipients. Can accept multiple addresses delimited by a comma.
  • Sender: The email address that will be used to send the email. This email address must be verified within the appropriate AWS region.
  • Email Display name: The name displayed by the sender email, typically the name of the person or organization sending the email.
  • Subject: The subject line of the email.
  • Body: The body of the email message. You may use HTML code within this message.

Email partitioning¶

SES has a maximum of 50 emails per batch, however Skuid can send more than 50 emails at a time. Skuid partitions emails into batches based on the priority of the recipients, which are ranked as follows:

1. To recipients
2. Cc recipients
3. Bcc recipients

For example, an SES action sends emails to 25 To recipients, 50 Cc recipients, and 75 Bcc recipients. These emails will be sent in 3 batches.

1. All 25 To recipients + the first 25 Cc recipients
2. The remaining 25 Cc recipients + the first 25 Bcc recipients
3. The final 50 Bcc recipients

My emails are not sending. [[]]¶

SES data source actions may fail without notifying the user unless an on-error action is added.

In many cases, you can glean useful troubleshooting information from the response AWS sends back to Skuid’s network request.

How to open the Network tab depends on your browser:

• Chrome
• Firefox
• Safari
• Edge
• Internet Explorer

Some common causes of SES errors include:

• The SendEmail permission: If this permission is not added to the IAM role used for the data source’s authentication provider, the action will fail. Verify that this role has the necessary permission.

• Misformed merge variables: Ensure that all merge variables used in the action’s properties are correct. A misformed merge variable in any property will break the entire action.

• Unverified emails: Ensure that the email used in the Sender property is verified for the authentication provider’s IAM role.

  • If the email address is verified, double check that the region in which it is verified matches the Skuid authentication provider’s region.

• Unverified emails in sandbox mode: Ensure that recipient email addresses are verified if testing SES in sandbox mode. Emails may only be sent to unverified recipients when your SES account has been moved out of sandbox mode.