'Returns a set of temporary security credentials (consisting of
an access key ID, a secret access key, and a security token)
that you can use to access AWS resources that you might not
normally have access to. Typically, you use `AssumeRole` for
cross-account access or federation.
For cross-account access, imagine that you own multiple
accounts and need to access resources in each account. You
could create long-term credentials in each account to access
those resources. However, managing all those credentials and
remembering which one can access which account can be time
consuming. Instead, you can create one set of long-term
credentials in one account and then use temporary security
credentials to access all the other accounts by assuming roles
in those accounts. For more information about roles, see
`Roles`_ in Using IAM .
For federation, you can, for example, grant single sign-on
access to the AWS Management Console. If you already have an
identity and authentication system in your corporate network,
you don\'t have to recreate user identities in AWS in order to
grant those user identities access to AWS. Instead, after a
user has been authenticated, you call `AssumeRole` (and
specify the role with the appropriate permissions) to get
temporary security credentials for that user. With those
temporary security credentials, you construct a sign-in URL
that users can use to access the console. For more
information, see `Scenarios for Granting Temporary Access`_ in
AWS Security Token Service .
The temporary security credentials are valid for the duration
that you specified when calling `AssumeRole`, which can be
from 900 seconds (15 minutes) to 3600 seconds (1 hour). The
default is 1 hour.
The temporary security credentials that are returned from the
`AssumeRoleWithWebIdentity` response have the permissions that
are associated with the access policy of the role being
assumed and any policies that are associated with the AWS
resource being accessed. You can further restrict the
permissions of the temporary security credentials by passing a
policy in the request. The resulting permissions are an
intersection of the role\'s access policy and the policy that
you passed. These policies and any applicable resource-based
policies are evaluated when calls to AWS service APIs are made
using the temporary security credentials.
To assume a role, your AWS account must be trusted by the
role. The trust relationship is defined in the role\'s trust
policy when the IAM role is created. You must also have a
policy that allows you to call `sts:AssumeRole`.
**Important:** You cannot call `Assumerole` by using AWS
account credentials; access will be denied. You must use IAM
user credentials to call `AssumeRole`.
:type role_arn: string
:param role_arn: The Amazon Resource Name (ARN) of the role that the
caller is assuming.
:type role_session_name: string
:param role_session_name: An identifier for the assumed role session.
The session name is included as part of the `AssumedRoleUser`.
:type policy: string
:param policy: A supplemental policy that is associated with the
temporary security credentials from the `AssumeRole` call. The
resulting permissions of the temporary security credentials are an
intersection of this policy and the access policy that is
associated with the role. Use this policy to further restrict the
permissions of the temporary security credentials.
:type duration_seconds: integer
:param duration_seconds: The duration, in seconds, of the role session.
The value can range from 900 seconds (15 minutes) to 3600 seconds
(1 hour). By default, the value is set to 3600 seconds.
:type external_id: string
:param external_id: A unique identifier that is used by third parties
to assume a role in their customers\' accounts. For each role that
the third party can assume, they should instruct their customers to
create a role with the external ID that the third party generated.
Each time the third party assumes the role, they must pass the
customer\'s external ID. The external ID is useful in order to help
third parties bind a role to the customer who created it. For more
information about the external ID, see `About the External ID`_ in
Using Temporary Security Credentials .
:type mfa_serial_number: string
:param mfa_serial_number: The identification number of the MFA device that
is associated with the user who is making the AssumeRole call.
Specify this value if the trust policy of the role being assumed
includes a condition 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). Minimum length of 9.
Maximum length of 256.
:type mfa_token: string
:param mfa_token: The value provided by the MFA device, if the trust
policy of the role being assumed requires MFA (that is, if the
policy includes a condition that tests for MFA). If the role being
assumed requires MFA and if the TokenCode value is missing or
expired, the AssumeRole call returns an "access denied" errror.
Minimum length of 6. Maximum length of 6.'

def assume_role(self, role_arn, role_session_name, policy=None, duration_seconds=None, external_id=None, mfa_serial_number=None, mfa_token=None):

    params = {'RoleArn': role_arn, 'RoleSessionName': role_session_name}
    if (policy is not None):
        params['Policy'] = policy
    if (duration_seconds is not None):
        params['DurationSeconds'] = duration_seconds
    if (external_id is not None):
        params['ExternalId'] = external_id
    if (mfa_serial_number is not None):
        params['SerialNumber'] = mfa_serial_number
    if (mfa_token is not None):
        params['TokenCode'] = mfa_token
    return self.get_object('AssumeRole', params, AssumedRole, verb='POST')
