UNPKG

11 kBTypeScriptView Raw
1import { Duration, Resource } from '@aws-cdk/core';
2import { Construct } from 'constructs';
3import { Grant } from './grant';
4import { IIdentity } from './identity-base';
5import { IManagedPolicy } from './managed-policy';
6import { Policy } from './policy';
7import { PolicyDocument } from './policy-document';
8import { PolicyStatement } from './policy-statement';
9import { AddToPrincipalPolicyResult, IPrincipal, PrincipalPolicyFragment } from './principals';
10/**
11 * Properties for defining an IAM Role
12 */
13export 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 */
129export 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 */
154export 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 */
256export 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 */
281export 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}