Metadata-Version: 2.1
Name: aws-cdk.aws-iam
Version: 1.13.0
Summary: CDK routines for easily assigning correct and minimal IAM permissions
Home-page: https://github.com/aws/aws-cdk
Author: Amazon Web Services
License: UNKNOWN
Project-URL: Source, https://github.com/aws/aws-cdk.git
Description: ## AWS Identity and Access Management Construct Library
        
        <html></html>---
        
        
        ![Stability: Stable](https://img.shields.io/badge/stability-Stable-success.svg?style=for-the-badge)
        
        ---
        <html></html>
        
        Define a role and add permissions to it. This will automatically create and
        attach an IAM policy to the role:
        
        ```python
        # Example may have issues. See https://github.com/aws/jsii/issues/826
        role = Role(self, "MyRole",
            assumed_by=ServicePrincipal("sns.amazonaws.com")
        )
        
        role.add_to_policy(PolicyStatement(
            resources=["*"],
            actions=["lambda:InvokeFunction"]
        ))
        ```
        
        Define a policy and attach it to groups, users and roles. Note that it is possible to attach
        the policy either by calling `xxx.attachInlinePolicy(policy)` or `policy.attachToXxx(xxx)`.
        
        ```python
        # Example may have issues. See https://github.com/aws/jsii/issues/826
        user = User(self, "MyUser", password=SecretValue.plain_text("1234"))
        group = Group(self, "MyGroup")
        
        policy = Policy(self, "MyPolicy")
        policy.attach_to_user(user)
        group.attach_inline_policy(policy)
        ```
        
        Managed policies can be attached using `xxx.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName))`:
        
        ```python
        # Example may have issues. See https://github.com/aws/jsii/issues/826
        group = Group(self, "MyGroup")
        group.add_managed_policy(ManagedPolicy.from_aws_managed_policy_name("policy/AdministratorAccess"))
        ```
        
        ### Granting permissions to resources
        
        Many of the AWS CDK resources have `grant*` methods that allow you to grant other resources access to that resource. As an example, the following code gives a Lambda function write permissions (Put, Update, Delete) to a DynamoDB table.
        
        ```python
        # Example may have issues. See https://github.com/aws/jsii/issues/826
        fn = lambda.Function(...)
        table = dynamodb.Table(...)
        
        table.grant_write_data(fn)
        ```
        
        The more generic `grant` method allows you to give specific permissions to a resource:
        
        ```python
        # Example may have issues. See https://github.com/aws/jsii/issues/826
        fn = lambda.Function(...)
        table = dynamodb.Table(...)
        
        table.grant(fn, "dynamodb:PutItem")
        ```
        
        The `grant*` methods accept an `IGrantable` object. This interface is implemented by IAM principlal resources (groups, users and roles) and resources that assume a role such as a Lambda function, EC2 instance or a Codebuild project.
        
        You can find which `grant*` methods exist for a resource in the [AWS CDK API Reference](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html).
        
        ### Configuring an ExternalId
        
        If you need to create roles that will be assumed by 3rd parties, it is generally a good idea to [require an `ExternalId`
        to assume them](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html).  Configuring
        an `ExternalId` works like this:
        
        ```python
        # Example may have issues. See https://github.com/aws/jsii/issues/826
        role = iam.Role(self, "MyRole",
            assumed_by=iam.AccountPrincipal("123456789012"),
            external_ids=["SUPPLY-ME"]
        )
        ```
        
        ### Principals vs Identities
        
        When we say *Principal*, we mean an entity you grant permissions to. This
        entity can be an AWS Service, a Role, or something more abstract such as "all
        users in this account" or even "all users in this organization". An
        *Identity* is an IAM representing a single IAM entity that can have
        a policy attached, one of `Role`, `User`, or `Group`.
        
        ### IAM Principals
        
        When defining policy statements as part of an AssumeRole policy or as part of a
        resource policy, statements would usually refer to a specific IAM principal
        under `Principal`.
        
        IAM principals are modeled as classes that derive from the `iam.PolicyPrincipal`
        abstract class. Principal objects include principal type (string) and value
        (array of string), optional set of conditions and the action that this principal
        requires when it is used in an assume role policy document.
        
        To add a principal to a policy statement you can either use the abstract
        `statement.addPrincipal`, one of the concrete `addXxxPrincipal` methods:
        
        * `addAwsPrincipal`, `addArnPrincipal` or `new ArnPrincipal(arn)` for `{ "AWS": arn }`
        * `addAwsAccountPrincipal` or `new AccountPrincipal(accountId)` for `{ "AWS": account-arn }`
        * `addServicePrincipal` or `new ServicePrincipal(service)` for `{ "Service": service }`
        * `addAccountRootPrincipal` or `new AccountRootPrincipal()` for `{ "AWS": { "Ref: "AWS::AccountId" } }`
        * `addCanonicalUserPrincipal` or `new CanonicalUserPrincipal(id)` for `{ "CanonicalUser": id }`
        * `addFederatedPrincipal` or `new FederatedPrincipal(federated, conditions, assumeAction)` for
          `{ "Federated": arn }` and a set of optional conditions and the assume role action to use.
        * `addAnyPrincipal` or `new AnyPrincipal` for `{ "AWS": "*" }`
        
        If multiple principals are added to the policy statement, they will be merged together:
        
        ```python
        # Example may have issues. See https://github.com/aws/jsii/issues/826
        statement = PolicyStatement()
        statement.add_service_principal("cloudwatch.amazonaws.com")
        statement.add_service_principal("ec2.amazonaws.com")
        statement.add_arn_principal("arn:aws:boom:boom")
        ```
        
        Will result in:
        
        ```json
        {
          "Principal": {
            "Service": [ "cloudwatch.amazonaws.com", "ec2.amazonaws.com" ],
            "AWS": "arn:aws:boom:boom"
          }
        }
        ```
        
        The `CompositePrincipal` class can also be used to define complex principals, for example:
        
        ```python
        # Example may have issues. See https://github.com/aws/jsii/issues/826
        role = iam.Role(self, "MyRole",
            assumed_by=iam.CompositePrincipal(
                iam.ServicePrincipal("ec2.amazonaws.com"),
                iam.AccountPrincipal("1818188181818187272"))
        )
        ```
        
        ### Features
        
        * Policy name uniqueness is enforced. If two policies by the same name are attached to the same
          principal, the attachment will fail.
        * Policy names are not required - the CDK logical ID will be used and ensured to be unique.
        
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
