@aws-sdk/client-sts

import { Command as $Command } from "@aws-sdk/smithy-client"; import { Handler, HttpHandlerOptions as __HttpHandlerOptions, MetadataBearer as __MetadataBearer, MiddlewareStack } from "@aws-sdk/types"; import { AssumeRoleRequest, AssumeRoleResponse } from "../models/models_0"; import { ServiceInputTypes, ServiceOutputTypes, STSClientResolvedConfig } from "../STSClient"; export interface AssumeRoleCommandInput extends AssumeRoleRequest { } export interface AssumeRoleCommandOutput extends AssumeRoleResponse, __MetadataBearer { } /** * Returns a set of temporary security credentials that you can use to access Amazon Web Services * resources that you might not normally have access to. These temporary credentials * consist of an access key ID, a secret access key, and a security token. Typically, you * use <code>AssumeRole</code> within your account or for cross-account access. For a * comparison of <code>AssumeRole</code> with other API operations that produce temporary * credentials, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html">Requesting Temporary Security * Credentials</a> and <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison">Comparing * the STS API operations</a> in the * IAM User Guide. * * Permissions * * The temporary security credentials created by <code>AssumeRole</code> can be used to * make API calls to any Amazon Web Services service with the following exception: You cannot call the * STS <code>GetFederationToken</code> or <code>GetSessionToken</code> API * operations. * (Optional) You can pass inline or managed <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session">session policies</a> to * this operation. You can pass a single JSON policy document to use as an inline session * policy. You can also specify up to 10 managed policies to use as managed session policies. * The plaintext that you use for both inline and managed session policies can't exceed 2,048 * characters. Passing policies to this operation returns new * temporary credentials. The resulting session's permissions are the intersection of the * role's identity-based policy and the session policies. You can use the role's temporary * credentials in subsequent Amazon Web Services API calls to access resources in the account that owns * the role. You cannot use session policies to grant more permissions than those allowed * by the identity-based policy of the role that is being assumed. For more information, see * <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session">Session * Policies</a> in the IAM User Guide. * To assume a role from a different account, your account must be trusted by the * role. The trust relationship is defined in the role's trust policy when the role is * created. That trust policy states which accounts are allowed to delegate that access to * users in the account. * A user who wants to access a role in a different account must also have permissions that * are delegated from the user account administrator. The administrator must attach a policy * that allows the user to call <code>AssumeRole</code> for the ARN of the role in the other * account. If the user is in the same account as the role, then you can do either of the * following: * <ul> * <li> * Attach a policy to the user (identical to the previous user in a different * account). * </li> * <li> * Add the user as a principal directly in the role's trust policy. * </li> * </ul> * In this case, the trust policy acts as an IAM resource-based policy. Users in the same * account as the role do not need explicit permission to assume the role. For more * information about trust policies and resource-based policies, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html">IAM Policies</a> in * the IAM User Guide. * * Tags * * (Optional) You can pass tag key-value pairs to your session. These tags are called * session tags. For more information about session tags, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html">Passing Session Tags in STS</a> in the * IAM User Guide. * An administrator must grant you the permissions necessary to pass session tags. The * administrator can also create granular permissions to allow you to pass only specific * session tags. For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html">Tutorial: Using Tags * for Attribute-Based Access Control</a> in the * IAM User Guide. * You can set the session tags as transitive. Transitive tags persist during role * chaining. For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_role-chaining">Chaining Roles * with Session Tags</a> in the IAM User Guide. * * Using MFA with AssumeRole * * (Optional) You can include multi-factor authentication (MFA) information when you call * <code>AssumeRole</code>. This is useful for cross-account scenarios to ensure that the * user that assumes the role has been authenticated with an Amazon Web Services MFA device. In that * scenario, the trust policy of the role being assumed includes a condition that tests for * MFA authentication. If the caller does not include valid MFA information, the request to * assume the role is denied. The condition in a trust policy that tests for MFA * authentication might look like the following example. * * <code>"Condition": {"Bool": {"aws:MultiFactorAuthPresent": true}}</code> * * For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/MFAProtectedAPI.html">Configuring MFA-Protected API Access</a> * in the IAM User Guide guide. * To use MFA with <code>AssumeRole</code>, you pass values for the * <code>SerialNumber</code> and <code>TokenCode</code> parameters. The * <code>SerialNumber</code> value identifies the user's hardware or virtual MFA device. * The <code>TokenCode</code> is the time-based one-time password (TOTP) that the MFA device * produces. * @example * Use a bare-bones client and the command you need to make an API call. * ```javascript * import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts"; // ES Modules import * // const { STSClient, AssumeRoleCommand } = require("@aws-sdk/client-sts"); // CommonJS import * const client = new STSClient(config); * const command = new AssumeRoleCommand(input); * const response = await client.send(command); * ``` * * @see {@link AssumeRoleCommandInput} for command's `input` shape. * @see {@link AssumeRoleCommandOutput} for command's `response` shape. * @see {@link STSClientResolvedConfig | config} for command's `input` shape. * */ export declare class AssumeRoleCommand extends $Command<AssumeRoleCommandInput, AssumeRoleCommandOutput, STSClientResolvedConfig> { readonly input: AssumeRoleCommandInput; constructor(input: AssumeRoleCommandInput); /** * @internal */ resolveMiddleware(clientStack: MiddlewareStack<ServiceInputTypes, ServiceOutputTypes>, configuration: STSClientResolvedConfig, options?: __HttpHandlerOptions): Handler<AssumeRoleCommandInput, AssumeRoleCommandOutput>; private serialize; private deserialize; }