Aws sts

Welcome to the AWS Security Token Service API Reference

AWS provides AWS Security Token Service (AWS STS) as a web service that enables you to request temporary, limited-privilege credentials for AWS Identity and Access Management (IAM) users or for users you authenticate (federated users). This guide describes the AWS STS API. For more information, see Temporary Security Credentials in the IAM User Guide.

Note

As an alternative to using the API, you can use one of the AWS SDKs, which consist of libraries and sample code for various programming languages and platforms such as Java, Ruby, .NET, iOS, Android, and others. The SDKs provide a convenient way to create programmatic access to AWS STS. For example, the SDKs can cryptographically sign requests, manage errors, and retry requests automatically. For information about the AWS SDKs, see Tools to Build on AWS.

For information about setting up signatures and authorization through the API, see Signing AWS API Requests in the Amazon Web Services General Reference. For general information about the Query API, see Making Query Requests in the IAM User Guide. For information about using security tokens with other AWS products, see AWS Services That Work with IAM in the IAM User Guide.

Endpoints

By default, AWS Security Token Service (AWS STS) is available as a global service, and all AWS STS requests go to a single endpoint at . Global requests map to the US East (N. Virginia) Region. AWS recommends using Regional AWS STS endpoints instead of the global endpoint to reduce latency, build in redundancy, and increase session token validity. For more information, see Managing AWS STS in an AWS Region in the IAM User Guide.

Most AWS Regions enable operations in all AWS services by default. These Regions automatically activate for use with AWS STS. Some Regions, such as Asia Pacific (Hong Kong), must be manually enabled. To learn more about enabling and disabling AWS Regions, see Managing AWS Regions in the Amazon Web Services General Reference. When you enable these AWS Regions, they are automatically activated for use with AWS STS. You cannot activate the AWS STS endpoint for a disabled Region. Tokens valid in all AWS Regions are longer than tokens valid in Regions enabled by default. Changing this setting might affect existing systems where you temporarily store tokens. For more information, see Managing Global Endpoint Session Tokens in the IAM User Guide.

After you activate a Region for use with AWS STS, you can direct AWS STS API calls to that Region. AWS STS recommends you provide both the Region and endpoint when you send calls to a Regional endpoint. You can provide the Region alone for manually enabled Regions, such as Asia Pacific (Hong Kong). In this case, you direct the calls to the AWS STS Regional endpoint. However, if you provide the Region alone for Regions enabled by default, AWS STS directs the calls to the global endpoint of .

To view the list of AWS STS endpoints and if they are active by default, see Writing Code to Use AWS STS Regions in the IAM User Guide.

Recording API requests

AWS STS supports AWS CloudTrail, a service that records AWS calls for your AWS account and delivers log files to an Amazon S3 bucket. By using information collected by CloudTrail, you can determine the requests successfully sent to AWS STS, as well as who sent the request, and when it was sent.

If you activate AWS STS endpoints in Regions other than the default global endpoint, then you must also enable CloudTrail logging in those Regions. You must do this to record any AWS STS API calls sent in those Regions. For more information, see Turning On CloudTrail in Additional Regions in the AWS CloudTrail User Guide.

AWS Security Token Service (AWS STS) is a global service with a single endpoint at . CloudTrail logs the calls to this endpoint as calls to a global service. However, because this endpoint is physically located in the US East (N. Virginia) Region, your logs list as the event Region. CloudTrail does not write these logs to the US East (Ohio) Region unless you choose to include global service logs in that Region. CloudTrail writes calls to all Regional endpoints to their respective Regions. For example, calls to sts.us-east-2.amazonaws.com are published to the US East (Ohio) Region and calls to sts.eu-central-1.amazonaws.com are published to the Europe (Frankfurt) Region.

For more information about CloudTrail, including how to enable it and find your log files, see the AWS CloudTrail User Guide.

Sours: https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html

Using AWS IAM with STS for access to AWS Resources

With increased focus on security and governance in today’s digital economy, I want to highlight a simple but important use case that demonstrates how to use AWS Identity and Access Management (IAM) with Security Token Service (STS) to give trusted AWS accounts access to resources that you control and manage.

What is STS (Security Token Service)?

Security Token Service is an extension of IAM and is one of several web services offered by AWS that does not incur any costs to use.  But, unlike IAM, there is no user interface on the AWS console to manage and interact with STS. Rather all interaction is done entirely through one of several extensive SDKs or directly using common HTTP protocol.  I will be using Terraform to create some simple resources in my sandbox account and .NET Core SDK to demonstrate how to interact with STS.

The main purpose and function of STS is to issue temporary security credentials for AWS resources to trusted and authenticated entities.  These credentials operate identically to the long-term keys that typical IAM users have, with a couple of special characteristics:

  • They automatically expire and become unusable after a short and defined period of time elapses
  • They are issued dynamically

These characteristics offer several advantages in terms of application security and development and are useful for cross-account delegation and access.  STS solves two problems for owners of AWS resources:

  • Meets the IAM best-practices requirement to regularly rotate access keys
  • You do not need to distribute access keys to external entities or store them within an application

One common scenario where STS is useful involves sharing resources between AWS accounts.  Let’s say, for example, that your organization captures and processes data in S3, and one of your clients would like to push large amounts of data from resources in their AWS account to an S3 bucket in your account in an automated and secure fashion.

aws sts assume role

Process Automation Challenges

While you could create an IAM user for your client, your corporate data policy requires that you rotate access keys on a regular basis, and this introduces challenges for automated processes.  Additionally, you would like to limit the distribution of secret access keys to your resources to external entities.  Let’s use STS to solve this!

To get started, let’s create some resources in your AWS cloud.  Do you even Terraform, bro?

Let’s create a new S3 bucket and set the bucket ACL to be private, meaning nobody but the bucket owner (that’s you!) has access.  Remember that bucket names must be unique across all existing buckets, and they should comply with DNS naming conventions.  Here is the Terraform HCL syntax to do this:

Using AWS IAM with STS for access to AWS Resources

Great! We now have a bucket… but for now, only the owner can access it.  This is a good start from a security perspective (i.e. “least permissive” access).

Amazon S3 Bucket Image

What an empty bucket may look like

Let’s create an IAM role that, once assumed, will allow IAM users with access to this role to have permissions to put objects into our bucket.  Roles are a secure way to grant trusted entities access to your resources.

You can think about roles in terms of a jacket that an IAM user can wear for a short period of time, and while wearing this jacket, the user has privileges that they wouldn’t normally have when they aren’t wearing it.  Kind of like a bright yellow Event Staff windbreaker!

For this role, we will specify that users from our client’s AWS account are the only ones that can wear the jacket. This is done by including the client’s AWS account ID in the Principal statement. AWS Account IDs are not considered to be secret, so your client can share this with you without compromising their security.  If you don’t have a client but still want to try this stuff out, put your own AWS account ID here instead.

AWS account ID in Code
Great, now we have a role that our trusted client can wear.  But, right now our client can’t do anything except wear the jacket.  Let’s give the jacket some special powers, such that anyone wearing it can put objects into our S3 bucket.

We will do this by creating a security policy for this role.  This policy will specify what exactly can be done to S3 buckets that it is attached to. Then we will attach it to the bucket we want our client to use.  Here is the Terraform syntax to accomplish this:
Terraform syntax

A couple things to note about this snippet – First, we are using Terraform interpolation to inject values from previous terraform statements into a couple of places in the policy – specifically the ARN from the role and bucket we created previously. Second, we are specifying a condition for the s3 policy – one that requires a specific object ACL for the action s3:PutObject, which is accomplished by including the HTTP request header x-amz-acl to have a value of bucket-owner-full-control with the PUT object request.

By default, objects PUT in S3 are owned by the account that created them, even if it is stored in someone else’s bucket.  For our scenario, this condition will require your client to explicitly grant ownership of objects placed in your bucket to you, otherwise the PUT request will fail.

So, now we have a bucket, a policy in place on our bucket, and a role that assumes that policy.  Now your client needs to get to work writing some code that will allow them to assume the role (wear the jacket) and start putting objects into your bucket.  Your client will need to know a couple of things from you before they get started:

  1. The bucket name and the region it was created in (the example above created a bucket named d4h2123b9-xaccount-bucket in us-west-2)
  2. The ARN for the role (Terraform can output this for you). It will look something like this but will have your actual AWS Account ID: arn:aws:iam::123456789012:role/sts-delegate-role

They will also need to create an IAM User in their account and attach a policy allowing the user to assume roles via STS.  The policy will look similar to this:

STS Policy Example
Let’s help your client out a bit and provide some C# code snippets for .NET Core 2.0 (available for Windows, macOS and LinuxTo get started, install the .NET SDK for your OS, then fire up a command prompt in a favorite directory and run these commands:
Command Prompt Example
The first command will create a new console app in the subdirectory s3cli.  Then switch context to that directory and import the AWS SDK for .NET Core, and then add packages for SecurityToken and S3 services.
Once you have the libraries in place, fire up your favorite IDE or text editor (I use Visual Studio Code), then open Program.cs and add some code:
Program.cs code
This snippet sends a request to STS for temporary credentials using the specified ARN.  Note that the client must provide IAM user credentials to call STS, and that IAM user must have a policy applied that allows it to assume a role from STS.

This next snippet takes the STS credentials, bucket name, and region name, and then uploads the Program.cs file that you’re editing and assigns it a random key/name.  Also note that it explicitly applies the Canned ACL that is required by the sts-delegate-role:
Snippet of STS credentials, bucket name, and region name
So, to put this all together, run this code block and make the magic happen!  Of course, you will have to define and provide proper variable values for your environment, including  securely storing your credentials.
securely storing your credentials example
Try it out from the command prompt:
Command Prompt
If all goes well, you will have a copy of Program.cs in the bucket. Not very useful itself, but it illustrates how to accomplish the task.
copy of Program.cs in the bucket

What a bucket with something in it may look like

Here is a high-level document of what we put together:

AWS STS Bucket Example

Putting it all together

Steps:

  1. Your client uses their IAM user to call AWS STS and requests the role ARN you gave them
  2. STS authenticates the client’s IAM user and verifies the policy for the ARN role, then issues a temporary credential to the client.
  3. The client can use the temporary credentials to access your S3 bucket (they will expire soon), and since they are now wearing the Event Staff jacket, they can successfully PUT stuff in your bucket!

There are many other use-cases for STS and assume STS. This is just one very simplistic example. However, with this brief introduction to the concepts, you should now have a decent idea of how STS works with IAM roles and policies, and how you can use STS to give access to your AWS resources for trusted entities. For more tips like this, contact us.

-Jonathan Eropkin, Cloud Consultant

Facebooktwitterlinkedinmailrss
Sours: https://www.2ndwatch.com/blog/use-aws-iam-sts-access-aws-resources/
  1. Craigslist tractor stockton
  2. Sub zero kuai liang
  3. Uefi mode
  4. Ariana grande wallpaper pinterest

What_is_Amazon_STS

AWS STS is an AWS service that allows you to request temporary security credentials for your AWS resources, for IAM authenticated users and users that are authenticated in AWS such as federated users via OpenID or SAML2.0.

You use STS to provide trusted users with temporary access to resources via API calls, your AWS console or the AWS command line interface (CLI)

The temporary security credentials work exactly like regular long term security access key credentials allocated to IAM users only the lifecycle of the access credentials is shorter.

Typically an application will make an API request to AWS STS endpoint for credentials, these access keys are not stored with the user, they are instead dynamically generated by STS when the request is made. The STS generated credentials will expire at which point the user can request new ones as long as they still have permission to do so.

Once the generated credentials expire they cannot be reused which reduces the risk of having your resource access compromised and removes the need to embed security tokens within your code.

The STS token lifecycle is determined by you and can be anywhere from 15 minutes to 36 hours.

AWS STS security tokens are typically used for identity federation, providing cross-account access and for resources related to EC2 instances that require access by other applications.

Identity Federation Use-Case

Using AWS STS you can grant access to AWS resources for users that have been authenticated at your enterprise network. This enterprise identity federation removes the need to create new AWS identities and no new login credentials are required.

External web identities can be authenticated by a third party online identity manager like amazon, google, facebook or any other open-id connect compatible service. This web identity federation also removes the need to distribute long-term security credentials to facilitate access to your AWS resources.

Enterprise federation can use a number of authentication protocols like SSO and supports open standards like security assertion markup language SAML2.0 with which you can use microsoft active directory federation services ADFS if you are using Microsoft AD or you can use SAML to build your own authentication service.

Cross-Account Access using AWS STS

Lots of organisations maintain multiple AWS accounts and can use IAM identities and cross account roles to allow users from one account to access resources in another. Once the permissions are delegated to an IAM user, this trusted relationship can be used to request temporary access via AWS STS temporary credentials.

EC2 Instance STS Credentials

If you have applications running on an EC2 instance that require access to AWS resources, you can create temporary access credentials using AWS STS when the EC2 instance is launched. To do that, the EC2 instance will need to be associated with an IAM role to allow the application to request credentials. Once the security credentials are granted, they are available to all applications hosted on the EC2 instance so you do not need to store any long-term security credentials in the instance. 

AWS STS Example

In this example we’ll set up a new AWS user with no specific permissions and create a role that has STS associated with it and has read-only S3 bucket permissions.

We’ll then try to access an S3 bucket from the AWS CLI before and after connecting to the profile with STS enabled.

First of all we need to set up a new AWS user by going into Console > Services > IAM then hitting the Add users button:

AWS_STS_1

Then name the user and set the access type to Programmatic Access. In this example we'll set our user to sts-user.

AWS_STS_2

In the next screen related to permissions and adding the user to a group, you can skip the page without setting any permissions

AWS_STS_3

You can also skip adding tags and advance to the review page:

AWS_STS_4

Click on create user.  When the user created success page is displayed, copy down the Access key ID and the Secret Access Key into a text notepad document

AWS_STS_5v2

Then return to the IAM users page and open the new user just created.

AWS_STS_6

Copy the User ARN (Amazon Resource Name) and add that to your text notepad 

AWS_STS_7

Now we need to create a new role, so navigate to the roles dashboard from the navigation bar on the left hand of the IAM services. Then “Create Role"

AWS_STS_8

The next step is to select the type of trusted entity that you want to grant permissions to, which will ultimately be the service or user that will be maing the API calls to STS for temporary access credentials

These options are:

  • AWS Service -  like EC2 or Lambda where an application will be requesting credentials
  • Another AWS account - this can be another AWS account ID or the account you are currently using to set up the new role
  • Web Identity - where AWS Congnito or another OpenID credentials provider has authentication rights.
  • SAML 2.0 Federation - Like your corporate active directory

For the purposes of this example, we’ll use ‘Another AWS account’ and enter in the account ID that we’re using to set up the role.

AWS_STS_9

The next step is to attach the permission policies you wish to allow this role to perform.

In this example, we want to grant access to read S3 buckets, so will attach the S3ReadOnlyAccess policy

AWS_STS_10

Next you can add tags if you wish, or skip them.

Then advance to the Review page and name the role and add a description.

AWS_STS_11

Once you are happy with the review page, create the role.

AWS_STS_12

Open up the role and copy the role ARN to the text notepad for future reference.

AWS_STS_13

Now open up the trust relationships tab and edit the trust relationship

By default the trust relationship is set to trust the root account. You need to change this to set up the relationship with the user we set up (sts-user) by changing the ARN in the policy to the ARN for the user we set up and copied to the text doc

AWS_STS_14

Then update the trust policy. Now return to the Users console, open up the new user and select the “Add Inline Policy” option.

AWS_STS_15

Now select “Policy Generator” - here is where we define the connection to the AWS Simple Token System (STS) service.

Here we set:

Effect - set to Allow

AWS Service - set to AWS Security Token Service (STS)

Actions - Assume Role

ARN - The ARN Role we created and noted down in the text notepad.

AWS_STS_16

Then create the policy and we are ready to go.

In this example We’ll use the AWS CLI to access an S3 bucket called “425magfiles” using the sts-user which will generate access tokens on the fly to gain the read-only permissions required.

From a terminal window we then:

Aws configure --profile sts-user 

Enter the Access Key  (paste from notepad)

Enter the Secret Key (paste from notepad)

Set the default region - in this example us-east-1

Set the output format - to json

AWS_STS_17

And then we’ll set the profile variable using:

export AWS_PROFILE=sts-user

AWS_STS_18

Now if we attempt to access an S3 bucket, because there are no explicit permissions granted to sts-user, the request fails.

AWS_STS_19

This is because we haven’t assumed the role required to grant the read permissions using STS.

To do this we use the command : 

aws sts assume-role --role-arn arn:aws:iam::xxxxxxxxxxxx:role/sts_role --role-session-name "Session1"

AWS_STS_20

Now to set up the current session variables to use the session values returned during the assume role, we need to set 3 values using the export CLI command;

export AWS_SECRET_ACCESS_KEY= (SecretAccessKey)

export AWS_SECURITY_TOKEN= (SessionToken)

export AWS_ACCESS_KEY_ID= (AccessKeyId)

The values can be extracted from the JSON returned from the sts assume-role command shown above

AWS_STS_21

Now the CLI session has the permissions granted by STS in play and we can interrogate the contents of our S3 bucket.

aws_sts_22

Success!

So there we have it, a quick run through AWS Security Token Service and an example use case using the AWS CLI.

If you are building on AWS and are still drawing AWS VPC diagrams manually we would like to invite you to experience a better way. Hava fully automates the generation and updating of your AWS, Azure and GCP network infrastructure diagrams. Using Hava you can free yourself from drag and drop forever while enjoying clear and accurate cloud network topology diagrams whenever you need them.

You can take Hava for a test drive using the button below. No credit card required.

Try Hava For Free Today!

 

Sours: https://www.hava.io/blog/what-is-aws-security-token-service-sts

Using temporary credentials with AWS resources

You can use temporary security credentials to make programmatic requests for AWS resources using the AWS CLI or AWS API (using the AWS SDKs). The temporary credentials provide the same permissions that you have with use long-term security credentials such as IAM user credentials. However, there are a few differences:

  • When you make a call using temporary security credentials, the call must include a session token, which is returned along with those temporary credentials. AWS uses the session token to validate the temporary security credentials.

  • The temporary credentials expire after a specified interval. After the credentials expire, any calls that you make with those credentials will fail, so you must get a new set of credentials.

  • When you use temporary credentials to make a request, your principal might include a set of tags. These tags come from session tags and tags that are attached to the role that you assume. For more information about session tags, see Passing session tags in AWS STS.

If you are using the AWS SDKs, the AWS Command Line Interface (AWS CLI), or the Tools for Windows PowerShell, the way to get and use temporary security credentials differs with the context. If you are running code, AWS CLI, or Tools for Windows PowerShell commands inside an EC2 instance, you can take advantage of roles for Amazon EC2. Otherwise, you can call an AWS STS API to get the temporary credentials, and then use them explicitly to make calls to AWS services.

Note

You can use AWS Security Token Service (AWS STS) to create and provide trusted users with temporary security credentials that can control access to your AWS resources. For more information about AWS STS, see Temporary security credentials in IAM. AWS STS is a global service that has a default endpoint at . This endpoint is in the US East (Ohio) Region, although credentials that you get from this and other endpoints are valid globally. These credentials work with services and resources in any Region. You can also choose to make AWS STS API calls to endpoints in any of the supported Regions. This can reduce latency by making the requests from servers in a Region that is geographically closer to you. No matter which Region your credentials come from, they work globally. For more information, see Managing AWS STS in an AWS Region.

Using temporary credentials in Amazon EC2 instances

If you want to run AWS CLI commands or code inside an EC2 instance, the recommended way to get credentials is to use roles for Amazon EC2. You create an IAM role that specifies the permissions that you want to grant to applications that run on the EC2 instances. When you launch the instance, you associate the role with the instance.

Applications, AWS CLI, and Tools for Windows PowerShell commands that run on the instance can then get automatic temporary security credentials from the instance metadata. You do not have to explicitly get the temporary security credentials. The AWS SDKs, AWS CLI, and Tools for Windows PowerShell automatically get the credentials from the EC2 instance metadata service and use them. The temporary credentials have the permissions that you define for the role that is associated with the instance.

For more information and for examples, see the following:

Using temporary security credentials with the AWS SDKs

To use temporary security credentials in code, you programmatically call an AWS STS API like and extract the resulting credentials and session token. You then use those values as credentials for subsequent calls to AWS. The following example shows pseudocode for how to use temporary security credentials if you're using an AWS SDK:

For an example written in Python (using the AWS SDK for Python (Boto)), see Switching to an IAM role (AWS API). This example shows how to call to get temporary security credentials and then use those credentials to make a call to Amazon S3.

For details about how to call , , and other API operations, see the AWS Security Token Service API Reference. For information on getting the temporary security credentials and session token from the result, see the documentation for the SDK that you're working with. You can find the documentation for all the AWS SDKs on the main AWS documentation page, in the SDKs and Toolkits section.

You must make sure that you get a new set of credentials before the old ones expire. In some SDKs, you can use a provider that manages the process of refreshing credentials for you; check the documentation for the SDK you're using.

Using temporary security credentials with the AWS CLI

You can use temporary security credentials with the AWS CLI. This can be useful for testing policies.

Using the AWS CLI, you can call an AWS STS API like or and then capture the resulting output. The following example shows a call to that sends the output to a file. In the example, the parameter is assumed to be a profile in the AWS CLI configuration file. It is also assumed to reference credentials for an IAM user who has permissions to assume the role.

When the command is finished, you can extract the access key ID, secret access key, and session token from wherever you've routed it. You can do this either manually or by using a script. You can then assign these values to environment variables.

When you run AWS CLI commands, the AWS CLI looks for credentials in a specific order—first in environment variables and then in the configuration file. Therefore, after you've put the temporary credentials into environment variables, the AWS CLI uses those credentials by default. (If you specify a parameter in the command, the AWS CLI skips the environment variables. Instead, the AWS CLI looks in the configuration file, which lets you override the credentials in the environment variables if you need to.)

The following example shows how you might set the environment variables for temporary security credentials and then call an AWS CLI command. Because no parameter is included in the AWS CLI command, the AWS CLI looks for credentials first in environment variables and therefore uses the temporary credentials.

Linux

Windows

Using temporary security credentials with API operations

If you're making direct HTTPS API requests to AWS, you can sign those requests with the temporary security credentials that you get from the AWS Security Token Service (AWS STS). To do this, you use the access key ID and secret access key that you receive from AWS STS. You use the access key ID and secret access key the same way you would use long-term credentials to sign a request. You also add to your API request the session token that you receive from AWS STS. You add the session token to an HTTP header or to a query string parameter named . You add the session token to the HTTP header or the query string parameter, but not both. For more information about signing HTTPS API requests, see Signing AWS API Requests in the AWS General Reference.

More information

For more information about using AWS STS with other AWS services, see the following links:

Document Conventions

Requesting temporary security credentials

Controlling permissions for temporary security credentials

Sours: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html

Sts aws

Requesting temporary security credentials

To request temporary security credentials, you can use AWS Security Token Service (AWS STS) operations in the AWS API. These include operations to create and provide trusted users with temporary security credentials that can control access to your AWS resources. For more information about AWS STS, see Temporary security credentials in IAM. To learn about the different methods that you can use to request temporary security credentials by assuming a role, see Using IAM roles.

To call the API operations, you can use one of the AWS SDKs. The SDKs are available for a variety of programming languages and environments, including Java, .NET, Python, Ruby, Android, and iOS. The SDKs take care of tasks such as cryptographically signing your requests, retrying requests if necessary, and handling error responses. You can also use the AWS STS Query API, which is described in the AWS Security Token Service API Reference. Finally, two command line tools support the AWS STS commands: the AWS Command Line Interface, and the AWS Tools for Windows PowerShell.

The AWS STS API operations create a new session with temporary security credentials that include an access key pair and a session token. The access key pair consists of an access key ID and a secret key. Users (or an application that the user runs) can use these credentials to access your resources. You can create a role session and pass session policies and session tags programmatically using AWS STS API operations. The resulting session permissions are the intersection of the role's identity-based policies and the session policies. For more information about session policies, see Session policies. For more information about session tags, see Passing session tags in AWS STS.

Note

The size of the security token that AWS STS API operations return is not fixed. We strongly recommend that you make no assumptions about the maximum size. The typical token size is less than 4096 bytes, but that can vary.

Using AWS STS with AWS Regions

You can send AWS STS API calls either to a global endpoint or to one of the Regional endpoints. If you choose an endpoint closer to you, you can reduce latency and improve the performance of your API calls. You also can choose to direct your calls to an alternative Regional endpoint if you can no longer communicate with the original endpoint. If you are using one of the various AWS SDKs, then use that SDK method to specify a Region before you make the API call. If you manually construct HTTP API requests, then you must direct the request to the correct endpoint yourself. For more information, see the AWS STS section of Regions and Endpoints and Managing AWS STS in an AWS Region.

The following are the API operations that you can use to acquire temporary credentials for use in your AWS environment and applications.

AssumeRole—cross-account delegation and federation through a custom identity broker

The API operation is useful for allowing existing IAM users to access AWS resources that they don't already have access to. For example, the user might need access to resources in another AWS account. It is also useful as a means to temporarily gain privileged access—for example, to provide multi-factor authentication (MFA). You must call this API using existing IAM user credentials. For more information, see Creating a role to delegate permissions to an IAM user and Configuring MFA-protected API access.

This call must be made using valid AWS security credentials. When you make this call, you pass the following information:

  • The Amazon Resource Name (ARN) of the role that the app should assume.

  • (Optional) Duration, which specifies the duration of the temporary security credentials. Use the parameter to specify the duration of the role session from 900 seconds (15 minutes) up to the maximum session duration setting for the role. To learn how to view the maximum value for your role, see View the maximum session duration setting for a role. If you do not pass this parameter, the temporary credentials expire in one hour. The parameter from this API is separate from the HTTP parameter that you use to specify the duration of a console session. Use the HTTP parameter in the request to the federation endpoint for a console sign-in token. For more information, see Enabling custom identity broker access to the AWS console.

  • Role session name. Use this string value to identify the session when a role is used by different principals. For security purposes, administrators can view this field in AWS CloudTrail logs to help identify who performed an action in AWS. Your administrator might require that you specify your IAM user name as the session name when you assume the role. For more information, see sts:RoleSessionName.

  • (Optional) Source identity. You can require users to specify a source identity when they assume a role. After the source identity is set, the value cannot be changed. It is present in the request for all actions that are taken during the role session. The source identity value persists across chained role sessions. You can use source identity information in AWS CloudTrail logs to determine who took actions with a role. For more information about using source identity, see Monitor and control actions taken with assumed roles.

  • (Optional) Inline or managed session policies. These policies limit the permissions from the role's identity-based policy that are assigned to the role session. The resulting session's permissions are the intersection of the role's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see Session policies.

  • (Optional) Session tags. You can assume a role and then use the temporary credentials to make a request. When you do, the session's principal tags include the role's tags and the passed session tags. If you make this call using temporary credentials, the new session also inherits transitive session tags from the calling session. For more information about session tags, see Passing session tags in AWS STS.

  • (Optional) MFA information. If configured to use multi-factor authentication (MFA), then you include the identifier for an MFA device and the one-time code provided by that device.

  • (Optional) value that can be used when delegating access to your account to a third party. This value helps ensure that only the specified third party can access the role. For more information, see How to use an external ID when granting access to your AWS resources to a third party.

The following example shows a sample request and response using . This example request assumes the role for the specified duration with the included session policy, session tags, external ID, and source identity. The resulting session is named .

Example request

The policy value shown in the preceding example is the URL-encoded version of the following policy:

The parameter in the example is a placeholder for your signature. A signature is the authentication information that you must include with AWS HTTP API requests. We recommend using the AWS SDKs to create API requests, and one benefit of doing so is that the SDKs handle request signing for you. If you must create and sign API requests manually, see Signing AWS Requests By Using Signature Version 4 in the Amazon Web Services General Reference to learn how to sign a request.

In addition to the temporary security credentials, the response includes the Amazon Resource Name (ARN) for the federated user and the expiration time of the credentials.

Example response

Note

An AWS conversion compresses the passed session policies and session tags into a packed binary format that has a separate limit. Your request can fail for this limit even if your plaintext meets the other requirements. The response element indicates by percentage how close the policies and tags for your request are to the upper size limit.

AssumeRoleWithWebIdentity—federation through a web-based identity provider

The API operation returns a set of temporary security credentials for federated users who are authenticated through a public identity provider. Examples of public identity providers include Login with Amazon, Facebook, Google, or any OpenID Connect (OIDC)-compatible identity provider. This operation is useful for creating mobile applications or client-based web applications that require access to AWS. Using this operation means that your users do not need their own AWS or IAM identities. For more information, see About web identity federation.

Instead of directly calling , we recommend that you use Amazon Cognito and the Amazon Cognito credentials provider with the AWS SDKs for mobile development. For more information, see the following:

If you are not using Amazon Cognito, you call the action of AWS STS. This is an unsigned call, meaning that the app does not need to have access to any AWS security credentials to make the call. When you make this call, you pass the following information:

  • The Amazon Resource Name (ARN) of the role that the app should assume. If your app supports multiple ways for users to sign in, you must define multiple roles, one per identity provider. The call to should include the ARN of the role that is specific to the provider through which the user signed in.

  • The token that the app gets from the IdP after the app authenticates the user.

  • You can configure your IdP to pass attributes into your token as session tags.

  • (Optional) Duration, which specifies the duration of the temporary security credentials. Use the parameter to specify the duration of the role session from 900 seconds (15 minutes) up to the maximum session duration setting for the role. To learn how to view the maximum value for your role, see View the maximum session duration setting for a role. If you do not pass this parameter, the temporary credentials expire in one hour. The parameter from this API is separate from the HTTP parameter that you use to specify the duration of a console session. Use the HTTP parameter in the request to the federation endpoint for a console sign-in token. For more information, see Enabling custom identity broker access to the AWS console.

  • Role session name. Use this string value to identify the session when a role is used by different principals. For security purposes, administrators can view this field in AWS CloudTrail logs to learn who performed an action in AWS. Your administrator might require that you provide a specific value for the session name when you assume the role. For more information, see sts:RoleSessionName.

  • (Optional) Source identity. You can require federated users to specify a source identity when they assume a role. After the source identity is set, the value cannot be changed. It is present in the request for all actions that are taken during the role session. The source identity value persists across chained role sessions. You can use source identity information in AWS CloudTrail logs to determine who took actions with a role. For more information about using source identity, see Monitor and control actions taken with assumed roles.

  • (Optional) Inline or managed session policies. These policies limit the permissions from the role's identity-based policy that are assigned to the role session. The resulting session's permissions are the intersection of the role's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see Session policies.

    Note

    A call to is not signed (encrypted). Therefore, you should only include optional session policies if the request is transmitted through a trusted intermediary. In this case, someone could alter the policy to remove the restrictions.

When you call , AWS verifies the authenticity of the token. For example, depending on the provider, AWS might make a call to the provider and include the token that the app has passed. Assuming that the identity provider validates the token, AWS returns the following information to you:

  • A set of temporary security credentials. These consist of an access key ID, a secret access key, and a session token.

  • The role ID and the ARN of the assumed role.

  • A value that contains the unique user ID.

When you have the temporary security credentials, you can use them to make AWS API calls. This is the same process as making an AWS API call with long-term security credentials. The difference is that you must include the session token, which lets AWS verify that the temporary security credentials are valid.

Your app should cache the credentials. As noted, by default the credentials expire after an hour. If you don't use the AmazonSTSCredentialsProvider operation in the AWS SDK, it's up to you and your app to call again. Call this operation to get a new set of temporary security credentials before the old ones expire.

AssumeRoleWithSAML—federation through an enterprise Identity Provider compatible with SAML 2.0

The API operation returns a set of temporary security credentials for federated users who are authenticated by your organization's existing identity system. The users must also use SAML 2.0 (Security Assertion Markup Language) to pass authentication and authorization information to AWS. This API operation is useful in organizations that have integrated their identity systems (such as Windows Active Directory or OpenLDAP) with software that can produce SAML assertions. Such an integration provides information about user identity and permissions (such as Active Directory Federation Services or Shibboleth). For more information, see About SAML 2.0-based federation.

Note

A call to is not signed (encrypted). Therefore, you should only include optional session policies if the request is transmitted through a trusted intermediary. In this case, someone could alter the policy to remove the restrictions.

This is an unsigned call, which means that the app does not need to have access to any AWS security credentials in order to make the call. When you make this call, you pass the following information:

  • The Amazon Resource Name (ARN) of the role that the app should assume.

  • The ARN of the SAML provider created in IAM that describes the identity provider.

  • The SAML assertion, encoded in base64, that was provided by the SAML identity provider in its authentication response to the sign-in request from your app.

  • You can configure your IdP to pass attributes into your SAML assertion as session tags.

  • (Optional) Duration, which specifies the duration of the temporary security credentials. Use the parameter to specify the duration of the role session from 900 seconds (15 minutes) up to the maximum session duration setting for the role. To learn how to view the maximum value for your role, see View the maximum session duration setting for a role. If you do not pass this parameter, the temporary credentials expire in one hour. The parameter from this API is separate from the HTTP parameter that you use to specify the duration of a console session. Use the HTTP parameter in the request to the federation endpoint for a console sign-in token. For more information, see Enabling custom identity broker access to the AWS console.

  • (Optional) Inline or managed session policies. These policies limit the permissions from the role's identity-based policy that are assigned to the role session. The resulting session's permissions are the intersection of the role's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see Session policies.

  • Role session name. Use this string value to identify the session when a role is used by different principals. For security purposes, administrators can view this field in AWS CloudTrail logs to learn who performed an action in AWS. Your administrator might require that you provide a specific value for the session name when you assume the role. For more information, see sts:RoleSessionName.

  • (Optional) Source identity. You can require federated users to specify a source identity when they assume a role. After the source identity is set, the value cannot be changed. It is present in the request for all actions that are taken during the role session. The source identity value persists across chained role sessions. You can use source identity information in AWS CloudTrail logs to determine who took actions with a role. For more information about using source identity, see Monitor and control actions taken with assumed roles.

When you call , AWS verifies the authenticity of the SAML assertion. Assuming that the identity provider validates the assertion, AWS returns the following information to you:

  • A set of temporary security credentials. These consist of an access key ID, a secret access key, and a session token.

  • The role ID and the ARN of the assumed role.

  • An value that contains the value of the attribute of the element of the SAML assertion.

  • An value that contains the value of the element of the SAML assertion.

  • A element that contains a hash value built from the value, the AWS account ID, and the friendly name of the SAML provider. When combined with the element, they can uniquely identify the federated user.

  • A element that contains the value of the element in the element of the SAML assertion.

  • A element that indicates the format of the element. The value can be , , or the full URI from the and elements used in your SAML assertion. For information about the element's attribute, see Configuring SAML assertions for the authentication response.

When you have the temporary security credentials, you can use them to make AWS API calls. This is the same process as making an AWS API call with long-term security credentials. The difference is that you must include the session token, which lets AWS verify that the temporary security credentials are valid.

Your app should cache the credentials. By default the credentials expire after an hour. If you are not using the AmazonSTSCredentialsProvider action in the AWS SDK, it's up to you and your app to call again. Call this operation to get a new set of temporary security credentials before the old ones expire.

GetFederationToken—federation through a custom identity broker

The API operation returns a set of temporary security credentials for federated users. This API differs from in that the default expiration period is substantially longer (12 hours instead of one hour). Additionally, you can use the parameter to specify a duration for the temporary security credentials to remain valid. The resulting credentials are valid for the specified duration, between 900 seconds (15 minutes) to 129,600 seconds (36 hours).The longer expiration period can help reduce the number of calls to AWS because you do not need to get new credentials as often. For more information, see Requesting temporary security credentials.

When you make this request, you use the credentials of a specific IAM user. The permissions for the temporary security credentials are determined by the session policies that you pass when you call . The resulting session permissions are the intersection of the IAM user policies and the session policies that you pass. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the IAM user that is requesting federation. For more information about role session permissions, see Session policies.

When you use the temporary credentials that are returned by the operation, the session's principal tags include the user's tags and the passed session tags. For more information about session tags, see Passing session tags in AWS STS.

The call returns temporary security credentials that consist of the security token, access key, secret key, and expiration. You can use if you want to manage permissions inside your organization (for example, using the proxy application to assign permissions). To view a sample application that uses , go to Identity Federation Sample Application for an Active Directory Use Case in the AWS Sample Code & Libraries.

The following example shows a sample request and response that uses . This example request federates the calling user for the specified duration with the session policy ARN and session tags. The resulting session is named .

Example request

The policy ARN shown in the preceding example includes the following URL-encoded ARN:

Also, note that the parameter in the example is meant as a placeholder for the authentication information. This is the signature, which you must include with AWS HTTP API requests. We recommend using the AWS SDKs to create API requests, and one benefit of doing so is that the SDKs handle request signing for you. If you must create and sign API requests manually, go to Signing AWS Requests By Using Signature Version 4 in the Amazon Web Services General Reference to learn how to sign a request.

In addition to the temporary security credentials, the response includes the Amazon Resource Name (ARN) for the federated user and the expiration time of the credentials.

Example response

Note

An AWS conversion compresses the passed session policies and session tags into a packed binary format that has a separate limit. Your request can fail for this limit even if your plaintext meets the other requirements. The response element indicates by percentage how close the policies and tags for your request are to the upper size limit.

AWS recommends that you grant permissions at the resource level (for example, you attach a resource-based policy to an Amazon S3 bucket), you can omit the parameter. However, if you do not include a policy for the federated user, the temporary security credentials will not grant any permissions. In this case, you must use resource policies to grant the federated user access to your AWS resources.

For example, assume your AWS account number is 111122223333, and you have an Amazon S3 bucket that you want to allow Susan to access. Susan's temporary security credentials don't include a policy for the bucket. In that case, you would need to ensure that the bucket has a policy with an ARN that matches Susan's ARN, such as .

GetSessionToken—temporary credentials for users in untrusted environments

The API operation returns a set of temporary security credentials to an existing IAM user. This is useful for providing enhanced security, such as allowing AWS requests only when MFA is enabled for the IAM user. Because the credentials are temporary, they provide enhanced security when you have an IAM user who accesses your resources through a less secure environment. Examples of less secure environments include a mobile device or web browser. For more information, see Requesting temporary security credentials or GetSessionToken in the AWS Security Token Service API Reference.

By default, temporary security credentials for an IAM user are valid for a maximum of 12 hours. But you can request a duration as short as 15 minutes or as long as 36 hours using the parameter. For security reasons, a token for an AWS account root user is restricted to a duration of one hour.

returns temporary security credentials consisting of a security token, an access key ID, and a secret access key. The following example shows a sample request and response using . The response also includes the expiration time of the temporary security credentials.

Example request

The parameter in the example is a placeholder for your signature. A signature is the authentication information that you must include with AWS HTTP API requests. We recommend using the AWS SDKs to create API requests, and one benefit of doing so is that the SDKs handle request signing for you. If you must create and sign API requests manually, go to Signing AWS Requests By Using Signature Version 4 in the Amazon Web Services General Reference to learn how to sign a request.

Example response

Optionally, the request can include and values for AWS multi-factor authentication (MFA) verification. If the provided values are valid, AWS STS provides temporary security credentials that include the state of MFA authentication. The temporary security credentials can then be used to access the MFA-protected API operations or AWS websites for as long as the MFA authentication is valid.

The following example shows a request that includes an MFA verification code and device serial number.

Note

The call to AWS STS can be to the global endpoint or to any of the Regional endpoints that you activate your AWS account. For more information, see the AWS STS section of Regions and Endpoints.

The parameter in the example is a placeholder for your signature. A signature is the authentication information that you must include with AWS HTTP API requests. We recommend using the AWS SDKs to create API requests, and one benefit of doing so is that the SDKs handle request signing for you. If you must create and sign API requests manually, see Signing AWS Requests By Using Signature Version 4 in the Amazon Web Services General Reference to learn how to sign a request.

Comparing the AWS STS API operations

The following table compares features of the API operations in AWS STS that return temporary security credentials. To learn about the different methods you can use to request temporary security credentials by assuming a role, see Using IAM roles. To learn about the different AWS STS API operations that allow you to pass session tags, see Passing session tags in AWS STS.

AWS STS APIWho can callCredential lifetime (min | max | default)MFA support¹ Session policy support² Restrictions on resulting temporary credentials
AssumeRoleIAM user or IAM role with existing temporary security credentials 15 m | Maximum session duration setting³ | 1 hr Yes Yes

Cannot call or .

AssumeRoleWithSAMLAny user; caller must pass a SAML authentication response that indicates authentication from a known identity provider 15 m | Maximum session duration setting³ | 1 hr NoYes

Cannot call or .

AssumeRoleWithWebIdentityAny user; caller must pass a web identity token that indicates authentication from a known identity provider 15 m | Maximum session duration setting³ | 1 hr NoYes

Cannot call or .

GetFederationTokenIAM user or AWS account root user

IAM user: 15 m | 36 hr | 12 hr

Root user: 15 m | 1 hr | 1 hr

No Yes

Cannot call IAM operations using the AWS CLI or AWS API.

Cannot call AWS STS operations except .⁴

SSO to console is allowed.⁵

GetSessionTokenIAM user or AWS account root user

IAM user: 15 m | 36 hr | 12 hr

Root user: 15 m | 1 hr | 1 hr

Yes No

Cannot call IAM API operations unless MFA information is included with the request.

Cannot call AWS STS API operations except or .

SSO to console is not allowed.⁶

¹ MFA support. You can include information about a multi-factor authentication (MFA) device when you call the AssumeRole and GetSessionToken API operations. This ensures that the temporary security credentials that result from the API call can be used only by users who are authenticated with an MFA device. For more information, see Configuring MFA-protected API access.

² Session policy support. Session policies are policies that you pass as a parameter when you programmatically create a temporary session for a role or federated user. This policy limits the permissions from the role or user's identity-based policy that are assigned to the session. The resulting session's permissions are the intersection of the entity's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see Session policies.

³ Maximum session duration setting. Use the parameter to specify the duration of your role session from 900 seconds (15 minutes) up to the maximum session duration setting for the role. To learn how to view the maximum value for your role, see View the maximum session duration setting for a role.

GetCallerIdentity. No permissions are required to perform this operation. If an administrator adds a policy to your IAM user or role that explicitly denies access to the action, you can still perform this operation. Permissions are not required because the same information is returned when an IAM user or role is denied access. To view an example response, see I am not authorized to perform: iam:DeleteVirtualMFADevice.

Single sign-on (SSO) to the console. To support SSO, AWS lets you call a federation endpoint () and pass temporary security credentials. The endpoint returns a token that you can use to construct a URL that signs a user directly into the console without requiring a password. For more information, see Enabling SAML 2.0 federated users to access the AWS Management Console and How to Enable Cross-Account Access to the AWS Management Console in the AWS Security Blog.

⁶ After you retrieve your temporary credentials, you can't access the AWS Management Console by passing the credentials to the federation single sign-on endpoint. For more information, see Enabling custom identity broker access to the AWS console.

Sours: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html

Getting Temporary Credentials with AWS STS

+

+

The duration of temporary credentials can range from 900 seconds (15 minutes) to 129600 seconds (36 hours) for IAM users. If a duration isn’t specified, then 43200 seconds (12 hours) is used by default.

+

For a root AWS account, the valid range of temporary credentials is from 900 to 3600 seconds (1 hour), with a default value of 3600 seconds if no duration is specified.

+ IMPORTANT: It is strongly recommended, from a security standpoint, that you use IAM users instead of the root account for AWS access. For more information, see IAM Best Practices in the IAM User Guide. . Call getSessionToken on the STS client to get a session token, using the object:

+

  1. Get session credentials using the result of the call to :

The session credentials provide access only for the duration that was specified by the object. Once the credentials expire, you will need to call again to obtain a new session token for continued access to AWS.

== Use the temporary credentials to access Amazon resources

Once you have temporary security credentials, you can use them to initialize an AWS service client to use its resources, using the technique described in Explicitly Specifying Credentials.

For example, to create an S3 client using temporary service credentials:

You can now use the object to make Amazon S3 requests.

== For more information

For more information about how to use temporary security credentials to access AWS resources, visit the following sections in the IAM User Guide:

Sours: https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/prog-services-sts.html

Now discussing:

sts¶

Note: You are viewing the documentation for an older major version of the AWS CLI (version 1).

AWS CLI version 2, the latest major version of AWS CLI, is now stable and recommended for general use. To view this page for the AWS CLI version 2, click here. For more information see the AWS CLI version 2 installation instructions and migration guide.

[ aws ]

Description¶

Security Token Service (STS) enables you to request temporary, limited-privilege credentials for Identity and Access Management (IAM) users or for users that you authenticate (federated users). This guide provides descriptions of the STS API. For more information about using this service, see Temporary Security Credentials .

Sours: https://docs.aws.amazon.com/cli/latest/reference/sts/


676 677 678 679 680