Este é o Guia do Desenvolvedor AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
A AWS Construct Library usa alguns idiomas comuns e amplamente implementados para gerenciar o acesso e as permissões. O módulo IAM fornece as ferramentas necessárias para usar esses idiomas.
AWS CDK usa AWS CloudFormation para implantar mudanças. Cada implantação envolve um ator (um desenvolvedor ou um sistema automatizado) que inicia uma AWS CloudFormation implantação. Ao fazer isso, o ator assumirá uma ou mais identidades do IAM (usuário ou funções) e, opcionalmente, passará uma função para. AWS CloudFormation
Se você usa AWS IAM Identity Center para se autenticar como usuário, o provedor de login único fornece credenciais de sessão de curta duração que autorizam você a atuar como uma função predefinida do IAM. Para saber como o AWS CDK obtém as AWS credenciais da autenticação do IAM Identity Center, consulte Compreender a autenticação do IAM Identity Center no Guia de referência AWS SDKs de ferramentas.
Entidades principais
Um principal do IAM é uma AWS entidade autenticada que representa um usuário, serviço ou aplicativo que pode chamar AWS APIs. A AWS Construct Library suporta a especificação de diretores de várias maneiras flexíveis para permitir que eles acessem seus AWS recursos.
Em contextos de segurança, o termo “entidade principal” se refere especificamente a entidades autenticadas, como usuários. Objetos como grupos e funções não representam usuários (e outras entidades autenticadas), mas os identificam indiretamente com o objetivo de conceder permissões.
Por exemplo, se você criar um grupo do IAM, poderá conceder ao grupo (e, portanto, a seus membros) acesso de gravação a uma tabela do Amazon RDS. No entanto, o grupo em si não é uma entidade principal porque não representa uma única entidade (além disso, você não pode fazer login em um grupo).
Na biblioteca IAM do CDK, classes que identificam direta ou indiretamente as entidades principais implementam a interface IPrincipal
, permitindo que esses objetos sejam usados de forma intercambiável nas políticas de acesso. No entanto, nem todos são entidades principais no sentido de segurança. Esses objetos incluem:
-
Entidades principais de serviço (
new iam.ServicePrincipal('service.amazonaws.com')
) -
Entidades principais federadas (
new iam.FederatedPrincipal('cognito-identity.amazonaws.com')
) -
Entidades principais da conta (
new iam.AccountPrincipal('0123456789012'))
) -
Entidades principais de usuários canônicos (
new iam.CanonicalUserPrincipal('79a59d[...]7ef2be')
) -
AWS Organizations diretores ()
new iam.OrganizationPrincipal('org-id')
-
Entidades principais arbitrárias do ARN (
new iam.ArnPrincipal(res.arn)
) -
Um
iam.CompositePrincipal(principal1, principal2, ...)
para confiar em várias entidades principais
Concessões
Cada constructo que representa um recurso que pode ser acessado, como um bucket do Amazon S3 ou uma tabela do Amazon DynamoDB, tem métodos que concedem acesso a outra entidade. Todos esses métodos têm nomes que começam com grant.
Por exemplo, os buckets do Amazon S3 têm os métodos grantRead
e grantReadWrite
(Python:grant_read
, grant_read_write
) para permitir o acesso de leitura e leitura/gravação, respectivamente, de uma entidade ao bucket. A entidade não precisa saber exatamente quais permissões do Amazon S3 IAM são necessárias para realizar essas operações.
O primeiro argumento de um método de concessão é sempre do tipo IGrantable. Essa interface representa entidades que podem receber permissões. Ou seja, ela representa recursos com funções, como os objetos do IAM Role
, User
e Group
.
Outras entidades também podem receber permissões. Por exemplo, mais adiante neste tópico, mostraremos como conceder a um CodeBuild projeto acesso a um bucket do Amazon S3. Geralmente, a função associada é obtida por meio de uma propriedade role
na entidade que está recebendo acesso.
Recursos que usam funções de execução, como o lambda.Function
, também implementam o IGrantable
, para que você possa conceder acesso direto a eles em vez de conceder acesso à função deles. Por exemplo, se bucket
for um bucket do Amazon S3 e function
for uma função do Lambda, o código a seguir concede à função acesso de leitura ao bucket.
bucket.grantRead(function);
Às vezes, as permissões precisam ser aplicadas enquanto sua pilha está sendo implantada. Um desses casos é quando você concede a um recurso personalizado AWS CloudFormation acesso a algum outro recurso. O recurso personalizado será invocado durante a implantação, portanto, ele deve ter as permissões especificadas no momento da implantação.
Outro caso é quando um serviço verifica se a função que você passa para ele tem as políticas corretas aplicadas. (Vários serviços AWS fazem isso para garantir que você não se esqueça de definir as políticas.) Nesses casos, a implantação pode falhar se as permissões forem aplicadas tarde demais.
Para forçar a aplicação das permissões da concessão antes da criação de outro recurso, você pode adicionar uma dependência da concessão em si, conforme mostrado aqui. Embora o valor de retorno dos métodos de concessão seja geralmente descartado, todo método de concessão na verdade retorna um objeto iam.Grant
.
const grant = bucket.grantRead(lambda);
const custom = new CustomResource(...);
custom.node.addDependency(grant);
Perfis
O pacote do IAM contém um constructo Role
que representa os perfis do IAM. O código a seguir cria uma nova função, confiando no EC2 serviço da Amazon.
import * as iam from 'aws-cdk-lib/aws-iam';
const role = new iam.Role(this, 'Role', {
assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'), // required
});
Você pode adicionar permissões a uma função chamando o método addToPolicy
da função (Python: add_to_policy
), passando um PolicyStatement
que define a regra a ser adicionada. A declaração é adicionada à política padrão da função; se não tiver nenhuma, uma será criada.
O exemplo a seguir adiciona uma declaração de política Deny
ao perfis para as ações ec2:SomeAction
e s3:AnotherAction
dos recursos bucket
e otherRole
(Python: other_role
), sob a condição de que o serviço autorizado seja AWS CodeBuild.
role.addToPolicy(new iam.PolicyStatement({
effect: iam.Effect.DENY,
resources: [bucket.bucketArn, otherRole.roleArn],
actions: ['ec2:SomeAction', 's3:AnotherAction'],
conditions: {StringEquals: {
'ec2:AuthorizedService': 'codebuild.amazonaws.com',
}}}));
No exemplo anterior, criamos uma nova linha PolicyStatement
com a chamada addToPolicy
(Python: add_to_policy
). Você também pode transmitir uma declaração de política existente ou uma que você tenha modificado. O PolicyStatementobjeto tem vários métodos para adicionar princípios, recursos, condições e ações.
Se estiver usando um constructo que requer uma função para funcionar corretamente, você pode executar uma das seguintes ações:
-
Passar uma função existente ao instanciar o objeto de constructo.
-
Deixar que o constructo crie uma nova função para você, confiando na entidade principal de serviço apropriada. O exemplo a seguir usa essa construção: um CodeBuild projeto.
import * as codebuild from 'aws-cdk-lib/aws-codebuild';
// imagine roleOrUndefined is a function that might return a Role object
// under some conditions, and undefined under other conditions
const someRole: iam.IRole | undefined = roleOrUndefined();
const project = new codebuild.Project(this, 'Project', {
// if someRole is undefined, the Project creates a new default role,
// trusting the codebuild.amazonaws.com service principal
role: someRole,
});
Depois que o objeto é criado, a função (seja a função passada ou a padrão criada pelo constructo) fica disponível como propriedade role
. No entanto, essa propriedade não está disponível em recursos externos. Portanto, esses constructos têm um método addToRolePolicy
(Python: add_to_role_policy
).
O método não faz nada se o constructo for um recurso externo e, caso contrário, chama o método addToPolicy
(Python: add_to_policy
) da propriedade role
. Isso evita que você precise lidar com o caso indefinido de forma explícita.
O exemplo a seguir demonstra:
// project is imported into the CDK application
const project = codebuild.Project.fromProjectName(this, 'Project', 'ProjectName');
// project is imported, so project.role is undefined, and this call has no effect
project.addToRolePolicy(new iam.PolicyStatement({
effect: iam.Effect.ALLOW, // ... and so on defining the policy
}));
Políticas de recursos
Alguns recursos AWS, como buckets do Amazon S3 e funções do IAM, também têm uma política de recursos. Esses constructos têm um método addToResourcePolicy
(Python: add_to_resource_policy
), que usa PolicyStatement
como argumento. Cada declaração de política adicionada a uma política de recursos deve especificar pelo menos uma entidade principal.
No exemplo a seguir, o bucket do Amazon S3 concede ao bucket
um perfil com a permissão s3:SomeAction
para si mesmo.
bucket.addToResourcePolicy(new iam.PolicyStatement({
effect: iam.Effect.ALLOW,
actions: ['s3:SomeAction'],
resources: [bucket.bucketArn],
principals: [role]
}));
Usando objetos externos do IAM
Se você definiu um usuário, diretor, grupo ou função do IAM fora do seu AWS CDK aplicativo, você pode usar esse objeto do IAM em seu AWS CDK aplicativo. Para fazer isso, crie uma referência a ele usando seu ARN ou seu nome. (Use o nome para usuários, grupos e perfis.) A referência retornada pode então ser usada para conceder permissões ou criar declarações de política, conforme explicado anteriormente.
-
Para usuários, chame
User.fromUserArn()
ouUser.fromUserName()
.User.fromUserAttributes()
também está disponível, mas atualmente fornece a mesma funcionalidade queUser.fromUserArn()
. -
Para as entidades principais, instancie um objeto
ArnPrincipal
. -
Para grupos, chame
Group.fromGroupArn()
ouGroup.fromGroupName()
. -
Para funções, chame
Role.fromRoleArn()
ouRole.fromRoleName()
.
As políticas (incluindo políticas gerenciadas) podem ser usadas de forma semelhante usando os métodos a seguir. Você pode usar referências a esses objetos em qualquer lugar em que uma política do IAM seja necessária.
nota
Como acontece com todas as referências a AWS recursos externos, você não pode modificar objetos externos do IAM em seu aplicativo CDK.