Configure AWS SES for Email

This document explains how to configure email notification and messaging services with AWS Simple Email Service in Fides.

Prerequisites Permalink for this section

In order to complete this, you will need the following:

• A valid AWS SES account with which to send emails. You'll need to have either: a verified domain, or a verified email address added to your AWS account. For more information on how to configure this, refer to the AWS SES docs (opens in a new tab).
• Ability to access and update Fides system config variables for your Fides installation. Read about config variables here.
• Fides OAuth access token with the following scopes.
  • messaging:read: Read an existing messaging configuration.
  • messaging:create_or_update: Create or update messaging configuration.
  • messaging:delete: Delete a messaging configuration.
  • config:read: Read Fides system configurations.
  • config:update: Update Fides system configurations.

Obtain your AWS SES credentials Permalink for this section

You'll need to obtain an access key and a secret key for a user with AWS SES access. The user should have full AWS SES access (opens in a new tab) (i.e both read and write permissions), or should have permission to assume a role (opens in a new tab) that has full AWS SES access.

Example: Set AWS SES as the default messaging provider Permalink for this section

To set AWS SES as the default messaging provider, make a PUT request to the api/v1/messaging/default endpoint as follows:

PUT /api/v1/messaging/default

curl '{{FIDES_URL}}/api/v1/messaging/default' \
-X PUT \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
    "service_type": "aws_ses",
    "details": {
        "domain": "{{AWS_SES_DOMAIN}}", // If you use `domain` you will need to omit `email_from`
        "email_from": "{{AWS_SES_EMAIL_FROM}}", // If you use `email_from` you will need to omit `domain`
        "aws_region": "{{AWS_SES_REGION}}",
    }
}'

In the above example {{FIDES_URL}} is the URL to your Fides server. The Authorization is Bearer and {{FIDES_ACCESS_TOKEN}} is your Fides access token. The request Content-Type is application/json.

The service_type is aws_ses and {{AWS_SES_REGION}} is the AWS region of your AWS account, e.g us-east-2.

You must provide either {{AWS_SES_DOMAIN}} or {{AWS_SES_EMAIL_FROM}}, depending on how your SES account is configured:

• If you provide a verified domain, Fides will automatically construct a default sender email using the format noreply@{domain}.
• If you prefer to use a specific sender address, you can instead provide a verified email address via email_from.

You do not need to verify or provide both a domain and an email address — only one is required.

The response to this request will return the configuration for the default messaging provider, including your domain and a key as shown below:

Default Messaging Provider Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "service_type": "aws_ses",
    "details": {
        "domain": "{{AWS_SES_DOMAIN}}",
        "email_from": "{{AWS_SES_EMAIL_FROM}}",
        "aws_region": "{{AWS_SES_REGION}}",
    },
    "name": "string",
    "key": "TNSm_.......K6je4ei"
}

Example: Add AWS SES credentials Permalink for this section

Next, you can add your AWS SES credentials by making a PUT request to the api/v1/messaging/default/aws_ses/secret endpoint as follows:

PUT /api/v1/messaging/default/aws_ses/secret

curl '{{FIDES_URL}}/api/v1/messaging/default/aws_ses/secret' \
-X PUT \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
    "auth_method": "{{AUTH_METHOD}}",
    "aws_access_key_id": "{{AWS_ACCESS_KEY}}",
    "aws_secret_access_key": "{{AWS_SECRET_KEY}}",
    "aws_assume_role_arn": "{{AWS_ROLE_ARN}}"
}'

The {{AUTH_METHOD}} is the authentication method used to access AWS SES; it takes two possible values: secret_keys or automatic. If secret_keys is used, you must provide the {{AWS_ACCESS_KEY}} and {{AWS_SECRET_KEY}} values. If automatic is used, these values will be obtained from your environment variables. In either case, you can optionally provide the AWS Role ARN ({{AWS_ROLE_ARN}}) of the role to assume. For more information on assuming roles, refer to the AWS docs (opens in a new tab).

The response to this request will be a confirmation message that the secret has been updated for the configuration identified by the key as shown in this example:

Default Messaging Provider Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg": "Secrets updated for MessagingConfig with key: TNSm_.......K6je4ei.",
    "test_status": null,
    "failure_reason": null
}

Messaging Config Variables Permalink for this section

Fides allows you to configure which messaging service is used to send system notifications. To do this you must update Fides' system-wide settings to ensure that your AWS SES service is selected. You may also configure what kinds of notifications Fides will send.

Below is a list of the notification configurations that can be set:

Example: Set Messaging Config Variables Permalink for this section

You can update your Fides messaging configuration by making a PATCH request to the api/v1/config endpoint as follows:

PATCH /api/v1/config

curl '{{FIDES_URL}}/api/v1/config' \
-X PATCH \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d '{
  "notifications": {
    "notification_service_type" : "aws_ses",
    "send_request_receipt_notification": true,
    "send_request_review_notification": true,
    "send_request_completion_notification": true
  },
  "execution": {
    "subject_identity_verification_required": true
  }
}'

The notification_service_type value is aws_ses and for each of the notifications you wish to send via AWS SES, set their value to true. You can also enable or disable subject identify verification on privacy requests here by setting execution.subject_identity_verification_required to true. Learn more about Subject Identify Verification here.

The response to this request will confirm the service type and the current status for each notification as shown in the example below:

Fides Configuration Update Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "notifications": {
        "send_request_completion_notification": true,
        "send_request_receipt_notification": true,
        "send_request_review_notification": true,
        "notification_service_type": "aws_ses"
    },
    "execution": {
        "subject_identity_verification_required": true
    }
}

Check the messaging configuration status Permalink for this section

To check that your messaging configuration has been fully configured, you can invoke the status endpoint at /api/v1/messaging/default/status.

GET /api/v1/messaging/default/status

curl '{{FIDES_URL}}/api/v1/messaging/default/status' \
-X GET \
-H 'Authorization: Bearer {{FIDES_ACCESS_TOKEN}}' \
-d ''

If everything is correctly configured you will receive a response similar to the example below with config_status of "configured".

Fides Configuration Update Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "config_status": "configured",
    "detail": "Active default messaging service of type aws_ses is fully configured"
}