Alternância para uma função do IAM (API da AWS)

Uma função especifica um conjunto de permissões que você pode usar para acessar os recursos da AWS. Nesse sentido, ela é semelhante a um usuário do IAM. Um principal (pessoa ou aplicativo) assume uma função para receber permissões temporárias para executar as tarefas necessárias e interagir com recursos do AWS. O perfil pode estar em sua própria conta ou em qualquer outra Conta da AWS. Para obter mais informações sobre funções, seus benefícios e como criar e configurá-las, consulte Perfis do IAMe Criação de funções do IAM. Para saber mais sobre os diferentes métodos que você pode usar para assumir uma função, consulte Uso de funções do IAM.

Importante

As permissões do usuário do IAM e quaisquer funções você venha a assumir não são cumulativas. Apenas um conjunto de permissões é ativo por vez. Quando você assume uma função, perde temporariamente as permissões de usuário ou função anteriores e trabalha com as permissões atribuídas à função. Ao sair da função, suas permissões originais serão, automaticamente, restauradas.

Para assumir uma função, um aplicativo chama a operação de API AWS STSAssumeRole do e transmite o ARN da função a ser usada. A operação cria uma nova sessão com credenciais temporárias. Esta sessão tem as mesmas permissões que as políticas baseadas em identidade para essa função.

Quando você chamar AssumeRole, poderá transmitir as políticas de políticas de sessão gerenciadas ou em linha. As políticas de sessão são políticas avançadas que você transmite como um parâmetro quando cria de forma programática uma sessão temporária para uma função ou usuário federado. Você pode passar um único documento de política JSON de sessão em linha usando o parâmetro Policy. Você pode usar o parâmetro PolicyArns para especificar até 10 políticas de sessão gerenciadas. As permissões da sessão resultam da interseção das políticas baseadas em identidade da entidade e das políticas de sessão. As políticas de sessão são úteis quando você precisa fornecer as credenciais temporárias da função para outra pessoa. A outra pessoa pode usar as credenciais temporárias da função em chamadas subsequentes à API da AWS para acessar recursos na conta que possui a função. Você não pode usar políticas de sessão para conceder mais permissões do que as permitidas pela política baseada em identidade. Para saber mais sobre como a AWS determina as permissões efetivas de uma função, consulte Lógica da avaliação de política.

Você pode chamar AssumeRole quando estiver conectado como um usuário do IAM ou como um usuário autenticado externamente (SAML ou OIDC) que já esteja usando uma função. Você também pode usar o encadeamento de funções, que é o uso de uma função para assumir uma segunda função. Você não pode assumir uma função quando está conectado como o Usuário raiz da conta da AWS.

Por padrão, a sessão da função dura uma hora. Quando assume esta função usando as operações de API AWS STSAssumeRole* do , você pode especificar uma valor para o parâmetro DurationSeconds. Esse valor pode variar de 900 segundos (15 minutos) até o valor configurado de duração máxima da sessão para a função. Para saber como visualizar o valor máximo para sua função, consulte Visualizar a configuração de duração máxima da sessão para uma função.

Se você usar o encadeamento de funções, a sessão será limitada a uma duração máxima de uma hora. Se você usar o parâmetro DurationSeconds para fornecer um valor maior do que uma hora, a operação falhará.

nota

Por motivos de segurança, os administradores podem revisar logs do AWS CloudTrail para saber quem executou uma ação na AWS. Seu administrador pode exigir que você especifique uma identidade-fonte ou um nome de sessão de função ao assumir a função. Para obter mais informações, consulte sts:SourceIdentity e sts:RoleSessionName.

O exemplo a seguir em Python usando a interface Boto3 para a AWS (AWS SDK for Python (Boto) V3) mostra como chamar AssumeRole. Ele também mostra como usar as credenciais de segurança temporárias retornadas por AssumeRole para listar todos os buckets do Amazon S3 na conta que possui a função.

import boto3

# The calls to AWS STS AssumeRole must be signed with the access key ID
# and secret access key of an existing IAM user or by using existing temporary 
# credentials such as those from another role. (You cannot call AssumeRole 
# with the access key for the root account.) The credentials can be in 
# environment variables or in a configuration file and will be discovered 
# automatically by the boto3.client() function. For more information, see the 
# Python SDK documentation: 
# http://boto3.readthedocs.io/en/latest/reference/services/sts.html#client

# create an STS client object that represents a live connection to the 
# STS service
sts_client = boto3.client('sts')

# Call the assume_role method of the STSConnection object and pass the role
# ARN and a role session name.
assumed_role_object=sts_client.assume_role(
    RoleArn="arn:aws:iam::account-of-role-to-assume:role/name-of-role",
    RoleSessionName="AssumeRoleSession1"
)

# From the response that contains the assumed role, get the temporary 
# credentials that can be used to make subsequent API calls
credentials=assumed_role_object['Credentials']

# Use the temporary credentials that AssumeRole returns to make a 
# connection to Amazon S3  
s3_resource=boto3.resource(
    's3',
    aws_access_key_id=credentials['AccessKeyId'],
    aws_secret_access_key=credentials['SecretAccessKey'],
    aws_session_token=credentials['SessionToken'],
)

# Use the Amazon S3 resource object that is now configured with the 
# credentials to access your S3 buckets. 
for bucket in s3_resource.buckets.all():
    print(bucket.name)