AssumeRole - Resource Access Management: Central de Documentação do Alibaba Cloud

Obtém uma credencial de identidade temporária (token STS) para assumir uma função RAM.

Descrição da operação

Cenários comuns

Autorização de acesso temporário: normalmente, invoque operações de API a partir do lado do servidor para evitar vazamentos de chave de acesso. No entanto, em alguns cenários de upload de arquivos, é melhor usar uploads diretos do lado do cliente para evitar a sobrecarga de encaminhamento do lado do servidor. Nesse caso, o servidor pode emitir um token de segurança temporário (token STS) e o cliente pode usar o token STS para fazer upload direto de recursos. Para obter mais informações, consulte Usar tokens de segurança temporários para aplicativos móveis acessarem o Alibaba Cloud.
Acesso entre contas: se você tiver várias contas do Alibaba Cloud, como Conta A e Conta B, e quiser que a Conta B acesse recursos específicos da Conta A. Nesse caso, você pode criar uma função RAM na Conta A com a Conta B como entidade confiável e conceder autorização a um usuário do Resource Access Management (RAM) ou função RAM na Conta B para assumir a função. Em seguida, o usuário RAM ou a função RAM na Conta B pode acessar os recursos específicos da Conta A assumindo a função. Para obter mais informações, consulte Acessar recursos entre contas do Alibaba Cloud.

Antes de começar

Você não pode invocar esta operação usando uma conta do Alibaba Cloud. Você só pode invocar esta operação como um usuário RAM ou uma função RAM. Certifique-se de que o chamador (o usuário RAM ou a função RAM) tenha recebido a autorização para assunção de função STS (AliyunSTSAssumeRoleAccess).

Caso contrário, o seguinte erro será retornado:

You are not authorized to do this action. You should be authorized by RAM.

Causas e soluções:

O chamador não possui a política de acesso que permite a assunção de função STS: anexe a política do sistema (AliyunSTSAssumeRoleAccess) ou uma política personalizada ao chamador. Para obter mais informações, consulte Posso especificar a função RAM que um usuário RAM pode assumir? e Conceder permissões a um usuário RAM.
A política de confiança da função RAM não inclui o chamador, o que significa que a função RAM não permite que o chamador a assuma: adicione uma política de confiança que permita ao chamador assumir a função RAM. Para obter mais informações, consulte Modificar a política de confiança de uma função RAM.

Práticas recomendadas

Um token STS é válido por um período especificado após sua emissão. Recomendamos que você defina um período de validade razoável para o token e reutilize o token dentro do período de validade. Isso evita que o limite de taxa de emissão de tokens STS afete seus negócios quando a taxa de solicitação aumenta. Para obter mais informações sobre o limite de taxa, consulte Há um limite de quantas vezes você pode invocar o serviço STS?. Você pode definir o período de validade do token usando o parâmetro de solicitação DurationSeconds.

Em cenários como upload ou download de arquivos OSS a partir de clientes móveis, o volume de acesso é grande. Mesmo que você reutilize tokens STS, os requisitos de limitação podem não ser atendidos. Para evitar que a limitação do STS se torne um gargalo para o acesso ao OSS, experimente a solução OSS de incluir uma assinatura em uma URL. Para obter mais informações, consulte Incluir uma assinatura em uma URL e Assinatura no lado do servidor e upload direto.

Experimente agora

Experimente esta API no OpenAPI Explorer, sem necessidade de assinatura manual. Chamadas bem-sucedidas geram automaticamente código SDK correspondente aos seus parâmetros. Faça o download com segurança de credenciais integrada para uso local.

Testar

Autorização RAM

A tabela abaixo descreve a autorização necessária para chamar esta API. Você pode defini-la em uma política do Resource Access Management (RAM). As colunas da tabela estão detalhadas abaixo:

Ação: As ações que podem ser usadas no elemento Action das instruções de política de permissão do RAM para conceder permissões para executar a operação.
API: A API que você pode chamar para executar a ação.
Nível de acesso: O nível de acesso predefinido concedido para cada API. Valores válidos: create, list, get, update e delete.
Tipo de recurso: O tipo de recurso que suporta autorização para executar a ação. Indica se a ação suporta permissão em nível de recurso. O recurso especificado deve ser compatível com a ação. Caso contrário, a política será ineficaz.
- Para APIs com permissões em nível de recurso, os tipos de recursos obrigatórios são marcados com um asterisco (*). Especifique o Nome de Recurso Alibaba Cloud (ARN) correspondente no elemento Resource da política.
- Para APIs sem permissões em nível de recurso, é exibido como Todos os Recursos. Use um asterisco (*) no elemento Resource da política.
Chave de condição: As chaves de condição definidas pelo serviço. A chave permite controle granular, aplicando-se somente a ações ou a ações associadas a recursos específicos. Além das chaves de condição específicas do serviço, o Alibaba Cloud fornece um conjunto de chaves de condição comuns aplicáveis a todos os serviços compatíveis com RAM.
Ação dependente: As ações dependentes necessárias para executar a ação. Para concluir a ação, o usuário RAM ou a função RAM deve ter permissões para executar todas as ações dependentes.

Ação

Nível de acesso

Tipo de recurso

Chave de condição

Ação dependente

sts:AssumeRole

get

*Role

acs:ram::{#accountId}:role/{#RoleName}

sts:SourceIdentity

sts:SetSourceIdentity

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
DurationSeconds	integer	Não	O período de validade do token. Unidade: segundos. O período mínimo de validade é de 900 segundos, e o período máximo de validade é o valor `MaxSessionDuration` da função RAM a ser assumida. Valor padrão: 3600. Você pode definir o parâmetro `MaxSessionDuration` chamando a operação CreateRole ou UpdateRole. Para obter mais informações, consulte CreateRole ou UpdateRole.	3600
Policy	string	Não	A política de acesso adicional anexada ao token STS para restringir ainda mais as permissões do token STS. Detalhes: Se esta política de acesso for especificada, a política de acesso final do token STS será a interseção da política de acesso da função RAM e desta política de acesso. Se esta política de acesso não for especificada, a política de acesso final do token STS será a política de acesso da função RAM. O valor deve ter de 1 a 2.048 caracteres. Para obter mais informações sobre elementos e exemplos de políticas de acesso, consulte Elementos básicos de uma política de acesso e Exemplos de políticas de acesso.	{"Statement": [{"Action": [""],"Effect": "Allow","Resource": [""]}],"Version":"1"}
RoleArn	string	Sim	O ARN da função RAM a ser assumida. A entidade confiável da função RAM é uma conta do Alibaba Cloud. Para obter mais informações, consulte Criar uma função RAM para uma conta confiável do Alibaba Cloud ou CreateRole. Formato: `acs:ram::<account_id>:role/<role_name>`. Você pode visualizar o ARN da função RAM no console RAM ou chamando uma operação de API. Detalhes: Console RAM: consulte Visualizar o ARN de uma função RAM. Operação de API: consulte ListRoles ou GetRole.	acs:ram::123456789012****:role/adminrole
RoleSessionName	string	Sim	O nome da sessão da função. Este parâmetro é definido pelo usuário. Normalmente, defina este parâmetro como a identidade do usuário que chama a operação de API, como o nome de usuário. Nos logs do ActionTrail, mesmo que as operações sejam realizadas pela mesma função RAM, você pode identificar o operador real com base no `RoleSessionName` para implementar a auditoria de acesso no nível do usuário. O valor deve ter de 2 a 64 caracteres e pode conter letras, dígitos e os seguintes caracteres especiais: `.@-_`.	alice
ExternalId	string	Não	O ID externo da função. Este parâmetro é fornecido por uma parte externa para identificar a função. O objetivo principal é evitar o problema de deputado confuso. Para obter mais informações, consulte Usar ExternalId para evitar o problema de deputado confuso. O valor deve ter de 2 a 1.224 caracteres e pode conter letras, dígitos e os seguintes caracteres especiais: `=,.@:/-_`. Expressão regular: `[\w+=,.@:\/-]*`.	abcd1234
SourceIdentity	string	Não	A identidade de origem. Ao assumir uma função, você pode especificar a identidade de origem do chamador como a identidade inicial da sessão. A identidade de origem persiste ao longo das sessões encadeadas de assunção de função e não pode ser alterada. Isso garante a rastreabilidade e a segurança das operações. O valor de SourceIdentity deve ter de 2 a 64 caracteres e pode conter letras, dígitos e os seguintes caracteres especiais: `=,.@-_`. Expressão regular: `[\w+=,.@-]*`. Você não pode usar valores que começam com `acs:`, `aliyun:` ou `alibabacloud:`. Esses prefixos são reservados para uso interno do Alibaba Cloud.	Alice

Para obter mais informações sobre parâmetros de solicitação comuns, consulte Parâmetros comuns.

Elementos de resposta

Elemento	Tipo	Descrição	Exemplo
	object	Os parâmetros de resposta.
RequestId	string	O ID da solicitação.	6894B13B-6D71-4EF5-88FA-F32781734A7F
AssumedRoleUser	object	A identidade temporária usada para a assunção de função.
AssumedRoleId	string	O ID da identidade temporária.	34458433936495****:alice
Arn	string	O ARN da identidade temporária.	acs:ram::123456789012****:role/adminrole/alice
Credentials	object	A credencial de acesso.
SecurityToken	string	O token de segurança. Nota O comprimento do token de segurança não é fixo. Não limite o comprimento máximo do token de segurança.	********
Expiration	string	A hora em que o token expira. A hora é exibida em UTC.	2015-04-09T11:52:19Z
AccessKeySecret	string	O segredo da AccessKey.	wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****
AccessKeyId	string	O ID da AccessKey.	STS.L4aBSCSJVMuKg5U1****
SourceIdentity	string	A identidade de origem. Ao assumir uma função, você pode especificar a identidade de origem do chamador como a identidade inicial da sessão. A identidade de origem persiste ao longo das sessões encadeadas de assunção de função e não pode ser alterada. Isso garante a rastreabilidade e a segurança das operações. Se a identidade de origem não for especificada, este campo não será retornado.	Alice

Exemplos

Resposta de sucesso

JSON formato

{
  "RequestId": "6894B13B-6D71-4EF5-88FA-F32781734A7F",
  "AssumedRoleUser": {
    "AssumedRoleId": "34458433936495****:alice",
    "Arn": "acs:ram::123456789012****:role/adminrole/alice"
  },
  "Credentials": {
    "SecurityToken": "********",
    "Expiration": "2015-04-09T11:52:19Z",
    "AccessKeySecret": "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****",
    "AccessKeyId": "STS.L4aBSCSJVMuKg5U1****"
  },
  "SourceIdentity": "Alice"
}

Códigos de erro

Código de status HTTP	Código de erro	Mensagem de erro	Descrição
400	InvalidParameter.DurationSeconds	The Min/Max value of DurationSeconds is 15min/1hr.	O parâmetro DurationSeconds é inválido. O valor mínimo de DurationSeconds é de 15 minutos e o valor máximo é de 1 hora.
400	InvalidParameter.ExternalId	The parameter ExternalId is wrongly formed.	O parâmetro ExternalId é inválido.
400	InvalidParameter.RoleArn	The parameter RoleArn is wrongly formed.	O parâmetro RoleArn não pode estar vazio.
400	InvalidParameter.RoleSessionName	The parameter RoleSessionName is wrongly formed.	O formato do parâmetro RoleSessionName é inválido.
400	InvalidParameter.SerialNumber	The parameter SerialNumber is wrongly formed.
400	InvalidParameter.TokenCode	The parameter TokenCode is wrongly formed.
400	InvalidParameter.PolicyGrammar	The parameter Policy has not passed grammar check.	A sintaxe do parâmetro Policy falhou na validação.
400	InvalidParameter.PolicySize	The size of Policy must be smaller than 2048 bytes.	O parâmetro Policy é inválido. O tamanho da Policy deve ser menor que 2048 bytes.
400	InvalidParameter.ContentType	The ContentType request header must be either "application/json" or "application/x-www-form-urlencoded".
500	InternalError	STS Server Internal Error happened, please send the RequestId to us.	Ocorreu um erro interno.
403	NoPermission	You are not authorized to do this action. You should be authorized by RAM.
403	AuthenticationFail.ApiUsername	The specified api username is not legal.
403	AuthenticationFail.ApiPassword	The specified api password is not legal.
404	EntityNotExist.Role	The specified Role not exists .

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.