UNPKG

19.5 kBTypeScriptView Raw
1import * as cdk from '@aws-cdk/core';
2import { IOpenIdConnectProvider } from './oidc-provider';
3import { PolicyDocument } from './policy-document';
4import { Condition, Conditions, PolicyStatement } from './policy-statement';
5import { ISamlProvider } from './saml-provider';
6/**
7 * Any object that has an associated principal that a permission can be granted to
8 */
9export interface IGrantable {
10 /**
11 * The principal to grant permissions to
12 */
13 readonly grantPrincipal: IPrincipal;
14}
15/**
16 * Represents a logical IAM principal.
17 *
18 * An IPrincipal describes a logical entity that can perform AWS API calls
19 * against sets of resources, optionally under certain conditions.
20 *
21 * Examples of simple principals are IAM objects that you create, such
22 * as Users or Roles.
23 *
24 * An example of a more complex principals is a `ServicePrincipal` (such as
25 * `new ServicePrincipal("sns.amazonaws.com")`, which represents the Simple
26 * Notifications Service).
27 *
28 * A single logical Principal may also map to a set of physical principals.
29 * For example, `new OrganizationPrincipal('o-1234')` represents all
30 * identities that are part of the given AWS Organization.
31 */
32export interface IPrincipal extends IGrantable {
33 /**
34 * When this Principal is used in an AssumeRole policy, the action to use.
35 */
36 readonly assumeRoleAction: string;
37 /**
38 * Return the policy fragment that identifies this principal in a Policy.
39 */
40 readonly policyFragment: PrincipalPolicyFragment;
41 /**
42 * The AWS account ID of this principal.
43 * Can be undefined when the account is not known
44 * (for example, for service principals).
45 * Can be a Token - in that case,
46 * it's assumed to be AWS::AccountId.
47 */
48 readonly principalAccount?: string;
49 /**
50 * Add to the policy of this principal.
51 *
52 * @returns true if the statement was added, false if the principal in
53 * question does not have a policy document to add the statement to.
54 *
55 * @deprecated Use `addToPrincipalPolicy` instead.
56 */
57 addToPolicy(statement: PolicyStatement): boolean;
58 /**
59 * Add to the policy of this principal.
60 */
61 addToPrincipalPolicy(statement: PolicyStatement): AddToPrincipalPolicyResult;
62}
63/**
64 * Interface for principals that can be compared.
65 *
66 * This only needs to be implemented for principals that could potentially be value-equal.
67 * Identity-equal principals will be handled correctly by default.
68 */
69export interface IComparablePrincipal extends IPrincipal {
70 /**
71 * Return a string format of this principal which should be identical if the two
72 * principals are the same.
73 */
74 dedupeString(): string | undefined;
75}
76/**
77 * Helper class for working with `IComparablePrincipal`s
78 */
79export declare class ComparablePrincipal {
80 /**
81 * Whether or not the given principal is a comparable principal
82 */
83 static isComparablePrincipal(x: IPrincipal): x is IComparablePrincipal;
84 /**
85 * Return the dedupeString of the given principal, if available
86 */
87 static dedupeStringFor(x: IPrincipal): string | undefined;
88}
89/**
90 * A type of principal that has more control over its own representation in AssumeRolePolicyDocuments
91 *
92 * More complex types of identity providers need more control over Role's policy documents
93 * than simply `{ Effect: 'Allow', Action: 'AssumeRole', Principal: <Whatever> }`.
94 *
95 * If that control is necessary, they can implement `IAssumeRolePrincipal` to get full
96 * access to a Role's AssumeRolePolicyDocument.
97 */
98export interface IAssumeRolePrincipal extends IPrincipal {
99 /**
100 * Add the princpial to the AssumeRolePolicyDocument
101 *
102 * Add the statements to the AssumeRolePolicyDocument necessary to give this principal
103 * permissions to assume the given role.
104 */
105 addToAssumeRolePolicy(document: PolicyDocument): void;
106}
107/**
108 * Result of calling `addToPrincipalPolicy`
109 */
110export interface AddToPrincipalPolicyResult {
111 /**
112 * Whether the statement was added to the identity's policies.
113 *
114 */
115 readonly statementAdded: boolean;
116 /**
117 * Dependable which allows depending on the policy change being applied
118 *
119 * @default - Required if `statementAdded` is true.
120 */
121 readonly policyDependable?: cdk.IDependable;
122}
123/**
124 * Base class for policy principals
125 */
126export declare abstract class PrincipalBase implements IAssumeRolePrincipal, IComparablePrincipal {
127 readonly grantPrincipal: IPrincipal;
128 readonly principalAccount: string | undefined;
129 /**
130 * Return the policy fragment that identifies this principal in a Policy.
131 */
132 abstract readonly policyFragment: PrincipalPolicyFragment;
133 /**
134 * When this Principal is used in an AssumeRole policy, the action to use.
135 */
136 readonly assumeRoleAction: string;
137 addToPolicy(statement: PolicyStatement): boolean;
138 addToPrincipalPolicy(_statement: PolicyStatement): AddToPrincipalPolicyResult;
139 addToAssumeRolePolicy(document: PolicyDocument): void;
140 toString(): string;
141 /**
142 * JSON-ify the principal
143 *
144 * Used when JSON.stringify() is called
145 */
146 toJSON(): {
147 [key: string]: string[];
148 };
149 /**
150 * Returns a new PrincipalWithConditions using this principal as the base, with the
151 * passed conditions added.
152 *
153 * When there is a value for the same operator and key in both the principal and the
154 * conditions parameter, the value from the conditions parameter will be used.
155 *
156 * @returns a new PrincipalWithConditions object.
157 */
158 withConditions(conditions: Conditions): PrincipalBase;
159 /**
160 * Returns a new principal using this principal as the base, with session tags enabled.
161 *
162 * @returns a new SessionTagsPrincipal object.
163 */
164 withSessionTags(): PrincipalBase;
165 /**
166 * Return whether or not this principal is equal to the given principal
167 */
168 abstract dedupeString(): string | undefined;
169}
170/**
171 * Base class for Principals that wrap other principals
172 */
173declare abstract class PrincipalAdapter extends PrincipalBase {
174 protected readonly wrapped: IPrincipal;
175 readonly assumeRoleAction: string;
176 readonly principalAccount: string | undefined;
177 constructor(wrapped: IPrincipal);
178 get policyFragment(): PrincipalPolicyFragment;
179 addToPolicy(statement: PolicyStatement): boolean;
180 addToPrincipalPolicy(statement: PolicyStatement): AddToPrincipalPolicyResult;
181 /**
182 * Append the given string to the wrapped principal's dedupe string (if available)
183 */
184 protected appendDedupe(append: string): string | undefined;
185}
186/**
187 * An IAM principal with additional conditions specifying when the policy is in effect.
188 *
189 * For more information about conditions, see:
190 * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html
191 */
192export declare class PrincipalWithConditions extends PrincipalAdapter {
193 private additionalConditions;
194 constructor(principal: IPrincipal, conditions: Conditions);
195 /**
196 * Add a condition to the principal
197 */
198 addCondition(key: string, value: Condition): void;
199 /**
200 * Adds multiple conditions to the principal
201 *
202 * Values from the conditions parameter will overwrite existing values with the same operator
203 * and key.
204 */
205 addConditions(conditions: Conditions): void;
206 /**
207 * The conditions under which the policy is in effect.
208 * See [the IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
209 */
210 get conditions(): Record<string, any>;
211 get policyFragment(): PrincipalPolicyFragment;
212 toString(): string;
213 /**
214 * JSON-ify the principal
215 *
216 * Used when JSON.stringify() is called
217 */
218 toJSON(): {
219 [key: string]: string[];
220 };
221 dedupeString(): string | undefined;
222 private mergeConditions;
223}
224/**
225 * Enables session tags on role assumptions from a principal
226 *
227 * For more information on session tags, see:
228 * https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html
229 */
230export declare class SessionTagsPrincipal extends PrincipalAdapter {
231 constructor(principal: IPrincipal);
232 addToAssumeRolePolicy(doc: PolicyDocument): void;
233 dedupeString(): string | undefined;
234}
235/**
236 * A collection of the fields in a PolicyStatement that can be used to identify a principal.
237 *
238 * This consists of the JSON used in the "Principal" field, and optionally a
239 * set of "Condition"s that need to be applied to the policy.
240 *
241 * Generally, a principal looks like:
242 *
243 * { '<TYPE>': ['ID', 'ID', ...] }
244 *
245 * And this is also the type of the field `principalJson`. However, there is a
246 * special type of principal that is just the string '*', which is treated
247 * differently by some services. To represent that principal, `principalJson`
248 * should contain `{ 'LiteralString': ['*'] }`.
249 */
250export declare class PrincipalPolicyFragment {
251 readonly principalJson: {
252 [key: string]: string[];
253 };
254 /**
255 * The conditions under which the policy is in effect.
256 * See [the IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
257 */
258 readonly conditions: Conditions;
259 /**
260 *
261 * @param principalJson JSON of the "Principal" section in a policy statement
262 * @param conditions conditions that need to be applied to this policy
263 */
264 constructor(principalJson: {
265 [key: string]: string[];
266 },
267 /**
268 * The conditions under which the policy is in effect.
269 * See [the IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
270 */
271 conditions?: Conditions);
272}
273/**
274 * Specify a principal by the Amazon Resource Name (ARN).
275 * You can specify AWS accounts, IAM users, Federated SAML users, IAM roles, and specific assumed-role sessions.
276 * You cannot specify IAM groups or instance profiles as principals
277 *
278 * @see https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html
279 */
280export declare class ArnPrincipal extends PrincipalBase {
281 readonly arn: string;
282 /**
283 *
284 * @param arn Amazon Resource Name (ARN) of the principal entity (i.e. arn:aws:iam::123456789012:user/user-name)
285 */
286 constructor(arn: string);
287 get policyFragment(): PrincipalPolicyFragment;
288 toString(): string;
289 /**
290 * A convenience method for adding a condition that the principal is part of the specified
291 * AWS Organization.
292 */
293 inOrganization(organizationId: string): PrincipalBase;
294 dedupeString(): string | undefined;
295}
296/**
297 * Specify AWS account ID as the principal entity in a policy to delegate authority to the account.
298 */
299export declare class AccountPrincipal extends ArnPrincipal {
300 readonly accountId: any;
301 readonly principalAccount: string | undefined;
302 /**
303 *
304 * @param accountId AWS account ID (i.e. 123456789012)
305 */
306 constructor(accountId: any);
307 toString(): string;
308}
309/**
310 * Options for a service principal.
311 */
312export interface ServicePrincipalOpts {
313 /**
314 * The region in which the service is operating.
315 *
316 * @default - the current Stack's region.
317 * @deprecated You should not need to set this. The stack's region is always correct.
318 */
319 readonly region?: string;
320 /**
321 * Additional conditions to add to the Service Principal
322 *
323 * @default - No conditions
324 */
325 readonly conditions?: {
326 [key: string]: any;
327 };
328}
329/**
330 * An IAM principal that represents an AWS service (i.e. sqs.amazonaws.com).
331 */
332export declare class ServicePrincipal extends PrincipalBase {
333 readonly service: string;
334 private readonly opts;
335 /**
336 * Translate the given service principal name based on the region it's used in.
337 *
338 * For example, for Chinese regions this may (depending on whether that's necessary
339 * for the given service principal) append `.cn` to the name.
340 *
341 * The `region-info` module is used to obtain this information.
342 *
343 * @example
344 * const principalName = iam.ServicePrincipal.servicePrincipalName('ec2.amazonaws.com');
345 */
346 static servicePrincipalName(service: string): string;
347 /**
348 *
349 * @param service AWS service (i.e. sqs.amazonaws.com)
350 */
351 constructor(service: string, opts?: ServicePrincipalOpts);
352 get policyFragment(): PrincipalPolicyFragment;
353 toString(): string;
354 dedupeString(): string | undefined;
355}
356/**
357 * A principal that represents an AWS Organization
358 */
359export declare class OrganizationPrincipal extends PrincipalBase {
360 readonly organizationId: string;
361 /**
362 *
363 * @param organizationId The unique identifier (ID) of an organization (i.e. o-12345abcde)
364 */
365 constructor(organizationId: string);
366 get policyFragment(): PrincipalPolicyFragment;
367 toString(): string;
368 dedupeString(): string | undefined;
369}
370/**
371 * A policy principal for canonicalUserIds - useful for S3 bucket policies that use
372 * Origin Access identities.
373 *
374 * See https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html
375 *
376 * and
377 *
378 * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html
379 *
380 * for more details.
381 *
382 */
383export declare class CanonicalUserPrincipal extends PrincipalBase {
384 readonly canonicalUserId: string;
385 /**
386 *
387 * @param canonicalUserId unique identifier assigned by AWS for every account.
388 * root user and IAM users for an account all see the same ID.
389 * (i.e. 79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be)
390 */
391 constructor(canonicalUserId: string);
392 get policyFragment(): PrincipalPolicyFragment;
393 toString(): string;
394 dedupeString(): string | undefined;
395}
396/**
397 * Principal entity that represents a federated identity provider such as Amazon Cognito,
398 * that can be used to provide temporary security credentials to users who have been authenticated.
399 * Additional condition keys are available when the temporary security credentials are used to make a request.
400 * You can use these keys to write policies that limit the access of federated users.
401 *
402 * @see https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#condition-keys-wif
403 */
404export declare class FederatedPrincipal extends PrincipalBase {
405 readonly federated: string;
406 readonly conditions: Conditions;
407 readonly assumeRoleAction: string;
408 /**
409 *
410 * @param federated federated identity provider (i.e. 'cognito-identity.amazonaws.com' for users authenticated through Cognito)
411 * @param conditions The conditions under which the policy is in effect.
412 * See [the IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
413 * @param sessionTags Whether to enable session tagging (see https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html)
414 */
415 constructor(federated: string, conditions: Conditions, assumeRoleAction?: string);
416 get policyFragment(): PrincipalPolicyFragment;
417 toString(): string;
418 dedupeString(): string | undefined;
419}
420/**
421 * A principal that represents a federated identity provider as Web Identity such as Cognito, Amazon,
422 * Facebook, Google, etc.
423 */
424export declare class WebIdentityPrincipal extends FederatedPrincipal {
425 /**
426 *
427 * @param identityProvider identity provider (i.e. 'cognito-identity.amazonaws.com' for users authenticated through Cognito)
428 * @param conditions The conditions under which the policy is in effect.
429 * See [the IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
430 * @param sessionTags Whether to enable session tagging (see https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html)
431 */
432 constructor(identityProvider: string, conditions?: Conditions);
433 get policyFragment(): PrincipalPolicyFragment;
434 toString(): string;
435}
436/**
437 * A principal that represents a federated identity provider as from a OpenID Connect provider.
438 */
439export declare class OpenIdConnectPrincipal extends WebIdentityPrincipal {
440 /**
441 *
442 * @param openIdConnectProvider OpenID Connect provider
443 * @param conditions The conditions under which the policy is in effect.
444 * See [the IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
445 */
446 constructor(openIdConnectProvider: IOpenIdConnectProvider, conditions?: Conditions);
447 get policyFragment(): PrincipalPolicyFragment;
448 toString(): string;
449}
450/**
451 * Principal entity that represents a SAML federated identity provider
452 */
453export declare class SamlPrincipal extends FederatedPrincipal {
454 constructor(samlProvider: ISamlProvider, conditions: Conditions);
455 toString(): string;
456}
457/**
458 * Principal entity that represents a SAML federated identity provider for
459 * programmatic and AWS Management Console access.
460 */
461export declare class SamlConsolePrincipal extends SamlPrincipal {
462 constructor(samlProvider: ISamlProvider, conditions?: Conditions);
463 toString(): string;
464}
465/**
466 * Use the AWS account into which a stack is deployed as the principal entity in a policy
467 */
468export declare class AccountRootPrincipal extends AccountPrincipal {
469 constructor();
470 toString(): string;
471}
472/**
473 * A principal representing all AWS identities in all accounts
474 *
475 * Some services behave differently when you specify `Principal: '*'`
476 * or `Principal: { AWS: "*" }` in their resource policy.
477 *
478 * `AnyPrincipal` renders to `Principal: { AWS: "*" }`. This is correct
479 * most of the time, but in cases where you need the other principal,
480 * use `StarPrincipal` instead.
481 */
482export declare class AnyPrincipal extends ArnPrincipal {
483 constructor();
484 toString(): string;
485}
486/**
487 * A principal representing all identities in all accounts
488 * @deprecated use `AnyPrincipal`
489 */
490export declare class Anyone extends AnyPrincipal {
491}
492/**
493 * A principal that uses a literal '*' in the IAM JSON language
494 *
495 * Some services behave differently when you specify `Principal: "*"`
496 * or `Principal: { AWS: "*" }` in their resource policy.
497 *
498 * `StarPrincipal` renders to `Principal: *`. Most of the time, you
499 * should use `AnyPrincipal` instead.
500 */
501export declare class StarPrincipal extends PrincipalBase {
502 readonly policyFragment: PrincipalPolicyFragment;
503 toString(): string;
504 dedupeString(): string | undefined;
505}
506/**
507 * Represents a principal that has multiple types of principals. A composite principal cannot
508 * have conditions. i.e. multiple ServicePrincipals that form a composite principal
509 */
510export declare class CompositePrincipal extends PrincipalBase {
511 readonly assumeRoleAction: string;
512 private readonly principals;
513 constructor(...principals: IPrincipal[]);
514 /**
515 * Adds IAM principals to the composite principal. Composite principals cannot have
516 * conditions.
517 *
518 * @param principals IAM principals that will be added to the composite principal
519 */
520 addPrincipals(...principals: IPrincipal[]): this;
521 addToAssumeRolePolicy(doc: PolicyDocument): void;
522 get policyFragment(): PrincipalPolicyFragment;
523 toString(): string;
524 dedupeString(): string | undefined;
525}
526export {};
527
\No newline at end of file