.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "VM::EC2::REST::security_token 3pm"
.TH VM::EC2::REST::security_token 3pm "2016-06-04" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME VM::EC2::REST::security_token \- AWS security tokens"
.IX Header "NAME VM::EC2::REST::security_token - AWS security tokens"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use VM::EC2 qw(:standard);
.Ve
.SH "EC2 REGIONS AND AVAILABILITY ZONES"
.IX Header "EC2 REGIONS AND AVAILABILITY ZONES"
\&\s-1AWS\s0 security tokens provide a way to grant temporary access to
resources in your \s-1EC2\s0 space without giving them permanent
accounts. They also provide the foundation for mobile services and
multifactor authentication devices (\s-1MFA\s0).
.PP
Used in conjunction with VM::EC2::Security::Policy and
VM::EC2::Security::Credentials, you can create a temporary user who is
authenticated for a limited length of time and pass the credentials to
him or her via a secure channel. He or she can then create a
credentials object to access your \s-1AWS\s0 resources.
.PP
Here is an example:
.PP
.Vb 9
\& # on your side of the connection
\& $ec2 = VM::EC2\->new(...);  # as usual
\& my $policy = VM::EC2::Security::Policy\->new;
\& $policy\->allow(\*(AqDescribeImages\*(Aq,\*(AqRunInstances\*(Aq);
\& my $token = $ec2\->get_federation_token(\-name     => \*(AqTemporaryUser\*(Aq,
\&                                        \-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\*(Aqs 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=>\*(Aqself\*(Aq);
.Ve
.PP
For temporary users who are not using the Perl \s-1VM::EC2 API,\s0 you can
transmit the required fields individually:
.PP
.Vb 7
\& 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);
.Ve
.PP
Calls to \fIget_federation_token()\fR return a VM::EC2::Security::Token
object. This object contains two sub-objects, a
VM::EC2::Security::Credentials object, and a
VM::EC2::Security::FederatedUser object. The Credentials object
contains a temporary access key \s-1ID,\s0 secret access key, and session
token which together can be used to authenticate to the \s-1EC2 API. \s0 The
FederatedUser object contains the temporary user account name and \s-1ID.\s0
.PP
See VM::EC2::Security::Token, VM::EC2::Security::FederatedUser,
VM::EC2::Security::Credentials, and VM::EC2::Security::Policy.
.PP
Implemented:
 GetFederationToken
 GetSessionToken
.PP
Unimplemented:
 (none)
.ie n .SS "$token = $ec2\->get_federation_token($username)"
.el .SS "\f(CW$token\fP = \f(CW$ec2\fP\->get_federation_token($username)"
.IX Subsection "$token = $ec2->get_federation_token($username)"
.ie n .SS "$token = $ec2\->get_federation_token(\-name=>$username,@args)"
.el .SS "\f(CW$token\fP = \f(CW$ec2\fP\->get_federation_token(\-name=>$username,@args)"
.IX Subsection "$token = $ec2->get_federation_token(-name=>$username,@args)"
This method creates a new temporary user under the provided username
and returns a VM::EC2::Security::Token object that contains temporary
credentials for the user, as well as information about the user's
account. Other options allow you to control the duration for which the
credentials will be valid, and the policy the controls what resources
the user is allowed to access.
.IP "Required arguments:" 4
.IX Item "Required arguments:"
.Vb 1
\& \-name The username
.Ve
.Sp
The username must comply with the guidelines described in
http://docs.amazonwebservices.com/IAM/latest/UserGuide/LimitationsOnEntities.html:
essentially all alphanumeric plus the characters [+=,.@\-].
.IP "Optional arguments:" 4
.IX Item "Optional arguments:"
.Vb 2
\& \-duration_seconds Length of time 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.
.Ve
.Sp
The duration must be no shorter than 1 hour (3600 seconds) and no
longer than 36 hours (129600 seconds). If no duration is specified,
Amazon will default to 12 hours. If no policy is provided, then the
user will not be able to execute \fBany\fR actions.
.Sp
Note that if the temporary user wishes to create a \s-1VM::EC2\s0 object and
specify a region name at create time
(e.g. \s-1VM::EC2\-\s0>new(\-region=>'us\-west\-1'), then the user must have
access to the DescribeRegions action:
.Sp
.Vb 1
\& $policy\->allow(\*(AqDescribeRegions\*(Aq)
.Ve
.Sp
Otherwise the call to \fInew()\fR will fail.
.ie n .SS "$token = $ec2\->get_session_token(%args)"
.el .SS "\f(CW$token\fP = \f(CW$ec2\fP\->get_session_token(%args)"
.IX Subsection "$token = $ec2->get_session_token(%args)"
This method creates a temporary VM::EC2::Security::Token object for an
anonymous user. The token has no policy associated with it, and can be
used to run any of the \s-1EC2\s0 actions available to the user who created
the token. Optional arguments allow the session token to be used in
conjunction with \s-1MFA\s0 devices.
.IP "Required arguments:" 4
.IX Item "Required arguments:"
none
.IP "Optional arguments:" 4
.IX Item "Optional arguments:"
.Vb 2
\& \-duration_seconds Length of time the session token will be valid for,
\&                    expressed in seconds.
\&
\& \-duration         Same thing, faster to type.
\&
\& \-serial_number    The identification number of the user\*(Aqs MFA device,
\&                     if any.
\&
\& \-token_code       The code provided by the MFA device, if any.
.Ve
.Sp
If no duration is specified, Amazon will default to 12 hours.
.Sp
See
http://docs.amazonwebservices.com/IAM/latest/UserGuide/Using_ManagingMFA.html
for information on using \s-1AWS\s0 in conjunction with \s-1MFA\s0 devices.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lincoln.stein@gmail.com>.
.PP
Copyright (c) 2011 Ontario Institute for Cancer Research
.PP
This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the \s-1GPL \s0(either
version 1, or at your option, any later version) or the Artistic
License 2.0.  Refer to \s-1LICENSE\s0 for the full license text. In addition,
please see \s-1DISCLAIMER\s0.txt for disclaimers of warranty.