Elementos da política JSON da AWS:Principal - AWS Identity and Access Management
Especificar um principalEntidades principais da Conta da AWSEntidades de segurança de função do IAMEntidades principais da sessão de funçãoEntidades principais de usuário do IAMEntidades principais do Centro de identidadeEntidades principais de sessão de usuário federadoResponsáveis pelos serviços da AWSEntidades principais de serviço da AWS nas regiões de aceitaçãoTodas as entidades principaisMais informações

Elementos da política JSON da AWS:Principal

Use o elemento Principal em uma política JSON baseada em recursos para especificar a entidade principal cujo acesso a um recurso é permitido ou negado.

Você pode usar o elemento Principal em políticas baseadas em recursos. Vários serviços suportam políticas baseadas em recursos, inclusive o IAM. O tipo de política do IAM baseada em recursos é uma política de confiança em função. Nas funções do IAM, use o elemento Principal na política de confiança em função para especificar quem pode assumir a função. Para o acesso entre contas, você deve especificar o identificador de 12 dígitos da conta confiável. Para saber se as entidades de contas fora de sua zona de confiança (organização confiável ou conta) têm acesso para assumir as suas funções, consulte O que é o IAM Access Analyzer?.

nota

Depois de criar a função, você pode alterar a conta para "*" a fim de permitir que todas as pessoas assumam a função. Se você fizer isso, recomendamos que você limite quem pode acessar a função através de outros meios, tal como um elemento Condition que limita o acesso somente a determinados endereços IP. Não deixe a função acessível a todos!

Outros exemplos de recursos que dão suporte a políticas baseadas em recursos incluem um bucket do Amazon S3 ou uma AWS KMS key.

Você não pode usar o elemento Principal em uma política baseada em identidade. As políticas baseadas em identidade são políticas de permissões que você anexa a identidades do IAM (usuários, grupos ou funções). Nesses casos, a entidade principal é implicitamente a identidade à qual a política está anexada.

Especificar um principal

Você especifica uma entidade principal no elemento Principal de uma política baseada em recursos ou em chaves de condição que dão suporte a entidades principais.

Você pode especificar qualquer um dos seguintes principais em uma política:

  • Conta da AWS e usuário raiz

  • Perfis do IAM

  • Sessões de função

  • IAM users

  • Sessões de usuário federado

  • Serviços da AWS

  • Todas as entidades principais

Não é possível identificar um grupo de usuários como entidade principal em uma política (como uma política baseada em recursos) porque os grupos são relacionados com permissões, não autenticação, e as entidades principais são entidades autenticadas do IAM.

Você pode especificar mais de uma entidade de segurança para cada um dos tipos de entidade de segurança nas seções a seguir usando uma matriz. As matrizes podem levar um ou mais valores. Ao especificar mais de uma entidade principal em um elemento, você concede permissões para cada entidade principal. Isso é um OR lógico e não um AND lógico, porque você autentica como uma entidade principal por vez. Se incluir mais de um valor, use colchetes ([ e ]) e delimite com vírgulas cada entrada da matriz. A política de exemplo a seguir define permissões para a conta 123456789012 ou para a conta 555555555555.

"Principal" : { 
"AWS": [ 
  "123456789012",
  "555555555555" 
  ]
}
nota

Não é possível usar um curinga para fazer a correspondência de parte de um nome de entidade principal ou ARN.

Entidades principais da Conta da AWS

Você pode especificar identificadores de Conta da AWS no elemento Principal de uma política baseada em recursos ou em chaves de condição que oferecem suporte a entidades principais. Isso delega autoridade para a conta. Quando você permite o acesso a uma conta diferente, um administrador nessa conta deve então conceder acesso a uma identidade (usuário ou função do IAM) nessa conta. Ao especificar uma Conta da AWS, você pode usar o ARN da conta (arn:aws:iam::account-ID:root), ou uma forma abreviada que consiste no prefixo "AWS": seguido pelo ID da conta.

Por exemplo, dado um ID da conta de 123456789012, você pode usar um dos seguintes métodos para especificar essa conta no elemento Principal:

"Principal": { "AWS": "arn:aws:iam::123456789012:root" }
"Principal": { "AWS": "123456789012" }

O ARN da conta e o ID da conta abreviado têm comportamento semelhante. Ambos delegam permissões à conta. O uso do ARN da conta no elemento Principal não limita permissões apenas para o usuário raiz da conta.

nota

Quando você salva uma política baseada em recursos que inclui o ID abreviado da conta, o serviço pode convertê-lo no ARN da entidade principal. Isso não altera a funcionalidade da política.

Alguns serviços da AWS são compatíveis com opções adicionais para especificar uma conta do principal. Por exemplo, o Amazon S3 permite que você especifique um ID de usuário canônico usando o seguinte formato:

"Principal": { "CanonicalUser": "79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be" }

Você também pode especificar mais de uma Conta da AWS (ou ID de usuário canônico) como uma entidade principal usando uma matriz. Por exemplo, você pode especificar uma entidade principal em uma política de bucket usando todos os três métodos.

"Principal": { 
  "AWS": [
    "arn:aws:iam::123456789012:root",
    "999999999999"
  ],
  "CanonicalUser": "79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be"
}

Entidades de segurança de função do IAM

Você pode especificar ARNs de entidades principais de funções do IAM no elemento Principal de uma política baseada em recursos ou em chaves de condição que suportam entidades principais. As funções do IAM são identidades. No IAM, identidades são recursos aos quais você pode atribuir permissões. Funções confiam em outra identidade autenticada para assumir a respectiva função. Isso inclui uma entidade principal na AWS ou um usuário de um provedor de identidade externo (IdP). Quando uma entidade principal ou uma identidade assume uma função, ela recebe credenciais de segurança temporárias com as permissões da função assumida. Quando elas usam essas credenciais de sessão para executar operações na AWS, elas se tornam uma entidade principal da sessão de função.

As funções do IAM são identidades que existem no IAM. Funções confiam em outra identidade autenticada, como uma entidade principal na AWS ou um usuário de um provedor de identidade externo. Quando uma entidade principal ou uma identidade assume uma função, elas recebem credenciais de segurança temporárias. Em seguida, elas podem usar essas credenciais como uma entidade principal de sessão de função para executar operações na AWS.

Quando você especifica uma entidade principal de função em uma política baseada em recursos, as permissões efetivas para a entidade principal são limitadas por qualquer tipo de política que limite as permissões para a função. Isso inclui políticas de sessão e limites de permissões. Para mais informações sobre como as permissões efetivas de uma sessão de função são avaliadas, consulte Lógica da avaliação de política.

Para especificar o ARN da função no elemento Principal, use o seguinte formato:

"Principal": { "AWS": "arn:aws:iam::AWS-account-ID:role/role-name" }
Importante

Se o seu elemento Principal em uma política de confiança de função contiver um ARN que aponte para uma função específica do IAM, esse ARN será transformado no ID exclusivo da entidade principal da função quando você salvar a política. Isso ajuda a reduzir o risco de alguém elevar seus privilégios ao remover e recriar a função. Normalmente, você não vê esse ID no console, porque o IAM utiliza uma transformação reversa de volta para o ARN de função quando a política de confiança é exibida. No entanto, se você excluir a função, a relação é interrompida. A política não se aplica mais, mesmo se você recriar a função, pois a nova função possui um novo ID principal que não corresponde ao ID armazenado na política de confiança. Quando isso acontece, o ID da entidade principal aparece nas políticas baseadas em recursos porque a AWS não pode mais mapeá-lo de volta para um ARN válido. O resultado final é que, se você excluir e recriar um perfil referenciado no elemento Principal de uma política de confiança, deverá editar o perfil na política para substituir o ID da entidade principal pelo ARN correto. O ARN se transforma novamente no novo ID da entidade principal da função quando você salva a política.

Como alternativa, você pode especificar a entidade principal da função como a entidade principal em uma política baseada em recurso ou criar uma política de permissão ampla que use a chave de condição aws:PrincipalArn. Quando você usa essa chave, a entidade principal de sessão de função recebe as permissões com base no ARN da função assumida e não no ARN da sessão resultante. Como a AWS não converte ARNs da chave de condição em IDs, as permissões concedidas ao ARN da função persistirão se você excluir a função e criar uma nova função com o mesmo nome. Tipos de políticas baseadas em identidade, como limites de permissões ou políticas de sessão, não limitam as permissões concedidas usando a chave de condição aws:PrincipalArn com um curinga (*) no elemento Principal, a menos que as políticas baseadas em identidade contenham uma negação explícita.

Entidades principais da sessão de função

Você pode especificar sessões de função no elemento Principal de uma política baseada em recursos ou em chaves de condição que suportam entidades principais. Quando uma entidade principal ou uma identidade assume uma função, ela recebe credenciais de segurança temporárias com as permissões da função assumida. Quando elas usam essas credenciais de sessão para executar operações na AWS, elas se tornam uma entidade principal da sessão de função.

O formato que você usa para uma entidade principal da sessão de função depende da operação AWS STS que foi usada para assumir a função.

Além disso, os administradores podem projetar um processo para controlar como as sessões de função são emitidas. Por exemplo, eles podem fornecer uma solução de um clique para seus usuários que cria um nome de sessão previsível. Se o administrador fizer isso, você poderá usar as entidades principais da sessão de função em suas políticas ou chaves de condição. Caso contrário, você pode especificar o ARN do perfil como a entidade principal na chave de condição do aws:PrincipalArn. O modo como você especifica a função como entidade principal pode alterar as permissões efetivas para a sessão resultante. Para ter mais informações, consulte Entidades de segurança de função do IAM.

Entidades principais da sessão de função assumida

Uma entidade principal da sessão de função assumida é uma entidade principal de sessão que resulta do uso da operação AssumeRole do AWS STS. Para mais informações sobre quais entidades principais podem assumir uma função usando essa operação, consulte Comparação das operações de API do AWS STS.

Para especificar o ARN da sessão de função assumida no elemento Principal, use o seguinte formato:

"Principal": { "AWS": "arn:aws:sts::AWS-account-ID:assumed-role/role-name/role-session-name" }

Ao especificar uma sessão de função assumida em um elemento Principal, não é possível usar um curinga “*” para indicar todas as sessões. Os principais devem sempre nomear uma sessão específica.

Entidades principais de sessão do OIDC

Uma entidade principal de sessão do OIDC é uma entidade principal de sessão que resulta do uso da operação AssumeRoleWithWebIdentity do AWS STS. Você pode usar um provedor OIDC externo (IdP) para se conectar e, em seguida, assumir um perfil do IAM usando essa operação. Isso tira proveito da federação de identidades e emite uma sessão de função. Para mais informações sobre quais entidades principais podem assumir uma função usando essa operação, consulte Comparação das operações de API do AWS STS.

Ao emitir uma função de um provedor OIDC, você obtém esse tipo especial de entidade principal de sessão que inclui informações sobre o provedor OIDC.

Use esse tipo de entidade principal em sua política para permitir ou negar acesso com base no provedor confiável de identidade da Web. Para especificar o ARN da sessão do perfil de OIDC no elemento Principal de uma política de confiança de perfil, use o seguinte formato:

"Principal": { "Federated": "cognito-identity.amazonaws.com" }
"Principal": { "Federated": "www.amazon.com" }
"Principal": { "Federated": "graph.facebook.com" }
"Principal": { "Federated": "accounts.google.com" }

Entidades principais de sessão SAML

Uma entidade principal da sessão SAML é uma entidade principal de sessão que resulta do uso da operação AWS STS AssumeRoleWithSAML. Você pode usar um provedor de identidade (IdP) SAML externo para se conectar e, em seguida, assumir uma função do IAM usando essa operação. Isso tira proveito da federação de identidades e emite uma sessão de função. Para mais informações sobre quais entidades principais podem assumir uma função usando essa operação, consulte Comparação das operações de API do AWS STS.

Ao emitir uma função de um provedor de identidade SAML, você obtém esse tipo especial de entidade principal de sessão que inclui informações sobre o provedor de identidade SAML.

Use esse tipo de entidade principal em sua política para permitir ou negar acesso com base no provedor confiável de identidade SAML. Para especificar o ARN da sessão de perfil de identidade SAML no elemento Principal de uma política de confiança de perfil, use o seguinte formato:

"Principal": { "Federated": "arn:aws:iam::AWS-account-ID:saml-provider/provider-name" }

Entidades principais de usuário do IAM

Você pode especificar usuários do IAM no elemento Principal de uma política baseada em recursos ou em chaves de condições que suportam entidades principais.

nota

Em um elemento Principal, a parte do nome de usuário do nome do recurso da Amazon (ARN) diferencia maiúsculas e minúsculas.

"Principal": { "AWS": "arn:aws:iam::AWS-account-ID:user/user-name" }
"Principal": {
  "AWS": [
    "arn:aws:iam::AWS-account-ID:user/user-name-1", 
    "arn:aws:iam::AWS-account-ID:user/user-name-2"
  ]
}

Ao especificar usuários em um elemento Principal, você não pode usar um curinga (*) para se referir a "todos os usuários". Entidades principais sempre devem nomear usuários específicos.

Importante

Se o seu elemento Principal em uma política de confiança de função contiver um ARN que aponte para um usuário específico do IAM, o IAM transformará o ARN no ID exclusivo da entidade principal do usuário quando você salvar a política. Isso ajuda a reduzir o risco de alguém elevar seus privilégios ao remover e recriar o usuário. Normalmente, você não vê esse ID no console, pois há também uma transformação reversa de volta para o ARN do usuário quando a política de confiança é exibida. No entanto, se você excluir o usuário, a relação é interrompida. A política não se aplica mais, mesmo se você recriar o usuário. Isso porque o novo usuário tem um novo ID principal que não corresponde ao ID armazenado na política de confiança. Quando isso acontece, o ID da entidade principal aparece nas políticas baseadas em recursos porque a AWS não pode mais mapeá-lo de volta para um ARN válido. Como resultado, se você excluir e recriar um usuário mencionado no elemento Principal de uma política de confiança, você deve editar a função para substituir o agora incorreto ID da entidade principal pelo ARN correto. O IAM transformará novamente o ARN no novo ID da entidade principal do usuário quando você salvar a política.

Entidades principais do Centro de identidade do IAM

No Centro de identidade do IAM, a entidade principal em uma política baseada em recursos deve ser definida como a entidade principal da Conta da AWS. Para especificar o acesso, faça referência ao ARN do perfil do conjunto de permissões no bloco de condições. Para obter detalhes, consulte Referencing permission sets in resource policies, Amazon EKS, and AWS KMS no Guia do usuário do Centro de identidade do IAM.

Entidades principais de sessão de usuário federado do AWS STS

Você pode especificar sessões de usuário federado no elemento Principal de uma política baseada em recursos ou em chaves de condição que suportam entidades principais.

Importante

A AWS recomenda usar as sessões de usuários federados do AWS STS somente quando necessário, como quando é necessário ter acesso de usuário raiz. Em vez disso, sugerimos usar funções para delegar permissões.

Uma entidade principal de sessão de usuário federado do AWS STS é uma entidade principal de sessão que resulta do uso da operação AWS STS GetFederationToken. Nesse caso, o AWS STS usa a federação de identidades como o método para obter tokens temporários de acesso em vez de usar funções do IAM.

Na AWS, um Usuário raiz da conta da AWS ou usuários do IAM podem fazer autenticação usando chaves de acesso de longo prazo. Para mais informações sobre quais entidades principais podem fazer a federação usando essa operação, consulte Comparação das operações de API do AWS STS.

  • Usuário federado do IAM: um usuário do IAM se federa usando a operação GetFederationToken, que resulta em uma entidade principal de sessão de usuário federado para esse usuário do IAM.

  • Usuário raiz federado: um usuário raiz se federa usando a operação GetFederationToken, que resulta em uma entidade principal de sessão de usuário federado para esse usuário raiz.

Quando um usuário do IAM ou usuário raiz solicita credenciais temporárias do AWS STS usando essa operação, ele inicia uma sessão temporária de usuário federado. O ARN dessa sessão é baseado na identidade original que foi federada.

Para especificar o ARN da sessão de usuário federado no elemento Principal, use o seguinte formato:

"Principal": { "AWS": "arn:aws:sts::AWS-account-ID:federated-user/user-name" }

Responsáveis pelos serviços da AWS

Você pode especificar serviços da AWS no elemento Principal de uma política baseada em recursos ou em chaves de condição que suportam entidades principais. Uma entidade principal de serviço é um identificador para um serviço.

As funções do IAM que podem ser assumidas por um produto da AWS são chamadas de funções de serviço. As funções de serviço devem incluir uma política de confiança. Políticas de confiança são políticas baseadas em recursos anexadas a uma função que define quais entidades principais podem assumir a função. Algumas funções de serviço têm políticas de confiança predefinidas. No entanto, em alguns casos, você deve especificar o escopo principal do serviço na política de confiança. A entidade principal do serviço em uma política do IAM não pode ser "Service": "*".

O identificador de uma entidade principal de serviço inclui o nome do serviço e geralmente está no seguinte formato:

service-name.amazonaws.com

O escopo principal do serviço é definido pelo serviço. É possível encontrar a entidade principal de serviço de alguns serviços abrindo Serviços da AWS que funcionam com o IAM, verificando se o serviço tem Yes (Sim) na coluna Service-linked role (Função vinculada ao serviço) e abrindo o link Yes (Sim) para visualizar a documentação da função vinculada a esse serviço específico. Localize a seção Service-Linked Role Permissions (Permissões da função vinculada ao serviço) desse serviço para visualizar o principal do serviço.

O exemplo a seguir mostra uma política que pode ser anexada a uma função do serviço. A política permite que dois serviços, o Amazon ECS eo Elastic Load Balancing, assumam a função. Os serviços podem então realizar qualquer tarefa concedida pela política de permissões atribuída à função (não exibida). Para especificar vários principais de serviço, você não especifica dois elementos Service; pode ter apenas um. Em vez disso, você usa uma variedade de principais de serviços múltiplas como o valor de um único elemento Service.

"Principal": {
    "Service": [
        "ecs.amazonaws.com",
        "elasticloadbalancing.amazonaws.com"
   ]
}

Entidades principais de serviço da AWS nas regiões de aceitação

Você pode lançar recursos em várias regiões da AWS e em algumas dessas regiões pelas quais você deve optar. Para obter uma lista completa das regiões pelas quais você deve optar, consulte Como gerenciar regiões da AWS no guia Referência geral da AWS.

Quando um serviço da AWS em uma região de aceitação faz uma solicitação dentro da mesma região, o formato do nome da entidade principal do serviço é identificado como a versão não regionalizada desse nome:

service-name.amazonaws.com

Quando um serviço da AWS em uma região de aceitação faz uma solicitação entre regiões para outra região, o formato do nome da entidade principal do serviço é identificado como a versão regionalizada desse nome:

service-name.{region}.amazonaws.com

Por exemplo, você tem um tópico do Amazon SNS localizado na região ap-southeast-1 e um bucket do Amazon S3 localizado na região de aceitação ap-east-1. Você deseja configurar as notificações do bucket do S3 para publicar mensagens no tópico do SNS. Para permitir que o serviço S3 publique mensagens no tópico do SNS, você deve conceder à entidade principal do serviço S3 a permissão sns:Publish por meio da política de acesso baseada em recursos do tópico.

Se você especificar a versão não regionalizada da entidade principal do serviço S3, s3.amazonaws.com, na política de acesso do tópico, a solicitação sns:Publish do bucket para o tópico falhará. O exemplo a seguir especifica a entidade principal do serviço S3 não regionalizado no elemento de política Principal da política de acesso a tópicos do SNS.

"Principal": { "Service": "s3.amazonaws.com" }

Como o bucket está localizado em uma região de aceitação e a solicitação é feita fora dessa mesma região, a entidade principal do serviço S3 aparece como o nome da entidade principal do serviço regionalizado, s3.ap-east-1.amazonaws.com. Você deve usar o nome da entidade principal do serviço regionalizado quando um serviço da AWS em uma região de aceitação fizer uma solicitação para outra região. Depois de especificar o nome da entidade principal do serviço regionalizado, se o bucket fizer uma solicitação sns:Publish ao tópico do SNS localizado em outra região, a solicitação será bem-sucedida. O exemplo a seguir especifica a entidade principal do serviço regionalizado S3 no elemento de política Principal da política de acesso a tópicos do SNS.

"Principal": { "Service": "s3.ap-east-1.amazonaws.com" }

Políticas de recursos ou listas de permissões baseadas em entidades principais de serviços para solicitações entre regiões de uma região de aceitação para outra região só serão bem-sucedidas se você especificar o nome da entidade principal do serviço regionalizado.

nota

Para políticas de confiança de perfis do IAM, recomendamos usar o nome da entidade principal do serviço não regionalizado. Os recursos do IAM são globais e, portanto, o mesmo perfil pode ser usado em qualquer região.

Todas as entidades principais

É possível usar um curinga (*) para especificar todas as entidades principais no elemento Principal de uma política baseada em recursos ou em chaves de condições compatíveis com entidades principais. Políticas baseadas em recursos concedem permissões e chaves de condições são usadas para limitar as condições de uma instrução de política.

Importante

É muito recomendável que você não use um caractere curinga (*) no elemento Principal de uma política baseada em recursos com um efeito Allow, a menos que pretenda conceder acesso público ou anônimo. Caso contrário, especifique entidades principais, serviços ou contas da AWS no elemento Principal e depois restrinja ainda mais o acesso no elemento Condition. Isso é especialmente verdadeiro para políticas de confiança do perfil do IAM, porque permitem que outras entidades principais se tornem uma entidade principal em sua conta.

Para políticas baseadas em recursos, usar um caractere curinga (*) com um efeito Allow concede acesso a todos os usuários, incluindo usuários anônimos (acesso público). Para usuários do IAM e entidades principais de função dentro da sua conta, nenhuma outra permissão é necessária. Para entidades principais em outras contas, elas também devem ter permissões baseadas em identidade em suas contas que lhes permitam acessar seu recurso. Isso é chamado de acesso entre contas.

Para usuários anônimos, os seguintes elementos são equivalentes:

"Principal": "*"
"Principal" : { "AWS" : "*" }

Não é possível usar um curinga para fazer a correspondência de parte de um nome de entidade principal ou ARN.

O exemplo a seguir mostra uma política baseada em recurso que pode ser usada em vez de Especificar NotPrincipal com Deny para negar explicitamente todas as entidades principais exceto as especificadas no elemento Condition.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "UsePrincipalArnInsteadOfNotPrincipalWithDeny",
      "Effect": "Deny",
      "Action": "s3:*",
      "Principal": "*",
      "Resource": [
        "arn:aws:s3:::BUCKETNAME/*",
        "arn:aws:s3:::BUCKETNAME"
      ],
      "Condition": {
        "ArnNotEquals": {
          "aws:PrincipalArn": "arn:aws:iam::444455556666:user/user-name"
        }
      }
    }
  ]
}

Mais informações

Para obter mais informações, consulte: