feat(appsync): grant APIs for managing permissions (#8993)

**[ISSUE]**
AppSync allows for `authorizationType` of `AWS_IAM`. However, no easy function or attribute to retrieve the `IAM Role` for later use.

**[APPROACH]**
Build out a basic granting interface that allows users to pass an `IAM Role` to grant permissions access.

```
const api = new appsync.GraphQLApi(...);
const role = new iam.Role(..);
api.grant(role, ... );
```

**[NOTE]**
Current implementation let's you use `IAM` authorization, but doesn't come with `grant`.

Fixes #6772 #7871 #7313

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: BryanPan342

packages/@aws-cdk/aws-appsync/.gitignore

@@ -16,4 +16,5 @@ nyc.config.js
 !.eslintrc.js
 !jest.config.js
 
-junit.xml
+!test/verify/*.js
+junit.xml

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

@@ -13,186 +13,149 @@
 ---
 <!--END STABILITY BANNER-->
 
-This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
+The `@aws-cdk/aws-appsync` package contains constructs for building flexible
+APIs that use GraphQL. 
 
-## Usage Example
+### Example
 
-Given the following GraphQL schema file `schema.graphql`:
+Example of a GraphQL API with `AWS_IAM` authorization resolving into a DynamoDb
+backend data source. 
 
-```graphql
-type ServiceVersion {
-    version: String!
-}
+GraphQL schema file `schema.graphql`:
 
-type Customer {
-    id: String!
-    name: String!
+```gql
+type demo {
+  id: String!
+  version: String!
 }
-
-input SaveCustomerInput {
-    name: String!
+type Query {
+  getDemos: [ test! ]
 }
-
-type Order {
-    customer: String!
-    order: String!
+input DemoInput {
+  version: String!
 }
-
-type Query {
-    getServiceVersion: ServiceVersion
-    getCustomers: [Customer]
-    getCustomer(id: String): Customer
+type Mutation {
+  addDemo(input: DemoInput!): demo
 }
+```
 
-input FirstOrderInput {
-    product: String!
-    quantity: Int!
-}
+CDK stack file `app-stack.ts`:
 
+```ts
+import * as appsync from '@aws-cdk/aws-appsync';
+import * as db from '@aws-cdk/aws-dynamodb';
+
+const api = new appsync.GraphQLApi(stack, 'Api', {
+  name: 'demo',
+  schemaDefinitionFile: join(__dirname, 'schema.graphql'),
+  authorizationConfig: {
+    defaultAuthorization: {
+      authorizationType: appsync.AuthorizationType.IAM
+    },
+  },
+});
+
+const demoTable = new db.Table(stack, 'DemoTable', {
+  partitionKey: {
+    name: 'id',
+    type: AttributeType.STRING,
+  },
+});
+
+const demoDS = api.addDynamoDbDataSource('demoDataSource', 'Table for Demos"', demoTable);
+
+// Resolver for the Query "getDemos" that scans the DyanmoDb table and returns the entire list.
+demoDS.createResolver({
+  typeName: 'Query',
+  fieldName: 'getDemos',
+  requestMappingTemplate: MappingTemplate.dynamoDbScanTable(),
+  responseMappingTemplate: MappingTemplate.dynamoDbResultList(),
+});
+
+// Resolver for the Mutation "addDemo" that puts the item into the DynamoDb table.
+demoDS.createResolver({
+  typeName: 'Mutation',
+  fieldName: 'addDemo',
+  requestMappingTemplate: MappingTemplate.dynamoDbPutItem(PrimaryKey.partition('id').auto(), Values.projecting('demo')),
+  responseMappingTemplate: MappingTemplate.dynamoDbResultItem(),
+});
+```
+
+## Permissions
+
+When using `AWS_IAM` as the authorization type for GraphQL API, an IAM Role
+with correct permissions must be used for access to API.
+
+When configuring permissions, you can specify specific resources to only be
+accessible by `IAM` authorization. For example, if you want to only allow mutability
+for `IAM` authorized access you would configure the following.
+
+In `schema.graphql`:
+```ts
 type Mutation {
-    addCustomer(customer: SaveCustomerInput!): Customer
-    saveCustomer(id: String!, customer: SaveCustomerInput!): Customer
-    removeCustomer(id: String!): Customer
-    saveCustomerWithFirstOrder(customer: SaveCustomerInput!, order: FirstOrderInput!, referral: String): Order
-    doPostOnAws: String!
+  updateExample(...): ...
+    @aws_iam
 }
 ```
 
-the following CDK app snippet will create a complete CRUD AppSync API:
+In `IAM`:
+```json
+{
+   "Version": "2012-10-17",
+   "Statement": [
+      {
+         "Effect": "Allow",
+         "Action": [
+            "appsync:GraphQL"
+         ],
+         "Resource": [
+            "arn:aws:appsync:REGION:ACCOUNT_ID:apis/GRAPHQL_ID/types/Mutation/fields/updateExample"
+         ]
+      }
+   ]
+}
+```
+
+See [documentation](https://docs.aws.amazon.com/appsync/latest/devguide/security.html#aws-iam-authorization) for more details.
+
+To make this easier, CDK provides `grant` API.
+
+Use the `grant` function for more granular authorization.
 
 ```ts
-export class ApiStack extends Stack {
-  constructor(scope: Construct, id: string) {
-    super(scope, id);
-
-    const userPool = new UserPool(this, 'UserPool', {
-      userPoolName: 'myPool',
-    });
-
-    const api = new GraphQLApi(this, 'Api', {
-      name: `demoapi`,
-      logConfig: {
-        fieldLogLevel: FieldLogLevel.ALL,
-      },
-      authorizationConfig: {
-        defaultAuthorization: {
-          authorizationType: AuthorizationType.USER_POOL,
-          userPoolConfig: {
-            userPool,
-            defaultAction: UserPoolDefaultAction.ALLOW
-          },
-        },
-        additionalAuthorizationModes: [
-          {
-            authorizationType: AuthorizationType.API_KEY,
-          }
-        ],
-      },
-      schemaDefinitionFile: './schema.graphql',
-    });
-
-    const noneDS = api.addNoneDataSource('None', 'Dummy data source');
-
-    noneDS.createResolver({
-      typeName: 'Query',
-      fieldName: 'getServiceVersion',
-      requestMappingTemplate: MappingTemplate.fromString(JSON.stringify({
-        version: '2017-02-28',
-      })),
-      responseMappingTemplate: MappingTemplate.fromString(JSON.stringify({
-        version: 'v1',
-      })),
-    });
-
-    const customerTable = new Table(this, 'CustomerTable', {
-      billingMode: BillingMode.PAY_PER_REQUEST,
-      partitionKey: {
-        name: 'id',
-        type: AttributeType.STRING,
-      },
-    });
-    // If your table is already created you can also use use import table and use it as data source.
-    const customerDS = api.addDynamoDbDataSource('Customer', 'The customer data source', customerTable);
-    customerDS.createResolver({
-      typeName: 'Query',
-      fieldName: 'getCustomers',
-      requestMappingTemplate: MappingTemplate.dynamoDbScanTable(),
-      responseMappingTemplate: MappingTemplate.dynamoDbResultList(),
-    });
-    customerDS.createResolver({
-      typeName: 'Query',
-      fieldName: 'getCustomer',
-      requestMappingTemplate: MappingTemplate.dynamoDbGetItem('id', 'id'),
-      responseMappingTemplate: MappingTemplate.dynamoDbResultItem(),
-    });
-    customerDS.createResolver({
-      typeName: 'Mutation',
-      fieldName: 'addCustomer',
-      requestMappingTemplate: MappingTemplate.dynamoDbPutItem(
-          PrimaryKey.partition('id').auto(),
-          Values.projecting('customer')),
-      responseMappingTemplate: MappingTemplate.dynamoDbResultItem(),
-    });
-    customerDS.createResolver({
-      typeName: 'Mutation',
-      fieldName: 'saveCustomer',
-      requestMappingTemplate: MappingTemplate.dynamoDbPutItem(
-          PrimaryKey.partition('id').is('id'),
-          Values.projecting('customer')),
-      responseMappingTemplate: MappingTemplate.dynamoDbResultItem(),
-    });
-    customerDS.createResolver({
-      typeName: 'Mutation',
-      fieldName: 'saveCustomerWithFirstOrder',
-      requestMappingTemplate: MappingTemplate.dynamoDbPutItem(
-          PrimaryKey
-              .partition('order').auto()
-              .sort('customer').is('customer.id'),
-          Values
-              .projecting('order')
-              .attribute('referral').is('referral')),
-      responseMappingTemplate: MappingTemplate.dynamoDbResultItem(),
-    });
-    customerDS.createResolver({
-      typeName: 'Mutation',
-      fieldName: 'removeCustomer',
-      requestMappingTemplate: MappingTemplate.dynamoDbDeleteItem('id', 'id'),
-      responseMappingTemplate: MappingTemplate.dynamoDbResultItem(),
-    });
-
-    const httpDS = api.addHttpDataSource('http', 'The http data source', 'https://aws.amazon.com/');
-
-    httpDS.createResolver({
-      typeName: 'Mutation',
-      fieldName: 'doPostOnAws',
-      requestMappingTemplate: MappingTemplate.fromString(`{
-        "version": "2018-05-29",
-        "method": "POST",
-        # if full path is https://api.xxxxxxxxx.com/posts then resourcePath would be /posts
-        "resourcePath": "/path/123",
-        "params":{
-            "body": $util.toJson($ctx.args),
-            "headers":{
-                "Content-Type": "application/json",
-                "Authorization": "$ctx.request.headers.Authorization"
-            }
-        }
-      }`),
-      responseMappingTemplate: MappingTemplate.fromString(`
-        ## Raise a GraphQL field error in case of a datasource invocation error
-        #if($ctx.error)
-          $util.error($ctx.error.message, $ctx.error.type)
-        #end
-        ## if the response status code is not 200, then return an error. Else return the body **
-        #if($ctx.result.statusCode == 200)
-            ## If response is 200, return the body.
-            $ctx.result.body
-        #else
-            ## If response is not 200, append the response to error block.
-            $utils.appendError($ctx.result.body, "$ctx.result.statusCode")
-        #end
-      `),
-    });
-  }
-}
+const role = new iam.Role(stack, 'Role', {
+  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+});
+const api = new appsync.GraphQLApi(stack, 'API', {
+  definition
+});
+
+api.grant(role, appsync.IamResource.custom('types/Mutation/fields/updateExample'), 'appsync:GraphQL')
 ```
+
+### IamResource
+
+In order to use the `grant` functions, you need to use the class `IamResource`.
+
+- `IamResource.custom(...arns)` permits custom ARNs and requires an argument.
+
+- `IamResouce.ofType(type, ...fields)` permits ARNs for types and their fields.
+
+- `IamResource.all()` permits ALL resources.
+
+### Generic Permissions
+
+Alternatively, you can use more generic `grant` functions to accomplish the same usage.
+
+These include:
+- grantMutation (use to grant access to Mutation fields)
+- grantQuery (use to grant access to Query fields)
+- grantSubscription (use to grant access to Subscription fields)
+
+```ts
+// For generic types
+api.grantMutation(role, 'updateExample');
+
+// For custom types and granular design
+api.grant(role, appsync.IamResource.ofType('Mutation', 'updateExample'), 'appsync:GraphQL');
+```