Introduction

AWS AppSync is a managed serverless GraphQL service that simplifies application development by enabling you to create a flexible API to securely access, manipulate, and combine data from multiple sources.

This guide will walk you through the steps to configure AWS AppSync to validate Descope JWTs, ensuring that only authenticated users can access your GraphQL endpoints.

Note: If you want to use the Descope JWTs to protect your AWS API Gateway endpoints, you can configure a JWT Authorizer to handle this.

Step 1: Configuring Your Descope Project

First, adjust your Descope project settings to generate JWTs compatible with AWS services:

1. Log in to your Descope dashboard.
2. Navigate to Project Settings.
3. Enable the option to generate AWS compliant JWTs. This will alter the Issuer (iss) claim in the JWT to include the full base URL of the Descope authentication service.Example: "iss": https://api.descope.com/__Project_ID__ instead of "iss": __Project_ID__.

Step 2: Setting Up AWS AppSync

Next, configure AWS AppSync to use Descope JWTs:

1. Go to the AWS Management Console and open up AppSync.
2. Select or create a new GraphQL API.
3. Navigate to the Settings section of your API, on the left-hand menu.

Step 3: Configuring the Authorization Type

In the settings:

1. Under Authorization type, select OpenID Connect.
2. For OpenID Connect Provider URL, enter the issuer URL from your Descope project (e.g., https://api.descope.com/__Project_ID__).
3. Set the Client ID field to your Descope Project ID.

Step 5: Modifying your GraphQL Schema

If you're using Descope as an OIDC provider for your authorization controls, you'll need to modify your GraphQL schema to be able to accept Descope JWTs as authorization tokens. If you're using AWS Amplify, you can do this by following the guide in the AWS Amplify docs page.

This table outlines different authorization strategies and their corresponding providers for accessing data in an AWS AppSync environment. Each row represents a specific use case and the strategy/provider to use for that scenario.

As an example, this schema will allow all users (as long as their signed in with Descope) to query from your backend:

type Todo
  @model
  @auth(
    rules: [
      { allow: private, provider: oidc }
    ]
  ) {
  content: String
}

Step 6: Make Sure that Descope JWTs are AWS Compliant

In order to make sure AWS can use the JWTs that are created when you login to your app with the Descope SDK, you'll need to make sure the Issuer URL in the JWT matches your OIDC configuration in Step 3.

You can do this in Project Settings in the Descope Console.

Step 7: Utilizing the Descope Tokens with your Queries and Mutations

import { generateClient } from 'aws-amplify/api';
import { getSessionToken } from '@descope/react-sdk';

const client = generateClient();

const fetchData = async () => {
  const sessionToken = getSessionToken();
  console.log(sessionToken);
  const todos = await client.graphql({ query: listTodos, authToken: sessionToken });
  console.log(todos);
  return todos;
};

Step 8: Deploying and Testing

After configuring the authorization settings:

1. Deploy your GraphQL API.
2. Test the API using a valid JWT token obtained from your Descope project. Ensure that authenticated requests are successful and unauthorized requests are denied.

Sample App

If you want to look at the source code of a sample Next.js application using the Amplify SDK with an AppSync schema and the Descope React SDK, you can look at our sample application on GitHub.

There are also instructions in the README for how to spin up your own version of the sample app, with your own AWS instance and AppSync backend.

Conclusion

By integrating Descope JWTs with AWS AppSync, you benefit from the streamlined and secure authentication flow provided by Descope, while leveraging the powerful features of AWS AppSync. This setup ensures that your GraphQL APIs are protected and only accessible by authenticated users.

For more detailed information on AWS AppSync and JWT authorization, refer to the AWS AppSync Developer Guide.

If you have any questions or need further assistance with Descope, don't hesitate to contact Descope Support.