Permissions for 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 session policies passed as a parameter of the
GetFederationToken
API call. (This is most common.) -
A resource-based policy that explicitly names the federated user in the
Principal
element of the policy. (This is less common.)
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.
In most cases if you do not pass a policy with the GetFederationToken
API call,
the resulting temporary security credentials have no permissions. However, a resource-based
policy can provide additional permissions for the session. You can access a resource with a
resource-based policy that specifies your session as the allowed principal.
The following figures show a visual representation of how the policies interact to determine
permissions for the temporary security credentials returned by a call to
GetFederationToken
.
Example: Assigning permissions using GetFederationToken
You can use the GetFederationToken
API action with different kinds of
policies. Here are a few examples.
Policy attached to the IAM user
In this example, you have a browser-based client application that relies on two backend
web services. One backend service is your own authentication server that uses your own
identity system to authenticate the client application. The other backend service is an
Amazon service that provides some of the client application's functionality. The client
application is authenticated by your server, and your server creates or retrieves the
appropriate permissions policy. Your server then calls the GetFederationToken
API to obtain temporary security credentials, and returns those credentials to the client
application. The client application can then make requests directly to the Amazon service
with the temporary security credentials. This architecture allows the client application to
make Amazon requests without embedding long-term Amazon credentials.
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.
Note
Amazon provides a sample Java application to serve this purpose, which you can download
here: Token Vending Machine for Identity
Registration - Sample Java Web Application
Example policy attached to IAM user token-app
that calls
GetFederationToken
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:GetFederationToken", "Resource": "*" }, { "Effect": "Allow", "Action": "dynamodb:ListTables", "Resource": "*" }, { "Effect": "Allow", "Action": "sqs:ReceiveMessage", "Resource": "*" }, { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "*" }, { "Effect": "Allow", "Action": "sns:ListSubscriptions", "Resource": "*" } ] }
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.
Session policy passed as parameter
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 federated user is assigned these permissions because the permissions are the intersection of the IAM user policies and the session policies that you pass.
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.
Example session policy passed as parameter of GetFederationToken
API
call
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws-cn:s3:::productionapp"] }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": ["arn:aws-cn:s3:::productionapp/*"] } ] }
Resource-based policies
Some Amazon resources support resource-based policies, and these policies provide another
mechanism to grant permissions directly to a federated user. Only some Amazon 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 Amazon services that work with
IAM 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
.
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.
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.
Example bucket policy that allows access to federated user
{ "Version": "2012-10-17", "Statement": { "Principal": {"AWS": "arn:aws-cn:sts::
account-id
:federated-user/Carol"}, "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": ["arn:aws-cn:s3:::productionapp/*"] } }
For more information about how policies are evaluated see Policy evaluation logic.