A Guide to the New Resource Policies for SMS Origination Identities

I. Introduction

AWS End User Messaging has made updates to how it handles SMS origination identities. These changes impact HAQM SNS (Simple Notification Service) and HAQM Pinpoint, which allow sending SMS messages. The updates aim to provide security, flexibility, and control over SMS messaging for AWS users.

For companies and developers using AWS for sending SMS messages, it’s important to understand the recent changes. The new rules affect how AWS services grant permissions and send SMS messages. This blog post explains these changes, discusses their impact, and provides guidance on how to adapt to the new procedures.

II. Understanding the New Resource Policies

AWS End User Messaging empowers developers to integrate scalable and reliable messaging capabilities into their applications. AWS End User Messaging supports SMS, MMS, Voice and WhatsApp. AWS End User Messaging provides enhanced capabilities and control over SMS origination identities (Sender IDs or phone numbers used to send SMS). It provides SMS/WhatsApp messaging capabilities for AWS services like Connect, SNS, and Pinpoint, allowing seamless sharing of SMS resources across accounts.

AWS End User Messaging introduced resource policies for origination identities on Sep 25, 2024. These policies define who has permissions to use SMS origination identities to send SMS messages.

III. Impact on Existing and New SMS Workloads

For customers using AWS for SMS communications, existing origination identities that have been created before September 24, 2024 have been automatically granted permissions to continue functioning as before. This means that if you’ve been sending SMS messages through SNS or Pinpoint, you won’t experience any disruption.

After September 24, 2024, all new Origination identities must have permission through resource policies. his security enhancement strengthens and refines the access control mechanisms.

IV. Behavior Changes in SMS Sending

Using End User Messaging resources such as origination identities requires proper permissions for SNS and Pinpoint to be granted. Without these permissions, you may encounter the following issues:

Error message: “The provided number does not exist or does not belong to the account”
Messages being sent via shared routes instead of dedicated ones

Note 1: In supported regions, AWS maintains a pool of shared origination identities for shared routes. These include Sender IDs and phone numbers, which vary within each country. A shared route uses a generic identifier like “NOTICE” when an application sends messages with a Sender ID as the origination identity.

Note 2: Use dedicated routes instead of shared routes because mobile carriers often block shared routes.

HAQM Pinpoint/SNS employs a fallback mechanism for new Sender IDs in specific scenarios. This happens when:

A message goes through SNS (Publish) or Pinpoint (SendMessages)
The Destination country supports Dynamic sender ID.
The Sender ID’s resource policy lacks permission for SNS or Pinpoint

During fallback,HAQM Pinpoint/SNS follows the below order to find a valid number for sending messages:

Origination number(with correct resource resource policy that allows SNS/Pinpoint Service )
- Short Code first
- 10DLC Number second
- Long Code or Toll Free numbers last
Sender ID (with correct resource resource policy that allows SNS/Pinpoint Service)
Shared routes

When a destination country supports Dynamic sender ID, you can specify sender ID in the OriginationIdentity parameter in the SendTextMessage API call.

V. Implementing Resource Policies

Add resource policies to allow SNS/Pinpoint to use Sender ID/Phone number when you request a phone number/Sender ID via the Console.

Modify resource policies in the End User Messaging console.

For a Phone number:

To modify the resource policy of a phone number, click on ‘Phone numbers’ under ‘Configurations’.
Select the phone number for which you want to modify the resource policy
Go to the ‘Resource policy’ tab. Click on ‘Edit’
Use the Resource policy JSON editor to make modifications. Here is a sample resource policy for a phone number that grants SMS sending permissions to both Pinpoint and SNS:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "pinpoint.amazonaws.com"
      },
      "Action": [
        "sms-voice:SendTextMessage",
        "sms-voice:SendVoiceMessage"
      ],
      "Resource": "arn:aws:sms-voice:<REGION>:<ACCOUNT-ID>:phone-number/<PHONE-NUMBER-ID>",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<ACCOUNT-ID>"
        }
      }
    },
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "sns.amazonaws.com"
      },
      "Action": "sms-voice:SendTextMessage",
      "Resource": "arn:aws:sms-voice:<REGION>:<ACCOUNT-ID>:phone-number/<PHONE-NUMBER-ID>",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<ACCOUNT-ID>"
        }
      }
    }
  ]
}

For a Sender ID:

To modify the resource policy of a Sender ID, click on ‘Sender IDs’ under ‘Configurations’.
Select the Sender ID for which you want to modify the resource policy
Go to the ‘Resource policy’ tab. Click on ‘Edit’
Use the Resource policy JSON editor to make modifications. Here is a sample resource policy for a Sender ID that grants SMS sending permissions to both Pinpoint and SNS:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "pinpoint.amazonaws.com"
      },
      "Action": [
        "sms-voice:SendTextMessage",
        "sms-voice:SendVoiceMessage"
      ],
      "Resource": "arn:aws:sms-voice:<REGION>:<ACCOUNT-ID>:sender-id/<SENDER-ID>/<COUNTRY-CODE>",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<ACCOUNT-ID>"
        }
      }
    },
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "sns.amazonaws.com"
      },
      "Action": "sms-voice:SendTextMessage",
      "Resource": "arn:aws:sms-voice:<REGION>:<ACCOUNT-ID>:sender-id/<SENDER-ID>/<COUNTRY-CODE>",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<ACCOUNT-ID>"
        }
      }
    }
  ]
}

You can use the PutResourcePolicy API call to modify resource policies via CLI/SDK.

As you navigate these changes, keep in mind below considerations:

Appropriate Resource Policies are required for any new Sender ID registered/procured via End User Messaging API’s or via Support case to send via SNS/Pinpoint.
Resources must be in the same region to be shared across accounts, and can only be used via end user messaging API’s. SNS and Pinpoint don’t support usage of cross account shared End User Messaging resources.

VI. Conclusion

The use of resource policies for SMS origination identities in AWS is a major change in how SMS messaging is managed. While it provides security and flexibility, it also requires careful planning and potential updates to existing systems.

It is important to understand these new policies and their impact on AWS services, along with proper implementation methods. This ensures that your SMS communications will continue working smoothly while benefiting from improved control and security.

Adapting these features will set up your SMS workloads for scalability, security, and compliance in the long run.

VII. References

For more detailed information, refer to the following AWS documentation and announcements:

AWS Messaging & Targeting Blog