AWS cdk documentation change
Summary
Formatting and typographical improvements including corrected Markdown link syntax, apostrophe/quote consistency, and ellipsis characters. No substantive content changes to security concepts.
Security assessment
Changes are purely cosmetic (formatting, typography, link syntax). No modifications to security guidance, vulnerability disclosures, or access control logic. The documentation continues to explain IAM security concepts without introducing new security features or addressing specific vulnerabilities.
Diff
diff --git a/cdk/v2/guide/permissions.md b/cdk/v2/guide/permissions.md index 0a62c2393..b3062cb98 100644 --- a//cdk/v2/guide/permissions.md +++ b//cdk/v2/guide/permissions.md @@ -23 +23 @@ In security contexts, the term "principal" refers specifically to authenticated -For example, if you create an IAM group, you can grant the group (and thus its members) write access to an Amazon RDS table. However, the group itself is not a principal because it doesn't represent a single entity (also, you cannot log in to a group). +For example, if you create an IAM group, you can grant the group (and thus its members) write access to an Amazon RDS table. However, the group itself is not a principal because it doesn’t represent a single entity (also, you cannot log in to a group). @@ -25 +25 @@ For example, if you create an IAM group, you can grant the group (and thus its m -In the CDK's IAM library, classes that directly or indirectly identify principals implement the [`IPrincipal`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) interface, allowing these objects to be used interchangeably in access policies. However, not all of them are principals in the security sense. These objects include: +In the CDK’s IAM library, classes that directly or indirectly identify principals implement the [`IPrincipal`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) interface, allowing these objects to be used interchangeably in access policies. However, not all of them are principals in the security sense. These objects include: @@ -27 +27 @@ In the CDK's IAM library, classes that directly or indirectly identify principal - 1. IAM resources such as `[Role](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)`, `[User](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html)`, and `[Group](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html)` + 1. IAM resources such as [`Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html), [`User`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html), and [`Group`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html) @@ -33 +33 @@ In the CDK's IAM library, classes that directly or indirectly identify principal - 4. Account principals (`new iam.[AccountPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.AccountPrincipal.html)('0123456789012'))` + 4. Account principals (`new iam.[AccountPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.AccountPrincipal.html)('0123456789012')`) @@ -35 +35 @@ In the CDK's IAM library, classes that directly or indirectly identify principal - 5. Canonical user principals (`new iam.[CanonicalUserPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.CanonicalUserPrincipal.html)('79a59d[...]7ef2be')`) + 5. Canonical user principals (`new iam.[CanonicalUserPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.CanonicalUserPrincipal.html)('79a59d[…]7ef2be')`) @@ -41 +41 @@ In the CDK's IAM library, classes that directly or indirectly identify principal - 8. An `iam.[CompositePrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.CompositePrincipal.html)(principal1, principal2, ...)` to trust multiple principals + 8. An `iam.[CompositePrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.CompositePrincipal.html)(principal1, principal2, …)` to trust multiple principals @@ -50 +50 @@ Every construct that represents a resource that can be accessed, such as an Amaz -For example, Amazon S3 buckets have the methods `[grantRead](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html#grantwbrreadidentity-objectskeypattern)` and `[grantReadWrite](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html#grantwbrreadwbrwriteidentity-objectskeypattern)` (Python: `grant_read`, `grant_read_write`) to enable read and read/write access, respectively, from an entity to the bucket. The entity doesn't have to know exactly which Amazon S3 IAM permissions are required to perform these operations. +For example, Amazon S3 buckets have the methods [`grantRead`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html#grantwbrreadidentity-objectskeypattern) and [`grantReadWrite`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html#grantwbrreadwbrwriteidentity-objectskeypattern) (Python: `grant_read`, `grant_read_write`) to enable read and read/write access, respectively, from an entity to the bucket. The entity doesn’t have to know exactly which Amazon S3 IAM permissions are required to perform these operations. @@ -52 +52 @@ For example, Amazon S3 buckets have the methods `[grantRead](https://docs.aws.am -The first argument of a **grant** method is always of type [IGrantable](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IGrantable.html). This interface represents entities that can be granted permissions. That is, it represents resources with roles, such as the IAM objects `[Role](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)`, `[User](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html)`, and `[Group](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html)`. +The first argument of a **grant** method is always of type [`IGrantable`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IGrantable.html). This interface represents entities that can be granted permissions. That is, it represents resources with roles, such as the IAM objects [`Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html), [`User`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html), and [`Group`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html). @@ -56 +56 @@ Other entities can also be granted permissions. For example, later in this topic -Resources that use execution roles, such as `[lambda.Function](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html)`, also implement `IGrantable`, so you can grant them access directly instead of granting access to their role. For example, if `bucket` is an Amazon S3 bucket, and `function` is a Lambda function, the following code grants the function read access to the bucket. +Resources that use execution roles, such as [`lambda.Function`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html), also implement `IGrantable`, so you can grant them access directly instead of granting access to their role. For example, if `bucket` is an Amazon S3 bucket, and `function` is a Lambda function, the following code grants the function read access to the bucket. @@ -90 +90 @@ Sometimes permissions must be applied while your stack is being deployed. One su -Another case is when a service verifies that the role you pass to it has the right policies applied. (A number of AWS services do this to make sure that you didn't forget to set the policies.) In those cases, the deployment might fail if the permissions are applied too late. +Another case is when a service verifies that the role you pass to it has the right policies applied. (A number of AWS services do this to make sure that you didn’t forget to set the policies.) In those cases, the deployment might fail if the permissions are applied too late. @@ -92 +92 @@ Another case is when a service verifies that the role you pass to it has the rig -To force the grant's permissions to be applied before another resource is created, you can add a dependency on the grant itself, as shown here. Though the return value of grant methods is commonly discarded, every grant method in fact returns an `iam.Grant` object. +To force the grant’s permissions to be applied before another resource is created, you can add a dependency on the grant itself, as shown here. Though the return value of grant methods is commonly discarded, every grant method in fact returns an `iam.Grant` object. @@ -136 +136 @@ C# -The IAM package contains a `[Role](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html)` construct that represents IAM roles. The following code creates a new role, trusting the Amazon EC2 service. +The IAM package contains a [`Role`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html) construct that represents IAM roles. The following code creates a new role, trusting the Amazon EC2 service. @@ -188 +188 @@ C# -You can add permissions to a role by calling the role's `[addToPolicy](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#addwbrtowbrpolicystatement)` method (Python: `add_to_policy`), passing in a `[PolicyStatement](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html)` that defines the rule to be added. The statement is added to the role's default policy; if it has none, one is created. +You can add permissions to a role by calling the role’s [`addToPolicy`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#addwbrtowbrpolicystatement) method (Python: `add_to_policy`), passing in a [`PolicyStatement`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html) that defines the rule to be added. The statement is added to the role’s default policy; if it has none, one is created. @@ -259 +259 @@ C# -In the preceding example, we've created a new `[PolicyStatement](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html)` inline with the `[addToPolicy](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#addwbrtowbrpolicystatement)` (Python: `add_to_policy`) call. You can also pass in an existing policy statement or one you've modified. The [PolicyStatement](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html) object has [numerous methods](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html#methods) for adding principals, resources, conditions, and actions. +In the preceding example, we’ve created a new [`PolicyStatement`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html) inline with the [`addToPolicy`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#addwbrtowbrpolicystatement) (Python: `add_to_policy`) call. You can also pass in an existing policy statement or one you’ve modified. The [`PolicyStatement`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html) object has [numerous methods](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html#methods) for adding principals, resources, conditions, and actions. @@ -261 +261 @@ In the preceding example, we've created a new `[PolicyStatement](https://docs.aw -If you're using a construct that requires a role to function correctly, you can do one of the following: +If you’re using a construct that requires a role to function correctly, you can do one of the following: @@ -392,0 +391 @@ Python + ) @@ -404,0 +404 @@ Java + ) @@ -421 +421 @@ C# -A few resources in AWS, such as Amazon S3 buckets and IAM roles, also have a resource policy. These constructs have an `addToResourcePolicy` method (Python: `add_to_resource_policy`), which takes a `[PolicyStatement](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html)` as its argument. Every policy statement added to a resource policy must specify at least one principal. +A few resources in AWS, such as Amazon S3 buckets and IAM roles, also have a resource policy. These constructs have an `addToResourcePolicy` method (Python: `add_to_resource_policy`), which takes a [`PolicyStatement`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html) as its argument. Every policy statement added to a resource policy must specify at least one principal. @@ -485 +484 @@ If you have defined an IAM user, principal, group, or role outside your AWS CDK - * For users, call `[User.fromUserArn()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html#static-fromwbruserwbrarnscope-id-userarn)` or `[User.fromUserName()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html#static-fromwbruserwbrnamescope-id-username)`. `User.fromUserAttributes()` is also available, but currently provides the same functionality as `User.fromUserArn()`. + * For users, call [`User.fromUserArn()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html#static-fromwbruserwbrarnscope-id-userarn) or [`User.fromUserName()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html#static-fromwbruserwbrnamescope-id-username). `User.fromUserAttributes()` is also available, but currently provides the same functionality as `User.fromUserArn()`. @@ -487 +486 @@ If you have defined an IAM user, principal, group, or role outside your AWS CDK - * For principals, instantiate an `[ArnPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ArnPrincipal.html)` object. + * For principals, instantiate an [`ArnPrincipal`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ArnPrincipal.html) object. @@ -489 +488 @@ If you have defined an IAM user, principal, group, or role outside your AWS CDK - * For groups, call `[Group.fromGroupArn()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html#static-fromwbrgroupwbrarnscope-id-grouparn)` or `[Group.fromGroupName()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html#static-fromwbrgroupwbrnamescope-id-groupname)`. + * For groups, call [`Group.fromGroupArn()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html#static-fromwbrgroupwbrarnscope-id-grouparn) or [`Group.fromGroupName()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html#static-fromwbrgroupwbrnamescope-id-groupname). @@ -491 +490 @@ If you have defined an IAM user, principal, group, or role outside your AWS CDK - * For roles, call `[Role.fromRoleArn()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#static-fromwbrrolewbrarnscope-id-rolearn-options)` or `[Role.fromRoleName()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#static-fromwbrrolewbrnamescope-id-rolename)`. + * For roles, call [`Role.fromRoleArn()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#static-fromwbrrolewbrarnscope-id-rolearn-options) or [`Role.fromRoleName()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#static-fromwbrrolewbrnamescope-id-rolename). @@ -498 +497 @@ Policies (including managed policies) can be used in similar fashion using the f - * `[Policy.fromPolicyName](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Policy.html#static-fromwbrpolicywbrnamescope-id-policyname)` + * [`Policy.fromPolicyName`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Policy.html#static-fromwbrpolicywbrnamescope-id-policyname) @@ -500 +499 @@ Policies (including managed policies) can be used in similar fashion using the f - * `[ManagedPolicy.fromManagedPolicyArn](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrarnscope-id-managedpolicyarn)` + * [`ManagedPolicy.fromManagedPolicyArn`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrarnscope-id-managedpolicyarn) @@ -502 +501 @@ Policies (including managed policies) can be used in similar fashion using the f - * `[ManagedPolicy.fromManagedPolicyName](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrnamescope-id-managedpolicyname)` + * [`ManagedPolicy.fromManagedPolicyName`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrnamescope-id-managedpolicyname) @@ -504 +503 @@ Policies (including managed policies) can be used in similar fashion using the f - * `[ManagedPolicy.fromAwsManagedPolicyName](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrawswbrmanagedwbrpolicywbrnamemanagedpolicyname)` + * [`ManagedPolicy.fromAwsManagedPolicyName`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrawswbrmanagedwbrpolicywbrnamemanagedpolicyname)