Understanding the API Options for Securely Delegating Access to Your AWS Account

Thinking about building a secure delegation solution to grant temporary access to your AWS account?  This week’s guest blogger Kai Zhao, Product Manager on our AWS Identity and Access Management (IAM) team, will discuss some considerations when deciding on an approach:

Introduction

Using temporary security credentials (“sessions”) enables you to securely delegate access to your AWS environment to one or more users or applications, without having to share your long-term credentials (i.e. password or secret access key).  Use cases include cross-account access (enabling users from one AWS account to access resources in another) and single sign-on to AWS (enabling users authenticated within your enterprise to access AWS without re-authentication).

Many customers have asked for guidance on how to build delegation solutions that grant temporary access to their AWS environment.  This blog post will cover two AWS APIs that you can use for this purpose (sts:GetFederationToken and sts:AssumeRole), how to call each API, and the benefits of using one versus the other.

Please be aware that this blog post will dive deep into some technical details.  It’s helpful to first have a basic understanding of IAM and how to make programmatic AWS API calls with IAM users.  You may want to brush up first by reviewing the Using IAM and Temporary Security Credentials documentation.

What’s in a session?

AWS supports access delegation through the AWS Security Token Service (STS), which enables you to request temporary security credentials that can be used like long-lived access credentials, but have limited duration and permissions.

If you’ve ever signed an AWS API request using your access key and secret key, then using temporary security credentials should be familiar.  They consist of an access key ID, secret access key, a session token, and an expiration time.  Use the keys to sign API requests and pass in the token as an additional parameter (which AWS uses to verify that the temporary access keys are valid).

Understanding how permissions are derived

Before we get into the details of how to call each API, let’s review a key difference between GetFederationToken and AssumeRole.  Both return a set of temporary security credentials, but they differ in how permissions associated with the temporary security credentials are derived.  The Venn diagram below details this:

Calling GetFederationToken requires an IAM user or root.  The resulting permissions inherit the permissions of the caller, scoped down by the permissions attached in the request (if you don’t attach permissions, the resulting permissions will be deny *).  The actual permissions associated with the session are the intersection of the caller’s base permissions and the permissions attached as an API parameter.  If you use an IAM user to call GetFederationToken, you’ll want this user to have the minimum permissions necessary to cover every federated user’s use case, since the actual delegated permissions are always a subset of the caller’s privileges.

Unlike GetFederationToken, AssumeRole sessions derive their permissions from the role policies that you’ve pre-defined, scoped down by the optional permissions attached in the request.  The actual permissions associated with the session are the intersection of the role’s permissions and the permissions attached as an API parameter.  Only an IAM user or another role with permissions to call AssumeRole can assume a role.  By default, you can define up to 250 roles (use the IAM Limit Increase form to request more), and your users/applications can assume any role you allow them to assume.  As a result, you can create role permission profiles tailored for individual use cases and don’t have to pass in a policy with your AssumeRole requests (though you can if you wish).

It’s important to understand that using either GetFederationToken or AssumeRole, the permissions are evaluated each time an AWS API call is made.  That means that even though you cannot revoke the session, you can always modify the permissions associated with a session even after the session has been issued.  Simply modify the permissions on the IAM user (for GetFederationToken) or IAM role (for AssumeRole), and the permissions on the session will automatically be affected as well.

How do you use these APIs?

GetFederationToken and AssumeRole also differ in their parameters.  Here’s a rundown of the possible parameters for each.

• GetFederationToken
  • DurationSeconds: The duration, in seconds, that the session should last (15 min – 36 hours).
  • Name: The name of the federated user associated with the credentials.
  • Policy: A policy specifying the permissions to associate with the credentials.  This is used to scope down the permissions derived from the IAM user making the GetFederationToken request. Note, if you don’t specify any policy here, the resulting temporary credentials will not have any permissions to access AWS resources.
• AssumeRole
  • DurationSeconds: The duration, in seconds, that the session should last (15 min – 1 hour).
  • RoleSessionName: An identifier for the assumed role session. Analogous to the “Name” parameter used in sts:GetFederationToken.
  • Policy: A policy specifying the permissions to associate with the credentials.  This is used to scope down the permissions derived from the role policy.  Note that if a policy is not specified in the request, the resulting permissions will just inherit the policy associated with the role.
  • ExternalID: A unique identifier used if the role is to be assumed by a third party on behalf of their customers.
  • RoleARN: The Amazon Resource Name (ARN) of the role being assumed.

How do I choose which API?

When deciding which API to use, you should consider what services are required for your use case and where you want to maintain the policies associated with your federated users.

How do you want to maintain the policies associated with your delegated users?

If you prefer to maintain permissions solely within your organization, GetFederationToken is the better choice.  Since the base permissions will be derived from the IAM user making the request and you need to cover your entire delegated user base, this IAM user will require the combination of all permissions of all federated users.

If you prefer to maintain permissions within AWS, choose AssumeRole, since the base permissions for the temporary credentials will be derived from the policy on a role. Like a GetFederationToken request, you can optionally scope down permissions by attaching a policy to the request.  Using this method, the IAM user credentials used by your proxy server only requires the ability to call sts:AssumeRole.

What AWS services do you want to use?

Refer to the IAM documentation for an up-to-date list of services and their support for different session types.  Note that temporary security credentials received from GetFederationToken cannot be used to call IAM or STS.

Getting Started

Here are some useful resources to get you started with AWS delegation technologies:

• Familiarize yourself with the IAM user guide
• Try out our pre-packaged federation application, which enables single-sign on to AWS from Active Directory
• Watch our re:Invent 2012 presentation on the topic of delegating access to your AWS environment

– Jim