Using Moesif Developer Portal with Amazon API Gateway

Overview

In this guide, you’ll learn how to integrate Moesif Developer Portal with Amazon API Gateway. For API access control, we’ll use JWTs (JSON Web Token).

The guide assumes you have basic knowledge of the following:

  • Amazon API Gateway
  • Lambda functions and Lambda authorizers
  • JWT
  • Node.js

Background

The guide sets up a very basic REST API in Amazon API Gateway. To keep the tutorial simple and concise, we don’t build the API from scratch. Rather, we integrate the REST API with an existing HTTP endpoint JSONPlaceholder.

Here’s the core flow of how the components work together that this tutorial focuses on:

  1. Auth0 manages user signups and logins.
  2. You use the Developer Portal to generate the JWT necessary to make authorized request to the API
  3. You make authorized requests by including the JWT in an HTTP reqeuest header.
  4. A Lambda authorizer verifies the JWT to determine whether to allow or deny access to the API.

Objectives

  • Set up Auth0 as the identity provider.
  • Set up a Amazon API Gateway REST API.
  • Set up a TOKEN Lambda authorizer for JWT.
  • Set up Moesif Developer Portal with its JWT plugin.

Before You Start

  • Make sure you have Node.js installed on your system.
  • Make sure you have active accounts in the following platforms:

Set up an Amazon API Gateway REST API

  1. Sign in to the API Gateway console.
  2. Select Create API.
  3. Choose REST API as the API type and select Build.
  4. Fill in the API details and then select Create API.

Create a Method

To send requests to the API, you must create methods for your API endpoint resources. For simplicity, let’s create a GET request method on the default root resource (/) of the API. Upon receiving the request, the AWS Gateway REST API actually sends the request down to an existing HTTP API hosted elsewhere. This tutorial specifies JSONPlaceholder as the external HTTP endpoint.

  1. Select Create Method.
  2. Select HTTP as the integration type.
  3. Select GET as the HTTP method.
  4. In the endpoint URL field, put https://jsonplaceholder.typicode.com/posts.
  5. Select Create method.

Deploy the API

  1. Select Deploy API in your API homepage.
  2. Define a stage and put in an optional description of the deployment.
  3. Select Deploy.

After the deployment finishes successfully, the Stages screen appears that lists the details of your deployment. Note down the Invoke URL in the Stage details pane where you can now start making requests to. The URL follows the format https://ABCDEFGXYZ.execute-api.ap-southeast-2.amazonaws.com/dev. dev indicates the stage name. Sending a GET request to your API endpoint sends back response like the following:

[
  {
    "userId": 1,
    "id": 2,
    "title": "qui est esse",
    "body": "est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla"
  },
  {
    "userId": 1,
    "id": 3,
    "title": "ea molestias quasi exercitationem repellat qui ipsa sit aut",
    "body": "et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut ad\nvoluptatem doloribus vel accusantium quis pariatur\nmolestiae porro eius odio et labore et velit aut"
  },
  {
    "userId": 1,
    "id": 4,
    "title": "eum et est occaecati",
    "body": "ullam et saepe reiciendis voluptatem adipisci\nsit amet autem assumenda provident rerum culpa\nquis hic commodi nesciunt rem tenetur doloremque ipsam iure\nquis sunt voluptatem rerum illo velit"
  },
  /*snip*/
]

Integrate Amazon API Gateway with Moesif

To integrate Moesif with API Gateway, follow the tutorial Integrating with AWS API Gateway. If you haven’t signed up for Moesif yet, the tutorial also walks you through setting up your Moesif account.

Obtain Your Moesif Application ID

During the onboarding process of your sign up, Moesif shows you your Application ID. You can always obtain your Application ID by following these steps any time:

  1. Log into Moesif Portal.
  2. Select the account icon to bring up the settings menu.
  3. Select Installation or API Keys.
  4. Copy your Moesif Application ID from the Collector Application ID field.

Obtain a Moesif Management Token

To generate a Management API key, follow these steps:

  1. In Moesif Portal, select the account icon to bring up the settings menu.
  2. Select API Keys.
  3. From the Management API Key section, select the necessary scopes and optionally set the key’s expiration time.
  4. Select Generate Token.

Make sure you at least select the Read scopes for the monetization, analytics, and dashboards resources so you can view your plans, prices, subscriptions, and embedded workspaces in the developer portal UI.

You’ll use your Application ID and Management token in the later steps of this tutorial.

Set up Auth0

Moesif Developer Portal uses Auth0 for user signups and logins. Follow these steps to integrate Auth0:

Create Auth0 Application

  1. Go to your Auth0 Dashboard.
  2. Go to Applications > Applications.
  3. Specify a name for your app and then select Single Page Web Applications as the application type.
  4. Select Create.
  5. In the Application Details page that appears, select the Settings tab.
  6. Go to the Application URIs section and add http://127.0.0.1:4001 to the list of Allowed Callback URLs, Allowed Logout URLs, and Allowed Web Origins. This URI represents the where you host the developer portal.
  7. Select Save Changes.

Add Auth0 in Developer Portal

  1. Set the following environment variables in the my-dev-portal/.env file:

     REACT_APP_AUTH_PROVIDER="Auth0"
 REACT_APP_AUTH0_DOMAIN=
 REACT_APP_AUTH0_CLIENT_ID=

  2. Set the following environment variables in the my-dev-portal-api/.env file:

     AUTH_PROVIDER="Auth0"
 AUTH0_DOMAIN=

To get the Auth0 domain and client ID values, follow these steps:

  1. Go to your Auth0 Dashboard.
  2. Go to Applications > Applications and then select the application you created for your developer portal.
  3. Select the Settings tab and go the Basic Information section.
  4. Copy the Domain and Client ID values.

Set up Stripe

Moesif Developer Portal supports Stripe as the billing provider. Through this integration, the Developer portal allows you to subscribe to Stripe products, while tracking API usage and billing accordingly.

Integrate Stripe with Moesif

  1. Log into Moesif Portal.
  2. Select the account icon to bring up the settings menu.
  3. Select Extensions .
  4. Search for Stripe and then follow the instructions.

Important: Make sure you select the Extension Enabled toggle on.

Add Stripe in Developer Portal

  1. Set the following environment variables in the my-dev-portal-api/.env file: 
     APP_PAYMENT_PROVIDER="stripe"
 STRIPE_API_KEY=
  2. Set the following environment variables in the my-dev-portal/.env file: 
     REACT_APP_STRIPE_PUBLISHABLE_KEY=
 REACT_APP_STRIPE_MANAGEMENT_URL=https://billing.stripe.com/p/login/test_6oEg0zcmPdBB492eUU

To get the Stripe API keys, see Reveal secret or restricted API keys.

The second environment variable holds links to the Stripe customer portal. For instructions on how to set up the customer portal, see Activate the no-code customer portal.

Create Product in Stripe

Stripe Products map to Plans in Moesif. In the Developer Portal, you can see the existing Plans and choose to subscribe to the ones you want. So if you don’t have any existing Products in Stripe, create them.

Set up Billing Meter in Moesif

Billing meters in Moesif performs two important tasks in API monetization process:

  • Track usage based on specific criteria.
  • Report that usage to the billing provider.

To create a Billing Meter, follow the instructions in Creating Meters.

Set up JWT

This tutorial uses JWT-based authorization to allow access to APIs. The Developer Portal provisions the JWT that you must pass in an HTTP request header to your API Gateway REST API. A Lambda authorizer verifies the token to allow or deny access to the API resources.

Therefore, to set up JWT, you have to set up JWT in these two components:

Moesif Developer Portal
Settng up the Developer Portal involves providing it with the following information:
  • The secret or private key the sign the JWT with.
  • The claims that you expect the JWT to contain.
  • The key ID value of a JWT that uniquely identifies the JWT in a JWKS (JSON Web Key Set).
  • The expiration period of a JWT.
TOKEN-based Lambda authorizer
A TOKEN Lambda authorizer supports bearer tokens like JWTs. The JWT you pass in the request header becomes available through the Lambda’s event object. To verify the JWT, the authorizer requries JWKS URI for RS256-signed JWTs. For HS256-signed JWTs, a single key both signs and verifies the JWT. So the authorizer only requires that secret.

Set up JWT in Developer Portal

Set the following environment variables in the my-dev-portal-api/.env file:

PLUGIN_APIM_PROVIDER="AWS"
PLUGIN_JWT_ALGORITHM=
PLUGIN_JWT_SECRET=
PLUGIN_JWT_KID=
PLUGIN_JWT_USER_ID_FIELD="sub"
PLUGIN_JWT_COMPANY_ID_FIELD="org_id"
PLUGIN_JWT_EXPIRES_IN=

We set the first environment variable to AWS since we use the API Gateway to host the API and authorize requests with Lambda authorizer. The later ones define the necessary details so Developer Portal can provision JWTs. For the JWT algorithm Developer Portal uses, set either RS256 or HS256.

Set up Lambda authorizer

This tutorial uses the sample Lambda authorizer in the Moesif Developer Portal source code repository. To make this authorizer work, follow these instructions:

Create the Lambda

To create the TOKEN authorizer, follow the instructions in Configure a Lambda authorizer (console).

Add the Authorizer to API Method

You must attach the authorizer to a method of your REST API. When API Gateway receives an API call that matches the resource and method, it invokes the authorizer.

For instructions, see Configure a method to use a Lambda authorizer (console).

Specify JWT Details for the Authorizer

You must specify to the authorizer how to get the public key or secret to verify the JWT.

  • For RS256-signed JWTs, set the following environment variable: 
    JWKS_URI="YOUR_JWKS_URI"

    Make sure to exlude the protocol part (https://) of the URI if you’re using the sample Lambda authorizer:

    const client = jwksClient({
  jwksUri: `https://${process.env.JWKS_URI}`,
});

  • For HS256-signed JWTs, set the following environment variable:

    JWT_VERIFY_KEY="YOUR_JWT_SECRET"

Run the Developer Portal

Set the Server URIs and Moesif Credentials

  • Check if you’ve set the following environment variables in my-dev-portal/.env.

      HOST="127.0.0.1"
  PORT=4001

  REACT_APP_DEV_PORTAL_API_SERVER="http://127.0.0.1:3030"

    Then check if you’ve set the following environment variables in my-dev-portal-api/.env:

      FRONT_END_DOMAIN=127.0.0.1:4001

    These variables define the following details:

    • The host and port where the Developer Portal UI server runs.
    • The address where the Developer Portal backend API runs.

    Change the sample values as you need.

  • Specify your Moesif Application ID, Moesif Management Token, and Moesif’s monetization data model version in my-dev-portal-api/.env:

      MOESIF_APPLICATION_ID=
  MOESIF_MANAGEMENT_TOKEN=
  # Only change to V1 if you're using an old version of Moesif monetization data model.
  MOESIF_MONETIZATION_VERSION="V2"

Start the Servers

Then start the servers:

  1. Go to my-dev-portal/ and run node app.js.
  2. Go to my-dev-portal-api/ and run npm start.

After the frontend server starts, it automatically opens in the browser. Based on the configuration so far, you can also manually open your browser at 127.0.0.1.4001.

Go to the API Keys page and select Create Key. Copy the key and send a request to your REST API with the HTTP request header you’ve configured in API Gateway containing the JWT:

curl -X GET -H "Authorization: JWT_KEY" https://ABCDEFGXYZ.execute-api.ap-southeast-2.amazonaws.com/dev

You should get the same valid response back from the API. But without the Authorization header, the API responds with a 401 Unauthorized status code.

Troubleshoot

For a general troubleshooting guide that can help you solve common problems, see Server Troubleshooting Guide.

Other troubleshooting supports:

Next Steps

Updated: