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

Last updated: 2022-04-04

When I tried to edit my AWS Identity and Access Management (IAM) role trust policy using the AWS Management Console, I received an error similar to the following:

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

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, 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, 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 and 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. For IAM user and role principals within your AWS account, no other permissions are required. For principals in other AWS accounts, they 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 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, 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, 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.