1VM::EC2::REST::securityU_steorkeCno(n3t)ributed Perl DocVuMm:e:nEtCa2t:i:oRnEST::security_token(3)
2
3
4

NAME VM::EC2::REST::security_token

SYNOPSIS

7        use VM::EC2 qw(:standard);
8

EC2 REGIONS AND AVAILABILITY ZONES

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
15       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
21       Here is an example:
22
23        # 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
33        # 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
39       For temporary users who are not using the Perl VM::EC2 API, you can
40       transmit the required fields individually:
41
42        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
50       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
58       See VM::EC2::Security::Token, VM::EC2::Security::FederatedUser,
59       VM::EC2::Security::Credentials, and VM::EC2::Security::Policy.
60
61       Implemented:
62        GetFederationToken
63        GetSessionToken
64
65       Unimplemented:
66        (none)
67
68   $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
77       Required arguments:
78            -name The username
79
80           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
84       Optional arguments:
85            -duration_seconds Length of time the session token will be valid for,
86                               expressed in seconds.
87
88            -duration         Same thing, faster to type.
89
90            -policy           A VM::EC2::Security::Policy object, or a JSON string
91                                complying with the IAM policy syntax.
92
93           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
98           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
103            $policy->allow('DescribeRegions')
104
105           Otherwise the call to new() will fail.
106
107   $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
114       Required arguments:
115           none
116
117       Optional arguments:
118            -duration_seconds Length of time the session token will be valid for,
119                               expressed in seconds.
120
121            -duration         Same thing, faster to type.
122
123            -serial_number    The identification number of the user's MFA device,
124                                if any.
125
126            -token_code       The code provided by the MFA device, if any.
127
128           If no duration is specified, Amazon will default to 12 hours.
129
130           See
131           http://docs.amazonwebservices.com/IAM/latest/UserGuide/Using_ManagingMFA.html
132           for information on using AWS in conjunction with MFA devices.
133

SEE ALSO

135       VM::EC2
136

AUTHOR

138       Lincoln Stein <lincoln.stein@gmail.com>.
139
140       Copyright (c) 2011 Ontario Institute for Cancer Research
141
142       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.
147
148
149
150perl v5.34.0                      2021-07-27  VM::EC2::REST::security_token(3)
Impressum