Using Descope JWTs with AWS API Gateway

By configuring Descope JWTs to work with AWS API Gateway, you leverage the built-in JWT validation mechanism of AWS and the secure token issuing capabilities of Descope. This ensures that the API's endpoints are only accessible by clients that present a valid Descope JWT.

If you're using Descope and want to use the Descope JWT tokens to protect your AWS API endpoints, you can configure a JWT Authorizer to handle this. An AWS JWT Authorizer is a specific type of Lambda authorizer, which allows you to use custom JSON Web Tokens (JWTs) as authorization tokens when clients try to access your APIs. The primary function of a JWT Authorizer is to:

1. Decode the incoming JWT token.
2. Validate the JWT signature.
3. Extract claims from the token.
4. Return an IAM policy to allow or deny the original API Gateway request.

On the Descope side of things, you'll need to generate an AWS API Gateway compliant JWT by going to the JWT Templates page in your Project Settings and creating an AWS API Gateway template:

Once you've done this, you'll need to configure an AWS JWT Authorizer by following the next section's steps closely.

How to Setup an AWS JWT Authorizer

Assuming you've already configured your Routes and have the necessary permissions established for each of your routes in the IAM Console, all you'll need to do from here is create a Lambda Trigger for the JWT

1. Create a JWT Authorizer: In the API Gateway console, navigate to the Authorizers section and choose Create New Authorizer. For the type, select JWT.

2. Input the following JWT Authorizer information (an example is shown below):

   • Name: Can be anything, or you can call it JWTAuth.
   • Input Token Source: Specify where the JWT will come from, usually this is the Authorization header, as shown in the photo below.
   • Issuer & Audience: You need to provide the issuer URL and audience of Descope. The issuer URL is https://api.descope.com/<Your Descope Project ID> and the audience is <Your Project ID>

4. Associate with API Endpoint: Once the authorizer is created, you can associate it with specific API methods. Whenever these methods are called, the JWT token will be validated by the JWT Authorizer. You do this by "attaching" an authorizer to an API route.

You can also use additional scopes and include these in your JWT if you want to have app specific scopes for each API route that's configured.

5. Test: Once everything is set up, test by making an API request with a valid JWT. Ensure that the request is authorized successfully, and invalid or expired tokens are appropriately denied.

Once you've set this up, you should be all set. To read more about JWT Authorizers and how they can be used, you can take a look at this guide on the AWS Documentation site.

Conclusion

Being able to use Descope and your custom JWT tokens with all of your current API Gateway infrastructure, is an incredibly powerful tool. With this, you can harness the power of Descope Flows and authentication, with the convenience of API Gateway and the rest of the AWS suite.

If you have any other questions about Descope, feel free to reach out to us!