Build and Secure a GraphQL Server with Node.js

TL;DR: Since its public release in 2015, GraphQL has grown from a new technology into a mature API specification, which is used by both small and big tech companies worldwide. Using a type system, it lets you query and mutate data using a simple and understandable format.

Although many articles online demonstrate how to create a GraphQL server with Node.js, how to handle authentication and authorization is often neglected. This post will show how to build a GraphQL server and consequently secure it using Auth0.

Prerequisites

Before you continue reading this tutorial, you'll need to make sure that you've Node.js and npm installed on your machine. If you don't have these installed yet, you can find the installation instructions here.

You will, of course, need to have some prior knowledge of JavaScript. Also, you will need an Auth0 authorization server to implement real-world authentication and authorization. As such, I invite you to sign up for a free Auth0 account here.

What is GraphQL?

In this tutorial, you'll build a GraphQL server with Node.js that uses Auth0 to handle authentication and authorization. But to build this server, you need to learn more about what GraphQL is and how it works. If you're already familiar with GraphQL and its principles, you can immediately proceed to the next section of this tutorial.

GraphQL can best be described as a query language for APIs that works with the principle "Ask for what you need, get exactly that." With GraphQL, you can send so-called documents containing operations (either queries, mutations, or subscriptions) to a GraphQL server, and the response of the server will follow the same structure of those documents. These three types of operations all use the GraphQL query language to return the same predictable format. Also, all operations are sent to the same endpoint no matter what data you're trying to query or mutate.

An example of such a document containing a

query

query {
  person(id: 12) {
    name
    age
  }
}

This query is for retrieving a person with the

id

{
  "data": {
    "person": {
      "name": "John Doe",
      "age": 43
    }
  }
}

Different than with REST APIs, this means the users are in control of the data response as they determine its format with their GraphQL document and not the API itself. How to structure those documents is found in the schema of the GraphQL API that receives and handles them. A schema is structured with types and defines what the returned data look like and which operations can be sent — as can be seen in the example schema for the previous document:

type Person {
  id: ID
  name: String
  age: Int
}
type Query {
  person(id: Int): Person
}

According to this schema, you can send a query to retrieve a person with the identifier

id

Person

Person

name

age

Person

String

As mentioned before, your documents are sent to just one (often called)

/graphql

Building a GraphQL Server with Node.js

In this section, you'll build a basic GraphQL server with Node.js, that uses data from a mock MongoDB instance. How to secure that server isn't handled until the next section, where you'll use JWTs and Auth0 to authenticate and authorize users and the requests they send.

Creating a GraphQL server with Express

With Express, you can easily create a fresh Node.js server with limited code, that is performant enough to serve as a GraphQL server. Before you can create the Express server, you'll need to create a new project on your machine. Start by creating a new directory from your terminal by running:

mkdir auth0-graphql-server

Afterward, move into this directory and initiate a new project using npm with the following commands:

cd auth0-graphql-server
npm init -y

This last command will create the new project in the directory

auth0-graphql-server

package.json

You can also execute the command

npm init

without the

-y

flag, which requires you to answer several questions to set up the project, such as name, author, etc.

Now that you’ve created the initial project, the packages for building the GraphQL server can be installed:

npm install express express-graphql graphql

These packages are

express

graphql

express-graphql

The actual code that runs the GraphQL server must be added in a new file in this project, which you can create in a new directory called

src

mkdir src
touch src/index.js

And subsequently, copy and paste the following code into this file:

// src/index.js

const express = require("express");
const graphqlHTTP = require("express-graphql");
const { buildSchema } = require("graphql");

// Construct a schema, using GraphQL schema language
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// Provide resolver functions for your schema fields
const resolvers = {
  hello: () => "Hello world!"
};

const app = express();
app.use(
  "/graphql",
  graphqlHTTP({
    schema,
    rootValue: resolvers
  })
);
app.listen(4000);

console.log(`🚀 Server ready at http://localhost:4000/graphql`);

In this file, the packages to create the server and to use GraphQL are imported, the schema and resolvers are created, and the GraphQL server is exposed to port

4000

String

You can test this by using

node

node src/index.js

That should return the following message in your terminal, meaning you're able to send documents to the GraphQL server:

🚀 Server ready at http://localhost:4000/graphql

This is, however, not the most practical solution to run your GraphQL server, as every change to the code would require a restart of the server. Instead of using

node

nodemon

npm install --save-dev nodemon

After the installation has completed, you can add a start script to the

package.json

// package.json
{
  "name": "auth0-graphql-server",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "nodemon src/index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.17.1",
    "express-graphql": "^0.9.0",
    "graphql": "^14.5.8"
  },
  "devDependencies": {
    "nodemon": "^1.19.4"
  }
}

Before running this start script, you need to stop the server from your terminal and then you can just run

npm start

curl -X POST -H "Content-Type: application/json" \
--data '{ "query": "{ hello }" }' \
http://localhost:4000/graphql

You've now sent your very first GraphQL query to the server, which returned a "Hello world!" string. In the next part of this section, you'll add a more and advanced schema to this server.

Construct a GraphQL schema

With the basics for the GraphQL server in order, you can now set up the actual schema that you want to use for the server. There are many approaches to define the structure of your schema, one of them being schema-first. With the schema-first approach, your schema is defined manually in the GraphQL server first, before the resolvers are connected to this schema.

As mentioned, there are multiple approaches to define the structure of your schema, and all have advantages and disadvantages. For this tutorial, the schema-first approach provides the most benefits, as the data for the schema is completely mocked, and the project is created from scratch. For a deeper understanding of these approaches, have a look at the article The Problems of "Schema-First" GraphQL Server Development by Nikolas Burk from Prisma.

The GraphQL server you'll create in this article will show and mutate a list of events and its attendees. In the introduction of this tutorial, the type

Person

src

schema.js

buildSchema

graphql

To create this new file, you need to run the following from the terminal:

touch src/schema.js

Afterward, copy the following code into the

schema.js

// src/schema.js

const { buildSchema } = require("graphql");

// Construct a schema, using GraphQL schema language
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

module.exports = schema;

In the file

src/index.js

src/schema.js

buildSchema

// src/index.js

const express = require('express');
const graphqlHTTP = require('express-graphql');
const schema = require('./schema');

// Provide resolver functions for your schema fields
const resolvers = {

...

As the GraphQL server should return information about events and the people attending these events, the schema can be altered like this in the file

src/schema.js

// src/schema.js

const { buildSchema } = require("graphql");

// Construct a schema, using GraphQL schema language
const schema = buildSchema(`
  type Event {
    id: ID!
    title: String!
    description: String
    date: String
    attendants: [Person!]
  }

  type Person {
    id: ID!
    name: String!
    age: Int
  }

  type Query {
    events: [Event!]!
    event(id: Int!): Event!
  }
`);

module.exports = schema;

The schema now consists of two queries that will either return an array of events or a specific event based on the argument

id

title: String!

title

attendants: [Person!]

Person

When you try and send a document with either of the two queries to the GraphQL server, you'll receive an error, as the resolvers aren't returning data in the structure of the schema yet. This will be added in the next part of this section, where a mock MongoDB instance is used to fill the server with data.

Connect the resolvers

Your resolvers are the functions that will gather all the data that you request in your documents, but they are indifferent to the data source. For this tutorial, you'll use a mock MongoDB instance to generate the data for your resolvers and thereby make it possible to send the operations from your schema to the server. If you're not familiar with MongoDB, then what you need to know is that it's a NoSQL database based on documents. These documents are formatted with JSON and, therefore, easy to read and also easy to query with JavaScript.

Creating a mock MongoDB instance can be done with the package

mongodb-memory-server

npm install mongodb-memory-server mongodb

After adding these packages you need to create a new file in your project that will set up the mock database, you can call this file

database.js

src

touch src/database.js

In this file, the code block below must be placed, which has all the code you need to create the MongoDB instance:

// src/database.js

const { MongoMemoryServer } = require("mongodb-memory-server");
const { MongoClient } = require("mongodb");

let database = null;

async function startDatabase() {
  const mongo = new MongoMemoryServer();
  const mongoDBURL = await mongo.getConnectionString();
  const connection = await MongoClient.connect(mongoDBURL, {
    useNewUrlParser: true
  });

  if (!database) {
    database = connection.db();
    await database.collection("events").insertMany([
      {
        id: 1,
        title: "GraphQL Introduction Night",
        description: "Introductionary night to GraphQL",
        date: "2019-11-06T17:34:25+00:00",
        attendants: [
          {
            id: 1,
            name: "Peter",
            age: 34
          },
          {
            id: 2,
            name: "Kassandra",
            age: 23
          }
        ]
      },
      {
        id: 2,
        title: "GraphQL Introduction Night #2",
        description: "Introductionary night to GraphQL",
        date: "2019-11-06T17:34:25+00:00",
        attendants: [
          {
            id: 3,
            name: "Kim",
            age: null
          }
        ]
      }
    ]);
  }

  return database;
}

module.exports = startDatabase;

As you can see in the block of code above, you use the function

startDatabase

This

startDatabase

Connecting your GraphQL server with a data source is often done by using the context function that is available from the resolvers. The context holds important contextual data like database access or user information and is created by the GraphQL server during setup.

In your project, you can add the context and connect with the database by making these changes to the file

src/index.js

// src/index.js

const express = require('express');
const graphqlHTTP = require('express-graphql');
const schema = require('./schema');
const startDatabase = require('./database');

// Create a context for holding contextual data
const context = async () => {
  const db = await startDatabase();

  return { db };
};

...

const app = express();
app.use(
  '/graphql',
  graphqlHTTP({
    schema,
    rootValue: resolvers,
    context,
  }),
);
app.listen(4000);

console.log(`🚀 Server ready at http://localhost:4000/graphql`);

You import the

database

context

context

graphqlHTTP

With these additions, the resolvers are now able to access the context function so they can thereby retrieve data from the mock database. To make this possible, you need to use the object

db

src/index.js

// src/index.js

...

// Provide resolver functions for your schema fields
const resolvers = {
  events: async (_, context) => {
    const { db } = await context();
    return db
      .collection('events')
      .find()
      .toArray();
  },
  event: async ({ id }, context) => {
    const { db } = await context();
    return db.collection('events').findOne({ id });
  },
};

...

Your resolvers are now using the

db

events

id

In the next section, you'll test if these queries are working as expected by using the GraphQL Playground interface instead of a cUrl request from your terminal.

Query a GraphQL server

As your resolvers are now connected to the mock MongoDB instance, you should be able to send queries to the GraphQL server. Instead of using the terminal to send documents to the GraphQL server, you can also install a more visual interface to help you do this. Out-of-box

express-graphql

graphql-playground-middleware-express

npm install graphql-playground-middleware-express

When the installation process has finished, this interface can be added to the setup by adding the following to the file

src/index.js

// src/index.js
const express = require('express');
const graphqlHTTP = require('express-graphql');
const schema = require('./schema');
const startDatabase = require('./database');
const expressPlayground =
    require('graphql-playground-middleware-express').default;

...

const app = express();
app.use(
  '/graphql',
  graphqlHTTP({
    schema,
    rootValue: resolvers,
    context,
  }),
);
app.get('/playground', expressPlayground({ endpoint: '/graphql' }));
app.listen(4000);

console.log(`🚀 Server ready at http://localhost:4000/graphql`);

You import the default export of the

graphql-playground-middleware-express

GET /playground

If you visit the URL

http://localhost:4000/playground

If this page isn't available, ensure that your GraphQL server is still running by checking the terminal. As you might remember, the command to start the server is

npm start

.

To test if the data is successfully retrieved from your mock database, you can send the document below to your GraphQL server using the Playground by copy-pasting this in the left side of the page and then clicking on the circular "play" button:

query {
  events {
    title
    date
    attendants {
      name
    }
  }
}

This should return the following data that will contain the information from the database about the events, and in the same structure as you've defined in your query:

{
  "data": {
    "events": [
      {
        "title": "GraphQL Introduction Night",
        "date": "2019-11-06T17:34:25+00:00",
        "attendants": [
          {
            "name": "Peter"
          },
          {
            "name": "Kassandra"
          }
        ]
      },
      {
        "title": "GraphQL Introduction Night #2",
        "date": "2019-11-06T17:34:25+00:00",
        "attendants": [
          {
            "name": "Kim"
          }
        ]
      }
    ]
  }
}

You can play around with this query and delete or add fields however you please, as that's the great advantage of the flexible structure of GraphQL. To retrieve information about a single event, you can send the following document that contains the query to retrieve the event and its data. Of course, you can add whatever fields you like, as long as they're mentioned in the schema.

query {
  event(id: 1) {
    title
    date
    attendants {
      name
    }
  }
}

The output of the query above can be again seen in the GraphiQL interface, and from the query, you can already predict what structure the result will follow. Besides sending queries, you probably also want to mutate data in your database, which will be demonstrated in the next section.

Mutating data with GraphQL

In this section, you'll also make it possible to send mutations to the server that lets you change the details of an event like the title and description. Mutations need to be added to the schema, similarly to the queries. To add the mutation to your schema, you need to make the following changes to the file

src/schema.js

// src/schema.js

const { buildSchema } = require("graphql");

// Construct a schema, using GraphQL schema language
const schema = buildSchema(`
    type Event {
        id: ID!
        title: String!
        description: String
        date: String
        attendants: [Person!]
    }

    type Person {
        id: ID!
        name: String!
        age: Int
    }

    type Query {
        events: [Event!]!
        event(id: Int!): Event!
    }

    type Mutation {
      editEvent(id: Int!, title: String!, description: String!): Event!
    }
`);

module.exports = schema;

After adding the mutation to the schema, the resolvers also need to be able to handle this mutation by adding another resolver that can edit the data in the mock database. This mutation takes the arguments

id

title

description

src/index.js

// src/index.js

...

// Provide resolver functions for your schema fields
const resolvers = {
  events: async (_, context) => {
    const { db } = await context();
    return db
      .collection('events')
      .find()
      .toArray();
  },
  event: async ({ id }, context) => {
    const { db } = await context();
    return db.collection('events').findOne({ id });
  },
 editEvent: async ({ id, title, description }, context) => {
   const { db } = await context();

   return db
     .collection('events')
     .findOneAndUpdate(
       { id },
       { $set: { title, description } },
       { returnOriginal: false },
     )
     .then(resp => resp.value);
 },
};

...

This resolver looks at the mutation

addEvent

mutation {
  editEvent(
    id: 2
    title: "Something else"
    description: "New information about this event"
  ) {
    title
    description
  }
}

The output of this mutation will be the new information for the event, as the mutation is linked to the type

Event

{
  "data": {
    "editEvent": {
      "title": "Something else",
      "description": "New information about this event"
    }
  }
}

Next to

title

description

“Learn how to test GraphQL queries using the GraphQL Playground interface instead of using cUrl requests.”

Tweet This

Securing a GraphQL Server with Auth0

So far, you've already learned how to create a GraphQL server with Node.js, and send queries to it that retrieve data from a mock MongoDB instance. Also, users can mutate an event or subscribe to one. The only thing missing here is authentication and authorization, for example, to secure the usage of mutations or limit the amount of information that's returned by a query.

Validating JWTs on the GraphQL server

The prerequisites of this tutorial stated that you need an Auth0 account to complete all the sections, which you can still get by signing up for a free Auth0 account here, if you haven't created it already.

Once you have an account, you can proceed by going to the Auth0 dashboard, where you should click on the Create API button. You'll be redirected to a new page where you can create an API that's able to issue and validate JSON Web Tokens (JWTs).

The form to create a new API requires the following information:

• Name: This name will be used to display your API in the Auth0 Dashboard, e.g., you can use something like "Auth0 GraphQL Server Tutorial".

• Identifier: An URL-like identifier for the API that you're creating, you can fill something like

  https://graphql-api

  in here. This URL will never be called by Auth0.

• Signing Algorithm: Leave this set to

  RS256

  as this is the recommended one.

After adding this information to the form, you can click the Create button. You are then taken to the "Quick Start" section of the Auth0 API you just created. In here, click on the "Node.js" tab to get an idea of the code you'll need to use in your GraphQL server to validate JWTs issued by Auth0.

There are two critical values on the Node.js code snippet that you'll need in a few moments: the values of the

audience

issuer

jwt

Leave this "Quick Start" page open and return to the project in your terminal where you'd need to run the following command:

npm install dotenv jsonwebtoken jwks-rsa

This command will install three packages:

dotenv

jsonwebtoken

jwks-rsa

First, you need to create a new file in the directory

src

validate.js

touch src/validate.js

This file will hold the code to validate the JWTs that are sent to your GraphQL server. In this file, you need to add the following code:

// src/validate.js

require("dotenv").config();
const jwt = require("jsonwebtoken");
const jwksClient = require("jwks-rsa");

const client = jwksClient({
  jwksUri: `https://${process.env.AUTH0_DOMAIN}/.well-known/jwks.json`
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, function(error, key) {
    const signingKey = key.publicKey || key.rsaPublicKey;
    callback(null, signingKey);
  });
}

async function isTokenValid(token) {
  if (token) {
    const bearerToken = token.split(" ");

    const result = new Promise((resolve, reject) => {
      jwt.verify(
        bearerToken[1],
        getKey,
        {
          audience: process.env.API_IDENTIFIER,
          issuer: `https://${process.env.AUTH0_DOMAIN}/`,
          algorithms: ["RS256"]
        },
        (error, decoded) => {
          if (error) {
            resolve({ error });
          }
          if (decoded) {
            resolve({ decoded });
          }
        }
      );
    });

    return result;
  }

  return { error: "No token provided" };
}

module.exports = isTokenValid;

The function

isTokenValid

verify

jsonwebtoken

AUTH0_DOMAIN

API_IDENTIFIER

process.env

dotenv

jwksClient

jwks-rsa

.env

If the token send to

isTokenValid

The values for these constants need to be added to a hidden file

.env

.env

touch .env

Now, place the code block below in that file:

AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
API_IDENTIFIER=YOUR_API_IDENTIFIER

The values of

YOUR_AUTH0_DOMAIN

YOUR_API_IDENTIFIER

• The value of

  AUTH0_DOMAIN

  is the value of the

  issuer

  object property from the code snippet, without the protocol,

  https://

  , the quotation marks, and the trailing slash. It follows this format

  YOUR-AUTH0-TENANT.auth0.com

  .

• The value of

  API_IDENTIFIER

  is the value of the

  audience

  object property from the code snippet, and it's the same value that you provided as an identifier to your Auth0 API earlier on. Do not include quotation marks.

If you're using git for the version control of your code, make sure that the file

.env

is listed in your

.gitignore

file. Otherwise, your local environment variables might be exposed to the world.

Your server is now able to validate JWTs, but you haven't been able to read them from the GraphQL documents yet. How to request and pass tokens to the validation function is demonstrated in the next section of this tutorial.

Requesting and passing JWT to the GraphQL Server

The validation function can validate JWTs that are created by Auth0 and there are a lot of ways to create tokens with Auth0. This tutorial won't focus on how to receive or sign a token, but if you want more information on this, have a look at the Login with Auth0 document.

From the Auth0 Dashboard, you're able to see the list of APIs that you've linked to your account. If you click on the API that you've created for this tutorial (e.g., "Auth0 GraphQL Server Tutorial"), you can find a test JWT on the tab Test, under the section labeled Response. The block with the test token has the following format:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbG...p4TkQ",
  "token_type": "Bearer"
}

To construct a JWT from this block, you need to combine the fields

access_token

token_type

Bearer eyJ0eXAiOiJKV1QiLCJhbG...p4TkQ

You can send this token with your request to the GraphQL server by including it in the

Authorization

If you open the Playground, you can see two tabs in the bottom left side of the interface, where one has the label Query Variables and the other HTTP Headers. As you might figure, the last one can be used to send headers with your GraphQL document. These headers can be added in a JSON format as seen below:

{
  "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbG...p4TkQ"
}

If you now send a new request to the GraphQL server, nothing will happen, as the token isn't received by the server just yet. Making it possible to read the token from your server will require some changes to

src/index.js

context

graphqlHTTP

context

graphqlHTTP

context

// src/index.js

...


const app = express();
app.use(
  '/graphql',
  graphqlHTTP(async (req) => ({
    schema,
    rootValue: resolvers,
    context: () => context(req)
  })),
);
app.get('/playground', expressPlayground({ endpoint: '/graphql' }));
app.listen(4000);

console.log(`🚀 Server ready at http://localhost:4000/graphql`);

With the change above, your

context

context

isTokenValid

// src/index.js
const express = require('express');
const graphqlHTTP = require('express-graphql');
const schema = require('./schema');
const startDatabase = require('./database');
const expressPlayground =
    require('graphql-playground-middleware-express').default;
const isTokenValid = require('./validate');

// Create a context for holding contextual data
const context = async req => {
  const db = await startDatabase();
  const { authorization: token } = req.headers;

  return { db, token };
};

// Provide resolver functions for your schema fields
const resolvers = {

...

Finally, you need to read the token from the context object in your resolvers. As you don't want users to change events without a valid token, the

isTokenValid

editEvent

// src/index.js

...

// Provide resolver functions for your schema fields
const resolvers = {

  ...

  editEvent: async ({ id, title, description }, context) => {
    const { db, token } = await context();

    const { error } = await isTokenValid(token);

    if (error) {
      throw new Error(error);
    }

    return db
      .collection('events')
      .findOneAndUpdate(
        { id },
        { $set: { title, description } },
        { returnOriginal: false },
      )
      .then(resp => resp.value);
  },

  ...

You can check the result of the token validator by sending the mutation for the event as you've already done before with and without the headers. If you provided the header with the test token from Auth0, you're able to execute the mutation, while failing to include a token, or including an invalid one, will return the following error:

{
  "error": {
    "errors": [
      {
        "message": "JsonWebTokenError: invalid token",
        "locations": [
          {
            "line": 2,
            "column": 3
          }
        ],
        "path": ["editEvent"]
      }
    ],
    "data": null
  }
}

The error message above will be displayed when you send an invalid token with your document. If you don't send any token at all for this mutation, the message "No token provided will be displayed."

Include the authorization header and send the following document from the playground:

mutation {
  editEvent(
    id: 2
    title: "New title"
    description: "Newer information about this event"
  ) {
    title
    description
  }
}

This time around, you should get a successful response from the server.

Just as you want users to be authenticated to edit events, you might also want users to be specifically authorized to view certain information from your queries. How to handle this for your GraphQL server will be handled in the next section.

“Learn how to handle authentication and authorization of a GraphQL server using Node.js and JWTs.”

Tweet This

Limiting responses

Some information in your queries might be private and only intended for users with a valid token, as you've already applied to the mutation

addEvent

attendants

null

Suppose you want to limit the data that's returned by the query for a list of events (let's leave out a single event for now), then you would need to send a valid token with your document to see the list of attendants. To accomplish this, you can use the same

isTokenValid

src/index.js

// src/index.js

...

// Provide resolver functions for your schema fields
const resolvers = {
  events: async (_, context) => {
    const { db, token } = await context();
    const { error } = await isTokenValid(token);
    const events = db.collection("events").find();
    return !error
      ? events.toArray()
      : events.project({ attendants: null }).toArray();
  },
  event: async ({ id }, context) => {
    const { db, token } = await context();
    const { error } = await isTokenValid(token);
    const event = await db.collection("events").findOne({ id });
    return !error ? event : { ...event, attendants: null };
  },

  ...

With this last change, the field

attendants

query {
  events {
    title
    date
    attendants {
      name
    }
  }
}

You won't get an error as a response. Instead, you'll get a response object that has an

attendants

null

attendants

null

Conclusion

In this tutorial, you've created a GraphQL server with Node.js, that uses a mock MongoDB instance for its data and Auth0 for authorization and authentication. You've learned how to set up a basic server with Express, define a GraphQL schema, and write resolvers that can collect data from a MongoDB database. Basic authentication is added by using validation JWTs that are issued by your Auth0 account, making it possible to secure certain queries and mutations. The full code for this tutorial can be found on Github.

You can go further with learning how to handle authorization by implementing a Role-Based Access Control in your API; however, getting a token with roles is much easier if you have a working client, which I’ll teach you how to build in an upcoming tutorial.