assume_root `async` ¶

assume_root(
    target_principal: TargetPrincipalType,
    task_policy_arn: PolicyDescriptorType,
    *,
    config_overrides: Optional[AsyncSTSClientConfig] = None,
    duration_seconds: Optional[RootDurationSecondsType] = None,
    minimum_session_token_size: Optional[minimumSessionTokenSizeType] = None,
) -> AssumeRootResponse

Returns a set of short term credentials you can use to perform privileged tasks on a member account in your organization. You must use credentials from an Organizations management account or a delegated administrator account for IAM to call AssumeRoot. You cannot use root user credentials to make this call.

Before you can launch a privileged session, you must have centralized root access in your organization. For steps to enable this feature, see Centralize root access for member accounts in the IAM User Guide.

The STS global endpoint is not supported for AssumeRoot. You must send this request to a Regional STS endpoint. For more information, see Endpoints.

You can track AssumeRoot in CloudTrail logs to determine what actions were performed in a session. For more information, see Track privileged tasks in CloudTrail in the IAM User Guide.

When granting access to privileged tasks you should only grant the necessary permissions required to perform that task. For more information, see Security best practices in IAM. In addition, you can use service control policies (SCPs) to manage and limit permissions in your organization. See General examples in the Organizations User Guide for more information on SCPs.

Parameters:

target_principal (TargetPrincipalType) –

The member account principal ARN or account ID.
task_policy_arn (PolicyDescriptorType) –
The identity based policy that scopes the session to the privileged tasks that can be performed. You must use one of following Amazon Web Services managed policies to scope root session actions:
duration_seconds (Optional[RootDurationSecondsType], default: None ) –

The duration, in seconds, of the privileged session. The value can range from 0 seconds up to the maximum session duration of 900 seconds (15 minutes). If you specify a value higher than this setting, the operation fails.

By default, the value is set to 900 seconds.

Raises:

ExpiredTokenException –

The web identity token that was passed is expired or is not valid. Get a new identity token from the identity provider and then retry the request.
RegionDisabledException –

STS is not activated in the requested region for the account that is being asked to generate credentials. The account administrator must use the IAM console to activate STS in that region. For more information, see Activating and Deactivating STS in an Amazon Web Services Region in the IAM User Guide.
UnknownServiceError –

The service returned an error code this client does not model.

Examples:

To launch a privileged session The following command retrieves a set of short-term credentials you can use to unlock an S3 bucket for a member account by removing the bucket policy.

>>> await client.assume_root(target_principal='111122223333', task_policy_arn={'arn': 'arn:aws:iam::aws:policy/root-task/S3UnlockBucketPolicy'}, duration_seconds=900)

Source code in docs_src/capo_sts/_services/async_sts.py

async def assume_root(
    self,
    target_principal: "capo_sts.types.target_principal_type.TargetPrincipalType",
    task_policy_arn: "capo_sts.types.policy_descriptor_type.PolicyDescriptorType",
    *,
    config_overrides: Optional[AsyncSTSClientConfig] = None,
    duration_seconds: Optional[
        "capo_sts.types.root_duration_seconds_type.RootDurationSecondsType"
    ] = None,
    minimum_session_token_size: Optional[
        "capo_sts.types.minimum_session_token_size_type.minimumSessionTokenSizeType"
    ] = None,
) -> "capo_sts.types.assume_root_response.AssumeRootResponse":
    """<p>Returns a set of short term credentials you can use to perform privileged tasks on a member account in your organization. You must use credentials from an Organizations management account or a delegated administrator account for IAM to call <code>AssumeRoot</code>. You cannot use root user credentials to make this call.</p> <p>Before you can launch a privileged session, you must have centralized root access in your organization. For steps to enable this feature, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-enable-root-access.html">Centralize root access for member accounts</a> in the <i>IAM User Guide</i>.</p> <note> <p>The STS global endpoint is not supported for AssumeRoot. You must send this request to a Regional STS endpoint. For more information, see <a href="https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html#sts-endpoints">Endpoints</a>.</p> </note> <p>You can track AssumeRoot in CloudTrail logs to determine what actions were performed in a session. For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/cloudtrail-track-privileged-tasks.html">Track privileged tasks in CloudTrail</a> in the <i>IAM User Guide</i>.</p> <p>When granting access to privileged tasks you should only grant the necessary permissions required to perform that task. For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html">Security best practices in IAM</a>. In addition, you can use <a href="https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html">service control policies</a> (SCPs) to manage and limit permissions in your organization. See <a href="https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps_examples_general.html">General examples</a> in the <i>Organizations User Guide</i> for more information on SCPs.</p>

    Args:
        target_principal: <p>The member account principal ARN or account ID.</p>
        task_policy_arn: <p>The identity based policy that scopes the session to the privileged tasks that can be performed. You must use one of following Amazon Web Services managed policies to scope root session actions:</p> <ul> <li> <p> <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/security-iam-awsmanpol.html#security-iam-awsmanpol-IAMAuditRootUserCredentials">IAMAuditRootUserCredentials</a> </p> </li> <li> <p> <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/security-iam-awsmanpol.html#security-iam-awsmanpol-IAMCreateRootUserPassword">IAMCreateRootUserPassword</a> </p> </li> <li> <p> <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/security-iam-awsmanpol.html#security-iam-awsmanpol-IAMDeleteRootUserCredentials">IAMDeleteRootUserCredentials</a> </p> </li> <li> <p> <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/security-iam-awsmanpol.html#security-iam-awsmanpol-S3UnlockBucketPolicy">S3UnlockBucketPolicy</a> </p> </li> <li> <p> <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/security-iam-awsmanpol.html#security-iam-awsmanpol-SQSUnlockQueuePolicy">SQSUnlockQueuePolicy</a> </p> </li> </ul>
        duration_seconds: <p>The duration, in seconds, of the privileged session. The value can range from 0 seconds up to the maximum session duration of 900 seconds (15 minutes). If you specify a value higher than this setting, the operation fails.</p> <p>By default, the value is set to <code>900</code> seconds.</p>

    Raises:
        capo_sts.errors.expired_token_exception.ExpiredTokenException: <p>The web identity token that was passed is expired or is not valid. Get a new identity token from the identity provider and then retry the request.</p>
        capo_sts.errors.region_disabled_exception.RegionDisabledException: <p>STS is not activated in the requested region for the account that is being asked to generate credentials. The account administrator must use the IAM console to activate STS in that region. For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate">Activating and Deactivating STS in an Amazon Web Services Region</a> in the <i>IAM User Guide</i>.</p>
        capo_sts.errors.UnknownServiceError: The service returned an error code this client does not model.

    Examples:
        To launch a privileged session
        The following command retrieves a set of short-term credentials you can use to unlock an S3 bucket for a member account by removing the bucket policy.

        >>> await client.assume_root(target_principal='111122223333', task_policy_arn={'arn': 'arn:aws:iam::aws:policy/root-task/S3UnlockBucketPolicy'}, duration_seconds=900)
    """

    async def _handler(
        req: "AsyncOperationRequest[capo_sts.types.assume_root_request.AssumeRootRequest]",
    ) -> AsyncOperationResponse[
        "capo_sts.types.assume_root_response.AssumeRootResponse"
    ]:
        import capo_sts._operations.aws_security_token_service_v20110615.assume_root

        (
            output,
            http_response,
        ) = await capo_sts._operations.aws_security_token_service_v20110615.assume_root.async_assume_root(
            req.options, req.input
        )
        return AsyncOperationResponse(output=output, response=http_response)

    def _redact_output(
        output: "capo_sts.types.assume_root_response.AssumeRootResponse",
    ) -> dict[str, Any]:
        import capo_sts.types.assume_root_response

        return capo_sts.types.assume_root_response.redact_sensitive(output)

    interceptors_, options_ = self.operation_options(
        config_overrides,
        OperationLogging("AssumeRoot", redact_output=_redact_output),
    )
    input_: capo_sts.types.assume_root_request.AssumeRootRequest = {
        "target_principal": target_principal,
        "task_policy_arn": task_policy_arn,
    }
    if duration_seconds is not None:
        input_["duration_seconds"] = duration_seconds
    if minimum_session_token_size is not None:
        input_["minimum_session_token_size"] = minimum_session_token_size

    response = await aexecute_pipeline(
        AsyncOperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    await response.response.aclose()
    return response.output

assume_root async ¶

assume_root `async` ¶