Directive on Janik von Rotz

Build an Apollo Graphql user authentication for your React app - part 3

Thu, 26 Sep 2019 10:31:27 +0200

This is the final post of my GraphQL Auth series. Before reading this post checkout post 1 and post 2.

As mentioned in my last post we need to polish our authentication solution. First we wanna ensure that the JWT token expires. Second, I think the isAuthenticated directive is insufficient for proper permission management on our types, queries and mutations. We need a role based solution. While the first point is simple to implement, the second is more complex and definitely requires walking through the previous posts.

Files

We will update the following files of our GraphQL server:

schema.js: Type, query, mutation and directive definitions.
context.js: Extracts claims from JWT token.
directives.js: Directive implementations.
resolvers.js: Resolve methods for schema.

Schema

Update the GraphQL schema with a role direcive.

schema.js

const { gql } = require('apollo-server-micro')

// GraphQL schema
const typeDefs = gql`
...

directive @hasRole(roles: [Role!]) on FIELD_DEFINITION

enum Role {
  ADMIN
  USER
}

...

type User {
  id: String!
  email: String!
  password: String!
  firstname: String!
  lastname: String!
  name: String
  role: Role!

  created: Date
  created_by: String!
  updated: Date
  updated_by: String!
}

type Query {
  currentUser: User @isAuthenticated
  users: [User] @hasRole(roles: [ADMIN])
}

type Mutation {
  createUser(email: String!, password: String!, firstname: String!, lastname: String!, role: Role): User @hasRole(roles: [ADMIN])
  updateUser(id: String!, email: String, password: String, firstname: String, lastname: String, role: Role): Response @hasRole(roles: [ADMIN])
  deleteUser(id: String!): Response @hasRole(roles: [ADMIN])
}
`
module.exports = typeDefs

In addition to our isAuthenticated there is now a hasRole directive. This directive accepts a list of roles and only grants user equipped with such role access or execution rights.

The User type has a new property role. It is now possible to assign a role from the Role enum to the user.

Context

In the GraphQL context the JWT token is verified and the user details are retrieved from the store.

context.js

...

  // Verify token if available
  if (token) {
    try {
      token = jwt.verify(token, process.env.JWT_SECRET)

      // Get user from database
      user = await (await usersCollection()).findOne({ email: token.email })

    } catch (error) {
      throw new AuthenticationError(
        'Authentication token is invalid, please log in.'
      )
    }
  }

  return {
    email: token ? token.email : null,
    name: token ? token.name : null,
    role: user ? user.role : null
  }
}

module.exports = context

The role attribute simply contains the user role.

Directive

This is the implementation of the hasRole directive.

directives.js

const { SchemaDirectiveVisitor, ForbiddenError } = require('apollo-server-micro')
const { defaultFieldResolver } = require('graphql')

...

// Custom directive to check if user has role
class hasRole extends SchemaDirectiveVisitor {
  // Field definition directive
  visitFieldDefinition (field) {
    // Get field resolver
    const { resolve = defaultFieldResolver } = field

    // List of roles from directive declaration
    const roles = this.args.roles

    field.resolve = async function (...args) {

      // Get context
      const [, , context] = args

      // Check if user email is in context
      if (roles.indexOf(context.role) === -1) {
        throw new ForbiddenError('You are not authorized for this ressource.')
      }

      // Resolve field
      return resolve.apply(this, args)
    }
  }
}

module.exports = { isAuthenticated: isAuthenticated, hasRole: hasRole }

It throws an error if the context role is not included in the directive roles arguments.

Resolver

By default new users should get the role USER.

resolvers.js

...
    createUser: async (obj, args, context) => {
      // Check if user already exists
      const user = prepare(await (await usersCollection()).findOne({ email: args.email }))
      if (user) {
        throw new ForbiddenError('User already exists.')
      }

      // Default value
      args.role = args.role ? args.role : 'USER'

      // Hash password
      args.password = await bcrypt.hash(args.password, BCRYPT_ROUNDS)
      args.created = new Date()
      args.created_by = context.name || 'system'
      return prepare((await (await usersCollection()).insertOne(args)).ops[0])
    },
...

That’s it! You now have role based authorization for your GraphQL resources.

Before we reach the conclusion of this post series, we wanna ensure that the JWT token expires after week.

resolvers.js

...
    loginUser: async (obj, args, context) => {
      // Find user by email and password
      const user = prepare(await (await collection('users')).findOne({ email: args.email }))

      // Compare hash
      if (user && await bcrypt.compare(args.password, user.password)) {
        // Generate and return JWT token
        const token = jwt.sign({ email: user.email, name: (user.firstname + ' ' + user.lastname) }, process.env.JWT_SECRET, { expiresIn: '7d' })
        return { token: token }
      } else {
        // Throw authentication error
        throw new AuthenticationError('Login failed.')
      }
    }
...

Adding the expiresIn: '7d' option to the sign method ensures that the verify method will throw an error if the token has expired.

Conclusion

In this post series we covered the basic of authentication with GraphQL and a React App. The solutions provided here are supposed to give you a basic idea and a far from production ready. Having type definitions and access control in the same place is very convenient. That is what like most about GraphQL. Having this flexible layer that unifies access control, api access and schema definitions.

I hope I was able to give you an idea and would be glad if you share your thoughts and question with me 😊.

Addition

Some final hints on what should be considered when developing an authentication solution like this.

JWT referesh token > Auth0 - Refresh Tokens: When to Use Them and How They Interact with JWTs
Token for identity only > iana - JSON Web Token Claims

Build an Apollo Graphql user authentication for your React app - part 2

Thu, 29 Aug 2019 19:34:07 +0200

In my last post we built a Graphql API that handles user authentication and authorization. In particular we added a loginUser query that returns a JWT token. This token can be used to access restricted resources. In this post I will show what the implementation looks like on Reacts side.

Walking through this guide requires basic React knowledge. We will use React Router for routing, React Hooks for executing Graphql queries and Matieral-UI for the component framework.

Files

Let’s get started with an overview of the project files.

Apollo.js: Apollo client configuration
HeaderLoginButton.js: Links to login page and handles logout
Login.js: Login page
Profile.js: View for user profile
queries.js: Exports all Graphql queries and mutations
Routes.js: React router component
hooks.js: Export React hooks

2019-09-18 Edit: Added React hook file

So obviously we are not going to build an React app from scratch. This guide assumes you already have one and intent to add authentication and authorization functionality.

Routes

Routes is a higher-order component (HOC) that connect our view components with specific routes.

Routes.js

import React from 'react'
import { Route } from 'react-router-dom'
import Home from './Home'
import Login from './Login'
import Profile from './Profile'

const Routes = () => (
  <>
    <Route exact path='/' component={Home} />
    <Route exact path='/login' component={Login} />
    <Route exact path='/profile' component={Profile} />
  </>
)

export default Routes

So if the user opens or gets redirected to /login the Login component will be shown.

So what does the Login component looks like?

Login.js

import React from 'react'
import { useLazyQuery } from '@apollo/react-hooks'
import { Redirect } from 'react-router'
import Paper from '@material-ui/core/Paper'
import Typography from '@material-ui/core/Typography'
import TextField from '@material-ui/core/TextField'
import Button from '@material-ui/core/Button'
import { LOGIN_USER } from './queries'
import Loading from './Loading'
import Error from './Error'
import { useForm } from './hooks'

const Login = () => {

  // Use form state
  const { values, handleChange, handleSubmit } = useForm((credentials) => loginUser(), {
    email: '',
    password: ''
  })

  // Lazy query for login user method
  const [loginUser, { called, loading, data, error }] = useLazyQuery(LOGIN_USER, { variables: values })

  // Wait for lazy query
  if (called && loading) return <Loading />

  // Show error message if lazy query fails
  if (error) return <Error message={error.message} />

  // Store token if login is successful
  if (data) {
    window.localStorage.setItem('token', data.loginUser.token)

    // Redirect to home page
    return <Redirect to='/' />
  }

  return (
    <Paper className={classes.paper}>
      <Typography className={classes.title} variant='h3' component='h1'>
        Login
      </Typography>
      <form onSubmit={handleSubmit}
      >
        <TextField
          variant='outlined'
          margin='normal'
          required
          fullWidth
          id='email'
          name='email'
          label='Email Address'
          type='email'
          value={values.email}
          onChange={handleChange}
          autoFocus
        />
        <TextField
          variant='outlined'
          margin='normal'
          required
          fullWidth
          id='password'
          name='password'
          label='Password'
          type='password'
          value={values.password}
          onChange={handleChange}
        />
        <Button
          type='submit'
          fullWidth
          variant='contained'
          color='primary'
          className={classes.submit}
        >
          Sign in
        </Button>
      </form>
    </Paper>
  )
}

export default Login

The component presents a login form. When credentials are submitted a React hook is used to run the lazy Graphql query and retrieve the JWT token. If the login is successful the token is stored in the local storage of the browser.

The form state is managed by a React hook as well. See the hooks.js for the simple useForm React hook example that can be reused for other form.

As you can see the query is imported from the queries.js file. This is externalized because we want to share queries among component.

queries.js

import gql from 'graphql-tag'

const GET_CURRENT_USER = gql`
{
    currentUser {
        firstname
        lastname
    }
}
`

const LOGIN_USER = gql`
query loginUser($email: String!, $password: String!) {
    loginUser(email: $email, password: $password) {
        token
    }
}
`

export {
  GET_CURRENT_USER,
  LOGIN_USER
}

And here is the useForm React hook.

hooks.js

import { useState } from 'react'

const useForm = (callback, data) => {
  const [values, setValues] = useState(data)

  const handleChange = (event) => {
    event.persist()
    setValues(values => ({
      ...values,
      [event.target.name]: event.target.value
    }))
  }

  const handleSubmit = (event, onSubmit) => {
    event.preventDefault()
    callback(values)
  }

  return {
    handleChange,
    handleSubmit,
    values
  }
}

export { useForm }

2019-09-18 Edit: Added useForm React hook

Apollo

We saw that the token is being stored in the local storage. But how is passed to Apollo server? This is done in the Apollo client.

Apollo.js

import ApolloClient from 'apollo-boost'
import React from 'react'
import PropTypes from 'prop-types'
import { ApolloProvider } from '@apollo/react-hooks'

// Initialize Apollo client
const client = new ApolloClient({
  uri: process.env.REACT_APP_APOLLO_URL || 'http://localhost:3000/api',
  request: async operation => {
    // Get JWT token from local storage
    const token = window.localStorage.getItem('token')

    // Pass token to headers
    operation.setContext({
      headers: {
        Authorization: token ? `Bearer ${token}` : ''
      }
    })
  }
})

// Define Apollo component
const Apollo = ({ children }) => (
  <ApolloProvider client={client}>
    {children}
  </ApolloProvider>
)

Apollo.propTypes = {
  children: PropTypes.object.isRequired
}

export default Apollo

This HOC initializes the Apollo client and connects to the API. For every request it check if a token is available and if so forwards it in the Bearer Authorization header.

Logout

Assuming the user has logged in, we can run queries that requires authorization from every other component.

Profile.js

import React from 'react'
import { useQuery } from '@apollo/react-hooks'
import Paper from '@material-ui/core/Paper'
import Typography from '@material-ui/core/Typography'
import { GET_CURRENT_USER } from './queries'
import Loading from './Loading'
import Error from './Error'

const Profile = () => {

  const { loading, error, data } = useQuery(GET_CURRENT_USER)

  if (loading) return <Loading />
  if (error) return <Error message={error.message} />

  return (
    <Paper>
      <Typography variant='h3' component='h1'>
            Profil
      </Typography>
      <Typography component='p'>
        {`${data.currentUser.firstname} ${data.currentUser.lastname}`}
      </Typography>
    </Paper>
  )
}

export default Profile

The getCurrentUser query requires an authentication. Data is only shown if the user has logged in.

Now we got to the final step. Usually you’ll find a login/logout button on the top right of the nav bar. This button is called HeaderLoginButton in our case and handles the logout.

HeaderLoginButton.js

import React from 'react'
import { useQuery } from '@apollo/react-hooks'
import { Link } from 'react-router-dom'
import Button from '@material-ui/core/Button'
import { GET_CURRENT_USER } from './queries'

const HeaderLoginButton = () => {

  const { client, data } = useQuery(GET_CURRENT_USER)

  // Reset Apollo and local store on logout
  const logout = () => {
    window.localStorage.clear()
    client.resetStore()
  }

  if (data && data.currentUser) {
    return (
      <Button onClick={logout} color='inherit'>Logout</Button>
    )
  }
  return (
    <Link to='/login'>
      <Button color='inherit'>Login</Button>
    </Link>
  )
}

export default HeaderLoginButton

If the user is not logged in the button if clicked will redirect to the login page. Once the user has logged in the button will logout the user if clicked. The logout process simply gets rid of the token in the local storage and resets the Apollo client.

Here you can also observe the power React hooks. We don’t have to pass the Apollo client object down the hierarchy. Simply retrieve it from the useQuery hook!

That’s it! 🎉

In the next and final post we are going to improve our solution regarding security. Cliff hanger questions: What if the user copies the token and paste it after logout? How can we ensure that a token cannot be used indefinitely 😕?

Navigate to part 1 or part 3.

Additions

As already mentioned in my last post I focus on the modifications you have to make to the app in order get a user authentication. Proper implementation of course requires various other features. So here are some I can think of:

Password reset component
User profile page
Proper error and success notification
Redirect to error page if user is unauthorized
User signup process

Edits

2019-09-18: Added useForm React hook.

Build an Apollo Graphql user authentication for your React app - part 1

Tue, 27 Aug 2019 18:35:12 +0200

I am currently building an Apollo Graphql API and a React web application. The application requires a user authentication functionality in order to enforce access restrictions on the Graphql endpoint. Apollo Graphql does not provide an out-of-the-box-solution and therefore I would like to present my solution.

This post requires some basic knowledge about building APIs with Apollo and later on combining the Apollo Client with React. First we are going to define the user schema and implement the resolvers. For the authentication mechanism we are going to implement a query that expects user credentials and returns a JSON Web Token as response. This token will be used by the React app and passed as an Bearer Authorization header to every sequentially API call. The Apollo server verifies the token and restricts access on certain calls if an invalid token has been provided. The access restriction is enforced on schema field level using a custom directive.

Files

My Apollo server implementation consists of the following files:

index.js: Creates the Apollo server
schema.js: Contains Graphql type definitions
resolvers.js: Schema resolvers for data transformation and persistence
context.js: Verifies the JWT token
directives.js: Custom directives for the schema

Note: This guide does not cover how user data is stored and retrieved. Comments in the code snippets will point out where to implement these functionalities. In short this guide can be read regardless of the storage solution.

Schema

Let us start with the type definitions. I have split the schema.js file into several parts.

schema.js

const { gql } = require('apollo-server-micro')

// GraphQL schema
const typeDefs = gql`

directive @isAuthenticated on FIELD_DEFINITION

scalar Date

The Date scalar is custom type, ignore it for now. The isAuthenticated directive will be discussed later.

Next follows the user type.

type User {
  id: String!
  email: String!
  password: String!
  firstname: String!
  lastname: String!

  created: Date
  created_by: String!
  updated: Date
  updated_by: String!
}

Then the token and default response.

type Token {
  token: String!
}

type Response {
  success: Boolean!
  message: String
}

Queries are restricted by the custom directive.

type Query {
  currentUser: User @isAuthenticated
  users: [User] @isAuthenticated
  loginUser(email: String!, password: String!): Token
}

And here are the mutation we need to actually create and manipulate a user.

type Mutation {
  createUser(email: String!, password: String!, firstname: String!, lastname: String!): User
  updateUser(id: String!, email: String, password: String, firstname: String, lastname: String): Response
  deleteUser(id: String!): Response
}
`

module.exports = typeDefs

Put everything together and you got the schema definitions.

Resolvers

In the resolvers file we map schema types and fields with functions that return the actual data. You can think of it as actually implementing the schema.

resolvers.js

const { GraphQLScalarType } = require('graphql')
const { AuthenticationError, ForbiddenError } = require('apollo-server-micro')
const bcrypt = require('bcrypt')
const jwt = require('jsonwebtoken')
const { Kind } = require('graphql/language')

// Hash configuration
const BCRYPT_ROUNDS = 12

// Resolve GraphQL queries, mutations and graph paths
const resolvers = {
  Query: {
    users: async (obj, args, context) => {
      const user // -> Access data layer and get user data
      return user
    },
    currentUser: async (obj, args, context) => {
      const user // -> Access data layer and get user data
      return user
    },
    loginUser: async (obj, args, context) => {
      // Find user by email and password
      const user // -> Access data layer and get user data

      // Compare hash
      if(user && await bcrypt.compare(args.password, user.password)) {
        // Generate and return JWT token
        const token = jwt.sign({ email: user.email, name: (user.firstname + ' ' + user.lastname) }, process.env.JWT_SECRET )
        return { token: token }
      } else {
        // Throw authentication error
        throw new AuthenticationError('Login failed.')
      }
    }
  },
  Mutation: {
    createUser: async (obj, args, context) => {
      // Check if user already exists
      const user // -> Access data layer and get user data
      if (user) {
        throw new ForbiddenError('User already exists.')
      }

      // Hash password
      args.password = await bcrypt.hash(args.password, BCRYPT_ROUNDS)
      args.created = new Date()
      args.created_by = context.name || "system"
      const user // -> Access data layer and store user data
      return user
    },
    updateUser: async (obj, args, context) => {
      args.updated = new Date()
      args.updated_by = context.name || "system"

      // Hash password if provided
      if(args.password){
        args.password = await bcrypt.hash(args.password, BCRYPT_ROUNDS)
      }

      // -> Access data layer and update user data
      return { 
        success: true
      }
    },
    deleteUser: async (obj, args, context) => {
      // -> Access data layer and delete user data
      return { 
        success: true
      }
    }
  },
  User: {
    // Hide password hash
    password() {
      return ''
    }
  }
}

module.exports = resolvers

The most important part of the resolver files are the bcrypt and jwt method calls. If a user is created the plaintext password is hashed and stored in the database. If the loginUser query is called the user is retrieved and the password hash compared. If successful a JWT token is generated and returned.

Context

We assume that during the login process in the client app the Apollo client calls the loginUser query, retrieves token and stores it in the local storage. If set the token is passed in the Bearer Authentication header with each API call. On the Apollo server side the token must be verified and its claims added to the Apollo context.

So what is the context? To put it simply the context is an object that is available to all resolvers. From the context user claims can be accessed and e.g. passed to a database query.

context.js

const { AuthenticationError } = require('apollo-server-micro')
const jwt = require('jsonwebtoken')

const context = ({ req }) => {
  // Get the user token from the headers
  let token = req.headers.authorization ? req.headers.authorization.split(' ')[1] : null

  // Verify token if available
  if (token) {
    try {
      token = jwt.verify(token, process.env.JWT_SECRET)
    } catch (error) {
      throw new AuthenticationError(
        'Authentication token is invalid, please log in.'
      )
    }
  }

  return {
    email: token ? token.email : null,
    name: token ? token.name : null
  }
}

module.exports = context

If the token is set in the header and has been verified, the two claims email and name are then added to the context.

Directive

As I mentioned we enforce schema field access with a custom directive. In the isAuthenticated directive we simply check if the email property is set in the context object.

const { SchemaDirectiveVisitor, ForbiddenError } = require('apollo-server-micro')
const { defaultFieldResolver } = require('graphql')

// Custom directive to check if user is authenicated
class isAuthenticated extends SchemaDirectiveVisitor {
  // Field definition directive
  visitFieldDefinition (field) {
    // Get field resolver
    const { resolve = defaultFieldResolver } = field

    field.resolve = async function (...args) {
      // Check if user email is in context
      if (!args[2].email) {
        throw new ForbiddenError('You are not authorized for this ressource.')
      }

      // Resolve field
      return resolve.apply(this, args)
    }
  }
}

module.exports = { isAuthenticated: isAuthenticated }

Whenever a field declared with the isAuthenticated directive is queried, the directive will also ensure the user has a valid token.

Server

In the index.js we stitch everything together.

const { ApolloServer } = require('apollo-server-micro')
const cors = require('micro-cors')()
const typeDefs = require('./schema')
const resolvers = require('./resolvers')
const context = require('./context')
const directives = require('./directives')

// Initialize Apollo server
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: context,
  introspection: true,
  playground: true,
  schemaDirectives: directives
})

// Export server as handler
module.exports = cors((req, res) => {
  // Workaround abort on Options method
  if (req.method === 'OPTIONS') {
    res.end()
    return
  }
  return server.createHandler({ path: '/api' })(req, res)
})

To those who noticed that I import apollo-server-micro instead of apollo-server, it is because I am deploying my apps as serverless functions with Zeit Now using their HTTP microservice.

Test

Start the Apollo server and open the Graphql playground.

Create a user with the createUser mutation.

mutation { 
  createUser(
    email: "login@example.com",
    password: "password",
    firstname: "Login",
    lastname: "Example"
  ) { id } }

{ loginUser(email: "login@example.org", password: "password") {
  token
} }

Copy the token in to the HTTP header field.

{
    "Authorization": "Bearer YOUR_TOKEN_HERE"
}

Query the user info.

{ currentUser {
  firstname
  lastname
  email
  password
  id
} }

What the final query should look like:

If this worked you have reached the end of part 1 😊.

In part 2 I will show how we implement the user authentication mechanism in a React app.

Additions

I try to keep my guides as slick as possible and therefore intentionally do not cover certain parts. But at least I wanna let know you which parts I ignored.

In order to provide a full user accounting module of course more queries are required. You would at least have to implement the following ones:

signupUser: Public query to create user account.
verifyUserEmail: Query to verify user account.
resetUserPassword: Query to initiate password reset.

If you have any questions, feel free to ask below 👋.

Updates

2019/08/30: Updated all code snippets after applying JavaScript Standard Style guide. Removed unnecessary await statements.