Making requests using IAM user temporary credentials - Amazon Simple Storage Service

Making requests using IAM user temporary credentials

An AWS account or an IAM user can request temporary security credentials and use them to send authenticated requests to Amazon S3. This section provides examples of how to use the AWS SDK for Java, .NET, and PHP to obtain temporary security credentials and use them to authenticate your requests to Amazon S3.

Java

An IAM user or an AWS account can request temporary security credentials (see Making requests) using the AWS SDK for Java and use them to access Amazon S3. These credentials expire after the specified session duration.

By default, the session duration is one hour. If you use IAM user credentials, you can specify the duration when requesting the temporary security credentials from 15 minutes to the maximum session duration for the role. For more information about temporary security credentials, see Temporary Security Credentials in the IAM User Guide. For more information about making requests, see Making requests.

To get temporary security credentials and access Amazon S3
  1. Create an instance of the AWSSecurityTokenService class. For information about providing credentials, see Developing with Amazon S3 using the AWS SDKs, and explorers.

  2. Retrieve the temporary security credentials for the desired role by calling the assumeRole() method of the Security Token Service (STS) client.

  3. Package the temporary security credentials into a BasicSessionCredentials object. You use this object to provide the temporary security credentials to your Amazon S3 client.

  4. Create an instance of the AmazonS3Client class using the temporary security credentials. You send requests to Amazon S3 using this client. If you send requests using expired credentials, Amazon S3 will return an error.

Note

If you obtain temporary security credentials using your AWS account security credentials, the temporary credentials are valid for only one hour. You can specify the session duration only if you use IAM user credentials to request a session.

The following example lists a set of object keys in the specified bucket. The example obtains temporary security credentials for a session and uses them to send an authenticated request to Amazon S3.

If you want to test the sample by using IAM user credentials, you must create an IAM user under your AWS account. For more information about how to create an IAM user, see Creating Your First IAM user and Administrators Group in the IAM User Guide.

For instructions on creating and testing a working sample, see Testing the Amazon S3 Java Code Examples.

import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.auth.AWSStaticCredentialsProvider; import com.amazonaws.auth.BasicSessionCredentials; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.model.ObjectListing; import com.amazonaws.services.securitytoken.AWSSecurityTokenService; import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClientBuilder; import com.amazonaws.services.securitytoken.model.AssumeRoleRequest; import com.amazonaws.services.securitytoken.model.AssumeRoleResult; import com.amazonaws.services.securitytoken.model.Credentials; public class MakingRequestsWithIAMTempCredentials { public static void main(String[] args) { String clientRegion = "*** Client region ***"; String roleARN = "*** ARN for role to be assumed ***"; String roleSessionName = "*** Role session name ***"; String bucketName = "*** Bucket name ***"; try { // Creating the STS client is part of your trusted code. It has // the security credentials you use to obtain temporary security credentials. AWSSecurityTokenService stsClient = AWSSecurityTokenServiceClientBuilder.standard() .withCredentials(new ProfileCredentialsProvider()) .withRegion(clientRegion) .build(); // Obtain credentials for the IAM role. Note that you cannot assume the role of // an AWS root account; // Amazon S3 will deny access. You must use credentials for an IAM user or an // IAM role. AssumeRoleRequest roleRequest = new AssumeRoleRequest() .withRoleArn(roleARN) .withRoleSessionName(roleSessionName); AssumeRoleResult roleResponse = stsClient.assumeRole(roleRequest); Credentials sessionCredentials = roleResponse.getCredentials(); // Create a BasicSessionCredentials object that contains the credentials you // just retrieved. BasicSessionCredentials awsCredentials = new BasicSessionCredentials( sessionCredentials.getAccessKeyId(), sessionCredentials.getSecretAccessKey(), sessionCredentials.getSessionToken()); // Provide temporary security credentials so that the Amazon S3 client // can send authenticated requests to Amazon S3. You create the client // using the sessionCredentials object. AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withCredentials(new AWSStaticCredentialsProvider(awsCredentials)) .withRegion(clientRegion) .build(); // Verify that assuming the role worked and the permissions are set correctly // by getting a set of object keys from the bucket. ObjectListing objects = s3Client.listObjects(bucketName); System.out.println("No. of Objects: " + objects.getObjectSummaries().size()); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it, so it returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } }
.NET

An IAM user or an AWS account can request temporary security credentials using the AWS SDK for .NET and use them to access Amazon S3. These credentials expire after the session duration.

By default, the session duration is one hour. If you use IAM user credentials, you can specify the duration when requesting the temporary security credentials from 15 minutes to the maximum session duration for the role. For more information about temporary security credentials, see Temporary Security Credentials in the IAM User Guide. For more information about making requests, see Making requests.

To get temporary security credentials and access Amazon S3
  1. Create an instance of the AWS Security Token Service client, AmazonSecurityTokenServiceClient. For information about providing credentials, see Developing with Amazon S3 using the AWS SDKs, and explorers.

  2. Start a session by calling the GetSessionToken method of the STS client you created in the preceding step. You provide session information to this method using a GetSessionTokenRequest object.

    The method returns your temporary security credentials.

  3. Package the temporary security credentials in an instance of the SessionAWSCredentials object. You use this object to provide the temporary security credentials to your Amazon S3 client.

  4. Create an instance of the AmazonS3Client class by passing in the temporary security credentials. You send requests to Amazon S3 using this client. If you send requests using expired credentials, Amazon S3 returns an error.

Note

If you obtain temporary security credentials using your AWS account security credentials, those credentials are valid for only one hour. You can specify a session duration only if you use IAM user credentials to request a session.

The following C# example lists object keys in the specified bucket. For illustration, the example obtains temporary security credentials for a default one-hour session and uses them to send authenticated request to Amazon S3.

If you want to test the sample by using IAM user credentials, you must create an IAM user under your AWS account. For more information about how to create an IAM user, see Creating Your First IAM user and Administrators Group in the IAM User Guide. For more information about making requests, see Making requests.

For instructions on creating and testing a working example, see Running the Amazon S3 .NET Code Examples.

using Amazon; using Amazon.Runtime; using Amazon.S3; using Amazon.S3.Model; using Amazon.SecurityToken; using Amazon.SecurityToken.Model; using System; using System.Collections.Generic; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class TempCredExplicitSessionStartTest { private const string bucketName = "*** bucket name ***"; // Specify your bucket region (an example region is shown). private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2; private static IAmazonS3 s3Client; public static void Main() { ListObjectsAsync().Wait(); } private static async Task ListObjectsAsync() { try { // Credentials use the default AWS SDK for .NET credential search chain. // On local development machines, this is your default profile. Console.WriteLine("Listing objects stored in a bucket"); SessionAWSCredentials tempCredentials = await GetTemporaryCredentialsAsync(); // Create a client by providing temporary security credentials. using (s3Client = new AmazonS3Client(tempCredentials, bucketRegion)) { var listObjectRequest = new ListObjectsRequest { BucketName = bucketName }; // Send request to Amazon S3. ListObjectsResponse response = await s3Client.ListObjectsAsync(listObjectRequest); List<S3Object> objects = response.S3Objects; Console.WriteLine("Object count = {0}", objects.Count); } } catch (AmazonS3Exception s3Exception) { Console.WriteLine(s3Exception.Message, s3Exception.InnerException); } catch (AmazonSecurityTokenServiceException stsException) { Console.WriteLine(stsException.Message, stsException.InnerException); } } private static async Task<SessionAWSCredentials> GetTemporaryCredentialsAsync() { using (var stsClient = new AmazonSecurityTokenServiceClient()) { var getSessionTokenRequest = new GetSessionTokenRequest { DurationSeconds = 7200 // seconds }; GetSessionTokenResponse sessionTokenResponse = await stsClient.GetSessionTokenAsync(getSessionTokenRequest); Credentials credentials = sessionTokenResponse.Credentials; var sessionCredentials = new SessionAWSCredentials(credentials.AccessKeyId, credentials.SecretAccessKey, credentials.SessionToken); return sessionCredentials; } } } }
PHP

This example assumes that you are already following the instructions for Using the AWS SDK for PHP and Running PHP Examples and have the AWS SDK for PHP properly installed.

An IAM user or an AWS account can request temporary security credentials using version 3 of the AWS SDK for PHP. It can then use the temporary credentials to access Amazon S3. The credentials expire when the session duration expires.

By default, the session duration is one hour. If you use IAM user credentials, you can specify the duration when requesting the temporary security credentials from 15 minutes to the maximum session duration for the role. For more information about temporary security credentials, see Temporary Security Credentials in the IAM User Guide. For more information about making requests, see Making requests.

Note

If you obtain temporary security credentials using your AWS account security credentials, the temporary security credentials are valid for only one hour. You can specify the session duration only if you use IAM user credentials to request a session.

The following PHP example lists object keys in the specified bucket using temporary security credentials. The example obtains temporary security credentials for a default one-hour session, and uses them to send authenticated request to Amazon S3. For information about running the PHP examples in this guide, see Running PHP Examples.

If you want to test the example by using IAM user credentials, you must create an IAM user under your AWS account. For information about how to create an IAM user, see Creating Your First IAM user and Administrators Group in the IAM User Guide. For examples of setting the session duration when using IAM user credentials to request a session, see Making requests using IAM user temporary credentials .

require 'vendor/autoload.php'; use Aws\S3\Exception\S3Exception; use Aws\S3\S3Client; use Aws\Sts\StsClient; $bucket = '*** Your Bucket Name ***'; $sts = new StsClient([ 'version' => 'latest', 'region' => 'us-east-1' ]); $sessionToken = $sts->getSessionToken(); $s3 = new S3Client([ 'region' => 'us-east-1', 'version' => 'latest', 'credentials' => [ 'key' => $sessionToken['Credentials']['AccessKeyId'], 'secret' => $sessionToken['Credentials']['SecretAccessKey'], 'token' => $sessionToken['Credentials']['SessionToken'] ] ]); $result = $s3->listBuckets(); try { // Retrieve a paginator for listing objects. $objects = $s3->getPaginator('ListObjects', [ 'Bucket' => $bucket ]); echo "Keys retrieved!" . PHP_EOL; // List objects foreach ($objects as $object) { echo $object['Key'] . PHP_EOL; } } catch (S3Exception $e) { echo $e->getMessage() . PHP_EOL; }
Ruby

An IAM user or an AWS account can request temporary security credentials using AWS SDK for Ruby and use them to access Amazon S3. These credentials expire after the session duration.

By default, the session duration is one hour. If you use IAM user credentials, you can specify the duration when requesting the temporary security credentials from 15 minutes to the maximum session duration for the role. For more information about temporary security credentials, see Temporary Security Credentials in the IAM User Guide. For more information about making requests, see Making requests.

Note

If you obtain temporary security credentials using your AWS account security credentials, the temporary security credentials are valid for only one hour. You can specify session duration only if you use IAM user credentials to request a session.

The following Ruby example creates a temporary user to list the items in a specified bucket for one hour. To use this example, you must have AWS credentials that have the necessary permissions to create new AWS Security Token Service (AWS STS) clients, and list Amazon S3 buckets.

# Prerequisites: # - A user in AWS Identity and Access Management (IAM). This user must # be able to assume the following IAM role. You must run this code example # within the context of this user. # - An existing role in IAM that allows all of the Amazon S3 actions for all of the # resources in this code example. This role must also trust the preceding IAM user. # - An existing S3 bucket. require "aws-sdk-core" require "aws-sdk-s3" require "aws-sdk-iam" # Checks whether a user exists in IAM. # # @param iam [Aws::IAM::Client] An initialized IAM client. # @param user_name [String] The user's name. # @return [Boolean] true if the user exists; otherwise, false. # @example # iam_client = Aws::IAM::Client.new(region: 'us-west-2') # exit 1 unless user_exists?(iam_client, 'my-user') def user_exists?(iam_client, user_name) response = iam_client.get_user(user_name: user_name) return true if response.user.user_name rescue Aws::IAM::Errors::NoSuchEntity # User doesn't exist. rescue StandardError => e puts "Error while determining whether the user " \ "'#{user_name}' exists: #{e.message}" end # Creates a user in IAM. # # @param iam_client [Aws::IAM::Client] An initialized IAM client. # @param user_name [String] The user's name. # @return [AWS:IAM::Types::User] The new user. # @example # iam_client = Aws::IAM::Client.new(region: 'us-west-2') # user = create_user(iam_client, 'my-user') # exit 1 unless user.user_name def create_user(iam_client, user_name) response = iam_client.create_user(user_name: user_name) return response.user rescue StandardError => e puts "Error while creating the user '#{user_name}': #{e.message}" end # Gets a user in IAM. # # @param iam_client [Aws::IAM::Client] An initialized IAM client. # @param user_name [String] The user's name. # @return [AWS:IAM::Types::User] The existing user. # @example # iam_client = Aws::IAM::Client.new(region: 'us-west-2') # user = get_user(iam_client, 'my-user') # exit 1 unless user.user_name def get_user(iam_client, user_name) response = iam_client.get_user(user_name: user_name) return response.user rescue StandardError => e puts "Error while getting the user '#{user_name}': #{e.message}" end # Checks whether a role exists in IAM. # # @param iam_client [Aws::IAM::Client] An initialized IAM client. # @param role_name [String] The role's name. # @return [Boolean] true if the role exists; otherwise, false. # @example # iam_client = Aws::IAM::Client.new(region: 'us-west-2') # exit 1 unless role_exists?(iam_client, 'my-role') def role_exists?(iam_client, role_name) response = iam_client.get_role(role_name: role_name) return true if response.role.role_name rescue StandardError => e puts "Error while determining whether the role " \ "'#{role_name}' exists: #{e.message}" end # Gets credentials for a role in IAM. # # @param sts_client [Aws::STS::Client] An initialized AWS STS client. # @param role_arn [String] The role's Amazon Resource Name (ARN). # @param role_session_name [String] A name for this role's session. # @param duration_seconds [Integer] The number of seconds this session is valid. # @return [AWS::AssumeRoleCredentials] The credentials. # @example # sts_client = Aws::STS::Client.new(region: 'us-west-2') # credentials = get_credentials( # sts_client, # 'arn:aws:iam::123456789012:role/AmazonS3ReadOnly', # 'ReadAmazonS3Bucket', # 3600 # ) # exit 1 if credentials.nil? def get_credentials(sts_client, role_arn, role_session_name, duration_seconds) Aws::AssumeRoleCredentials.new( client: sts_client, role_arn: role_arn, role_session_name: role_session_name, duration_seconds: duration_seconds ) rescue StandardError => e puts "Error while getting credentials: #{e.message}" end # Checks whether a bucket exists in Amazon S3. # # @param s3_client [Aws::S3::Client] An initialized Amazon S3 client. # @param bucket_name [String] The name of the bucket. # @return [Boolean] true if the bucket exists; otherwise, false. # @example # s3_client = Aws::S3::Client.new(region: 'us-west-2') # exit 1 unless bucket_exists?(s3_client, 'doc-example-bucket') def bucket_exists?(s3_client, bucket_name) response = s3_client.list_buckets response.buckets.each do |bucket| return true if bucket.name == bucket_name end rescue StandardError => e puts "Error while checking whether the bucket '#{bucket_name}' " \ "exists: #{e.message}" end # Lists the keys and ETags for the objects in an Amazon S3 bucket. # # @param s3_client [Aws::S3::Client] An initialized Amazon S3 client. # @param bucket_name [String] The bucket's name. # @return [Boolean] true if the objects were listed; otherwise, false. # @example # s3_client = Aws::S3::Client.new(region: 'us-west-2') # exit 1 unless list_objects_in_bucket?(s3_client, 'doc-example-bucket') def list_objects_in_bucket?(s3_client, bucket_name) puts "Accessing the contents of the bucket named '#{bucket_name}'..." response = s3_client.list_objects_v2( bucket: bucket_name, max_keys: 50 ) if response.count.positive? puts "Contents of the bucket named '#{bucket_name}' (first 50 objects):" puts "Name => ETag" response.contents.each do |obj| puts "#{obj.key} => #{obj.etag}" end else puts "No objects in the bucket named '#{bucket_name}'." end return true rescue StandardError => e puts "Error while accessing the bucket named '#{bucket_name}': #{e.message}" end

Related resources