How do I decode an encoded authorization error message for AWS Backup?

2 minute read

I want to decode an encoded authorization status message for AWS Backup.

Short description

A message is encoded because the details of the authorization status might contain privileged information that the user who requested the operation can't see. A decoded message includes the following type of information:

  • Whether the request was denied because of an explicit deny or the absence of an explicit allow. For more information, see Determining whether a request is allowed or denied within an account.
  • The principal who made the request.
  • The requested action.
  • The requested resource.
  • The values of conditions keys in the context of the user's request.

For example, if a user isn't authorized to perform an operation that they requested, the request returns a Client.UnauthorizedOperation response (an HTTP 403 response). Some AWS operations also return an encoded message that can provide details about an authorization failure.


Prerequisite: You must have the sts:DecodeAuthorizationMessage AWS Identity and Access Management (IAM) permission to decode an authorization status message.

To decode an authorization status message, use the AWS Command Line Interface (AWS CLI) to run the decode-authorization-message command. The following is an example command:

Tip: If you're using a Linux-based operating system, then you can combine this command with the jq utility (from the GitHub website) to see a viewer-friendly output.

aws sts decode-authorization-message --encoded-message (encoded error message) --query DecodedMessage --output text | jq '.'

Note: If you receive errors when running AWS CLI commands, then make sure that you're using the most recent version of the AWS CLI.

The following is an example output of the preceding command:

"allowed": false,  
"context": {  
"principal": {  
"id": "AROAAAAAAAAAA:AWSBackup-AWSBackupDefaultServiceRole",  
"arn": "arn:aws:sts::111122223333:assumed-role/AWSBackupDefaultServiceRole/AWSBackup-AWSBackupDefaultServiceRole"  
"action": "iam:PassRole",  
"resource": "arn:aws:iam::111122223333:role/AmazonSSMRoleForInstancesQuickSetup",  
"conditions": {  
"items": [  

The example output shows that the restore role is AWSBackupDefaultServiceRole. The restore role must have the iam:PassRole permission so that it can interact with the AmazonSSMRoleForInstancesQuickSetup role that's required to restore the instance. To resolve this example issue, use the IAM policy to add permissions for the IAM role.

Related information

How do I troubleshoot failed Amazon EC2 restore jobs using AWS Backup?

AWS OFFICIALUpdated a year ago