AWS Cognito

Introduction

In this recipe, you'll learn how to configure an existing AWS Cognito user pool and generate a JWT which you can pass in the header of your requests to Hasura. After setting up your AuthConfig object to use JWT mode, this will allow you to validate users' identities and create permission rules which can limit access to underlying data served by Hasura DDN.

Prerequisites

Before continuing, ensure you have:

• An AWS Cognito user pool with a domain configured.
• A local application that can integrate with Cognito for authentication.
• A local Hasura DDN project.

Recipe

Step 1. Create a Lambda trigger for modifying JWT claims

To add the custom claims that Hasura requires, you will need to create an AWS Lambda function and set it as a trigger for your Cognito user pool.

In the AWS Lambda console, create a new Lambda function. Select the Author from scratch option and provide a name, runtime, architecture, and any advanced settings you wish to configure.

After your Lambda is created, you'll be redirected to an editor where you can modify the Lambda's handler. Add the following code to modify the Cognito JWT and inject the custom Hasura namespace claims:

export const handler = async (event) => {
  // Here, you'll need to fetch the user's role from Hasura DDN using an admin-level authenticated request
  // Learn more here: https://hasura.io/docs/3.0/auth/authentication/jwt/special-roles
  // Below, we're hard-coding the value for now
  const user_role = "user"; // the role returned from your request ☝️
  event.response = {
    claimsOverrideDetails: {
      claimsToAddOrOverride: {
        "claims.jwt.hasura.io": JSON.stringify({
          "x-hasura-user-id": event.request.userAttributes.sub,
          "x-hasura-default-role": user_role,
          "x-hasura-allowed-roles": ["user"],
        }),
      },
    },
  };

  return event;
};

This will add the required Hasura namespace with the keys that Hasura DDN expects when decoding a JWT. You can modify the keys to suit your Hasura DDN roles.

Click Deploy.

Custom claims

You can create any custom keys you wish and reference them in your permissions using session variables. Above, x-hasura-user-id is simply an example. Any claim prefixed with x-hasura- is accessible to the Hasura DDN Engine. For more information on which values are required, check the authorization docs.

Step 2. Add the Lambda as an Authentication trigger

From your user pool's dashboard, select the User pool properties tab and then click Add Lambda trigger. Choose Authentication as the trigger type and choose Pre token generation trigger.

Then, select the Lambda you generated in the previous step and click Add Lambda trigger.

Step 3. Update your AuthConfig

Update your AuthConfig object to use JWT mode and your Cognito JWKs, which you can find on your User pool overview card:

kind: AuthConfig
version: v2
definition:
  mode:
    jwt:
      claimsConfig:
        namespace:
          claimsFormat: StringifiedJson
          location: "/claims.jwt.hasura.io"
      key:
        jwkFromUrl: "https://cognito-idp.<your_region>.amazonaws.com/<your_region>_<your_user_pool_id>.well-known/jwks.json"
      tokenLocation:
        type: Header
        name: Auth-Token

Then, create a new build of your supergraph:

ddn supergraph build local

Step 4. Test your configuration

Generate a new JWT by logging into your application. These values aren't typically displayed to users, so you'll need to log them while in development. You can then add that value as a header in the console and test any permissions you have in your metadata.

Wrapping up

In this guide, you learned how to integrate AWS Cognito with Hasura DDN to create a secure and scalable identity management solution using JWTs. By leveraging custom claims in conjunction with permissions, you can define precise access-control rules, ensuring that your application remains secure and meets your users' needs.

As you continue building out your supergraph, keep in mind that authentication and authorization are crucial components. Always validate your configuration and regularly test your setup to ensure it functions as expected across different roles and environments.

If you encounter issues or need further customization, consider reviewing our related documentation or exploring additional AWS Cognito features that can enhance your authentication flows.

Learn more about authentication and authorization

• Authentication with Hasura DDN
• Authorization with Hasura DDN
• Permissions with Hasura DDN

Similar recipes

• Authentication recipes