Metadata-Version: 2.1
Name: aws-cdk.aws-iam
Version: 1.91.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: Apache-2.0
Project-URL: Source, https://github.com/aws/aws-cdk.git
Description: # AWS Identity and Access Management Construct Library
        
        <!--BEGIN STABILITY BANNER-->---
        
        
        ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
        
        ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
        
        ---
        <!--END STABILITY BANNER-->
        
        Define a role and add permissions to it. This will automatically create and
        attach an IAM policy to the role:
        
        ```python
        # Example automatically generated. 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 automatically generated. See https://github.com/aws/jsii/issues/826
        user = User(self, "MyUser", password=cdk.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 automatically generated. See https://github.com/aws/jsii/issues/826
        group = Group(self, "MyGroup")
        group.add_managed_policy(ManagedPolicy.from_aws_managed_policy_name("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 automatically generated. See https://github.com/aws/jsii/issues/826
        fn = lambda_.Function(self, "Function", function_props)
        table = dynamodb.Table(self, "Table", table_props)
        
        table.grant_write_data(fn)
        ```
        
        The more generic `grant` method allows you to give specific permissions to a resource:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        fn = lambda_.Function(self, "Function", function_props)
        table = dynamodb.Table(self, "Table", table_props)
        
        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).
        
        ## Roles
        
        Many AWS resources require *Roles* to operate. These Roles define the AWS API
        calls an instance or other AWS service is allowed to make.
        
        Creating Roles and populating them with the right permissions *Statements* is
        a necessary but tedious part of setting up AWS infrastructure. In order to
        help you focus on your business logic, CDK will take care of creating
        roles and populating them with least-privilege permissions automatically.
        
        All constructs that require Roles will create one for you if don't specify
        one at construction time. Permissions will be added to that role
        automatically if you associate the construct with other constructs from the
        AWS Construct Library (for example, if you tell an *AWS CodePipeline* to trigger
        an *AWS Lambda Function*, the Pipeline's Role will automatically get
        `lambda:InvokeFunction` permissions on that particular Lambda Function),
        or if you explicitly grant permissions using `grant` functions (see the
        previous section).
        
        ### Opting out of automatic permissions management
        
        You may prefer to manage a Role's permissions yourself instead of having the
        CDK automatically manage them for you. This may happen in one of the
        following cases:
        
        * You don't like the permissions that CDK automatically generates and
          want to substitute your own set.
        * The least-permissions policy that the CDK generates is becoming too
          big for IAM to store, and you need to add some wildcards to keep the
          policy size down.
        
        To prevent constructs from updating your Role's policy, pass the object
        returned by `myRole.withoutPolicyUpdates()` instead of `myRole` itself.
        
        For example, to have an AWS CodePipeline *not* automatically add the required
        permissions to trigger the expected targets, do the following:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        role = iam.Role(self, "Role",
            assumed_by=iam.ServicePrincipal("codepipeline.amazonaws.com"),
            # custom description if desired
            description="This is a custom role..."
        )
        
        codepipeline.Pipeline(self, "Pipeline",
            # Give the Pipeline an immutable view of the Role
            role=role.without_policy_updates()
        )
        
        # You now have to manage the Role policies yourself
        role.add_to_policy(iam.PolicyStatement(
            actions=[],
            resources=[]
        ))
        ```
        
        ### Using existing roles
        
        If there are Roles in your account that have already been created which you
        would like to use in your CDK application, you can use `Role.fromRoleArn` to
        import them, as follows:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        role = iam.Role.from_role_arn(self, "Role", "arn:aws:iam::123456789012:role/MyExistingRole",
            # Set 'mutable' to 'false' to use the role as-is and prevent adding new
            # policies to it. The default is 'true', which means the role may be
            # modified as part of the deployment.
            mutable=False
        )
        ```
        
        ## Configuring an ExternalId
        
        If you need to create Roles that will be assumed by third 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 automatically generated. 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 automatically generated. See https://github.com/aws/jsii/issues/826
        statement = iam.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 automatically generated. 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"))
        )
        ```
        
        The `PrincipalWithConditions` class can be used to add conditions to a
        principal, especially those that don't take a `conditions` parameter in their
        constructor. The `principal.withConditions()` method can be used to create a
        `PrincipalWithConditions` from an existing principal, for example:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        principal = iam.AccountPrincipal("123456789000").with_conditions({"StringEquals": {"foo": "baz"}})
        ```
        
        > NOTE: If you need to define an IAM condition that uses a token (such as a
        > deploy-time attribute of another resource) in a JSON map key, use `CfnJson` to
        > render this condition. See [this test](./test/integ-condition-with-ref.ts) for
        > an example.
        
        The `WebIdentityPrincipal` class can be used as a principal for web identities like
        Cognito, Amazon, Google or Facebook, for example:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        principal = iam.WebIdentityPrincipal("cognito-identity.amazonaws.com").with_conditions({
            "StringEquals": {"cognito-identity.amazonaws.com:aud": "us-east-2:12345678-abcd-abcd-abcd-123456"},
            "ForAnyValue:StringLike": {"cognito-identity.amazonaws.com:amr": "unauthenticated"}
        })
        ```
        
        ## Parsing JSON Policy Documents
        
        The `PolicyDocument.fromJson` and `PolicyStatement.fromJson` static methods can be used to parse JSON objects. For example:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        policy_document = {
            "Version": "2012-10-17",
            "Statement": [{
                "Sid": "FirstStatement",
                "Effect": "Allow",
                "Action": ["iam:ChangePassword"],
                "Resource": "*"
            }, {
                "Sid": "SecondStatement",
                "Effect": "Allow",
                "Action": "s3:ListAllMyBuckets",
                "Resource": "*"
            }, {
                "Sid": "ThirdStatement",
                "Effect": "Allow",
                "Action": ["s3:List*", "s3:Get*"
                ],
                "Resource": ["arn:aws:s3:::confidential-data", "arn:aws:s3:::confidential-data/*"
                ],
                "Condition": {"Bool": {"aws:_multi_factor_auth_present": "true"}}
            }
            ]
        }
        
        custom_policy_document = iam.PolicyDocument.from_json(policy_document)
        
        # You can pass this document as an initial document to a ManagedPolicy
        # or inline Policy.
        new_managed_policy = ManagedPolicy(stack, "MyNewManagedPolicy",
            document=custom_policy_document
        )
        new_policy = Policy(stack, "MyNewPolicy",
            document=custom_policy_document
        )
        ```
        
        ## Permissions Boundaries
        
        [Permissions
        Boundaries](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)
        can be used as a mechanism to prevent privilege esclation by creating new
        `Role`s. Permissions Boundaries are a Managed Policy, attached to Roles or
        Users, that represent the *maximum* set of permissions they can have. The
        effective set of permissions of a Role (or User) will be the intersection of
        the Identity Policy and the Permissions Boundary attached to the Role (or
        User). Permissions Boundaries are typically created by account
        Administrators, and their use on newly created `Role`s will be enforced by
        IAM policies.
        
        It is possible to attach Permissions Boundaries to all Roles created in a construct
        tree all at once:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        # This imports an existing policy.
        boundary = iam.ManagedPolicy.from_managed_policy_arn(self, "Boundary", "arn:aws:iam::123456789012:policy/boundary")
        
        # This creates a new boundary
        boundary2 = iam.ManagedPolicy(self, "Boundary2",
            statements=[
                iam.PolicyStatement(
                    effect=iam.Effect.DENY,
                    actions=["iam:*"],
                    resources=["*"]
                )
            ]
        )
        
        # Directly apply the boundary to a Role you create
        iam.PermissionsBoundary.of(role).apply(boundary)
        
        # Apply the boundary to an Role that was implicitly created for you
        iam.PermissionsBoundary.of(lambda_function).apply(boundary)
        
        # Apply the boundary to all Roles in a stack
        iam.PermissionsBoundary.of(stack).apply(boundary)
        
        # Remove a Permissions Boundary that is inherited, for example from the Stack level
        iam.PermissionsBoundary.of(custom_resource).clear()
        ```
        
        ## OpenID Connect Providers
        
        OIDC identity providers are entities in IAM that describe an external identity
        provider (IdP) service that supports the [OpenID Connect](http://openid.net/connect) (OIDC) standard, such
        as Google or Salesforce. You use an IAM OIDC identity provider when you want to
        establish trust between an OIDC-compatible IdP and your AWS account. This is
        useful when creating a mobile app or web application that requires access to AWS
        resources, but you don't want to create custom sign-in code or manage your own
        user identities. For more information about this scenario, see [About Web
        Identity Federation] and the relevant documentation in the [Amazon Cognito
        Identity Pools Developer Guide].
        
        The following examples defines an OpenID Connect provider. Two client IDs
        (audiences) are will be able to send authentication requests to
        https://openid/connect.
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        provider = iam.OpenIdConnectProvider(self, "MyProvider",
            url="https://openid/connect",
            client_ids=["myclient1", "myclient2"]
        )
        ```
        
        You can specify an optional list of `thumbprints`. If not specified, the
        thumbprint of the root certificate authority (CA) will automatically be obtained
        from the host as described
        [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html).
        
        Once you define an OpenID connect provider, you can use it with AWS services
        that expect an IAM OIDC provider. For example, when you define an [Amazon
        Cognito identity
        pool](https://docs.aws.amazon.com/cognito/latest/developerguide/open-id.html)
        you can reference the provider's ARN as follows:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        cognito.CfnIdentityPool(self, "IdentityPool",
            open_id_connect_provider_arns=[my_provider.open_id_connect_provider_arn],
            # And the other properties for your identity pool
            allow_unauthenticated_identities=allow_unauthenticated_identities
        )
        ```
        
        The `OpenIdConnectPrincipal` class can be used as a principal used with a `OpenIdConnectProvider`, for example:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        provider = iam.OpenIdConnectProvider(self, "MyProvider",
            url="https://openid/connect",
            client_ids=["myclient1", "myclient2"]
        )
        principal = iam.OpenIdConnectPrincipal(provider)
        ```
        
        ## Users
        
        IAM manages users for your AWS account. To create a new user:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        user = User(self, "MyUser")
        ```
        
        To import an existing user by name [with path](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names):
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        user = User.from_user_name(stack, "MyImportedUserByName", "johnsmith")
        ```
        
        To import an existing user by ARN:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        user = User.from_user_arn(self, "MyImportedUserByArn", "arn:aws:iam::123456789012:user/johnsmith")
        ```
        
        To import an existing user by attributes:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        user = User.from_user_attributes(stack, "MyImportedUserByAttributes",
            user_arn="arn:aws:iam::123456789012:user/johnsmith"
        )
        ```
        
        ## 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.
        * Policies are validated during synthesis to ensure that they have actions, and that policies
          attached to IAM principals specify relevant resources, while policies attached to resources
          specify which IAM principals they apply to.
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Typing :: Typed
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved
Classifier: Framework :: AWS CDK
Classifier: Framework :: AWS CDK :: 1
Requires-Python: >=3.6
Description-Content-Type: text/markdown
