GraphQL Authentication with Apollo and React

Written by Pete Corey on May 15, 2017.

Continuing on from last week, we have our authentication and authorization workflow ironed out in our Elixir/Absinthe powered back-end. Fantastic!

But what about the front-end?

How do we get our auth_token (or authToken, once it’s passed through Apollo) from the server? How do we manage active user sessions on the client? How do we ensure our authToken is passed up with each request? How do we handle authentication failures?

More great questions! Let’s dive in and set up client-side authentication in our React/Apollo-powered front-end.

Getting Our Authentication Token

In order to have an authToken to authenticate our GraphQL requests, we first need to get one from the server.

An authToken can be returned by any publicly accessible GraphQL mutation, such as a signIn mutation, or in my case, a verifyRequestedToken mutation.

Assuming we’re in an Apollo-wrapped React component with a mutation function called verifyRequestedToken, we can call it to retrieve our authToken:


this.props.verifyRequestedToken(token)
    .then(({ data: { verifyRequestedToken: { authToken } } }) => {
        localStorage.setItem("authToken", authToken);
    })

Once we retrieve the token from the verifyRequestedToken mutation, we’ll store it in localStorage for later use.

Attaching Our Authentication Token

Now that we have our hands on an authToken, we can send it up with each GraphQL request made from the client.

But how do we do this?

Apollo middleware gives us an easily accessible hook into all requests made against our GraphQL server. Let’s add a middleware function to our network interface that attaches our token:


networkInterface.use([{
    applyMiddleware(req, next) {
        let authToken = localStorage.getItem("authToken");
        if (authToken) {
            req.options.headers = _.extend(req.options.headers, {
                authorization: `Bearer ${authToken}`
            });
        }
        next();
    }
}]);

This middleware function checks to see if an authToken is stored in localStorage. If it is, it’s added as a bearer token to the authorization header of our GraphQL request.

Otherwise, if no authToken is found in localStorage, no authorization header is set.

Remember, if no authorization header is provided, our Absinthe server will let the unauthorized user access publicly available mutations and queries. An invalid authToken will result in an authorization error at the HTTP level.

Handling HTTP Authentication Errors

If an invalid authCode is passed up to the server, the server will return a 403 authorization error. This error is returned at the HTTP level, not as a GraphQL error.

We can add another layer of middleware, or “afterware”, to our network interface in order to catch these 403 errors as they come back from the server:


networkInterface.useAfter([{
    applyAfterware({ response }, next) {
        if (response.status === 403) {
            localStorage.removeItem("authToken");
        }
        next();
    }
}]);

In the afterware function, we check each response for a 403 status. If we encounter a 403 response, we clear the current authToken from localStorage, effectively signing out the current user.

When using Apollo in this way, clearing the authToken from localStorage signs the user our for subsequent requests, but the currently signed in user object is still floating around in the client’s data store.

In Inject Detect, I’m flushing this user out of the client’s data store by manually querying for the current user (user) after removing authToken from localStorage:


client.query({
    query: gql`
        query {
            user {
                id
            }
        }
    `,
     fetchPolicy: "network-only"
});

Specifying a fetchPolicy of "network-only" forces the Apollo client to fetch the current user from the server, rather than returning the user cached on the client.

Because this query is made without an authToken, no user is returned from the server. The user in the client’s store is cleared out, and any components relying on this query result are re-rendered.

Full disclosure - there are probably better ways to update the store in this situation. If you have any suggestions, or are doing something similar, please let me know!

Handling GraphQL Authentication Errors

You may remember that on top of throwing HTTP authentication errors, our GraphQL resolvers will also throw authorization errors if the current user doesn’t have permission to access a given query or mutation.

These errors will be handled inline, at the source of the query or mutation, just like any other GraphQL error.

Let’s run through an example.

Going off of our examples from last week, let’s pretend that we’re accidentally showing the “Sign out” button to unauthenticated users. Clicking the sign out button triggers a signOut mutation:


this.props.signOut()
    .then(() => localStorage.removeItem("jwt"))
    ...

If we try to call this mutation as an unauthenticated user, the sign_out resolver will throw a GraphQL error down to the client. We’ll need to catch this, parse the resulting graphQLErrors, and show the errors to the user in some meaningful way:


this.props.signOut()
    .then(() => localStorage.removeItem("jwt"))
    ...
    .catch((err) => {
        let errors = _.isEmpty(err.graphQLErrors)
                   ? ["Unexpected error."]
                   : _.map(err.graphQLErrors, "message");
        this.setState({ errors });
    });

Any resulting errors can be rendered by the component in a way that makes sense in the context of the application.

Final Thoughts

With that’s we’ve set up a full-stack authentication system using React, Apollo, Absinthe, and Elixir!

While all of the moving pieces can feel daunting at first glance, breaking the problem into its piece components leads us to a relatively simple solution. All we needed to build a basic Apollo-powered session management system on the client was two middleware functions and some basic error handling.

Not bad for a day’s work.

GraphQL Authentication with Elixir and Absinthe

Written by Pete Corey on May 8, 2017.

You’ve assembled your superhero stack. Your React front-end is communicating with an Elixir/Phoenix back-end through an Apollo/Absinthe GraphQL data layer.

You feel invincible.

But that feeling of invincibility quickly turns to panic as your first real development task comes down the pipe. You need to add user authentication to your system.

How do we even do authentication in this stack?

Our application will need to handle both publicly accessible and private queries and mutations through its GraphQL API. How do we set up these queries on the server, and how do we manage users’ sessions on the client?

Great questions! Let the panic pass over you and let’s dive in.

Two Layers of Authentication

Every request made against our Absinthe-based GraphQL server is done through an HTTP request. This request layer provides a fantastic opportunity to lay the groundwork for our authentication system.

Every GraphQL request that’s made against our system will come with an optional auth_token. A valid auth_token will map to a single user in our system. This auth_token is assigned to a user when they sign in.

On each request we’ll look up the user associated with the given auth_token and attach them to the context of our GraphQL resolvers.

If we can’t find a user associated with a given auth_token, we’ll return an authorization error (403) at the HTTP level. Otherwise, if no auth_token was provided, we simply won’t set the user_id in our GraphQL context and we’ll move onto processing our query and mutation resolvers.

The key to our authentication (and authorization) system is that the currently signed in user can be pulled from the GraphQL context. This context can be accessed by all of our resolvers and can be used to make decisions about what data to return, which mutations to allow, etc…

Writing Our Context Plug

The first step of building our authentication solution is to write a piece of Plug middleware that populates our GraphQL context with the currently signed in user.

To make things more real, let’s consider the context middleware I’m using for the security-focused SaaS application I’m building (Inject Detect). The middleware is based on the middleware provided by the Absinthe guide.

With that in mind, let’s build out our Plug in a module called InjectDetect.Web.Context:


defmodule InjectDetect.Web.Context do
  @behaviour Plug

  import Plug.Conn

  def init(opts)
  def call(conn, _)

end

To start, we’ll want our plug to implement the Plug behavior, and to import Plug.Conn. Implementing the Plug behavior means that we’ll need to define an init/1 function, and a call/2 function.

The call function is the entry point into our Plug middleware. Let’s flesh it out a bit:


def call(conn, _) do
  case build_context(conn) do
    {:ok, context} ->
      put_private(conn, :absinthe, %{context: context})
    {:error, reason} ->
      conn
      |> send_resp(403, reason)
      |> halt()
    _ ->
      conn
      |> send_resp(400, "Bad Request")
      |> halt()
  end
end

Here’s the meat of our context middleware. We call out to a function called build_context which builds our GraphQL context, as the name suggests.

If build_context returns an :ok tuple, we stuff the resulting context into our conn as is expected by Absinthe.

Otherwise, we return either a 403 error or a 400 error in the case of either a bad authentication token, or any other unexpected error.

Now we need to flesh out the build_context function:


def build_context(conn) do
  with ["Bearer " <> auth_token] <- get_req_header(conn, "authorization"),
       {:ok, user_id}            <- authorize(auth_token)
  do
    {:ok, %{user_id: user_id}}
  else
    []    -> {:ok, %{}}
    error -> error
  end
end

build_context pulls the auth_token out of the authorization header of the request and passes it into an authorize function. authorize either returns an :ok tuple with the current user_id, or an :error.

If authorize returns an error, we’ll pass that back up to our call function, which returns a 403 for us.

Otherwise, if the authorization header on the request is empty, we’ll return an empty map in the place of our GraphQL context. This empty context will allow our resolvers to let unauthenticated users access public queries and mutations.

Lastly, let’s take a look at authorize:


def authorize(auth_token) do
  InjectDetect.State.User.find(auth_token: auth_token)
  |> case do
       nil  -> {:error, "Invalid authorization token"}
       user -> {:ok, user.id}
     end
end

authorize is a relatively simple function.

It takes in an auth_token, looks up the user associated with that token, and either returns that user’s id, or an :error tuple if no associated user was found.


Armed with our new InjectDetect.Web.Context Plug, we can build a new :graphql pipeline in our router:


pipeline :graphql do
  plug :fetch_session
  plug :fetch_flash
  plug InjectDetect.Web.Context
end

And pipe our /graphql endpoint through it:


scope "/graphql" do
  pipe_through :graphql
  forward "/", Absinthe.Plug, schema: InjectDetect.Schema
end

Now all GraphQL requests made against our server will run through our authentication middleware, and the currently signed in user will be available to all of our GraphQL resolvers.

Contextual Authentication and Authorization

Now that the currently signed in user can be accessed through our GraphQL context, we can start to perform authentication and authorization checks in our resolvers.

But first, let’s take a look at how we would set up a public query as a point of comparison.

A Public Query

In our application the user query must be public. It will either return the currently signed in user (if a user is signed in), or nil if the current user is unauthenticated.


field :user, :user do
  resolve &resolve_user/2
end

The user query takes no parameters, and it directly calls a function called resolve_user:


def resolve_user(_args, %{context: %{user_id: user_id}}) do
  {:ok, User.find(user_id)}
end
def resolve_user(_args, _context), do: {:ok, nil}

We use pattern matching to pull the current user_id out of our GraphQL context, and then return the user with that user_id back to our client. If our context is empty, the current user is unauthenticated, so we’ll return nil back to our client.

Great, that makes sense. The query is returning data to both authenticated and unauthenticated users. It’s completely public and accessible by anyone with access to the GraphQL API.

But what about a private queries?

A Private Query

Similarly, our application has an application query that returns an object representing a user’s application registered with Inject Detect. This query should only return a specified application if it belongs to the currently signed in user.


field :application, :application do
  arg :id, non_null(:string)
  resolve &resolve_application/2
end

Once again, our application query calls out to a resolver function called resolve_application:


def resolve_application(%{id: id}, %{context: %{user_id: user_id}}) do
  case application = Application.find(id) do
    %{user_id: ^user_id} -> {:ok, application}
    _                    -> {:error, %{code: :not_found,
                                       error: "Not found",
                                       message: "Not found"}}
  end
end

def resolve_application(_args, _context), do:
  {:error, %{code: :not_found,
             error: "Not found",
             message: "Not found"}}

In this case, we’re once again pattern matching on our GraphQL context to grab the current user_id. Next, we look up the specified application. If the user_id set on the application matches the current user’s user_id, we return the application.

Otherwise, we return a :not_found error. We’ll also return a :not_found error if no user_id is found in our GraphQL context.

By making these checks, an authenticated user can only access their own applications. Anyone else trying to query against their application will receive a :not_found authorization error.

A Private Mutation with Absinthe Middleware

Let’s take a look at another way of enforcing authentication at the query level.

We have a sign_in mutation that should only be callable by a signed in user:


field :sign_out, type: :user do
  middleware InjectDetect.Middleware.Auth
  resolve &handle_sign_out/2
end

You’ll notice that we’ve added a call to an Absinthe middleware module before the call to our &handle_sign_out/2 resolver. As you might have guessed, the InjectDetect.Middleware.Auth module is where we’re enforcing an authentication check.


defmodule InjectDetect.Middleware.Auth do
  @behavior Absinthe.Middleware

  def call(resolution = %{context: %{user_id: _}}, _config) do
    resolution
  end

  def call(resolution, _config) do
    resolution
    |> Absinthe.Resolution.put_result({:error, %{code: :not_authenticated,
                                                 error: "Not authenticated",
                                                 message: "Not authenticated"}})
  end

end

The call function is our entry-point into our middleware module. It takes an Absinthe.Resolution struct as an argument, which contains the current GraphQL context.

If the context contains a user_id, we know that the user making the request is authorized. We can return the unmodified resolution from our middleware function, which lets it continue on to the &handle_sign_out/2 resolver function.

Otherwise, if no user_id is found in the context, we use Absinthe.Resolution.put_result to modify the resolution struct before returning it from our middleware. Giving the resolution a result, in this case a :not_authenticated :error tuple, will short circuit the query or mutation’s resolution and immediately return that result to the client.

This piece of middleware effectively prevents unauthenticated users from accessing the sign_out mutation.

Beautiful.

This middleware pattern is extremely powerful. It can easily be extended to check for specific user roles or other criteria, and can be easily added to an existing query or mutation.

Additionally, multiple middleware modules or functions can be chained together to create a very readable, declarative authentication and authorization scheme around your GraphQL API.

Final Thoughts

At first, all of the moving parts related to handling authentication and authorization in a GraphQL application can be overwhelming.

Thankfully, once you wrap your head around the basic strategies and building blocks involved, the end solution easily falls into place. Authorization and authentication in a GraphQL-based system isn’t much different than in any other system.

Next week, we’ll move on to answering the second set of questions raised in the beginning of this article. How do we manage user sessions on the front-end of our application?

Stay tuned!

Inject Detect Progress Report

Written by Pete Corey on May 1, 2017.

It’s been almost two months since I announced I was working on a security focused SaaS application called Inject Detect.

For those that haven’t been following along, Inject Detect is a service designed to detect NoSQL Injection attacks against your Meteor applications. It does this by monitoring queries made against your application, looking for unexpected queries that may be the result of an injection attack.

I had lots of ideas about how I wanted to build out Inject Detect. To keep myself accountable and in an effort to iterate in public, I’ve decided to put together a progress report.

Let’s dive into how my plans have played out, where I’m at in the project, and most importantly let’s talk about when Inject Detect will be ready to use!

Front-end Progress

Since it was announced, I’ve been making steady headway on both the front-end and back-end components of Inject Detect.

The front-end of Inject Detect is being built as a React application, backed by Create React App tooling. On top of vanilla React, I’m using Apollo client to integrate with my Absinthe-powered GraphQL back-end.

So far, this combination has been a dream to work with.

The productivity gains I’ve experienced working with React and Apollo is off the charts. After climbing over a few learning curves, I’ve found myself effortlessly cranking out feature after feature.

I’m addicted to the GraphQL workflow.


The front-end of Inject Detect is still heavily under construction. I’ll be the first to say that I’m no designer. I’m using Semantic UI as the base for most of my designs and tweaking from there.

Overall, I’m very happy with the progress I’ve made so far on the front-end.

Check out a few screen shots to see where I’m at:






Since NoSQL Injection is a relatively unknown (but unbelievably common) vulnerability, I’m trying to incorporate healthy doses of education into its user interface.

I’m discovering that balancing education with brevity and clarity is a difficult thing to do.

Back-end Progress

Most of the first month of development was spent building out the back-end infrastructure and business logic to handle all of the various use cases of Inject Detect.

In my post about the high level design of Inject Detect, I talked about implementing the core domain of the application using Event Sourcing.

So far, I’m very happy with this choice.

Let’s look a little closer at some of the design decisions I’ve made, and dive into what it means to be an “Event Sourced” system.


Interactions with the system are done through “commands”. A command is just an instruction for the system to do something. Based on the current state of the system, the processing of a command will either return a list of events representing the changes to the system, or an error.

Keep in mind that events don’t actually modify the system in any way (write to a database, etc…). They just return a list of events, side-effect free.

Diving into the code, a command is just an Elixir struct. For example, here’s a command to toggle “alerting” on an application in Inject Detect:


defmodule InjectDetect.Command.ToggleAlerting do
  defstruct application_id: nil
end

The struct holds all of the information we need to carry out the command. In this case, we just need the application_id of the application in question.

Each command implements a Command protocol, which means it defines a handle function. Command.handle takes in the command struct being handled and a “context” map, which in our case holds the currently signed in user.

Our handle implementation for the ToggleAlerting command looks like this:


defimpl InjectDetect.Command, for: InjectDetect.Command.ToggleAlerting do

  alias InjectDetect.Event.TurnedOffAlerting
  alias InjectDetect.Event.TurnedOnAlerting
  alias InjectDetect.State.Application

  def toggle_alerting(application = %{user_id: user_id}, command, %{user_id: user_id}) do
    case application.alerting do
      true ->
        {:ok, [%TurnedOffAlerting{application_id: command.application_id}]}
      false ->
        {:ok, [%TurnedOnAlerting{application_id: command.application_id}]}
    end
  end

  def toggle_alerting(_, _, _) do
    {:error, %{code: :not_authorized,
               error: "Not authorized",
               message: "Not authorized"}}
  end

  def handle(command, context) do
    Application.find(command.application_id)
    |> toggle_alerting(command, context)
  end

end

If the current user has permission to toggle alerting on the specified application, we return either a TurnedOffAlerting event, or a TurnedOnAlerting event.

Otherwise, we throw an authorization error.


Events, like commands, are just Elixir structs. The TurnedOffAlerting event we mentioned earlier looks something like this:


defmodule InjectDetect.Event.TurnedOffAlerting do
  defstruct application_id: nil
end

Again, the only information we need to represent this event is the application_id of the application in question.

Events implement a Reducer protocol, which defines a apply function. The apply function takes in the system’s current state as its first argument, and the event being applied as the second argument. It’s purpose is to transform the current state according to the event being applied.

The Reducer implementation for TurnedOffAlerting looks like this:


defimpl InjectDetect.State.Reducer,
   for: InjectDetect.Event.TurnedOffAlerting do

  def apply(event, state) do
    put_in(state, [Lens.key(:users),
                   Lens.all,
                   Lens.key(:applications),
                   Lens.filter(&(&1.id == event.application_id)),
                   Lens.key(:alerting)], false)
  end

end

We basically just dig through our application’s state structure, finding the application we care about and we set its alerting key to false.


You may have noticed that we’re passing the entire system’s state into each Reducer.apply function call. Does this mean that the entire system’s state needs to exist in memory at all times?

Yes!

Inject Detect is storing application state entirely in memory as a Memory Image.

This means that Inject Detect isn’t using a database to hold information about the application’s users, applications, and queries. The only thing being stored in the database is a stream of events.

Instead, Inject Detect stores this stateful information in a long-lived GenServer process. Every time we grab the application’s current state (InjectDetect.State.get), it queries the database for any events that have happened since the last get, applies them using Reducer.apply, and then returns the resulting state.

This was definitely the most radical decision I made while building Inject Detect, but in my experience so far, it has proven to be incredibly powerful.


I definitely made some adventurous design decisions when implementing Inject Detect’s back-end. So far, I’m incredibly satisfied with my decisions to date.

I’m eager to see how they perform under continued development, load testing, and real-world usage.

I’m planning on writing more articles outlining and detailing these design choices in the future. If you’re particularly interested in any one aspect of this system, reach out and let me know!

What’s Next?

While I didn’t mention it in this post, the Meteor plugin component of Inject Detect is essentially finished. The back-end portion of the projects is a few loose ends and a few missing features away from being completed. The front-end of the application represents the bulk of the remaining work, but it’s moving along at a steady pace.

I expect to be ready for beta testing for a small number of real-world users in the next one or two months.

If you haven’t yet, be sure to subscribe to the Inject Detect newsletter to get official news on the release as soon as it’s ready!