VM::EC...y_token(3pm)

💖 VM::EC2::REST::security_token 💖

okay so this whole page is the manual for VM::EC2::REST::security_token, and it lives in the User Contributed Perl Documentation corner of the world (which is where the community puts its stuff, and yes it slays). it's all about AWS security tokens and honestly? iconic.

---

✨ NAME ✨

VM::EC2::REST::security_token — AWS security tokens 🎀

✨ SYNOPSIS ✨

use VM::EC2 qw(:standard);

---

🌈 EC2 REGIONS AND AVAILABILITY ZONES 🌈

(no bestie i don't know why it's called that either, the heading just IS that, we respect it 💅)

so, AWS security tokens are the move when you want to hand someone temporary access to the resources in your EC2 space without giving them a whole permanent account. they're also literally the foundation for mobile services and for multifactor authentication devices (MFA). no cap.

pair them up with VM::EC2::Security::Policy and VM::EC2::Security::Credentials and you can spin up a temporary user who's authenticated for a limited length of time, then pass those credentials to them over a secure channel. then they make a credentials object and go touch your AWS resources. 🫶

here's the example, verbatim, because it's perfect:

# on your side of the connection
$ec2 = VM::EC2->new(...);  # as usual
my $policy = VM::EC2::Security::Policy->new;
$policy->allow('DescribeImages','RunInstances');
my $token = $ec2->get_federation_token(-name     => 'TemporaryUser',
                                       -duration => 60*60*3, # 3 hrs, as seconds
                                       -policy   => $policy);
my $serialized = $token->credentials->serialize;
send_data_to_user_somehow($serialized);

# on the temporary user's side of the connection
my $serialized = get_data_somehow();
my $token = VM::EC2::Security::Credentials->new_from_serialized($serialized);
my $ec2   = VM::EC2->new(-security_token => $token);
print $ec2->describe_images(-owner=>'self');

and if your temporary user isn't out here using the Perl VM::EC2 API at all? no worries, you can just transmit the fields one by one:

my $credentials   = $token->credentials;
my $access_key_id = $credentials->accessKeyId;
my $secret_key    = $credentials->secretKey;
my $session_token = $credentials->sessionToken;
send_data_to_user_somehow($session_token,
                          $access_key_id,
                          $secret_key);

calls to get_federation_token() hand you back a VM::EC2::Security::Token object. that object is basically carrying two sub-objects: a VM::EC2::Security::Credentials object and a VM::EC2::Security::FederatedUser object. the Credentials one has the temporary access key ID, secret access key, and session token — together those authenticate you to the EC2 API. the FederatedUser one has the temporary user's account name and ID. ✨

go read VM::EC2::Security::Token, VM::EC2::Security::FederatedUser, VM::EC2::Security::Credentials, and VM::EC2::Security::Policy for more.

Implemented:

• GetFederationToken
• GetSessionToken

Unimplemented:

• (none) — literally nothing missing, we ate 🍓

💫 $token = $ec2->get_federation_token($username)

💫 $token = $ec2->get_federation_token(-name=>$username,@args)

this method makes a brand new temporary user under the username you give it, and returns a VM::EC2::Security::Token object holding temporary credentials for that user plus info about their account. the other options let you control how long the credentials stay valid, and the policy that decides what resources the user is allowed to touch. 👑

Required arguments:

• -name — the username. that's the one you can't skip.

the username has to follow the guidelines in http://docs.amazonwebservices.com/IAM/latest/UserGuide/LimitationsOnEntities.html: basically all alphanumeric characters plus the characters [+=,.@-].

Optional arguments:

• -duration_seconds — how long the session token will be valid for, expressed in seconds.
• -duration — same thing, faster to type.
• -policy — a VM::EC2::Security::Policy object, or a JSON string complying with the IAM policy syntax.

the duration can't be shorter than 1 hour (3600 seconds) and can't be longer than 36 hours (129600 seconds). if you don't specify a duration, Amazon defaults to 12 hours. and if you don't provide a policy? then your user literally cannot execute any actions. 😭 nothing. zero. nada.

also heads up bestie: if your temporary user wants to create a VM::EC2 object and name a region at create time (like VM::EC2->new(-region=>'us-west-1')), then that user must have access to the DescribeRegions action:

$policy->allow('DescribeRegions')

otherwise the call to new() will fail. fr fr.

💫 $token = $ec2->get_session_token(%args)

this one creates a temporary VM::EC2::Security::Token object for an anonymous user. the token has no policy attached to it, and it can be used to run any of the EC2 actions available to the user who created the token. the optional arguments let the session token be used together with MFA devices. 🦋

Required arguments:

• none 🙈

Optional arguments:

• -duration_seconds — how long the session token will be valid for, expressed in seconds.
• -duration — same thing, faster to type.
• -serial_number — the identification number of the user's MFA device, if any.
• -token_code — the code provided by the MFA device, if any.

if no duration is specified, Amazon defaults to 12 hours.

for info on using AWS together with MFA devices, go see http://docs.amazonwebservices.com/IAM/latest/UserGuide/Using_ManagingMFA.html. ✨

---

👀 SEE ALSO 👀

VM::EC2

💜 AUTHOR 💜

Lincoln Stein <lincoln.stein@gmail.com>.

Copyright (c) 2011 Ontario Institute for Cancer Research

This package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL (either version 1, or at your option, any later version) or the Artistic License 2.0. Refer to LICENSE for the full license text. In addition, please see DISCLAIMER.txt for disclaimers of warranty.

---

and that's the whole thing bestie, no notes. this page was brought to you by perl v5.38.2, dated 2024-08-10 — go forth and federate those tokens responsibly. 💅🌸💖