Skip to content

Commit

Permalink
Docs: Amazon SES: fix IAM policy recommendations
Browse files Browse the repository at this point in the history
Correct IAM action permissions required for
Amazon SES v2 API.

Fixes #384
  • Loading branch information
medmunds committed Jul 11, 2024
1 parent 2d9ca13 commit f86c019
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 22 deletions.
18 changes: 18 additions & 0 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,23 @@ Release history
.. This extra heading level keeps the ToC from becoming unmanageably long
v11.0.1
-------

*2024-07-11*

(This release updates only documentation and package metadata; the code is
identical to v11.0.)

Fixes
~~~~~

* **Amazon SES (docs):** Correct IAM policies required for using
the Amazon SES v2 API. See
`Migrating to the SES v2 API <https://anymail.dev/en/stable/esps/amazon_ses/#amazon-ses-v2>`__.
(Thanks to `@scur-iolus`_ for identifying the problem.)


v11.0
-----

Expand Down Expand Up @@ -1681,6 +1698,7 @@ Features
.. _@puru02: https://github.com/puru02
.. _@RignonNoel: https://github.com/RignonNoel
.. _@sblondon: https://github.com/sblondon
.. _@scur-iolus: https://github.com/scur-iolus
.. _@sdarwin: https://github.com/sdarwin
.. _@sebashwa: https://github.com/sebashwa
.. _@sebbacon: https://github.com/sebbacon
Expand Down
53 changes: 31 additions & 22 deletions docs/esps/amazon_ses.rst
Original file line number Diff line number Diff line change
Expand Up @@ -693,8 +693,8 @@ Anymail requires IAM permissions that will allow it to use these actions:

* To send mail:

* Ordinary (non-templated) sends: ``ses:SendEmail``
* Template/merge sends: ``ses:SendBulkEmail``
* Ordinary (non-templated) sends: ``ses:SendEmail`` and ``ses:SendRawEmail``
* Template/merge sends: ``ses:SendBulkEmail`` and ``ses:SendBulkTemplatedEmail``

* To :ref:`automatically confirm <amazon-ses-confirm-sns-subscriptions>`
webhook SNS subscriptions: ``sns:ConfirmSubscription``
Expand All @@ -717,7 +717,12 @@ This IAM policy covers all of those:
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["ses:SendEmail", "ses:SendBulkEmail"],
"Action": [
"ses:SendEmail",
"ses:SendRawEmail",
"ses:SendBulkEmail",
"ses:SendBulkTemplatedEmail"
],
"Resource": "*"
}, {
"Effect": "Allow",
Expand All @@ -730,35 +735,41 @@ This IAM policy covers all of those:
}]
}
(Anymail does not need access to ``ses:SendRawEmail``
or ``ses:SendBulkTemplatedEmail``. Those are SES v1 actions.)

.. _amazon-ses-iam-errors:

.. note:: **Misleading IAM error messages**
.. note:: **Confusing IAM error messages**

Permissions errors for the SES v2 API often refer to the equivalent SES v1 API name,
which can be confusing. For example, this error (emphasis added):
Permissions errors for the SES v2 API refer to both the v2 API "operation"
and the underlying action whose permission is being checked. This can be
confusing. For example, this error (emphasis added):

.. parsed-literal::
An error occurred (AccessDeniedException) when calling the **SendEmail** operation:
User 'arn:...' is not authorized to perform **'ses:SendRawEmail'** on resource 'arn:...'
actually indicates problems with IAM policies for the v2 ``ses:SendEmail`` action,
*not* the v1 ``ses:SendRawEmail`` action. (The correct action appears as the "operation"
in the first line of the error message.)
actually indicates problems with IAM policies for the ``ses:SendRawEmail``
*action*, not the ``ses:SendEmail`` action. (Even though Anymail calls
the SES v2 SendEmail API, not SendRawEmail.)

Following the principle of `least privilege`_, you should omit permissions
for any features you aren't using, and you may want to add additional restrictions:

* For Amazon SES sending, you can add conditions to restrict senders, recipients, times,
or other properties. See Amazon's `Controlling access to Amazon SES`_ guide.
(Be aware that the SES v2 ``SendBulkEmail`` API does not support condition keys
that restrict email addresses, and using them can cause misleading error messages.
All other SES APIs used by Anymail *do* support address restrictions, including
the SES v2 ``SendEmail`` API used for non-template sends.)
But be aware that:

* The v2 ``ses:SendBulkEmail`` action does not support condition keys that
restrict email addresses, and using them can cause misleading error messages.
To restrict template sends, apply condition keys to ``ses:SendBulkTemplatedEmail``
and then add a separate statement to allow ``ses:SendBulkEmail`` without conditions.
* The v2 ``ses:SendRawEmail`` and ``ses:SendEmail`` actions used for non-template
sends *do* support conditions to restrict addresses.
* Technically, the v2 ``ses:SendEmail`` *action* does not seem to be required
for the SES v2 SendEmail *API operation* as Anymail uses it (with the Content.Raw
param), but including it seems prudent given Amazon's confusing error messages
and incomplete documentation on the subject.

* For auto-confirming webhooks, you might limit the resource to SNS topics owned
by your AWS account, and/or specific topic names or patterns. E.g.,
Expand Down Expand Up @@ -810,12 +821,10 @@ for status tracking webhooks or receiving inbound email.)
Migrating to SES v2 requires minimal code changes:

1. Update your :ref:`IAM permissions <amazon-ses-iam-permissions>` to grant Anymail
access to the SES v2 sending actions: ``ses:SendEmail`` for ordinary sends, and/or
``ses:SendBulkEmail`` to send using SES templates. (The IAM action
prefix is just ``ses`` for both the v1 and v2 APIs.)

Access to ``ses:SendRawEmail`` or ``ses:SendBulkTemplatedEmail`` can be removed.
(Those actions are only needed for SES v1.)
access to the SES v2 sending actions: ``ses:SendEmail`` *and* ``ses:SendRawEmail``
for ordinary sends, and/or ``ses:SendBulkEmail`` *and* ``ses:SendBulkTemplatedEmail``
to send using SES templates. (The IAM action prefix is just ``ses`` for both
the v1 and v2 APIs.)

If you run into unexpected IAM authorization failures, see the note about
:ref:`misleading IAM permissions errors <amazon-ses-iam-errors>` above.
Expand Down

0 comments on commit f86c019

Please sign in to comment.