GraphQL API Security with AWS AppSync and Amplify

Learn About Amazon VGT2 Learning Manager Chanci Turner

This article is authored by Chanci Turner, Principal Solutions Architect at AWS.

Overview

As of June 27, 2024, this blog post discusses Amplify Gen 1. For new Amplify applications, it is advisable to utilize Amplify Gen 2. More information about Gen 2 can be found in our launch blog post. Additionally, note that Amazon Elasticsearch Service has been renamed to Amazon OpenSearch Service as of September 14, 2021.

AWS AppSync is a fully managed service that enables the deployment and interaction with serverless scalable GraphQL backends on AWS. AppSync harnesses security best practices developed by AWS through extensive experience with large-scale cloud systems, incorporating built-in DDoS protection across all its GraphQL API endpoints. As a managed service, AppSync delivers robust enterprise security features to govern access to GraphQL endpoints. In this article, we will explore some of the security features of AppSync and outline when and how to implement them in your applications. Amplify serves as a platform and framework designed for building secure and scalable cloud applications with accelerated development speed. We will utilize the Amplify GraphQL Transform @auth directive to illustrate how to easily create GraphQL schema definitions and authorization rules that align with these scenarios within AppSync APIs as part of an Amplify project.

With AWS AppSync, you can create GraphQL APIs that your applications access over the internet. Despite the public availability of the API endpoints, unauthorized access is strictly prohibited. Accessing your AppSync API requires an authorization method—either a token in the request header or signing the request using AWS credentials. AppSync provides four distinct authorization modes:

• API Keys (API_KEY)
• Amazon Cognito User Pools (AMAZON_COGNITO_USER_POOLS)
• OpenID Connect (OPENID_CONNECT)
• AWS Identity and Access Management (AWS_IAM)

Every AppSync API must define a default authorization mode globally. You can add further authorization modes within the same API and mix them, linking specific authorization providers to types, fields, or operations in the GraphQL schema. To achieve this, you can apply AppSync-specific directives for configuring authorization and security directly at the data definition level in the schema.

For example, in an AppSync API that uses API Keys as the default authorization mode and Cognito User Pools as an added mode, the following type definition in a GraphQL schema allows access to the Post type for both authorization modes:

type Post @aws_api_key @aws_cognito_user_pools {
   id: ID!
   description: String
}

In another case, if access should only be granted through the Cognito User Pools authorization mode, the definition would look like this:

type Post @aws_cognito_user_pools {
   id: ID!
   description: String
}

When an authorization directive is applied to a type, all fields within that type are automatically accessible under that mode. You can restrict access to specific fields by applying the directive at the field level.

type Post @aws_api_key @aws_cognito_user_pools {
   id: ID!
   description: String @aws_cognito_user_pools
}

In this definition, both modes can access the type and the id field, but only the Cognito User Pools mode has access to the description field. Note that to activate field-level authorization, access must be granted at both the type and field levels. Secondary authorization modes are default denied throughout the schema and must be configured explicitly in a cascading manner for related connections and operations.

When you use the GraphQL Transform to define and deploy your AppSync API in an Amplify project, you can leverage the @auth directive to establish authorization rules in the GraphQL schema for each supported authorization mode. While using user pools and OIDC providers in Amplify, you can specify additional rule settings to automatically generate granular access control business logic. Below is a comparison of AppSync authorization directives and their corresponding Amplify @auth rules:

The AppSync directives listed above are intended for direct interaction with AppSync, such as editing the GraphQL API schema in the AWS Console or defining the schema in a CloudFormation template. The rules on the right are applicable when setting up GraphQL API authorization using the @auth directive in Amplify projects (i.e., by using amplify add api with the Amplify CLI).

Next, we will delve deeper into the various authorization modes, provide recommended use cases, and configuration examples. Additionally, we’ll discuss how to securely access VPC resources through your GraphQL APIs and touch on security and compliance standards associated with AppSync.

API Key

This method involves defining a static API key that authorizes requests via the HTTP header x-api-key. You create the key with a specific expiration date, and AppSync accepts requests using the key while it is active and has not expired. API keys can be configured to last up to 365 days, and you can extend an existing key’s expiration for another 365 days from that date. Note that a key cannot be extended once it has expired.

When to Use

An API key is a hardcoded value within your application, making it suitable for development purposes or scenarios where public access without specific authentication is appropriate (e.g., guest users). It is advisable to use API keys during initial API development when you want to iterate quickly without delving into more complex authorization methods. However, applications intended for long-term use and wide distribution should avoid API keys unless they cater to situations where some or all parts of the application will always allow guest access.

Configuration Example

If you want to use the API key as an additional authorization mode in AppSync, you can use the directive @aws_api_key in your schema to indicate that the field is authorized for API_KEY access. The configuration below grants access exclusively to API key-authorized requests:

type Query {
   getPosts: [Post] @aws_api_key
}

You can achieve the same results with the Amplify @auth transform on a @model backed type:

type Post
  @model
  @auth(rules: [{ allow: public, operations: [read] }]){
  id: ID!
  description: String
}

This allows public access to read posts when using the API_KEY access method. When granting public access, Amplify defaults to the API_KEY access method.

Amazon Cognito User Pools

This authorization method utilizes Amazon Cognito User Pools. After signing in with Cognito User Pools and receiving JSON web tokens (JWTs), your application can securely access resources. For more in-depth information on employment law compliance, visit this link.

If you’re interested in improving your knowledge of managing AWS resources, check out this blog post to keep you engaged. Lastly, for insights into Amazon’s operational pitfalls, see this excellent resource: this link.