| Copyright | (c) 2013-2021 Brendan Hay |
|---|---|
| License | Mozilla Public License, v. 2.0. |
| Maintainer | Brendan Hay <brendan.g.hay+amazonka@gmail.com> |
| Stability | auto-generated |
| Portability | non-portable (GHC extensions) |
| Safe Haskell | None |
Amazonka.STS.GetSessionToken
Description
Returns a set of temporary credentials for an Amazon Web Services
account or IAM user. The credentials consist of an access key ID, a
secret access key, and a security token. Typically, you use
GetSessionToken if you want to use MFA to protect programmatic calls
to specific Amazon Web Services API operations like Amazon EC2
StopInstances. MFA-enabled IAM users would need to call
GetSessionToken and submit an MFA code that is associated with their
MFA device. Using the temporary security credentials that are returned
from the call, IAM users can then make programmatic calls to API
operations that require MFA authentication. If you do not supply a
correct MFA code, then the API returns an access denied error. For a
comparison of GetSessionToken with the other API operations that
produce temporary credentials, see
Requesting Temporary Security Credentials
and
Comparing the STS API operations
in the IAM User Guide.
Session Duration
The GetSessionToken operation must be called by using the long-term
Amazon Web Services security credentials of the Amazon Web Services
account root user or an IAM user. Credentials that are created by IAM
users are valid for the duration that you specify. This duration can
range from 900 seconds (15 minutes) up to a maximum of 129,600 seconds
(36 hours), with a default of 43,200 seconds (12 hours). Credentials
based on account credentials can range from 900 seconds (15 minutes) up
to 3,600 seconds (1 hour), with a default of 1 hour.
Permissions
The temporary security credentials created by GetSessionToken can be
used to make API calls to any Amazon Web Services service with the
following exceptions:
- You cannot call any IAM API operations unless MFA authentication information is included in the request.
- You cannot call any STS API except
AssumeRoleorGetCallerIdentity.
We recommend that you do not call GetSessionToken with Amazon Web
Services account root user credentials. Instead, follow our
best practices
by creating one or more IAM users, giving them the necessary
permissions, and using IAM users for everyday interaction with Amazon
Web Services.
The credentials that are returned by GetSessionToken are based on
permissions associated with the user whose credentials were used to call
the operation. If GetSessionToken is called using Amazon Web Services
account root user credentials, the temporary credentials have root user
permissions. Similarly, if GetSessionToken is called using the
credentials of an IAM user, the temporary credentials have the same
permissions as the IAM user.
For more information about using GetSessionToken to create temporary
credentials, go to
Temporary Credentials for Users in Untrusted Environments
in the IAM User Guide.
Synopsis
- data GetSessionToken = GetSessionToken' {}
- newGetSessionToken :: GetSessionToken
- getSessionToken_tokenCode :: Lens' GetSessionToken (Maybe Text)
- getSessionToken_durationSeconds :: Lens' GetSessionToken (Maybe Natural)
- getSessionToken_serialNumber :: Lens' GetSessionToken (Maybe Text)
- data GetSessionTokenResponse = GetSessionTokenResponse' {
- credentials :: Maybe AuthEnv
- httpStatus :: Int
- newGetSessionTokenResponse :: Int -> GetSessionTokenResponse
- getSessionTokenResponse_credentials :: Lens' GetSessionTokenResponse (Maybe AuthEnv)
- getSessionTokenResponse_httpStatus :: Lens' GetSessionTokenResponse Int
Creating a Request
data GetSessionToken Source #
See: newGetSessionToken smart constructor.
Constructors
| GetSessionToken' | |
Fields
| |
Instances
newGetSessionToken :: GetSessionToken Source #
Create a value of GetSessionToken with all optional fields omitted.
Use generic-lens or optics to modify other optional fields.
The following record fields are available, with the corresponding lenses provided for backwards compatibility:
$sel:tokenCode:GetSessionToken', getSessionToken_tokenCode - The value provided by the MFA device, if MFA is required. If any policy
requires the IAM user to submit an MFA code, specify this value. If MFA
authentication is required, the user must provide a code when requesting
a set of temporary security credentials. A user who fails to provide the
code receives an "access denied" response when requesting resources
that require MFA authentication.
The format for this parameter, as described by its regex pattern, is a sequence of six numeric digits.
$sel:durationSeconds:GetSessionToken', getSessionToken_durationSeconds - The duration, in seconds, that the credentials should remain valid.
Acceptable durations for IAM user sessions range from 900 seconds (15
minutes) to 129,600 seconds (36 hours), with 43,200 seconds (12 hours)
as the default. Sessions for Amazon Web Services account owners are
restricted to a maximum of 3,600 seconds (one hour). If the duration is
longer than one hour, the session for Amazon Web Services account owners
defaults to one hour.
$sel:serialNumber:GetSessionToken', getSessionToken_serialNumber - The identification number of the MFA device that is associated with the
IAM user who is making the GetSessionToken call. Specify this value if
the IAM user has a policy that requires MFA authentication. The value is
either the serial number for a hardware device (such as GAHT12345678)
or an Amazon Resource Name (ARN) for a virtual device (such as
arn:aws:iam::123456789012:mfa/user). You can find the device for an
IAM user by going to the Management Console and viewing the user's
security credentials.
The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@:/-
Request Lenses
getSessionToken_tokenCode :: Lens' GetSessionToken (Maybe Text) Source #
The value provided by the MFA device, if MFA is required. If any policy requires the IAM user to submit an MFA code, specify this value. If MFA authentication is required, the user must provide a code when requesting a set of temporary security credentials. A user who fails to provide the code receives an "access denied" response when requesting resources that require MFA authentication.
The format for this parameter, as described by its regex pattern, is a sequence of six numeric digits.
getSessionToken_durationSeconds :: Lens' GetSessionToken (Maybe Natural) Source #
The duration, in seconds, that the credentials should remain valid. Acceptable durations for IAM user sessions range from 900 seconds (15 minutes) to 129,600 seconds (36 hours), with 43,200 seconds (12 hours) as the default. Sessions for Amazon Web Services account owners are restricted to a maximum of 3,600 seconds (one hour). If the duration is longer than one hour, the session for Amazon Web Services account owners defaults to one hour.
getSessionToken_serialNumber :: Lens' GetSessionToken (Maybe Text) Source #
The identification number of the MFA device that is associated with the
IAM user who is making the GetSessionToken call. Specify this value if
the IAM user has a policy that requires MFA authentication. The value is
either the serial number for a hardware device (such as GAHT12345678)
or an Amazon Resource Name (ARN) for a virtual device (such as
arn:aws:iam::123456789012:mfa/user). You can find the device for an
IAM user by going to the Management Console and viewing the user's
security credentials.
The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@:/-
Destructuring the Response
data GetSessionTokenResponse Source #
Contains the response to a successful GetSessionToken request, including temporary Amazon Web Services credentials that can be used to make Amazon Web Services requests.
See: newGetSessionTokenResponse smart constructor.
Constructors
| GetSessionTokenResponse' | |
Fields
| |
Instances
newGetSessionTokenResponse Source #
Create a value of GetSessionTokenResponse with all optional fields omitted.
Use generic-lens or optics to modify other optional fields.
The following record fields are available, with the corresponding lenses provided for backwards compatibility:
$sel:credentials:GetSessionTokenResponse', getSessionTokenResponse_credentials - The temporary security credentials, which include an access key ID, a
secret access key, and a security (or session) token.
The size of the security token that STS API operations return is not fixed. We strongly recommend that you make no assumptions about the maximum size.
$sel:httpStatus:GetSessionTokenResponse', getSessionTokenResponse_httpStatus - The response's http status code.
Response Lenses
getSessionTokenResponse_credentials :: Lens' GetSessionTokenResponse (Maybe AuthEnv) Source #
The temporary security credentials, which include an access key ID, a secret access key, and a security (or session) token.
The size of the security token that STS API operations return is not fixed. We strongly recommend that you make no assumptions about the maximum size.
getSessionTokenResponse_httpStatus :: Lens' GetSessionTokenResponse Int Source #
The response's http status code.