How do I resolve the IAM trust policy error "Failed to update trust policy. Invalid principal in policy"?

Short description

This error message indicates that the value of a Principal element in your IAM trust policy isn't valid. To resolve this error, confirm the following:

• Your IAM role trust policy uses supported values with correct format for the Principal element.
• If the IAM role trust policy uses an IAM users or roles as principals, then confirm that the user or role wasn't deleted.

Note: If the standard AWS account tries to add the AWS GovCloud (US) account number, then AWS GovCloud (US) accounts might also receive this error. You can't create a role to delegate access between an AWS GovCloud (US) account and a standard AWS account. For more information, see How IAM Differs for AWS GovCloud (US).

Resolution

Verify the supported values for the Principal element

The Principal element in the IAM trust policy of your role must include the following supported values.

1. Make sure that the IAM policy includes the correct AWS 12-digit AWS account ID similar to the following:

   "Principal": 
   {"AWS": "123456789012"
   }

   Note: You can also use the root user Amazon Resource Name (ARN) to specify the AWS account. For example, arn:aws:iam::123456789012:root.

2. If the IAM trust policy principals are IAM users, roles, or federated users, then the entire ARN must be specified similar to the following:

   "Principal": 
   {  "AWS": [
       "arn:aws:iam::123456789012:user/user-name",
       "arn:aws:iam::123456789012:role/role-name",
       "arn:aws:sts::123456789012:assumed-role/role-name/role-session-name",
       "arn:aws:sts::123456789012:federated-user/user-name"
     ]
   }

3. If the IAM trust policy includes a wildcard, then follow these guidelines.
   Note: You can't use a wildcard "*" to match part of a Principal name or ARN. The following example has an incorrect use of a wildcard in an IAM trust policy:

   "Principal": 
   {  "AWS": "arn:aws:iam::123456789012:user/user-*"
   }

   To use a wildcard to match part of principal name, use a Condition element with the global condition key aws:PrincipalArn. Then, specify an ARN with the wildcard. To specify identities from all AWS accounts, use a wildcard similar to the following:

   "Principal": {
     "AWS": "*"
   }

   Important: You can use a wildcard in the Principal element with an Allow effect in a trust policy. However, this allows any IAM user, assumed role session, or federated user in any AWS account in the same partition to access your role. IAM user and role principals within your AWS account don't require any other permissions. Principals in other AWS accounts must have identity-based permissions to assume your IAM role. This method doesn't allow web identity session principals, SAML session principals, or service principals to access your resources. It's a best practice to use this method only with the Condition element and a condition key such as aws:PrincipalArn to limit permissions. The following example trust policy uses the aws:PrincipalArn condition key to permit only users with user names that match to assume the IAM role:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "*"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringLike": {
             "aws:PrincipalArn": "arn:aws:iam::123456789012:user/user-*"
           }
         }
       }
     ]
   }

4. If your IAM role is an AWS service role, then the entire service principal must be specified similar to the following:

   "Principal": {
     "Service": "ec2.amazonaws.com"
   }

5. You can use SAML session principals with an external SAML identity provider to authenticate IAM users. The trust policy of the IAM role must have a Principal element similar to the following:

   "Principal": {
     "Federated": "arn:aws:iam::123456789012:saml-provider/provider-name"
   }

6. You can use web identity session principals to authenticate IAM users. The trust policy of the IAM role that provides access must have a Principal element similar to the following:

   "Principal": {
      "Federated": "cognito-identity.amazonaws.com" 
   }

7. If you use different principal types within a single statement, then format the IAM trust policy similar to the following:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::123456789012:user/user-name",
           "Service": "ec2.amazonaws.com"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }

Verify that the trust policy doesn't contain AIDA or AROA prefixes

If your trust policy contains a Principal element with an ARN for IAM entities, the ARN changes to a unique principal ID when it's saved. This unique Principal ID has the prefix AIDA for IAM users, and AROA for IAM roles similar to the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "AIDAW4GTDFISYQEXAMPLE",
          "AROAW4GTDFISYQEXAMPLE"
        ]
      },
      "Action": "sts:AssumeRole",
      "Condition": {}
    }
  ]
}

The unique principal ID in a trust policy indicates that the IAM user or role was deleted. The principal ID appears because AWS can't map it back to a valid ARN. If you edit the trust policy, you must either remove the principal ID or replace it with a valid Principal ARN. The ARN changes to the user or roles new unique ID after you save the policy.

For more information, see Why is there an unknown principal format in my IAM resource-based policy?

Related information

How do I use IAM to allow user access to resources?

How do I access resources in another AWS account using AWS IAM?