get_session_token¶
Operation¶
async
¶
get_session_token(input: GetSessionTokenInput, plugins: list[Plugin] | None = None) -> GetSessionTokenOutput
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 must call GetSessionToken and submit an MFA code
that is associated with their MFA device. Using the temporary security
credentials that the call returns, IAM users can then make programmatic
calls to API operations that require MFA authentication. An incorrect
MFA code causes the API to return an access denied error. For a
comparison of GetSessionToken with the other API operations that
produce temporary credentials, see Requesting Temporary Security
Credentials
and Compare STS
credentials
in the IAM User Guide.
Note
No permissions are required for users to perform this operation. The
purpose of the sts:GetSessionToken operation is to authenticate the
user using MFA. You cannot use policies to control authentication
operations. For more information, see Permissions for
GetSessionToken
in the IAM User Guide.
Session Duration
The GetSessionToken operation must be called by using the long-term
Amazon Web Services security credentials of 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.
The credentials that GetSessionToken returns are based on permissions
associated with the IAM user whose credentials were used to call the
operation. The temporary credentials have the same permissions as the
IAM user.
Note
Although it is possible to call GetSessionToken using the security
credentials of an Amazon Web Services account root user rather than an
IAM user, we do not recommend it. If GetSessionToken is called using
root user credentials, the temporary credentials have root user
permissions. For more information, see Safeguard your root user
credentials and don't use them for everyday
tasks
in the IAM User Guide
For more information about using GetSessionToken to create temporary
credentials, see Temporary Credentials for Users in Untrusted
Environments
in the IAM User Guide.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input
|
GetSessionTokenInput
|
An instance of |
required |
plugins
|
list[Plugin] | None
|
A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations. |
None
|
Returns:
| Type | Description |
|---|---|
GetSessionTokenOutput
|
An instance of |
Input¶
dataclass
¶
Dataclass for GetSessionTokenInput structure.
Attributes¶
class-attribute
instance-attribute
¶
duration_seconds: int | None = None
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.
class-attribute
instance-attribute
¶
serial_number: str | None = None
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 Amazon Web Services 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: =,.@:/-
class-attribute
instance-attribute
¶
token_code: str | None = None
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.
Output¶
dataclass
¶
Contains the response to a successful GetSessionToken request, including temporary Amazon Web Services credentials that can be used to make Amazon Web Services requests.
Attributes¶
class-attribute
instance-attribute
¶
credentials: Credentials | None = None
The temporary security credentials, which include an access key ID, a secret access key, and a security (or session) token.
Note
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.