How do I configure my cross-account or cross-Region Amazon SQS endpoint to the Amazon SNS topic?

10 minute read

I want to configure Amazon Simple Queue Service (Amazon SQS) to receive notifications from an Amazon Simple Notification Service (Amazon SNS) topic across different AWS accounts or AWS Regions.

Short description

To subscribe a cross-account or cross-Region Amazon SQS queue to an Amazon SNS topic, you can subscribe as the queue owner or the topic owner. Both approaches require correct permissions on the SNS topic access policy and the SQS queue access policy.

Resolution

Subscribe as a queue owner

To modify the SNS access policy in account B, complete the following steps:

Open the Amazon SNS console in account B.
Switch to the Region where you hosted your SNS topic.
In the navigation pane, choose Topics, and then choose your SNS topic.
Choose Edit, and then choose the Access policy section to expand it.
Remove the existing access policy in the JSON editor.

Enter the following access policy in the JSON editor:

{
 "Statement": [
  {
   "Effect": "Allow",
   "Principal": {
    "AWS": "111122223333"
   },
   "Action": "sns:Subscribe",
   "Resource": "arn:aws:sns:Region:account-id:topic-name"
  }
 ]
}

Note: Replace 111122223333 with your AWS account ID, Region with your AWS Region, account-id with your account ID, and topic-name with your topic name.

Choose Save changes.

To subscribe your SQS queue in account A to your SNS topic in account B, complete the following steps:

Open the Amazon SQS console in account A.
Switch to the Region where you hosted your SQS queue.
In the navigation pane, choose Queues, and then choose your SQS queue.
Choose the SNS subscriptions section, and then choose Subscribe to Amazon SNS topic.
For Specify an Amazon SNS topic available for this queue, choose the dropdown list, and then choose Enter Amazon SNS topic ARN.
For An Amazon SNS topic that can send notifications to an Amazon SQS queue, enter your SNS topic Amazon Resource Name (ARN).
Choose Save.

To confirm your subscription, complete the following steps:

Open the Amazon SNS console in account B.
In the navigation pane, choose Topics, and then choose your SNS topic.

Review the Subscriptions section to verify that your subscription is in the Confirmed state.
Note: After you create the subscription, Amazon SNS adds a statement to the SQS queue access policy. The policy allows the SNS topic to send messages to your queue and looks similar to the following:

{
 "Sid": "topic-subscription-arn:aws:sns:Region:account-id:topic-name",
 "Effect": "Allow",
 "Principal": {
  "AWS": "*"
 },
 "Action": "SQS:SendMessage",
 "Resource": "arn:aws:sqs:Region:account-id:queue-name",
 "Condition": {
  "ArnLike": {
   "aws:SourceArn": "arn:aws:sns:Region:account-id:topic-name"
  }
 }
}

Note: When you use infrastructure-as-code tools such as Terraform or AWS CloudFormation, creating the subscription from the queue owner's side automatically bypasses the manual confirmation step. Amazon SNS immediately confirms the subscription because the queue owner directly initiates the request.

Subscribe as a topic owner

To modify the SQS queue access policy in account A, complete the following steps:

Open the Amazon SQS console in account A.
Switch to the Region where you hosted your SQS queue.
In the navigation pane, choose Queues, and then choose your SQS queue.
Choose Edit, and then choose the Access policy section to expand it.
Remove the existing access policy in the JSON editor.

Enter the following access policy in the JSON editor:

{
 "Sid": "Allow_SNS_topic_in_Account_B_to_Send_Message",
 "Effect": "Allow",
 "Principal": {
  "AWS": "*"
 },
 "Action": "SQS:SendMessage",
 "Resource": "arn:aws:sqs:Region:account-id:queue-name",
 "Condition": {
  "ArnLike": {
   "aws:SourceArn": "arn:aws:sns:Region:account-id:topic-name"
  }
 }
}

Note: Replace Region with your AWS Region, account-id with your account ID, queue-name with your queue name, and topic-name with your topic name.

Choose Save.

To subscribe your SQS queue in account A to your SNS topic in account B, complete the following steps:

Open the Amazon SNS console in account B.
Switch to the Region where you hosted your SNS topic.
In the navigation pane, choose Topics, and then choose your SNS topic.
Under Subscriptions, choose Create subscription.
Choose the Protocol dropdown list, and then choose Amazon SQS.
For Endpoint, enter your SQS queue ARN.
Choose Create subscription.

To confirm your subscription, complete the following steps:

Open the Amazon SQS console in account A.
In the navigation pane, choose Queues, and then choose the subscribed SQS queue.
Choose Send and receive messages.
Under Receive messages, choose Poll for messages. The confirmation message appears in the Receive messages section.
Note: If your SQS queue has an existing consumer such as an AWS Lambda function, then the consumer might process the confirmation message before you poll. Check the consumer's logs such as Amazon CloudWatch Logs for Lambda to retrieve the SubscribeURL from the confirmation message.
Choose the message ID. Under SubscribeURL, copy the URL in quotation marks.
To see the ConfirmSubscriptionResult with SubscriptionArn, enter the preceding URL link in your web browser.
Open the Amazon SNS console in account B.
In the navigation pane, choose Topics, and then choose your SNS topic.
Review the Subscriptions section to verify that your subscription is in the Confirmed state.
Note: The SNS account owns the subscription, so you can't see the subscription listed in the SQS console.

Configure cross-Region subscriptions for opt-in Regions

When you subscribe an SQS queue to an SNS topic across different AWS Regions, the same permission principles apply as cross-account subscriptions. You must configure access policies on both the topic and queue.

You must run the Amazon SNS subscription command in the Region where you host the SNS topic. For example, if the SNS topic is in us-east-1 and the SQS queue is in us-east-2, then run the subscription command in us-east-1.

You must activate opt-in Regions such as af-south-1, ap-east-1, me-south-1, and eu-south-1 in your AWS account to use them. These Regions use regionalized service principals for security isolation. The standard service principal format sns.amazonaws.com doesn't work for cross-Region subscriptions that involve opt-in Regions.

When one of the Regions is an opt-in Region, use the following regionalized service principal formats in your SQS queue access policy:

If the SNS topic is in a default-activated Region and the SQS queue is in an opt-in Region, then use sns.queue-region.amazonaws.com.
If the SNS topic is in an opt-in Region and the SQS queue is in a default-activated Region, then use sns.topic-region.amazonaws.com.
If both the SNS topic and SQS queue are in opt-in Regions, then use sns.queue-region.amazonaws.com.

Example SQS queue policy to subscribe an SQS queue in the default-activated Region of us-east-1 to an SNS topic in the opt-in Region of af-south-1:

{
 "Version": "2012-10-17",
 "Statement": [{
  "Effect": "Allow",
  "Principal": {
   "Service": "sns.af-south-1.amazonaws.com"
  },
  "Action": "SQS:SendMessage",
  "Resource": "arn:aws:sqs:us-east-1:111122223333:MyQueue",
  "Condition": {
   "ArnEquals": {
    "aws:SourceArn": "arn:aws:sns:af-south-1:222233334444:MyTopic"
   }
  }
 }]
}

Note: Replace 111122223333 with your SQS account ID, MyQueue with your queue name, 222233334444 with your SNS account ID, and MyTopic with your topic name.

Regionalized service principals apply only to the SQS queue access policy. The SNS topic access policy uses an AWS account principal, so it doesn't require a regionalized format.

Example SNS topic access policy for the preceding subscription example:

{
 "Effect": "Allow",
 "Principal": {
  "AWS": "111122223333"
 },
 "Action": "sns:Subscribe",
 "Resource": "arn:aws:sns:af-south-1:222233334444:MyTopic"
}

Note: Replace 111122223333 with your SQS account ID, 222233334444 with your SNS account ID, and MyTopic with your topic name.

Troubleshoot Amazon SNS or Amazon SQS

Use Amazon SNS delivery status logging

To troubleshoot delivery issues between Amazon SNS and Amazon SQS, activate Amazon SNS delivery status logging for your SNS topic. Delivery status logs provide detailed information about message delivery attempts, including success and failure responses from Amazon SQS.

Configure KMS key permissions for encrypted SQS queues

SQS queues that you encrypt with an AWS Key Management Service (AWS KMS) key can restrict access between accounts. If you don't define a key for your encrypted queue, then the queue uses the AWS managed key (SSE-KMS) as the default key. You can use this key only with principals in the same account.

To access encrypted queues that use SSE-KMS, create a customer managed AWS KMS key. Then, add permissions in the key policy that allow Amazon SNS to make the AWS KMS API calls.

To allow Amazon SNS to use the GenerateDataKey and Decrypt API methods, add the following statement to the customer managed key policy:

{
 "Effect": "Allow",
 "Principal": {
  "Service": "sns.amazonaws.com"
 },
 "Action": [
  "kms:GenerateDataKey*",
  "kms:Decrypt"
 ],
 "Resource": "*"
}

Note: If the SNS topic is in an opt-in Region, then update the service principal to the regionalized format such as sns.af-south-1.amazonaws.com.

For more information, see Encryption at rest in Amazon SQS and Configuring server-side encryption for a queue using the Amazon SQS console.

Resolve a pending subscription in the SNS console

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Complete the following steps:

Delete your subscription.
To create a new subscription, follow the subscription instructions in the Subscribe as a topic owner section of this article.

To retrieve the SubscribeURL, run the following receive-message AWS CLI command:

aws sqs receive-message --queue-url https://sqs.us-east-1.amazonaws.com/80398EXAMPLE/MyQueue \
  --attribute-names All --message-attribute-names All --max-number-of-messages 10

Note: Replace https://sqs.us-east-1.amazonaws.com/80398EXAMPLE/MyQueue with your queue URL. If your SQS queue has an existing consumer such as a Lambda function, then the receive-message command might not return the subscription confirmation message. The consumer might have already processed it. Check the consumer's logs such as CloudWatch Logs for Lambda to retrieve the SubscribeURL and confirm the subscription.

To confirm the subscription, enter the SubscribeURL in your web browser.

Resolve the "Couldn't set topic access policy" error

When you copy and paste your SNS topic access policy, you might receive the following error:

"Couldn't set topic access policy. Error code: InvalidParameter - Error message: An error occurred while setting the attribute access policy. Invalid parameter: Policy Error: null."

To resolve this error, take the following actions:

Verify that the syntax of your policy is correct.
Copy and paste the access policy to a JSON validator tool.
Review your access policy to confirm that you don't have a duplicate statement.
Confirm that there's a comma after your first statement ID.

Resolve a deleted subscription status in the Amazon SNS console

In cross-account integration of Amazon SNS and Amazon SQS, the account that creates the subscription owns it. If you create the subscription from the SQS account in account A, then account A owns the subscription. If you create the subscription from the SNS account in account B, then account B owns the subscription.

Note: Only the account that owns the subscription can make GetSubscriptionAttributes and SetSubscriptionAttributes API calls on the subscription.

If you call the Unsubscribe API from an account that doesn't own the subscription, then the subscription enters the Deleted status. When the subscription is in Deleted status, the account that owns the subscription can't resubscribe the same endpoint to the topic.

After 48 hours, the Deleted status clears automatically. The account that owns the subscription can then resubscribe the same endpoint to the topic.

To resubscribe before 48 hours, call the Subscribe API from the AWS account that owns the SNS topic to recreate the subscription.

Note: It's a best practice to authenticate your SNS subscription to your SQS queue. With this configuration, only the topic owner and subscription owner can unsubscribe the SQS queue from the SNS topic.