AWS IAM documentation change
Summary
Updated documentation to consistently use 'AWS STS federated user session' terminology and clarify permission assignment mechanisms
Security assessment
Changes focus on terminology clarification (adding 'AWS STS' qualifier) and precision in describing how permissions are assigned to federated sessions. While this improves documentation accuracy, there is no evidence of addressing a specific security vulnerability or weakness. The changes better explain existing security controls but don't introduce new security features or address disclosed issues.
Diff
diff --git a/IAM/latest/UserGuide/id_credentials_temp_control-access_getfederationtoken.md b/IAM/latest/UserGuide/id_credentials_temp_control-access_getfederationtoken.md index 23b9b893b..88c7af575 100644 --- a//IAM/latest/UserGuide/id_credentials_temp_control-access_getfederationtoken.md +++ b//IAM/latest/UserGuide/id_credentials_temp_control-access_getfederationtoken.md @@ -9 +9 @@ Example: Assigning permissions using GetFederationToken -The `GetFederationToken` operation is called by an IAM user and returns temporary credentials for that user. This operation _federates_ the user. The permissions assigned a federated user are defined in one of two places: +The `GetFederationToken` operation is called by an IAM user and returns temporary credentials for that user. This operation _federates_ the user. The permissions assigned to an AWS STS federated user session are defined in one of two places: @@ -13 +13 @@ The `GetFederationToken` operation is called by an IAM user and returns temporar - * A resource-based policy that explicitly names the federated user in the `Principal` element of the policy. (This is less common.) + * A resource-based policy that explicitly names the AWS STS federated user session in the `Principal` element of the policy. (This is less common.) @@ -18 +18 @@ The `GetFederationToken` operation is called by an IAM user and returns temporar -Session policies are advanced policies that you pass as parameters when you programmatically create a temporary session. When you create a federated user session and pass session policies, the resulting session's permissions are the intersection of the user's identity-based policy and the session policies. You cannot use the session policy to grant more permissions than those allowed by the identity-based policy of the user that is being federated. +Session policies are advanced policies that you pass as parameters when you programmatically create a temporary session. When you create an AWS STS federated user session and pass session policies, the resulting session's permissions are the intersection of the user's identity-based policy and the session policies. You cannot use the session policy to grant more permissions than those allowed by the identity-based policy of the user that is being federated. @@ -34 +34 @@ In this example, you have a browser-based client application that relies on two -Your authentication server calls the `GetFederationToken` API with the long-term security credentials of an IAM user named `token-app`. But the long-term IAM user credentials remain on your server and are never distributed to the client. The following example policy is attached to the `token-app` IAM user and defines the broadest set of permissions that your federated users (clients) will need. Note that the `sts:GetFederationToken` permission is required for your authentication service to obtain temporary security credentials for the federated users. +Your authentication server calls the `GetFederationToken` API with the long-term security credentials of an IAM user named `token-app`. But the long-term IAM user credentials remain on your server and are never distributed to the client. The following example policy is attached to the `token-app` IAM user and defines the broadest set of permissions that your AWS STS federated users (clients) will need. Note that the `sts:GetFederationToken` permission is required for your authentication service to obtain temporary security credentials for the AWS STS federated users. @@ -74 +74 @@ AWS provides a sample Java application to serve this purpose, which you can down -The preceding policy grants several permissions to the IAM user. However, this policy alone doesn't grant any permissions to the federated user. If this IAM user calls `GetFederationToken` and does not pass a policy as a parameter of the API call, the resulting federated user has no effective permissions. +The preceding policy grants several permissions to the IAM user. However, this policy alone doesn't grant any permissions to the AWS STS federated user. If this IAM user calls `GetFederationToken` and does not pass a policy as a parameter of the API call, the resulting AWS STS federated user has no effective permissions. @@ -78 +78 @@ The preceding policy grants several permissions to the IAM user. However, this p -The most common way to ensure that the federated user is assigned appropriate permission is to pass session policies in the `GetFederationToken` API call. Expanding on the previous example, imagine that `GetFederationToken` is called with the credentials of the IAM user `token-app`. Then imagine that the following session policy is passed as a parameter of the API call. The resulting federated user has permission to list the contents of the Amazon S3 bucket named `productionapp`. The user can't perform the Amazon S3 `GetObject`, `PutObject`, and `DeleteObject` actions on items in the `productionapp` bucket. +The most common way to ensure that the AWS STS federated user is assigned appropriate permission is to pass session policies in the `GetFederationToken` API call. Expanding on the previous example, imagine that `GetFederationToken` is called with the credentials of the IAM user `token-app`. Then imagine that the following session policy is passed as a parameter of the API call. The resulting AWS STS federated user has permission to list the contents of the Amazon S3 bucket named `productionapp`. The user can't perform the Amazon S3 `GetObject`, `PutObject`, and `DeleteObject` actions on items in the `productionapp` bucket. @@ -82 +82 @@ The federated user is assigned these permissions because the permissions are the -The federated user could not perform actions in Amazon SNS, Amazon SQS, Amazon DynamoDB, or in any S3 bucket except `productionapp`. These actions are denied even though those permissions are granted to the IAM user that is associated with the `GetFederationToken` call. +The AWS STS federated user could not perform actions in Amazon SNS, Amazon SQS, Amazon DynamoDB, or in any S3 bucket except `productionapp`. These actions are denied even though those permissions are granted to the IAM user that is associated with the `GetFederationToken` call. @@ -109 +109 @@ The federated user could not perform actions in Amazon SNS, Amazon SQS, Amazon D -Some AWS resources support resource-based policies, and these policies provide another mechanism to grant permissions directly to a federated user. Only some AWS services support resource-based policies. For example, Amazon S3 has buckets, Amazon SNS has topics, and Amazon SQS has queues that you can attach policies to. For a list of all services that support resource-based policies, see [AWS services that work with IAM](./reference_aws-services-that-work-with-iam.html) and review the "Resource-based policies" column of the tables. You can use resource-based policies to assign permissions directly to a federated user. Do this by specifying the Amazon Resource Name (ARN) of the federated user in the `Principal` element of the resource-based policy. The following example illustrates this and expands on the previous examples, using an S3 bucket named `productionapp`. +Some AWS resources support resource-based policies, and these policies provide another mechanism to grant permissions directly to an AWS STS federated user. Only some AWS services support resource-based policies. For example, Amazon S3 has buckets, Amazon SNS has topics, and Amazon SQS has queues that you can attach policies to. For a list of all services that support resource-based policies, see [AWS services that work with IAM](./reference_aws-services-that-work-with-iam.html) and review the "Resource-based policies" column of the tables. You can use resource-based policies to assign permissions directly to an AWS STS federated user. Do this by specifying the Amazon Resource Name (ARN) of the AWS STS federated user in the `Principal` element of the resource-based policy. The following example illustrates this and expands on the previous examples, using an S3 bucket named `productionapp`. @@ -111 +111 @@ Some AWS resources support resource-based policies, and these policies provide a -The following resource-based policy is attached to the bucket. This bucket policy allows a federated user named Carol to access the bucket. When the example policy described earlier is attached to the `token-app` IAM user, the federated user named Carol has permission to perform the `s3:GetObject`, `s3:PutObject`, and `s3:DeleteObject` actions on the bucket named `productionapp`. This is true even when no session policy is passed as a parameter of the `GetFederationToken` API call. That's because in this case the federated user named Carol has been explicitly granted permissions by the following resource-based policy. +The following resource-based policy is attached to the bucket. This bucket policy allows an AWS STS federated user named Carol to access the bucket. When the example policy described earlier is attached to the `token-app` IAM user, the AWS STS federated user named Carol has permission to perform the `s3:GetObject`, `s3:PutObject`, and `s3:DeleteObject` actions on the bucket named `productionapp`. This is true even when no session policy is passed as a parameter of the `GetFederationToken` API call. That's because in this case the AWS STS federated user named Carol has been explicitly granted permissions by the following resource-based policy. @@ -113 +113 @@ The following resource-based policy is attached to the bucket. This bucket polic -Remember, a federated user is granted permissions only when those permissions are explicitly granted to both the IAM user _**and**_ the federated user. They can also be granted (within the account) by a resource-based policy that explicitly names the federated user in the `Principal` element of the policy, as in the following example. +Remember, an AWS STS federated user is granted permissions only when those permissions are explicitly granted to both the IAM user _**and**_ the AWS STS federated user. They can also be granted (within the account) by a resource-based policy that explicitly names the AWS STS federated user in the `Principal` element of the policy, as in the following example.