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

💖 VM::EC2::Security::Token — the whole tea ☕

okay bestie, gather round, because we're talking about VM::EC2::Security::Token (the page is filed under VM::EC...:Token(3pm), iykyk, the filename's just a little ✨abbreviated✨ because Perl manpages are dramatic like that). This is the Temporary security token object and it's genuinely iconic.

---

✨ SYNOPSIS ✨

the vibe, in code:

use VM::EC2;
use VM::EC2::Security::Policy

# under your account
$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);
print $token->sessionToken,"\n";
print $token->accessKeyId,"\n";
print $token->secretAccessKey,"\n";
print $token->federatedUser,"\n";

my $serialized = $token->credentials->serialize;

# get the serialized token to the temporary user
send_data_to_user_somehow($serialized);

# under the temporary user's account
my $serialized = get_data_somehow();

# create a copy of the token from its serialized form
my $token = VM::EC2::Security::Credentials->new_from_serialized($serialized);

# open a new EC2 connection with this token. User will be
# able to run all the methods specified in the policy.
my $ec2   = VM::EC2->new(-security_token => $token);
print $ec2->describe_images(-owner=>'self');

# convenience routine; will return a VM::EC2 object authorized
# to use the current token
my $ec2   = $token->new_ec2;
print $ec2->describe_images(-owner=>'self');

(no, bestie, I'm not adding the missing semicolon after use VM::EC2::Security::Policy — that's exactly how the original wrote it and we do not touch the facts 💅)

---

🌸 DESCRIPTION 🌸

so like. VM::EC2::Security::Token objects let you grant a user access to some or all of your EC2 resources for a limited period of time. the gag is, that user does not have to have their own AWS account. rent-free access, periodt. 🎀

you get these token objects from calls to VM::EC2->get_federation_token() and get_session_token(). here's the difference, because it matters:

• get_federation_token() — makes a temporary user whose privileges are restricted to exactly the stuff listed in the accompanying policy (which is a VM::EC2::Security::Policy object).
• get_session_token() — this one works with multi-factor authentication devices, like smart cards. tokens from this call are not tied to a user account and not tied to a policy, and they grant privileges to all EC2 actions and resources. yes, all of them. main character energy fr.

both federation tokens and session tokens have an expiry time between a few seconds and 36 hours.

inside the token there's a VM::EC2::Security::Credentials object, and it holds the temporary secret access key, the access key ID, and a session token string that unlocks the access key 🔑. that credentials object can be serialized into a form that's suitable for sending to a user over a secure channel — think SSL or S/MIME e-mail — and then unserialized at the receiving end into a copy of the original credentials object. it's giving ✨mail it in a locked box✨.

and either the token object itself, or the credentials object inside it, can be passed to VM::EC2->new() via the -security_token parameter so you can actually get at your EC2 resources. 🫶

---

🦋 METHODS 🦋

• credentials() — the VM::EC2::Security::Credentials object that contains the session token, the access key ID, and the secret key. the lil treasure chest 🎁
• federatedUser() — the VM::EC2::Security::FederatedUser object, which has the info about the temporary user account.
• packedPolicySize() — a percentage value showing how big the policy is in packed form relative to the maximum allowed size. heads up: policies in excess of 100% get rejected by the service. 😭
• secret_access_key() — convenience method that calls the credentials object's secret_access_key() method.
• access_key_id() — convenience method that calls the credentials object's access_key_id() method.
• session_token() — convenience method that calls the credentials object's session_token() method.
• new_ec2(@args) — convenience method that returns a VM::EC2 object authorized with the current token. you can pass any of the arguments that VM::EC2->new() accepts, except that -access_key and -secret_key will be ignored if present. noted 📝

---

💜 STRING OVERLOADING 💜

when you use this object in a string context, it interpolates as the session token, and you can use it for the -security_token parameter in VM::EC2->new(). that's it, that's the whole section, and honestly? slay. ✨

---

👑 SEE ALSO 👑

• VM::EC2
• VM::EC2::Generic
• VM::EC2::Security::Credentials
• VM::EC2::Security::FederatedUser

---

🌈 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 page bestie 💖 this one's from perl v5.38.2, dated 2024-08-10, so go forth and hand out temporary credentials responsibly. mwah. 🎀🦋🌸