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

Last updated: 2023-02-06

I receive the error "Failed to update trust policy. Invalid principal in policy." when trying to edit the trust policy for my AWS Identity and Access Management (IAM) role using the AWS Management Console.

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 formatting for the Principal element.
  • If the IAM role trust policy uses IAM identities (users, user groups, and roles) as principals, then confirm that the user or role wasn't deleted.

Note: AWS GovCloud (US) accounts might also receive this error if the standard AWS account tries to add the AWS GovCloud (US) account number. 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: The AWS account can also be specified using the root user Amazon Resource Name (ARN). 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 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 match part of principal name using a wildcard, 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.

As a best practice, use this method only with the Condition element and a condition key such as aws:PrincipalArn to limit permissions. For example, your file might look similar to the following:

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

This example trust policy uses the aws:PrincipalArn condition key to permit only users with matching user names to assume the IAM role.

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"
    }
  ]
}

The IAM user or role must be an existing identity

If the IAM role trust policy uses IAM users or roles as principals, then confirm that those IAM identities aren't deleted. The "Invalid principal in policy" error occurs if you modify the IAM trust policy and the principal was deleted.

Note: If the principal was deleted, note the unique ID of the principal in the IAM trust policy, and not the ARN.