1VM::EC2::REST::securityU_steorkeCno(n3t)ributed Perl DocVuMm:e:nEtCa2t:i:oRnEST::security_token(3)
2
7 use VM::EC2 qw(:standard);
8
10 AWS security tokens provide a way to grant temporary access to
11 resources in your EC2 space without giving them permanent accounts.
12 They also provide the foundation for mobile services and multifactor
13 authentication devices (MFA).
14 Used in conjunction with VM::EC2::Security::Policy and
16 VM::EC2::Security::Credentials, you can create a temporary user who is
17 authenticated for a limited length of time and pass the credentials to
18 him or her via a secure channel. He or she can then create a
19 credentials object to access your AWS resources.
20 Here is an example:
22 # on your side of the connection
24 $ec2 = VM::EC2->new(...); # as usual
25 my $policy = VM::EC2::Security::Policy->new;
26 $policy->allow('DescribeImages','RunInstances');
27 my $token = $ec2->get_federation_token(-name => 'TemporaryUser',
28 -duration => 60*60*3, # 3 hrs, as seconds
29 -policy => $policy);
30 my $serialized = $token->credentials->serialize;
31 send_data_to_user_somehow($serialized);
32 # on the temporary user's side of the connection
34 my $serialized = get_data_somehow();
35 my $token = VM::EC2::Security::Credentials->new_from_serialized($serialized);
36 my $ec2 = VM::EC2->new(-security_token => $token);
37 print $ec2->describe_images(-owner=>'self');
38 For temporary users who are not using the Perl VM::EC2 API, you can
40 transmit the required fields individually:
41 my $credentials = $token->credentials;
43 my $access_key_id = $credentials->accessKeyId;
44 my $secret_key = $credentials->secretKey;
45 my $session_token = $credentials->sessionToken;
46 send_data_to_user_somehow($session_token,
47 $access_key_id,
48 $secret_key);
49 Calls to get_federation_token() return a VM::EC2::Security::Token
51 object. This object contains two sub-objects, a
52 VM::EC2::Security::Credentials object, and a
53 VM::EC2::Security::FederatedUser object. The Credentials object
54 contains a temporary access key ID, secret access key, and session
55 token which together can be used to authenticate to the EC2 API. The
56 FederatedUser object contains the temporary user account name and ID.
57 See VM::EC2::Security::Token, VM::EC2::Security::FederatedUser,
59 VM::EC2::Security::Credentials, and VM::EC2::Security::Policy.
60 Implemented:
62 GetFederationToken
63 GetSessionToken
64 Unimplemented:
66 (none)
67 $token = $ec2->get_federation_token($username)
69 $token = $ec2->get_federation_token(-name=>$username,@args)
70 This method creates a new temporary user under the provided username
71 and returns a VM::EC2::Security::Token object that contains temporary
72 credentials for the user, as well as information about the user's
73 account. Other options allow you to control the duration for which the
74 credentials will be valid, and the policy the controls what resources
75 the user is allowed to access.
76 Required arguments:
78 -name The username
79 The username must comply with the guidelines described in
81 http://docs.amazonwebservices.com/IAM/latest/UserGuide/LimitationsOnEntities.html:
82 essentially all alphanumeric plus the characters [+=,.@-].
83 Optional arguments:
85 -duration_seconds Length of time the session token will be valid for,
86 expressed in seconds.
87 -duration Same thing, faster to type.
89 -policy A VM::EC2::Security::Policy object, or a JSON string
91 complying with the IAM policy syntax.
92 The duration must be no shorter than 1 hour (3600 seconds) and no
94 longer than 36 hours (129600 seconds). If no duration is specified,
95 Amazon will default to 12 hours. If no policy is provided, then the
96 user will not be able to execute any actions.
97 Note that if the temporary user wishes to create a VM::EC2 object
99 and specify a region name at create time (e.g.
100 VM::EC2->new(-region=>'us-west-1'), then the user must have access
101 to the DescribeRegions action:
102 $policy->allow('DescribeRegions')
104 Otherwise the call to new() will fail.
106 $token = $ec2->get_session_token(%args)
108 This method creates a temporary VM::EC2::Security::Token object for an
109 anonymous user. The token has no policy associated with it, and can be
110 used to run any of the EC2 actions available to the user who created
111 the token. Optional arguments allow the session token to be used in
112 conjunction with MFA devices.
113 Required arguments:
115 none
116 Optional arguments:
118 -duration_seconds Length of time the session token will be valid for,
119 expressed in seconds.
120 -duration Same thing, faster to type.
122 -serial_number The identification number of the user's MFA device,
124 if any.
125 -token_code The code provided by the MFA device, if any.
127 If no duration is specified, Amazon will default to 12 hours.
129 See
131 http://docs.amazonwebservices.com/IAM/latest/UserGuide/Using_ManagingMFA.html
132 for information on using AWS in conjunction with MFA devices.
133
135 VM::EC2
136
138 Lincoln Stein <lincoln.stein@gmail.com>.
139 Copyright (c) 2011 Ontario Institute for Cancer Research
141 This package and its accompanying libraries is free software; you can
143 redistribute it and/or modify it under the terms of the GPL (either
144 version 1, or at your option, any later version) or the Artistic
145 License 2.0. Refer to LICENSE for the full license text. In addition,
146 please see DISCLAIMER.txt for disclaimers of warranty.
147perl v5.34.0 2022-01-21 VM::EC2::REST::security_token(3)