# Configuring authorization and authentication to secure your GraphQL APIs
AWS AppSync offers the following authorization types to secure GraphQL APIs: API keys, Lambda, IAM, OpenID Connect, and Cognito User Pools. Each option provides a different method of security:
1. **API Key Authorization**: Controls throttling for unauthenticated APIs, providing a simple security option.
1. **Lambda Authorization**: Enables custom authorization logic, explaining function inputs and outputs in detail.
1. **IAM Authorization**: Utilizes AWS's signature version 4 signing process, allowing fine-grained access control through IAM policies.
1. **OpenID Connect Authorization**: Integrates with OIDC-compliant services for user authentication.
1. **Cognito User Pools**: Implements group-based access control using Cognito's user management features.
## Authorization types
There are five ways you can authorize applications to interact with your AWS AppSync GraphQL API. You specify which authorization type you use by specifying one of the following authorization type values in your AWS AppSync API or CLI call:
+
** `API_KEY` **
For using API keys.
+
** `AWS_LAMBDA` **
For using an AWS Lambda function.
+
** `AWS_IAM` **
For using AWS Identity and Access Management ([IAM](https://aws.amazon.com/iam/)) permissions.
+
** `OPENID_CONNECT` **
For using your OpenID Connect provider.
+
** `AMAZON_COGNITO_USER_POOLS` **
For using an Amazon Cognito user pool.
These basic authorization types work for most developers. For more advanced use cases, you can add additional authorization modes through the console, the CLI, and AWS CloudFormation. For additional authorization modes, AWS AppSync provides an authorization type that takes the values listed above (that is, `API_KEY`, `AWS_LAMBDA`, `AWS_IAM`, `OPENID_CONNECT`, and `AMAZON_COGNITO_USER_POOLS`).
When you specify `API_KEY`,`AWS_LAMBDA`, or `AWS_IAM` as the main or default authorization type, you can’t specify them again as one of the additional authorization modes. Similarly, you can’t duplicate `API_KEY`, `AWS_LAMBDA` or `AWS_IAM` inside the additional authorization modes. You can use multiple Amazon Cognito User Pools and OpenID Connect providers. However, you can’t use duplicate Amazon Cognito User Pools or OpenID Connect providers between the default authorization mode and any of the additional authorization modes. You can specify different clients for your Amazon Cognito User Pool or OpenID Connect provider using the corresponding configuration regular expression.
When you save changes to your API configuration, AWS AppSync starts to propagate the changes. Until your configuration change is propagated, AWS AppSync continues to serve your content from the previous configuration. After your configuration change is propagated, AWS AppSync immediately starts to serve your content based on the new configuration. While AWS AppSync is propagating your changes for an API, we can't determine whether the API is serving your content based on the previous configuration or the new configuration.
## API\$1KEY authorization
Unauthenticated APIs require more strict throttling than authenticated APIs. One way to control throttling for unauthenticated GraphQL endpoints is through the use of API keys. An API key is a hard-coded value in your application that is generated by the AWS AppSync service when you create an unauthenticated GraphQL endpoint. You can rotate API keys from the console, from the CLI, or from the [AWS AppSync API reference](https://docs.aws.amazon.com/appsync/latest/APIReference/).
------
#### [ Console ]
1. Sign in to the AWS Management Console and open the [AppSync console](https://console.aws.amazon.com/appsync/).
1. In the **APIs dashboard**, choose your GraphQL API.
1. In the **Sidebar**, choose **Settings**.
1. Under **Default authorization mode**, choose **API key**.
1. In the **API keys** table, choose **Add API key**.
A new API key will be generated in the table.
1. To delete an old API key, select the API key in the table and then choose **Delete**.
1. Choose **Save** at the bottom of the page.
------
#### [ CLI ]
1. If you haven't already done so, configure your access to the AWS CLI. For more information, see [Configuration basics](https://docs.aws.amazon.com//cli/latest/userguide/cli-configure-quickstart.html).
1. Create a GraphQL API object by running the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-graphql-api.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-graphql-api.html) command.
You'll need to type in two parameters for this particular command:
1. The `api-id` of your GraphQL API.
1. The new `name` of your API. You can use the same `name`.
1. The `authentication-type`, which will be `API_KEY`.
**Note**
There are other parameters such as `Region` that must be configured but will usually default to your CLI configuration values.
An example command may look like this:
```
aws appsync update-graphql-api --api-id abcdefghijklmnopqrstuvwxyz --name TestAPI --authentication-type API_KEY
```
An output will be returned in the CLI. Here's an example in JSON:
```
{
"graphqlApi": {
"xrayEnabled": false,
"name": "TestAPI",
"authenticationType": "API_KEY",
"tags": {},
"apiId": "abcdefghijklmnopqrstuvwxyz",
"uris": {
"GRAPHQL": "https://s8i3kk3ufhe9034ujnv73r513e.appsync-api.us-west-2.amazonaws.com/graphql",
"REALTIME": "wss://s8i3kk3ufhe9034ujnv73r513e.appsync-realtime-api.us-west-2.amazonaws.com/graphql"
},
"arn": "arn:aws:appsync:us-west-2:348581070237:apis/abcdefghijklmnopqrstuvwxyz"
}
}
```
------
API keys are configurable for up to 365 days, and you can extend an existing expiration date for up to another 365 days from that day. API Keys are recommended for development purposes or use cases where it’s safe to expose a public API.
On the client, the API key is specified by the header `x-api-key`.
For example, if your `API_KEY` is `'ABC123'`, you can send a GraphQL query via `curl` as follows:
```
$ curl -XPOST -H "Content-Type:application/graphql" -H "x-api-key:ABC123" -d '{ "query": "query { movies { id } }" }' https://YOURAPPSYNCENDPOINT/graphql
```
## AWS\$1LAMBDA authorization
You can implement your own API authorization logic using an AWS Lambda function. You can use a Lambda function for either your primary or secondary authorizer, but there may only be one Lambda authorization function per API. When using Lambda functions for authorization, the following applies:
+ If the API has the `AWS_LAMBDA` and `AWS_IAM` authorization modes enabled, then the SigV4 signature cannot be used as the `AWS_LAMBDA` authorization token.
+ If the API has the `AWS_LAMBDA` and `OPENID_CONNECT` authorization modes or the `AMAZON_COGNITO_USER_POOLS` authorization mode enabled, then the OIDC token cannot be used as the `AWS_LAMBDA` authorization token. Note that the OIDC token can be a Bearer scheme.
+ A Lambda function must not return more than 5MB of contextual data for resolvers.
For example, if your authorization token is `'ABC123'`, you can send a GraphQL query via curl as follows:
```
$ curl -XPOST -H "Content-Type:application/graphql" -H "Authorization:ABC123" -d '{ "query":
"query { movies { id } }" }' https://YOURAPPSYNCENDPOINT/graphql
```
Lambda functions are called before each query or mutation. The return value can be cached based on the API ID and the authentication token. When a Lambda authorizer response is less than 1,048,576 bytes, AWS AppSync caches the response for subsequent requests. If the Lambda authorizer response is equal to or greater than 1,048,576 bytes, AWS AppSync doesn't cache the response and invokes the Lambda authorizer for each incoming request. To optimize performance and minimize Lambda invocation costs, we recommend that you limit your Lambda authorizer responses to 1,048,576 bytes. By default, caching is not turned on, but this can be enabled at the API level or by setting the `ttlOverride` value in a function's return value.
A regular expression that validates authorization tokens before the function is called can be specified if desired. These regular expressions are used to validate that an authorization token is of the correct format before your function is called. Any request using a token which does not match this regular expression will be denied automatically.
Lambda functions used for authorization require a principal policy for `appsync.amazonaws.com` to be applied on them to allow AWS AppSync to call them. This action is done automatically in the AWS AppSync console; The AWS AppSync console does *not* remove the policy. For more information on attaching policies to Lambda functions, see [Resource-based policies](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html#permissions-resource-serviceinvoke) in the AWS Lambda Developer Guide.
The Lambda function you specify will receive an event with the following shape:
```
{
"authorizationToken": "ExampleAUTHtoken123123123",
"requestContext": {
"apiId": "aaaaaa123123123example123",
"accountId": "111122223333",
"requestId": "f4081827-1111-4444-5555-5cf4695f339f",
"queryString": "mutation CreateEvent {...}\n\nquery MyQuery {...}\n",
"operationName": "MyQuery",
"variables": {}
}
"requestHeaders": {
application request headers
}
}
```
The `event` object contains the headers that were sent in the request from the application client to AWS AppSync.
The authorization function must return at least `isAuthorized`, a boolean indicating if the request is authorized. AWS AppSync recognizes the following keys returned from Lambda authorization functions:
**Note**
The value for the `operationName` in the `requestContext` for a WebSocket connect operation is set by AWS AppSync to "`DeepDish:Connect`".
### Functions list
`isAuthorized` (boolean, required)
A boolean value indicating if the value in `authorizationToken` is authorized to make calls to the GraphQL API.
If this value is true, execution of the GraphQL API continues. If this value is false, an `UnauthorizedException` is raised
`deniedFields` (list of string, optional)
A list of which are forcibly changed to `null`, even if a value was returned from a resolver.
Each item is either a fully qualified field ARN in the form of `arn:aws:appsync:us-east-1:111122223333:apis/GraphQLApiId/types/TypeName/fields/FieldName` or a short form of `TypeName.FieldName`. The full ARN form should be used when two APIs share a Lambda function authorizer and there might be ambiguity between common types and fields between the two APIs.
`resolverContext` (JSON Object, optional)
A JSON object visible as `$ctx.identity.resolverContext` in resolver templates. For example, if the following structure is returned by a resolver:
```
{
"isAuthorized":true
"resolverContext": {
"banana":"very yellow",
"apple":"very green"
}
}
```
The value of `ctx.identity.resolverContext.apple` in resolver templates will be "`very green`". The `resolverContext` object only supports key-value pairs. Nested keys are not supported.
The total size of this JSON object must not exceed 5MB.
`ttlOverride` (integer, optional)
The number of seconds that the response should be cached for. If no value is returned, the value from the API is used. If this is 0, the response is not cached.
Lambda authorizers have a standard timeout of 10 seconds but may time out earlier under peak traffic conditions. We recommend designing functions to execute in the shortest amount of time as possible (under 1s) to scale the performance of your API.
Multiple AWS AppSync APIs can share a single authentication Lambda function. Cross account authorizer use is not permitted.
When sharing an authorization function between multiple APIs, be aware that short-form field names (`typename.fieldname`) may inadvertently hide fields. To disambiguate a field in `deniedFields`, you can specify an unambiguous field ARN in the form of `arn:aws:appsync:region:accountId:apis/GraphQLApiId/types/typeName/fields/fieldName`.
To add a Lambda function as the default authorization mode in AWS AppSync:
------
#### [ Console ]
1. Log into the AWS AppSync Console and navigate to the API you wish to update.
1. Navigate to the Settings page for your API.
Change the API-Level authorization to **AWS Lambda**.
1. Choose the AWS Region and Lambda ARN to authorize API calls against.
**Note**
The appropriate principal policy will be added automatically, allowing AWS AppSync to call your Lambda function.
1. Optionally, set the response TTL and token validation regular expression.
------
#### [ AWS CLI ]
1. Attach the following policy to the Lambda function being used:
```
aws lambda add-permission --function-name "my-function" --statement-id "appsync" --principal appsync.amazonaws.com --action lambda:InvokeFunction --output text
```
**Important**
If you want the policy of the function to be locked to a single GraphQL API, you can run this command:
```
aws lambda add-permission --function-name “my-function” --statement-id “appsync” --principal appsync.amazonaws.com --action lambda:InvokeFunction --source-arn “” --output text
```
1. Update your AWS AppSync API to use the given Lambda function ARN as the authorizer:
```
aws appsync update-graphql-api --api-id example2f0ur2oid7acexample --name exampleAPI --authentication-type AWS_LAMBDA --lambda-authorizer-config authorizerUri="arn:aws:lambda:us-east-2:111122223333:function:my-function"
```
**Note**
You can also include other configuration options such as the token regular expression.
------
The following example describes a Lambda function that demonstrates the various authentication and failure states a Lambda function can have when used as a AWS AppSync authorization mechanism:
```
def handler(event, context):
# This is the authorization token passed by the client
token = event.get('authorizationToken')
# If a lambda authorizer throws an exception, it will be treated as unauthorized.
if 'Fail' in token:
raise Exception('Purposefully thrown exception in Lambda Authorizer.')
if 'Authorized' in token and 'ReturnContext' in token:
return {
'isAuthorized': True,
'resolverContext': {
'key': 'value'
}
}
# Authorized with no f
if 'Authorized' in token:
return {
'isAuthorized': True
}
# Partial authorization
if 'Partial' in token:
return {
'isAuthorized': True,
'deniedFields':['user.favoriteColor']
}
if 'NeverCache' in token:
return {
'isAuthorized': True,
'ttlOverride': 0
}
if 'Unauthorized' in token:
return {
'isAuthorized': False
}
# if nothing is returned, then the authorization fails.
return {}
```
### Circumventing SigV4 and OIDC token authorization limitations
The following methods can be used to circumvent the issue of not being able to use your SigV4 signature or OIDC token as your Lambda authorization token when certain authorization modes are enabled.
If you want to use the SigV4 signature as the Lambda authorization token when the `AWS_IAM` and `AWS_LAMBDA` authorization modes are enabled for AWS AppSync's API, do the following:
+ To create a new Lambda authorization token, add random suffixes and/or prefixes to the SigV4 signature.
+ To retrieve the original SigV4 signature, update your Lambda function by removing the random prefixes and/or suffixes from the Lambda authorization token. Then, use the original SigV4 signature for authentication.
If you want to use the OIDC token as the Lambda authorization token when the `OPENID_CONNECT` authorization mode or the `AMAZON_COGNITO_USER_POOLS` and `AWS_LAMBDA` authorization modes are enabled for AWS AppSync's API, do the following:
+ To create a new Lambda authorization token, add random suffixes and/or prefixes to the OIDC token. The Lambda authorization token should not contain a Bearer scheme prefix.
+ To retrieve the original OIDC token, update your Lambda function by removing the random prefixes and/or suffixes from the Lambda authorization token. Then, use the original OIDC token for authentication.
## AWS\$1IAM authorization
This authorization type enforces the [AWS signature version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) on the GraphQL API. You can associate Identity and Access Management ([IAM](https://aws.amazon.com/iam/)) access policies with this authorization type. Your application can leverage this association by using an access key (which consists of an access key ID and secret access key) or by using short-lived, temporary credentials provided by Amazon Cognito Federated Identities.
If you want a role that has access to perform all data operations:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"appsync:GraphQL"
],
"Resource": [
"arn:aws:appsync:us-west-2:123456789012:apis/YourGraphQLApiId/*"
]
}
]
}
```
------
You can find `YourGraphQLApiId` from the main API listing page in the AppSync console, directly under the name of your API. Alternatively you can retrieve it with the CLI: `aws appsync list-graphql-apis`
If you want to restrict access to just certain GraphQL operations, you can do this for the root `Query`, `Mutation`, and `Subscription` fields.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"appsync:GraphQL"
],
"Resource": [
"arn:aws:appsync:us-west-2:123456789012:apis/YourGraphQLApiId/types/Query/fields/",
"arn:aws:appsync:us-west-2:123456789012:apis/YourGraphQLApiId/types/Query/fields/",
"arn:aws:appsync:us-west-2:123456789012:apis/YourGraphQLApiId/types/Mutation/fields/",
"arn:aws:appsync:us-west-2:123456789012:apis/YourGraphQLApiId/types/Subscription/fields/"
]
}
]
}
```
------
For example, suppose you have the following schema and you want to restrict access to getting all posts:
```
schema {
query: Query
mutation: Mutation
}
type Query {
posts:[Post!]!
}
type Mutation {
addPost(id:ID!, title:String!):Post!
}
```
The corresponding IAM policy for a role (that you could attach to an Amazon Cognito identity pool, for example) would look like the following:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"appsync:GraphQL"
],
"Resource": [
"arn:aws:appsync:us-west-2:123456789012:apis/YourGraphQLApiId/types/Query/fields/posts"
]
}
]
}
```
------
## OPENID\$1CONNECT authorization
This authorization type enforces [OpenID connect](https://openid.net/specs/openid-connect-core-1_0.html) (OIDC) tokens provided by an OIDC-compliant service. Your application can leverage users and privileges defined by your OIDC provider for controlling access.
An Issuer URL is the only required configuration value that you provide to AWS AppSync (for example, `https://auth.example.com`). This URL must be addressable over HTTPS. AWS AppSync appends `/.well-known/openid-configuration` to the issuer URL and locates the OpenID configuration at `https://auth.example.com/.well-known/openid-configuration` per the [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) specification. It expects to retrieve an [RFC5785](https://tools.ietf.org/html/rfc5785) compliant JSON document at this URL. This JSON document must contain a `jwks_uri` key, which points to the JSON Web Key Set (JWKS) document with the signing keys. AWS AppSync requires the JWKS to contain JSON fields of `kty` and `kid`.
AWS AppSync supports a wide range of signing algorithms.
| Signing algorithms |
| --- |
| RS256 |
| RS384 |
| RS512 |
| PS256 |
| PS384 |
| PS512 |
| HS256 |
| HS384 |
| HS512 |
| ES256 |
| ES384 |
| ES512 |
We recommend that you use the RSA algorithms. Tokens issued by the provider must include the time at which the token was issued (`iat`) and may include the time at which it was authenticated (`auth_time`). You can provide TTL values for issued time (`iatTTL`) and authentication time (`authTTL`) in your OpenID Connect configuration for additional validation. If your provider authorizes multiple applications, you can also provide a regular expression (`clientId`) that is used to authorize by client ID. When the `clientId` is present in your OpenID Connect configuration, AWS AppSync validates the claim by requiring the `clientId` to match with either the `aud` or `azp` claim in the token.
To validate multiple client IDs use the pipeline operator (“\$1”) which is an “or” in regular expression. For example, if your OIDC application has four clients with client IDs such as 0A1S2D, 1F4G9H, 1J6L4B, 6GS5MG, to validate only the first three client IDs, you would place 1F4G9H\$11J6L4B\$16GS5MG in the client ID field.
If an API is configured with multiple authorization types, AWS AppSync validates the issuer (iss claim) present in the JWT token from request headers by comparing it against the issuer URL specified in the API configuration. However, when an API is configured with only OPENID\$1CONNECT authorization, AWS AppSync skips this issuer URL validation step.
## AMAZON\$1COGNITO\$1USER\$1POOLS authorization
This authorization type enforces OIDC tokens provided by Amazon Cognito User Pools. Your application can leverage the users and groups in both your user pools and user pools from another AWS account and associate these with GraphQL fields for controlling access.
When using Amazon Cognito User Pools, you can create groups that users belong to. This information is encoded in a JWT token that your application sends to AWS AppSync in an authorization header when sending GraphQL operations. You can use GraphQL directives on the schema to control which groups can invoke which resolvers on a field, thereby giving more controlled access to your customers.
For example, suppose you have the following GraphQL schema:
```
schema {
query: Query
mutation: Mutation
}
type Query {
posts:[Post!]!
}
type Mutation {
addPost(id:ID!, title:String!):Post!
}
...
```
If you have two groups in Amazon Cognito User Pools - bloggers and readers - and you want to restrict the readers so that they cannot add new entries, then your schema should look like this:
```
schema {
query: Query
mutation: Mutation
}
```
```
type Query {
posts:[Post!]!
@aws_auth(cognito_groups: ["Bloggers", "Readers"])
}
type Mutation {
addPost(id:ID!, title:String!):Post!
@aws_auth(cognito_groups: ["Bloggers"])
}
...
```
Note that you can omit the `@aws_auth` directive if you want to default to a specific grant-or-deny strategy on access. You can specify the grant-or-deny strategy in the user pool configuration when you create your GraphQL API via the console or via the following CLI command:
```
$ aws appsync --region us-west-2 create-graphql-api --authentication-type AMAZON_COGNITO_USER_POOLS --name userpoolstest --user-pool-config '{ "userPoolId":"test", "defaultEffect":"ALLOW", "awsRegion":"us-west-2"}'
```
## Using additional authorization modes
When you add additional authorization modes, you can directly configure the authorization setting at the AWS AppSync GraphQL API level (that is, the `authenticationType` field that you can directly configure on the `GraphqlApi` object) and it acts as the default on the schema. This means that any type that doesn’t have a specific directive has to pass the API level authorization setting.
At the schema level, you can specify additional authorization modes using directives on the schema. You can specify authorization modes on individual fields in the schema. For example, for `API_KEY` authorization you would use `@aws_api_key` on schema object type definitions/fields. The following directives are supported on schema fields and object type definitions:
+ `@aws_api_key` - To specify the field is `API_KEY` authorized.
+ `@aws_iam` - To specify that the field is `AWS_IAM` authorized.
+ `@aws_oidc` - To specify that the field is `OPENID_CONNECT` authorized.
+ `@aws_cognito_user_pools` - To specify that the field is `AMAZON_COGNITO_USER_POOLS` authorized.
+ `@aws_lambda` - To specify that the field is `AWS_LAMBDA` authorized.
You can’t use the `@aws_auth` directive along with additional authorization modes. `@aws_auth` works only in the context of `AMAZON_COGNITO_USER_POOLS` authorization with no additional authorization modes. However, you can use the `@aws_cognito_user_pools` directive in place of the `@aws_auth` directive, using the same arguments. The main difference between the two is that you can specify `@aws_cognito_user_pools` on any field and object type definitions.
To understand how the additional authorization modes work and how they can be specified on a schema, let’s have a look at the following schema:
```
schema {
query: Query
mutation: Mutation
}
type Query {
getPost(id: ID): Post
getAllPosts(): [Post]
@aws_api_key
}
type Mutation {
addPost(
id: ID!
author: String!
title: String!
content: String!
url: String!
): Post!
}
type Post @aws_api_key @aws_iam {
id: ID!
author: String
title: String
content: String
url: String
ups: Int!
downs: Int!
version: Int!
}
...
```
For this schema, assume that `AWS_IAM` is the default authorization type on the AWS AppSync GraphQL API. This means that fields that don’t have a directive are protected using `AWS_IAM`. For example, that’s the case for the `getPost` field on the `Query` type. Schema directives enable you to use more than one authorization mode. For example, you can have `API_KEY` configured as an additional authorization mode on the AWS AppSync GraphQL API, and you can mark a field using the `@aws_api_key` directive (for example, `getAllPosts` in this example). Directives work at the field level so you need to give `API_KEY` access to the `Post` type too. You can do this either by marking each field in the `Post` type with a directive, or by marking the `Post` type with the `@aws_api_key` directive.
To further restrict access to fields in the `Post` type you can use directives against individual fields in the `Post` type as shown following.
For example, you can add a `restrictedContent` field to the `Post` type and restrict access to it by using the `@aws_iam` directive. `AWS_IAM` authenticated requests could access `restrictedContent`, however, `API_KEY` requests wouldn’t be able to access it.
```
type Post @aws_api_key @aws_iam{
id: ID!
author: String
title: String
content: String
url: String
ups: Int!
downs: Int!
version: Int!
restrictedContent: String!
@aws_iam
}
...
```
## Fine-grained access control
The preceding information demonstrates how to restrict or grant access to certain GraphQL fields. If you want to set access controls on the data based on certain conditions (for example, based on the user that’s making a call and whether the user owns the data) you can use mapping templates in your resolvers. You can also perform more complex business logic, which we describe in [Filtering Information](#aws-appsync-filtering-information).
This section shows how to set access controls on your data using a DynamoDB resolver mapping template.
Before proceeding any further, if you’re not familiar with mapping templates in AWS AppSync, you may want to review the [Resolver mapping template reference](resolver-mapping-template-reference.md#aws-appsync-resolver-mapping-template-reference) and the [Resolver mapping template reference for DynamoDB](resolver-mapping-template-reference-dynamodb.md#aws-appsync-resolver-mapping-template-reference-dynamodb).
In the following example using DynamoDB, suppose you’re using the preceding blog post schema, and only users that created a post are allowed to edit it. The evaluation process would be for the user to gain credentials in their application, using Amazon Cognito User Pools for example, and then pass these credentials as part of a GraphQL operation. The mapping template will then substitute a value from the credentials (like the username)in a conditional statement which will then be compared to a value in your database.
![\[Diagram showing authentication flow from user login to database operation using AWS services.\]](http://docs.aws.amazon.com/appsync/latest/devguide/images/FGAC.png)
To add this functionality, add a GraphQL field of `editPost` as follows:
```
schema {
query: Query
mutation: Mutation
}
type Query {
posts:[Post!]!
}
type Mutation {
editPost(id:ID!, title:String, content:String):Post
addPost(id:ID!, title:String!):Post!
}
...
```
The resolver mapping template for `editPost` (shown in an example at the end of this section) needs to perform a logical check against your data store to allow only the user that created a post to edit it. Since this is an edit operation, it corresponds to an `UpdateItem` in DynamoDB. You can perform a conditional check before performing this action, using context passed through for user identity validation. This is stored in an `Identity` object that has the following values:
```
{
"accountId" : "12321434323",
"cognitoIdentityPoolId" : "",
"cognitoIdentityId" : "",
"sourceIP" : "",
"caller" : "ThisistheprincipalARN",
"username" : "username",
"userArn" : "Sameasabove"
}
```
To use this object in a DynamoDB`UpdateItem` call, you need to store the user identity information in the table for comparison. First, your `addPost` mutation needs to store the creator. Second, your `editPost` mutation needs to perform the conditional check before updating.
Here is an example of the resolver code for `addPost` that stores the user identity as an `Author` column:
```
import { util, Context } from '@aws-appsync/utils';
import { put } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const { id: postId, ...item } = ctx.args;
return put({
key: { postId },
item: { ...item, Author: ctx.identity.username },
condition: { postId: { attributeExists: false } },
});
}
export const response = (ctx) => ctx.result;
```
Note that the `Author` attribute is populated from the `Identity` object, which came from the application.
Finally, here is an example of the resolver code for `editPost`, which only updates the content of the blog post if the request comes from the user that created the post:
```
import { util, Context } from '@aws-appsync/utils';
import { put } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
const { id, ...item } = ctx.args;
return put({
key: { id },
item,
condition: { author: { contains: ctx.identity.username } },
});
}
export const response = (ctx) => ctx.result;
```
This example uses a `PutItem` that overwrites all values rather than an `UpdateItem`, but the same concept applies on the `condition` statement block.
## Filtering information
There may be cases where you cannot control the response from your data source, but you don’t want to send unnecessary information to clients on a successful write or read to the data source. In these cases, you can filter information by using a response mapping template.
For example, suppose you don’t have an appropriate index on your blog post DynamoDB table (such as an index on `Author`). You could use the following resolver:
```
import { util, Context } from '@aws-appsync/utils';
import { get } from '@aws-appsync/utils/dynamodb';
export function request(ctx) {
return get({ key: { ctx.args.id } });
}
export function response(ctx) {
if (ctx.result.author === ctx.identity.username) {
return ctx.result;
}
return null;
}
```
The request handler fetches the item even if the caller isn’t the author who created the post. To prevent this from returning all data, the response handler checks to make sure the caller matches the item’s author. If the caller doesn’t match this check, only a null response is returned.
## Data source access
AWS AppSync communicates with data sources using Identity and Access Management ([IAM](https://aws.amazon.com/iam/)) roles and access policies. If you are using an existing role, a Trust Policy needs to be added in order for AWS AppSync to assume the role. The trust relationship will look like below:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appsync.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
It’s important to scope down the access policy on the role to only have permissions to act on the minimal set of resources necessary. When using the AppSync console to create a data source and create a role, this is done automatically for you. However when using a built in sample template from the IAM console to create a role outside of the AWS AppSync console the permissions will not be automatically scoped down on a resource and you should perform this action before moving your application to production.
# Access control use cases for securing requests and responses
In the [Security](security-authz.md#aws-appsync-security) section you learned about the different Authorization modes for protecting your API and an introduction was given on Fine Grained Authorization mechanisms to understand the concepts and flow. Since AWS AppSync allows you to perform logic full operations on data through the use of GraphQL Resolver [Mapping templates](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview), you can protect data on read or write in a very flexible manner using a combination of user identity, conditionals, and data injection.
If you’re not familiar with editing AWS AppSync Resolvers, review the [programming guide](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide).
## Overview
Granting access to data in a system is traditionally done through an [Access control matrix](https://en.wikipedia.org/wiki/Access_Control_Matrix) where the intersection of a row (resource) and column (user/role) is the permissions granted.
AWS AppSync uses resources in your own account and threads identity (user/role) information into the GraphQL request and response as a [context object](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference), which you can use in the resolver. This means that permissions can be granted appropriately either on write or read operations based on the resolver logic. If this logic is at the resource level, for example only certain named users or groups can read/write to a specific database row, then that “authorization metadata” must be stored. AWS AppSync does not store any data so therefore you must store this authorization metadata with the resources so that permissions can be calculated. Authorization metadata is usually an attribute (column) in a DynamoDB table, such as an **owner** or list of users/groups. For example there could be **Readers** and **Writers** attributes.
From a high level, what this means is that if you are reading an individual item from a data source, you perform a conditional `#if () ... #end` statement in the response template after the resolver has read from the data source. The check will normally be using user or group values in `$context.identity` for membership checks against the authorization metadata returned from a read operation. For multiple records, such as lists returned from a table `Scan` or `Query`, you’ll send the condition check as part of the operation to the data source using similar user or group values.
Similarly when writing data you’ll apply a conditional statement to the action (like a `PutItem` or `UpdateItem` to see if the user or group making a mutation has permission. The conditional again will many times be using a value in `$context.identity` to compare against authorization metadata on that resource. For both request and response templates you can also use custom headers from clients to perform validation checks.
## Reading data
As outlined above the authorization metadata to perform a check must be stored with a resource or passed in to the GraphQL request (identity, header, etc.). To demonstrate this suppose you have the DynamoDB table below:
![\[DynamoDB table with ID, Data, PeopleCanAccess, GroupsCanAccess, and Owner columns.\]](http://docs.aws.amazon.com/appsync/latest/devguide/images/auth.png)
The primary key is `id` and the data to be accessed is `Data`. The other columns are examples of checks you can perform for authorization. `Owner` would be a `String` while `PeopleCanAccess` and `GroupsCanAccess` would be `String Sets` as outlined in the [Resolver mapping template reference for DynamoDB](resolver-mapping-template-reference-dynamodb.md#aws-appsync-resolver-mapping-template-reference-dynamodb).
In the [resolver mapping template overview](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview) the diagram shows how the response template contains not only the context object but also the results from the data source. For GraphQL queries of individual items, you can use the response template to check if the user is allowed to see these results or return an authorization error message. This is sometimes referred to as an “Authorization filter”. For GraphQL queries returning lists, using a Scan or Query, it is more performant to perform the check on the request template and return data only if an authorization condition is satisfied. The implementation is then:
1. GetItem - authorization check for individual records. Done using `#if() ... #end` statements.
1. Scan/Query operations - authorization check is a `"filter":{"expression":...}` statement. Common checks are equality (`attribute = :input`) or checking if a value is in a list (`contains(attribute, :input)`).
In \$12 the `attribute` in both statements represents the column name of the record in a table, such as `Owner` in our above example. You can alias this with a `#` sign and use `"expressionNames":{...}` but it’s not mandatory. The `:input` is a reference to the value you’re comparing to the database attribute, which you will define in `"expressionValues":{...}`. You’ll see these examples below.
### Use case: owner can read
Using the table above, if you only wanted to return data if `Owner == Nadia` for an individual read operation (`GetItem`) your template would look like:
```
#if($context.result["Owner"] == $context.identity.username)
$utils.toJson($context.result)
#else
$utils.unauthorized()
#end
```
A couple things to mention here which will be re-used in the remaining sections. First, the check uses `$context.identity.username` which will be the friendly user sign-up name if Amazon Cognito user pools is used and will be the user identity if IAM is used (including Amazon Cognito Federated Identities). There are other values to store for an owner such as the unique “Amazon Cognito identity” value, which is useful when federating logins from multiple locations, and you should review the options available in the [Resolver Mapping Template Context Reference](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference).
Second, the conditional else check responding with `$util.unauthorized()` is completely optional but recommended as a best practice when designing your GraphQL API.
### Use case: hardcode specific access
```
// This checks if the user is part of the Admin group and makes the call
#foreach($group in $context.identity.claims.get("cognito:groups"))
#if($group == "Admin")
#set($inCognitoGroup = true)
#end
#end
#if($inCognitoGroup)
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"attributeValues" : {
"owner" : $util.dynamodb.toDynamoDBJson($context.identity.username)
#foreach( $entry in $context.arguments.entrySet() )
,"${entry.key}" : $util.dynamodb.toDynamoDBJson($entry.value)
#end
}
}
#else
$utils.unauthorized()
#end
```
### Use case: filtering a list of results
In the previous example you were able to perform a check against `$context.result` directly as it returned a single item, however some operations like a scan will return multiple items in `$context.result.items` where you need to perform the authorization filter and only return results that the user is allowed to see. Suppose the `Owner` field had the Amazon Cognito IdentityID this time set on the record, you could then use the following response mapping template to filter to only show those records that the user owned:
```
#set($myResults = [])
#foreach($item in $context.result.items)
##For userpools use $context.identity.username instead
#if($item.Owner == $context.identity.cognitoIdentityId)
#set($added = $myResults.add($item))
#end
#end
$utils.toJson($myResults)
```
### Use case: multiple people can read
Another popular authorization option is to allow a group of people to be able to read data. In the example below the `"filter":{"expression":...}` only returns values from a table scan if the user running the GraphQL query is listed in the set for `PeopleCanAccess`.
```
{
"version" : "2017-02-28",
"operation" : "Scan",
"limit": #if(${context.arguments.count}) $util.toJson($context.arguments.count) #else 20 #end,
"nextToken": #if(${context.arguments.nextToken}) $util.toJson($context.arguments.nextToken) #else null #end,
"filter":{
"expression": "contains(#peopleCanAccess, :value)",
"expressionNames": {
"#peopleCanAccess": "peopleCanAccess"
},
"expressionValues": {
":value": $util.dynamodb.toDynamoDBJson($context.identity.username)
}
}
}
```
### Use case: group can read
Similar to the last use case, it may be that only people in one or more groups have rights to read certain items in a database. Use of the `"expression": "contains()"` operation is similar however it’s a logical-OR of all the groups that a user might be a part of which needs to be accounted for in the set membership. In this case we build up a `$expression` statement below for each group the user is in and then pass this to the filter:
```
#set($expression = "")
#set($expressionValues = {})
#foreach($group in $context.identity.claims.get("cognito:groups"))
#set( $expression = "${expression} contains(groupsCanAccess, :var$foreach.count )" )
#set( $val = {})
#set( $test = $val.put("S", $group))
#set( $values = $expressionValues.put(":var$foreach.count", $val))
#if ( $foreach.hasNext )
#set( $expression = "${expression} OR" )
#end
#end
{
"version" : "2017-02-28",
"operation" : "Scan",
"limit": #if(${context.arguments.count}) $util.toJson($context.arguments.count) #else 20 #end,
"nextToken": #if(${context.arguments.nextToken}) $util.toJson($context.arguments.nextToken) #else null #end,
"filter":{
"expression": "$expression",
"expressionValues": $utils.toJson($expressionValues)
}
}
```
## Writing data
Writing data on mutations is always controlled on the request mapping template. In the case of DynamoDB data sources, the key is to use an appropriate `"condition":{"expression"...}"` which performs validation against the authorization metadata in that table. In [Security](security-authz.md#aws-appsync-security), we provided an example you can use to check the `Author` field in a table. The use cases in this section explore more use cases.
### Use case: multiple owners
Using the example table diagram from earlier, suppose the `PeopleCanAccess` list
```
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"update" : {
"expression" : "SET meta = :meta",
"expressionValues": {
":meta" : $util.dynamodb.toDynamoDBJson($ctx.args.meta)
}
},
"condition" : {
"expression" : "contains(Owner,:expectedOwner)",
"expressionValues" : {
":expectedOwner" : $util.dynamodb.toDynamoDBJson($context.identity.username)
}
}
}
```
### Use case: group can create new record
```
#set($expression = "")
#set($expressionValues = {})
#foreach($group in $context.identity.claims.get("cognito:groups"))
#set( $expression = "${expression} contains(groupsCanAccess, :var$foreach.count )" )
#set( $val = {})
#set( $test = $val.put("S", $group))
#set( $values = $expressionValues.put(":var$foreach.count", $val))
#if ( $foreach.hasNext )
#set( $expression = "${expression} OR" )
#end
#end
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
## If your table's hash key is not named 'id', update it here. **
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
## If your table has a sort key, add it as an item here. **
},
"attributeValues" : {
## Add an item for each field you would like to store to Amazon DynamoDB. **
"title" : $util.dynamodb.toDynamoDBJson($ctx.args.title),
"content": $util.dynamodb.toDynamoDBJson($ctx.args.content),
"owner": $util.dynamodb.toDynamoDBJson($context.identity.username)
},
"condition" : {
"expression": $util.toJson("attribute_not_exists(id) AND $expression"),
"expressionValues": $utils.toJson($expressionValues)
}
}
```
### Use case: group can update existing record
```
#set($expression = "")
#set($expressionValues = {})
#foreach($group in $context.identity.claims.get("cognito:groups"))
#set( $expression = "${expression} contains(groupsCanAccess, :var$foreach.count )" )
#set( $val = {})
#set( $test = $val.put("S", $group))
#set( $values = $expressionValues.put(":var$foreach.count", $val))
#if ( $foreach.hasNext )
#set( $expression = "${expression} OR" )
#end
#end
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"update":{
"expression" : "SET title = :title, content = :content",
"expressionValues": {
":title" : $util.dynamodb.toDynamoDBJson($ctx.args.title),
":content" : $util.dynamodb.toDynamoDBJson($ctx.args.content)
}
},
"condition" : {
"expression": $util.toJson($expression),
"expressionValues": $utils.toJson($expressionValues)
}
}
```
## Public and private records
With the conditional filters you can also choose to mark data as private, public or some other Boolean check. This can then be combined as part of an authorization filter inside the response template. Using this check is a nice way to temporarily hide data or remove it from view without trying to control group membership.
For example suppose you added an attribute on each item in your DynamoDB table called `public` with either a value of `yes` or `no`. The following response template could be used on a `GetItem` call to only display data if the user is in a group that has access AND if that data is marked as public:
```
#set($permissions = $context.result.GroupsCanAccess)
#set($claimPermissions = $context.identity.claims.get("cognito:groups"))
#foreach($per in $permissions)
#foreach($cgroups in $claimPermissions)
#if($cgroups == $per)
#set($hasPermission = true)
#end
#end
#end
#if($hasPermission && $context.result.public == 'yes')
$utils.toJson($context.result)
#else
$utils.unauthorized()
#end
```
The above code could also use a logical OR (`||`) to allow people to read if they have permission to a record or if it’s public:
```
#if($hasPermission || $context.result.public == 'yes')
$utils.toJson($context.result)
#else
$utils.unauthorized()
#end
```
In general, you will find the standard operators `==`, `!=`, `&&`, and `||` helpful when performing authorization checks.
## Real-time data
You can apply Fine Grained Access Controls to GraphQL subscriptions at the time a client makes a subscription, using the same techniques described earlier in this documentation. You attach a resolver to the subscription field, at which point you can query data from a data source and perform conditional logic in either the request or response mapping template. You can also return additional data to the client, such as the initial results from a subscription, as long as the data structure matches that of the returned type in your GraphQL subscription.
### Use case: user can subscribe to specific conversations only
A common use case for real-time data with GraphQL subscriptions is building a messaging or private chat application. When creating a chat application that has multiple users, conversations can occur between two people or among multiple people. These might be grouped into “rooms”, which are private or public. As such, you would only want to authorize a user to subscribe to a conversation (which could be one to one or among a group) for which they have been granted access. For demonstration purposes, the sample below shows a simple use case of one user sending a private message to another. The setup has two Amazon DynamoDB tables:
+ Messages table: (primary key) `toUser`, (sort key) `id`
+ Permissions table: (primary key) `username`
The Messages table stores the actual messages that get sent via a GraphQL mutation. The Permissions table is checked by the GraphQL subscription for authorization at client connection time. The example below assumes you are using the following GraphQL schema:
```
input CreateUserPermissionsInput {
user: String!
isAuthorizedForSubscriptions: Boolean
}
type Message {
id: ID
toUser: String
fromUser: String
content: String
}
type MessageConnection {
items: [Message]
nextToken: String
}
type Mutation {
sendMessage(toUser: String!, content: String!): Message
createUserPermissions(input: CreateUserPermissionsInput!): UserPermissions
updateUserPermissions(input: UpdateUserPermissionInput!): UserPermissions
}
type Query {
getMyMessages(first: Int, after: String): MessageConnection
getUserPermissions(user: String!): UserPermissions
}
type Subscription {
newMessage(toUser: String!): Message
@aws_subscribe(mutations: ["sendMessage"])
}
input UpdateUserPermissionInput {
user: String!
isAuthorizedForSubscriptions: Boolean
}
type UserPermissions {
user: String
isAuthorizedForSubscriptions: Boolean
}
schema {
query: Query
mutation: Mutation
subscription: Subscription
}
```
Some of the standard operations, such as `createUserPermissions()`, are not covered below to illustrate the subscription resolvers, but are standard implementations of DynamoDB resolvers. Instead, we’ll focus on subscription authorization flows with resolvers. To send a message from one user to another, attach a resolver to the `sendMessage()` field and select the **Messages** table data source with the following request template:
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"toUser" : $util.dynamodb.toDynamoDBJson($ctx.args.toUser),
"id" : $util.dynamodb.toDynamoDBJson($util.autoId())
},
"attributeValues" : {
"fromUser" : $util.dynamodb.toDynamoDBJson($context.identity.username),
"content" : $util.dynamodb.toDynamoDBJson($ctx.args.content),
}
}
```
In this example, we use `$context.identity.username`. This returns user information for AWS Identity and Access Management or Amazon Cognito users. The response template is a simple passthrough of `$util.toJson($ctx.result)`. Save and go back to the schema page. Then attach a resolver for the `newMessage()` subscription, using the **Permissions** table as a data source and the following request mapping template:
```
{
"version": "2018-05-29",
"operation": "GetItem",
"key": {
"username": $util.dynamodb.toDynamoDBJson($ctx.identity.username),
},
}
```
Then use the following response mapping template to perform your authorization checks using data from the **Permissions** table:
```
#if(! ${context.result})
$utils.unauthorized()
#elseif(${context.identity.username} != ${context.arguments.toUser})
$utils.unauthorized()
#elseif(! ${context.result.isAuthorizedForSubscriptions})
$utils.unauthorized()
#else
##User is authorized, but we return null to continue
null
#end
```
In this case, you’re doing three authorization checks. The first ensures that a result is returned. The second ensures that the user isn’t subscribing to messages that are meant for another person. The third ensures that the user is allowed to subscribe to any fields, by checking a DynamoDB attribute of `isAuthorizedForSubscriptions` stored as a `BOOL`.
To test things out, you could sign in to the AWS AppSync console using Amazon Cognito user pools and a user named “Nadia”, and then run the following GraphQL subscription:
```
subscription AuthorizedSubscription {
newMessage(toUser: "Nadia") {
id
toUser
fromUser
content
}
}
```
If in the **Permissions** table there is a record for the `username` key attribute of `Nadia` with `isAuthorizedForSubscriptions` set to `true`, you’ll see a successful response. If you try a different `username` in the `newMessage()` query above, an error will be returned.
# Using AWS WAF to protect your AWS AppSync APIs
AWS WAF is a web application firewall that helps protect web applications and APIs from attacks. It allows you to configure a set of rules, called a web access control list (web ACL), that allow, block, or monitor (count) web requests based on customizable web security rules and conditions that you define. When you integrate your AWS AppSync API with AWS WAF, you gain more control and visibility into the HTTP traffic accepted by your API. To learn more about AWS WAF, see [How AWS WAF Works](https://docs.aws.amazon.com/waf/latest/developerguide/how-aws-waf-works.html) in the AWS WAF Developer Guide.
You can use AWS WAF to protect your AppSync API from common web exploits, such as SQL injection and cross-site scripting (XSS) attacks. These could affect API availability and performance, compromise security, or consume excessive resources. For example, you can create rules to allow or block requests from specified IP address ranges, requests from CIDR blocks, requests that originate from a specific country or region, requests that contain malicious SQL code, or requests that contain malicious script.
You can also create rules that match a specified string or a regular expression pattern in HTTP headers, method, query string, URI, and the request body (limited to the first 8 KB). Additionally, you can create rules to block attacks from specific user agents, bad bots, and content scrapers. For example, you can use rate-based rules to specify the number of web requests that are allowed by each client IP in a trailing, continuously updated, 5-minute period.
To learn more about the types of rules that are supported and additional AWS WAF features, see the [AWS WAF Developer Guide](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) and the [AWS WAF API Reference](https://docs.aws.amazon.com/waf/latest/APIReference/API_Types_AWS_WAFV2.html).
**Important**
AWS WAF is your first line of defense against web exploits. When AWS WAF is enabled on an API, AWS WAF rules are evaluated before other access control features, such as API key authorization, IAM policies, OIDC tokens, and Amazon Cognito user pools.
## Integrate an AppSync API with AWS WAF
You can integrate an Appsync API with AWS WAF using the AWS Management Console, the AWS CLI, AWS CloudFormation, or any other compatible client.
**To integrate an AWS AppSync API with AWS WAF**
1. Create an AWS WAF web ACL. For detailed steps using the [AWS WAF Console](https://console.aws.amazon.com/waf/), see [Creating a web ACL](https://docs.aws.amazon.com/waf/latest/developerguide/web-acl-creating.html).
1. Define the rules for the web ACL. A rule or rules are defined in the process of creating the web ACL. For information about how to structure rules, see [AWS WAF rules](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rules.html). For examples of useful rules you can define for your AWS AppSync API, see [Creating rules for a web ACL](#Creating-web-acl-rules).
1. Associate the web ACL with an AWS AppSync API. You can perform this step in the [AWS WAF Console](https://console.aws.amazon.com/wafv2/) or in the [AppSync Console](https://console.aws.amazon.com/appsync/).
+ To associate the web ACL with an AWS AppSync API in the AWS WAF Console, follow the instructions for [Associating or disassociating a Web ACL with an AWS resource](https://docs.aws.amazon.com/waf/latest/developerguide/web-acl-associating-aws-resource.html) in the AWS WAF Developer Guide.
+ To associate the web ACL with an AWS AppSync API in the AWS AppSync Console
1. Sign in to the AWS Management Console and open the [AppSync Console](https://console.aws.amazon.com/appsync/).
1. Choose the API that you want to associate with a web ACL.
1. In the navigation pane, choose **Settings**.
1. In the **Web application firewall** section, turn on **Enable AWS WAF**.
1. In the **Web ACL** dropdown list, choose the name of the web ACL to associate with your API.
1. Choose **Save** to associate the web ACL with your API.
**Note**
After you create a web ACL in the AWS WAF Console, it can take a few minutes for the new web ACL to be available. If you do not see a newly created web ACL in the **Web application firewall** menu, wait a few minutes and retry the steps to associate the web ACL with your API.
**Note**
AWS WAF integration only supports the `Subscription registration message` event for real-time endpoints. AWS AppSync will respond with an error message instead of a `start_ack` message for any `Subscription registration message` blocked by AWS WAF.
After you associate a web ACL with an AWS AppSync API, you will manage the web ACL using the AWS WAF APIs. You do not need to re-associate the web ACL with your AWS AppSync API unless you want to associate the AWS AppSync API with a different web ACL.
## Creating rules for a web ACL
Rules define how to inspect web requests and what to do when a web request matches the inspection criteria. Rules don't exist in AWS WAF on their own. You can access a rule by name in a rule group or in the web ACL where it's defined. For more information, see [AWS WAF rules](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rules.html). The following examples demonstrate how to define and associate rules that are useful for protecting an AppSync API.
**Example web ACL rule to limit request body size**
The following is an example of a rule that limits the body size of requests. This would be entered into the **Rule JSON editor** when creating a web ACL in the AWS WAF Console.
```
{
"Name": "BodySizeRule",
"Priority": 1,
"Action": {
"Block": {}
},
"Statement": {
"SizeConstraintStatement": {
"ComparisonOperator": "GE",
"FieldToMatch": {
"Body": {}
},
"Size": 1024,
"TextTransformations": [
{
"Priority": 0,
"Type": "NONE"
}
]
}
},
"VisibilityConfig": {
"CloudWatchMetricsEnabled": true,
"MetricName": "BodySizeRule",
"SampledRequestsEnabled": true
}
}
```
After you have created your web ACL using the preceding example rule, you must associate it with your AppSync API. As an alternative to using the AWS Management Console, you can perform this step in the AWS CLI by running the following command.
```
aws waf associate-web-acl --web-acl-id waf-web-acl-arn --resource-arn appsync-api-arn
```
It can take a few minutes for the changes to propagate, but after running this command, requests that contain a body larger than 1024 bytes will be rejected by AWS AppSync.
After you create a new web ACL in the AWS WAF Console, it can take a few minutes for the web ACL to be available to associate with an API. If you run the CLI command and get a `WAFUnavailableEntityException` error, wait a few minutes and retry running the command.
**Example web ACL rule to limit requests from a single IP address**
The following is an example of a rule that throttles an AppSync API to 100 requests from a single IP address. This would be entered into the **Rule JSON editor** when creating a web ACL with a rate-based rule in the AWS WAF Console.
```
{
"Name": "Throttle",
"Priority": 0,
"Action": {
"Block": {}
},
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "Throttle"
},
"Statement": {
"RateBasedStatement": {
"Limit": 100,
"AggregateKeyType": "IP"
}
}
}
```
After you have created your web ACL using the preceding example rule, you must associate it with your AppSync API. You can perform this step in the AWS CLI by running the following command.
```
aws waf associate-web-acl --web-acl-id waf-web-acl-arn --resource-arn appsync-api-arn
```
**Example web ACL rule to prevent GraphQL \$1\$1schema introspection queries to an API**
The following is an example of a rule that prevents GraphQL \$1\$1schema introspection queries to an API. Any HTTP body that includes the string "\$1\$1schema" will be blocked. This would be entered into the **Rule JSON editor** when creating a web ACL in the AWS WAF Console.
```
{
"Name": "BodyRule",
"Priority": 5,
"Action": {
"Block": {}
},
"VisibilityConfig": {
"SampledRequestsEnabled": true,
"CloudWatchMetricsEnabled": true,
"MetricName": "BodyRule"
},
"Statement": {
"ByteMatchStatement": {
"FieldToMatch": {
"Body": {}
},
"PositionalConstraint": "CONTAINS",
"SearchString": "__schema",
"TextTransformations": [
{
"Type": "NONE",
"Priority": 0
}
]
}
}
}
```
After you have created your web ACL using the preceding example rule, you must associate it with your AppSync API. You can perform this step in the AWS CLI by running the following command.
```
aws waf associate-web-acl --web-acl-id waf-web-acl-arn --resource-arn appsync-api-arn
```