feat(lambda): grant function permissions to an AWS organization

packages/@aws-cdk/aws-lambda/README.md

@@ -155,12 +155,13 @@ if (fn.timeout) {
 
 AWS Lambda supports resource-based policies for controlling access to Lambda
 functions and layers on a per-resource basis. In particular, this allows you to
-give permission to AWS services and other AWS accounts to modify and invoke your
-functions. You can also restrict permissions given to AWS services by providing
-a source account or ARN (representing the account and identifier of the resource
-that accesses the function or layer).
+give permission to AWS services, AWS Organizations, or other AWS accounts to
+modify and invoke your functions.
+
+### Grant function access to AWS services
 
 ```ts
+// Grant permissions to a service
 declare const fn: lambda.Function;
 const principal = new iam.ServicePrincipal('my-service');
 
@@ -172,10 +173,76 @@ fn.addPermission('my-service Invocation', {
 });
 ```
 
-For more information, see [Resource-based
-policies](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)
+You can also restrict permissions given to AWS services by providing
+a source account or ARN (representing the account and identifier of the resource
+that accesses the function or layer).
+
+For more information, see
+[Granting function access to AWS services](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html#permissions-resource-serviceinvoke)
 in the AWS Lambda Developer Guide.
 
+### Grant function access to an AWS Organization
+
+```ts
+// Grant permissions to an entire AWS organization
+declare const fn: lambda.Function;
+const orgPrincipal = new iam.OrganizationPrincipal('o-xxxxxxxxxx');
+
+fn.grantInvoke(orgPrincipal);
+
+// Equivalent to:
+fn.addPermission('grant to entire org', {
+  principal: orgPrincipal,
+});
+
+// Equivalent to:
+fn.addPermission('grant to entire org', {
+  principal: new iam.StarPrincipal(),
+  principalOrg: orgPrincipal,
+})
+```
+
+In the above example, the `principal` will be `*` and all users in the
+organization `o-xxxxxxxxxx` will get function invocation permissions.
+
+You can restrict permissions given to the organization by specifying an
+AWS account or role as the `principal`:
+
+```ts
+// Grant permission to an account ONLY IF they are part of the organization
+declare const fn: lambda.Function;
+
+fn.addPermission('grant to account in org', {
+  principal: new iam.AccountPrincipal('123456789012'),
+  principalOrg: new iam.OrganizationPrincipal('o-xxxxxxxxxx'),
+});
+```
+
+For more information, see
+[Granting function access to an organization](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html#permissions-resource-xorginvoke)
+in the AWS Lambda Developer Guide.
+
+### Grant function access to other AWS accounts
+
+```ts
+// Grant permission to other AWS account
+declare const fn: lambda.Function;
+const account = new iam.AccountPrincipal('123456789012');
+
+fn.grantInvoke(account);
+
+// Equivalent to:
+fn.addPermission('grant to account in org', {
+  principal: account,
+});
+```
+
+For more information, see
+[Granting function access to other accounts](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html#permissions-resource-xaccountinvoke)
+in the AWS Lambda Developer Guide.
+
+### Grant function access to unowned principals
+
 Providing an unowned principal (such as account principals, generic ARN
 principals, service principals, and principals in other accounts) to a call to
 `fn.grantInvoke` will result in a resource-based policy being created. If the

packages/@aws-cdk/aws-lambda/lib/function-base.ts

@@ -345,8 +345,17 @@ export abstract class FunctionBase extends Resource implements IFunction, ec2.IC
       return;
     }
 
-    const principal = this.parsePermissionPrincipal(permission.principal);
-    const { sourceAccount, sourceArn } = this.parseConditions(permission.principal) ?? {};
+    let principal = this.parsePermissionPrincipal(permission.principal);
+
+    let { sourceArn, sourceAccount, principalOrgID } = this.validateConditionCombinations(permission.principal) ?? {};
+
+    // Lambda does not actually accept an organization principal here.
+    // so the principal becomes '*' and the organization ID will be sent to
+    // the 'principalOrgID' property.
+    if (permission.principal instanceof iam.OrganizationPrincipal) {
+      principalOrgID = permission.principal.organizationId;
+    }
+
     const action = permission.action ?? 'lambda:InvokeFunction';
     const scope = permission.scope ?? this;
 
@@ -359,6 +368,7 @@ export abstract class FunctionBase extends Resource implements IFunction, ec2.IC
       eventSourceToken: permission.eventSourceToken,
       sourceAccount: permission.sourceAccount ?? sourceAccount,
       sourceArn: permission.sourceArn ?? sourceArn,
+      principalOrgId: permission.principalOrg?.organizationId ?? principalOrgID,
       functionUrlAuthType: permission.functionUrlAuthType,
     });
   }
@@ -566,6 +576,15 @@ export abstract class FunctionBase extends Resource implements IFunction, ec2.IC
       return (principal as iam.ArnPrincipal).arn;
     }
 
+    if (principal instanceof iam.OrganizationPrincipal) {
+      // we will move the organization id to the `principalOrgId` property of `Permissions`.
+      return '*';
+    }
+
+    if (principal instanceof iam.StarPrincipal) {
+      return '*';
+    }
+
     // Try a best-effort approach to support simple principals that are not any of the predefined
     // classes, but are simple enough that they will fit into the Permission model. Main target
     // here: imported Roles, Users, Groups.
@@ -580,17 +599,61 @@ export abstract class FunctionBase extends Resource implements IFunction, ec2.IC
     }
 
     throw new Error(`Invalid principal type for Lambda permission statement: ${principal.constructor.name}. ` +
-      'Supported: AccountPrincipal, ArnPrincipal, ServicePrincipal');
+      'Supported: AccountPrincipal, ArnPrincipal, ServicePrincipal, OrganizationPrincipal');
+  }
+
+  private validateConditionCombinations(principal: iam.IPrincipal): {
+    sourceArn: string | undefined,
+    sourceAccount: string | undefined,
+    principalOrgID: string | undefined,
+  } | undefined {
+    const conditions = this.validateConditions(principal);
+
+    if (!conditions) { return undefined; }
+
+    const sourceArn = conditions.ArnLike ? conditions.ArnLike['aws:SourceArn'] : undefined;
+    const sourceAccount = conditions.StringEquals ? conditions.StringEquals['aws:SourceAccount'] : undefined;
+    const principalOrgID = conditions.StringEquals ? conditions.StringEquals['aws:PrincipalOrgID'] : undefined;
+
+    // PrincipalOrgID cannot be combined with any other conditions
+    if (principalOrgID && (sourceArn || sourceAccount)) {
+      throw new Error('PrincipalWithConditions had unsupported condition combinations for Lambda permission statement: principalOrgID cannot be set with other conditions.');
+    }
+
+    // SourceArn and SourceAccount must be set together
+    if ((sourceArn && !sourceAccount) || (!sourceArn && sourceAccount)) {
+      throw new Error('PrincipalWithConditions had unsupported condition combinations for Lambda permission statement: you cannot set sourceAccount without sourceArn and vice versa');
+    }
+
+    return {
+      sourceArn,
+      sourceAccount,
+      principalOrgID,
+    };
   }
 
-  private parseConditions(principal: iam.IPrincipal): { sourceAccount: string, sourceArn: string } | null {
+  private validateConditions(principal: iam.IPrincipal): iam.Conditions | undefined {
     if (this.isPrincipalWithConditions(principal)) {
       const conditions: iam.Conditions = principal.policyFragment.conditions;
       const conditionPairs = flatMap(
         Object.entries(conditions),
         ([operator, conditionObjs]) => Object.keys(conditionObjs as object).map(key => { return { operator, key }; }),
       );
-      const supportedPrincipalConditions = [{ operator: 'ArnLike', key: 'aws:SourceArn' }, { operator: 'StringEquals', key: 'aws:SourceAccount' }];
+
+      // These are all the supported conditions. Some combinations are not supported,
+      // like only 'aws:SourceArn' or 'aws:PrincipalOrgID' and 'aws:SourceAccount'.
+      // These will be validated through `this.validateConditionCombinations`.
+      const supportedPrincipalConditions = [{
+        operator: 'ArnLike',
+        key: 'aws:SourceArn',
+      },
+      {
+        operator: 'StringEquals',
+        key: 'aws:SourceAccount',
+      }, {
+        operator: 'StringEquals',
+        key: 'aws:PrincipalOrgID',
+      }];
 
       const unsupportedConditions = conditionPairs.filter(
         (condition) => !supportedPrincipalConditions.some(
@@ -599,17 +662,14 @@ export abstract class FunctionBase extends Resource implements IFunction, ec2.IC
       );
 
       if (unsupportedConditions.length == 0) {
-        return {
-          sourceAccount: conditions.StringEquals['aws:SourceAccount'],
-          sourceArn: conditions.ArnLike['aws:SourceArn'],
-        };
+        return conditions;
       } else {
         throw new Error(`PrincipalWithConditions had unsupported conditions for Lambda permission statement: ${JSON.stringify(unsupportedConditions)}. ` +
           `Supported operator/condition pairs: ${JSON.stringify(supportedPrincipalConditions)}`);
       }
-    } else {
-      return null;
     }
+
+    return undefined;
   }
 
   private isPrincipalWithConditions(principal: iam.IPrincipal): principal is iam.PrincipalWithConditions {

packages/@aws-cdk/aws-lambda/lib/permission.ts

@@ -26,19 +26,22 @@ export interface Permission {
    * A unique token that must be supplied by the principal invoking the
    * function.
    *
-   * @default The caller would not need to present a token.
+   * @default - The caller would not need to present a token.
    */
   readonly eventSourceToken?: string;
 
   /**
    * The entity for which you are granting permission to invoke the Lambda
-   * function. This entity can be any valid AWS service principal, such as
-   * s3.amazonaws.com or sns.amazonaws.com, or, if you are granting
-   * cross-account permission, an AWS account ID. For example, you might want
-   * to allow a custom application in another AWS account to push events to
-   * Lambda by invoking your function.
+   * function. This entity can be any of the following:
    *
-   * The principal can be either an AccountPrincipal or a ServicePrincipal.
+   * - a valid AWS service principal, such as `s3.amazonaws.com` or `sns.amazonaws.com`
+   * - an AWS account ID for cross-account permissions. For example, you might want
+   *   to allow a custom application in another AWS account to push events to
+   *   Lambda by invoking your function.
+   * - an AWS organization principal to grant permissions to an entire organization.
+   *
+   * The principal can be an AccountPrincipal, an ArnPrincipal, a ServicePrincipal,
+   * or an OrganizationPrincipal.
    */
   readonly principal: iam.IPrincipal;
 
@@ -70,6 +73,19 @@ export interface Permission {
    */
   readonly sourceArn?: string;
 
+  /**
+   * The organization you want to grant permissions to. Use this ONLY if you
+   * need to grant permissions to a subset of the organization. If you want to
+   * grant permissions to the entire organization, sending the organization principal
+   * through the `principal` property will suffice.
+   *
+   * You can use this property to ensure that all source principals are owned by
+   * a specific organization.
+   *
+   * @default - No principalOrg
+   */
+  readonly principalOrg?: iam.OrganizationPrincipal;
+
   /**
    * The authType for the function URL that you are granting permissions for.
    *