1 | import { Duration, Resource } from '@aws-cdk/core';
|
2 | import { Construct } from 'constructs';
|
3 | import { Grant } from './grant';
|
4 | import { IIdentity } from './identity-base';
|
5 | import { IManagedPolicy } from './managed-policy';
|
6 | import { Policy } from './policy';
|
7 | import { PolicyDocument } from './policy-document';
|
8 | import { PolicyStatement } from './policy-statement';
|
9 | import { AddToPrincipalPolicyResult, IPrincipal, PrincipalPolicyFragment } from './principals';
|
10 | /**
|
11 | * Properties for defining an IAM Role
|
12 | */
|
13 | export interface RoleProps {
|
14 | /**
|
15 | * The IAM principal (i.e. `new ServicePrincipal('sns.amazonaws.com')`)
|
16 | * which can assume this role.
|
17 | *
|
18 | * You can later modify the assume role policy document by accessing it via
|
19 | * the `assumeRolePolicy` property.
|
20 | */
|
21 | readonly assumedBy: IPrincipal;
|
22 | /**
|
23 | * ID that the role assumer needs to provide when assuming this role
|
24 | *
|
25 | * If the configured and provided external IDs do not match, the
|
26 | * AssumeRole operation will fail.
|
27 | *
|
28 | * @deprecated see {@link externalIds}
|
29 | *
|
30 | * @default No external ID required
|
31 | */
|
32 | readonly externalId?: string;
|
33 | /**
|
34 | * List of IDs that the role assumer needs to provide one of when assuming this role
|
35 | *
|
36 | * If the configured and provided external IDs do not match, the
|
37 | * AssumeRole operation will fail.
|
38 | *
|
39 | * @default No external ID required
|
40 | */
|
41 | readonly externalIds?: string[];
|
42 | /**
|
43 | * A list of managed policies associated with this role.
|
44 | *
|
45 | * You can add managed policies later using
|
46 | * `addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName))`.
|
47 | *
|
48 | * @default - No managed policies.
|
49 | */
|
50 | readonly managedPolicies?: IManagedPolicy[];
|
51 | /**
|
52 | * A list of named policies to inline into this role. These policies will be
|
53 | * created with the role, whereas those added by ``addToPolicy`` are added
|
54 | * using a separate CloudFormation resource (allowing a way around circular
|
55 | * dependencies that could otherwise be introduced).
|
56 | *
|
57 | * @default - No policy is inlined in the Role resource.
|
58 | */
|
59 | readonly inlinePolicies?: {
|
60 | [name: string]: PolicyDocument;
|
61 | };
|
62 | /**
|
63 | * The path associated with this role. For information about IAM paths, see
|
64 | * Friendly Names and Paths in IAM User Guide.
|
65 | *
|
66 | * @default /
|
67 | */
|
68 | readonly path?: string;
|
69 | /**
|
70 | * AWS supports permissions boundaries for IAM entities (users or roles).
|
71 | * A permissions boundary is an advanced feature for using a managed policy
|
72 | * to set the maximum permissions that an identity-based policy can grant to
|
73 | * an IAM entity. An entity's permissions boundary allows it to perform only
|
74 | * the actions that are allowed by both its identity-based policies and its
|
75 | * permissions boundaries.
|
76 | *
|
77 | * @link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html#cfn-iam-role-permissionsboundary
|
78 | * @link https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html
|
79 | *
|
80 | * @default - No permissions boundary.
|
81 | */
|
82 | readonly permissionsBoundary?: IManagedPolicy;
|
83 | /**
|
84 | * A name for the IAM role. For valid values, see the RoleName parameter for
|
85 | * the CreateRole action in the IAM API Reference.
|
86 | *
|
87 | * IMPORTANT: If you specify a name, you cannot perform updates that require
|
88 | * replacement of this resource. You can perform updates that require no or
|
89 | * some interruption. If you must replace the resource, specify a new name.
|
90 | *
|
91 | * If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to
|
92 | * acknowledge your template's capabilities. For more information, see
|
93 | * Acknowledging IAM Resources in AWS CloudFormation Templates.
|
94 | *
|
95 | * @default - AWS CloudFormation generates a unique physical ID and uses that ID
|
96 | * for the role name.
|
97 | */
|
98 | readonly roleName?: string;
|
99 | /**
|
100 | * The maximum session duration that you want to set for the specified role.
|
101 | * This setting can have a value from 1 hour (3600sec) to 12 (43200sec) hours.
|
102 | *
|
103 | * Anyone who assumes the role from the AWS CLI or API can use the
|
104 | * DurationSeconds API parameter or the duration-seconds CLI parameter to
|
105 | * request a longer session. The MaxSessionDuration setting determines the
|
106 | * maximum duration that can be requested using the DurationSeconds
|
107 | * parameter.
|
108 | *
|
109 | * If users don't specify a value for the DurationSeconds parameter, their
|
110 | * security credentials are valid for one hour by default. This applies when
|
111 | * you use the AssumeRole* API operations or the assume-role* CLI operations
|
112 | * but does not apply when you use those operations to create a console URL.
|
113 | *
|
114 | * @link https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html
|
115 | *
|
116 | * @default Duration.hours(1)
|
117 | */
|
118 | readonly maxSessionDuration?: Duration;
|
119 | /**
|
120 | * A description of the role. It can be up to 1000 characters long.
|
121 | *
|
122 | * @default - No description.
|
123 | */
|
124 | readonly description?: string;
|
125 | }
|
126 | /**
|
127 | * Options allowing customizing the behavior of {@link Role.fromRoleArn}.
|
128 | */
|
129 | export interface FromRoleArnOptions {
|
130 | /**
|
131 | * Whether the imported role can be modified by attaching policy resources to it.
|
132 | *
|
133 | * @default true
|
134 | */
|
135 | readonly mutable?: boolean;
|
136 | /**
|
137 | * For immutable roles: add grants to resources instead of dropping them
|
138 | *
|
139 | * If this is `false` or not specified, grant permissions added to this role are ignored.
|
140 | * It is your own responsibility to make sure the role has the required permissions.
|
141 | *
|
142 | * If this is `true`, any grant permissions will be added to the resource instead.
|
143 | *
|
144 | * @default false
|
145 | */
|
146 | readonly addGrantsToResources?: boolean;
|
147 | }
|
148 | /**
|
149 | * IAM Role
|
150 | *
|
151 | * Defines an IAM role. The role is created with an assume policy document associated with
|
152 | * the specified AWS service principal defined in `serviceAssumeRole`.
|
153 | */
|
154 | export declare class Role extends Resource implements IRole {
|
155 | /**
|
156 | * Import an external role by ARN.
|
157 | *
|
158 | * If the imported Role ARN is a Token (such as a
|
159 | * `CfnParameter.valueAsString` or a `Fn.importValue()`) *and* the referenced
|
160 | * role has a `path` (like `arn:...:role/AdminRoles/Alice`), the
|
161 | * `roleName` property will not resolve to the correct value. Instead it
|
162 | * will resolve to the first path component. We unfortunately cannot express
|
163 | * the correct calculation of the full path name as a CloudFormation
|
164 | * expression. In this scenario the Role ARN should be supplied without the
|
165 | * `path` in order to resolve the correct role resource.
|
166 | *
|
167 | * @param scope construct scope
|
168 | * @param id construct id
|
169 | * @param roleArn the ARN of the role to import
|
170 | * @param options allow customizing the behavior of the returned role
|
171 | */
|
172 | static fromRoleArn(scope: Construct, id: string, roleArn: string, options?: FromRoleArnOptions): IRole;
|
173 | /**
|
174 | * Import an external role by name.
|
175 | *
|
176 | * The imported role is assumed to exist in the same account as the account
|
177 | * the scope's containing Stack is being deployed to.
|
178 | */
|
179 | static fromRoleName(scope: Construct, id: string, roleName: string): IRole;
|
180 | readonly grantPrincipal: IPrincipal;
|
181 | readonly principalAccount: string | undefined;
|
182 | readonly assumeRoleAction: string;
|
183 | /**
|
184 | * The assume role policy document associated with this role.
|
185 | */
|
186 | readonly assumeRolePolicy?: PolicyDocument;
|
187 | /**
|
188 | * Returns the ARN of this role.
|
189 | */
|
190 | readonly roleArn: string;
|
191 | /**
|
192 | * Returns the stable and unique string identifying the role. For example,
|
193 | * AIDAJQABLZS4A3QDU576Q.
|
194 | *
|
195 | * @attribute
|
196 | */
|
197 | readonly roleId: string;
|
198 | /**
|
199 | * Returns the name of the role.
|
200 | */
|
201 | readonly roleName: string;
|
202 | /**
|
203 | * Returns the role.
|
204 | */
|
205 | readonly policyFragment: PrincipalPolicyFragment;
|
206 | /**
|
207 | * Returns the permissions boundary attached to this role
|
208 | */
|
209 | readonly permissionsBoundary?: IManagedPolicy;
|
210 | private defaultPolicy?;
|
211 | private readonly managedPolicies;
|
212 | private readonly attachedPolicies;
|
213 | private readonly inlinePolicies;
|
214 | private immutableRole?;
|
215 | constructor(scope: Construct, id: string, props: RoleProps);
|
216 | /**
|
217 | * Adds a permission to the role's default policy document.
|
218 | * If there is no default policy attached to this role, it will be created.
|
219 | * @param statement The permission statement to add to the policy document
|
220 | */
|
221 | addToPrincipalPolicy(statement: PolicyStatement): AddToPrincipalPolicyResult;
|
222 | addToPolicy(statement: PolicyStatement): boolean;
|
223 | /**
|
224 | * Attaches a managed policy to this role.
|
225 | * @param policy The the managed policy to attach.
|
226 | */
|
227 | addManagedPolicy(policy: IManagedPolicy): void;
|
228 | /**
|
229 | * Attaches a policy to this role.
|
230 | * @param policy The policy to attach
|
231 | */
|
232 | attachInlinePolicy(policy: Policy): void;
|
233 | /**
|
234 | * Grant the actions defined in actions to the identity Principal on this resource.
|
235 | */
|
236 | grant(grantee: IPrincipal, ...actions: string[]): Grant;
|
237 | /**
|
238 | * Grant permissions to the given principal to pass this role.
|
239 | */
|
240 | grantPassRole(identity: IPrincipal): Grant;
|
241 | /**
|
242 | * Return a copy of this Role object whose Policies will not be updated
|
243 | *
|
244 | * Use the object returned by this method if you want this Role to be used by
|
245 | * a construct without it automatically updating the Role's Policies.
|
246 | *
|
247 | * If you do, you are responsible for adding the correct statements to the
|
248 | * Role's policies yourself.
|
249 | */
|
250 | withoutPolicyUpdates(options?: WithoutPolicyUpdatesOptions): IRole;
|
251 | protected validate(): string[];
|
252 | }
|
253 | /**
|
254 | * A Role object
|
255 | */
|
256 | export interface IRole extends IIdentity {
|
257 | /**
|
258 | * Returns the ARN of this role.
|
259 | *
|
260 | * @attribute
|
261 | */
|
262 | readonly roleArn: string;
|
263 | /**
|
264 | * Returns the name of this role.
|
265 | *
|
266 | * @attribute
|
267 | */
|
268 | readonly roleName: string;
|
269 | /**
|
270 | * Grant the actions defined in actions to the identity Principal on this resource.
|
271 | */
|
272 | grant(grantee: IPrincipal, ...actions: string[]): Grant;
|
273 | /**
|
274 | * Grant permissions to the given principal to pass this role.
|
275 | */
|
276 | grantPassRole(grantee: IPrincipal): Grant;
|
277 | }
|
278 | /**
|
279 | * Options for the `withoutPolicyUpdates()` modifier of a Role
|
280 | */
|
281 | export interface WithoutPolicyUpdatesOptions {
|
282 | /**
|
283 | * Add grants to resources instead of dropping them
|
284 | *
|
285 | * If this is `false` or not specified, grant permissions added to this role are ignored.
|
286 | * It is your own responsibility to make sure the role has the required permissions.
|
287 | *
|
288 | * If this is `true`, any grant permissions will be added to the resource instead.
|
289 | *
|
290 | * @default false
|
291 | */
|
292 | readonly addGrantsToResources?: boolean;
|
293 | }
|