DEV Community: Ian Kleats

Easy GraphQL Access Control with GRANDstack

Ian Kleats — Sun, 06 Sep 2020 17:58:02 +0000

This article might be for you if you're interested in...

A quick and flexible development experience to build:

Multi-tenant apps
Apps that let their users choose:
- WHAT data they want to share and
- WHO to share it with
Collaboration apps

GRANDstack (i.e. GraphQL, React, Apollo, Neo4j Database) already lowers technical overhead for initial app development, but it can be complicated or difficult to implement the above access-control features yourself. I'd like to share a package that fills those gaps, making the GRANDstack one of the best options for getting your next MVP up and running.

Long ago in a galaxy far, far away...

Exaggeration is fun, but seriously. A while back, I wrote a series of articles exploring some thoughts about GRANDstack (i.e. GraphQL, React, Apollo, Neo4j Database) and how its nested relationship filtering could be applied to access control. It feels like forever ago. Something called 2020 happened, and it took a while for it to go from rough proof-of-concept code to something I could share.

That day has come.

Introducing: `neo4j-deepauth` v0.2.0 release

Directive-based support for fine-grained access control in neo4j-graphql-js GraphQL endpoints (i.e. GRANDstack apps). Notable improvements from the early thoughts/code I shared include:

Restoring baseline filter functionality.
Adding support for @deepAuth to be applied to an Interface and any Object Type that implements it.

Using the `neo4j-deepauth` package

1. Install package via NPM or Yarn

yarn add neo4j-deepauth or npm install neo4j-deepauth

Link to NPM page: https://www.npmjs.com/package/neo4j-deepauth

2. Add schema definition for `@deepAuth` directive to your SDL.

Your type definitions should include the following:

const typeDefs = `
  # Other TypeDefs you defined before

  directive @deepAuth(
    path: String
    variables: [String]
  ) on OBJECT | INTERFACE
`

Note that, under its current implementation, the behavior of @deepAuth will only be applied to Objects or Interface types. A hotfix is in the works for "Relationship Types" due to the way neo4j-graphql-js generates new Object type definitions Field-level access control can be implemented (rather inelegantly but simply) by moving restricted fields onto their own Object with a one-to-one relationship to the primary Type.

3. Add directive to user-defined types.

Modify your previously-defined type definitions by including @deepAuth on any Object you want it to apply to. Using our To-Do example, that might look like:

const typeDefs = `

type User @deepAuth(
  path: """{ OR: [{userId: "$user_id"},
                {friends_some: {userId: "$user_id"}}] }""",
  variables: ["$user_id"]
){
  userId: ID!
  firstName: String
  lastName: String
  email: String!
  friends: [User] @relation(name: "FRIENDS_WITH", direction: "OUT")
  taskList: [Task] @relation(name: "TO_DO", direction: "OUT")
  visibleTasks: [Task] @relation(name: "CAN_READ", direction: "IN")
}

type Task @deepAuth(
  path: """{ visibleTo_some: {userId: "$user_id"} }"""
  variables: ["$user_id"]
) {
  taskId: ID!
  name: String!
  details: String
  location: Point
  complete: Boolean!
  assignedTo: User @relation(name: "TO_DO", direction: "IN")
  visibleTo: [User] @relation(name: "CAN_READ", direction: "OUT")
}

# ...Directive definition from above
`

Here we've limited access to Users if: a) the client is the User; or b) the client is friends with the User. And we've limited access to Tasks if and only if the client's User has a CAN_READ relationship to the Task. This is not the only or best authorization structure, just a simple example.

Please note that the path argument strongly corresponds to the filter argument Input Types that would define the existence of the ACL structure. Declaring a path argument that does not conform to the correct filter Input Type is a potential cause of errors when applyDeepAuth attempts to coerce the argument value to that type.

4. Modify resolvers and request context

Unless or until @deepAuth is integrated as a broader feature into neo4j-graphql-js, we will not be able to rely on the automatically-generated resolvers. We will have to modify them ourselves.

Per the GRANDstack docs, "inside each resolver, use neo4j-graphql() to generate the Cypher required to resolve the GraphQL query, passing through the query arguments, context and resolveInfo objects." This would normally look like:

import { neo4jgraphql } from "neo4j-graphql-js";

const resolvers = {
  // entry point to GraphQL service
  Query: {
    User(object, params, ctx, resolveInfo) {
      return neo4jgraphql(object, params, ctx, resolveInfo);
    },
    Task(object, params, ctx, resolveInfo) {
      return neo4jgraphql(object, params, ctx, resolveInfo);
    },
  }
};

As alluded to above, we must modify these resolvers to replace the resolveInfo.operation and resolveInfo.fragments used by neo4jgraphql() with the pieces of your transformed query. Additionally, it should be noted that the top-level filter is obtained by neo4jgraphql() from the params argument, while subsequent filters are obtained from the resolveInfo. That might look something like:

import { neo4jgraphql } from "neo4j-graphql-js";
import { applyDeepAuth } from "neo4j-deepauth";

const resolvers = {
  // entry point to GraphQL service
  Query: {
    User(object, params, ctx, resolveInfo) {
      const { authParams, authResolveInfo } = applyDeepAuth(params, ctx, resolveInfo);
      return neo4jgraphql(object, authParams, ctx, authResolveInfo);
    },
    Task(object, params, ctx, resolveInfo) {
      const { authParams, authResolveInfo } = applyDeepAuth(params, ctx, resolveInfo);
      return neo4jgraphql(object, authParams, ctx, authResolveInfo);
    },
  }
};

If you use any variables in your @deepAuth directives, you must define them within your request context with the key as it appears in your variables argument. Here is an example of how to add values to the deepAuthParams in the context using express-graphql (Note: issues with ApolloServer have been diagnosed and resolved in the v0.2.1 release, but we can still give express-graphql some love.):

const app = express();
app.use('/', graphqlHTTP((request) => ({
  schema,
  context: {
    driver,
    deepAuthParams: {
      $user_id: request.user.id
    }
  },
  ...
})));

5. Update Custom Mutations

The automatically-generated mutations will not currently respect or enforce the authorization paths provided on @deepAuth. Also, it will often be helpful or necessary to create/delete additional authorization nodes/relationships in the same transaction as a Create/Delete mutation.

For these reasons, you will need to create your own custom mutation resolvers for pretty much any Type that has @deepAuth applied or has a relationship to a @deepAuthed Type.

Examples

An example of neo4j-deepauth use can be found at github.com/imkleats/neo4j-deepauth-example

imkleats / neo4j-deepauth-example

ApolloServer example with neo4j-graphql-js and neo4j-deepauth

Issues and Contributions

As an early version number release, I'm still working on identifying all edge cases and continually fleshing out the test suite. If you run into any bugs or have ideas for future feature releases, please open up an Issue on the Github repository.

imkleats / neo4j-graphql-deepauth

Directive-based support for fine-grained access control in neo4j-graphql-js GraphQL endpoints

Thanks for listening! Hope you find it useful, and I look forward to hearing from you!

GRANDstack Access Control - Checking out the MVP

Ian Kleats — Tue, 10 Mar 2020 01:23:59 +0000

Hi! It's me again. Welcome to this fifth article in my series on discretionary access control with the GRANDstack. The past couple posts have ventured into some highly theoretical territory. After "losing" a weekend for some snowboarding (aka shredding the gnar), I have finally caught my code up to actually do all the things I talked about doing. I don't know about you, but I am super duper excited.

This article will cover the features implemented currently, lay out limitations that I intend to address with later enhancements (i.e. future articles), and demonstrate how this tool might be integrated into a neo4j-graphql-js-generated endpoint. First things first, let me show you the code:

imkleats / neo4j-graphql-deepauth

Directive-based support for fine-grained access control in neo4j-graphql-js GraphQL endpoints

Disclaimer and Reminder

The importance of data privacy cannot be overstated. Aside from any legal obligations, we have a moral responsibility as coders/developers to ensure the safety of those using our products. It is not hyperbole to say that poorly constructed access control can literally put people's lives at risk.

At this stage, please do not assume my work is production-ready. I make no guarantees of its quality or potential flaws. If you want to use this code, be responsible in writing your own unit and integration tests.

@deepAuth MVP build

Minimum Viable Features

Simplicity: Anyone building a GraphQL backend using neo4j-graphql-js should be able to add fine-grained access control to their read-resources in three easy steps.
1. Add schema definition for @deepAuth directive to your SDL.
2. Add directive to user-defined types.
3. Modify resolvers to replace the resolveInfo.operation and resolveInfo.fragments used by neo4jgraphql() with the pieces of your transformed query.
Powerful Security: Clients should be able to access only the information for which they have been granted permission.
- Leverage Neo4j's graph database capabilities to efficiently traverse arbitrarily complex access control relationships.
- Prevents inference of unauthorized nested data by removing any client-defined filter arguments prior to execution. (Future enhancement to allow and dynamically modify client-defined filter arguments.)
Flexibility & Freedom: In designing @deepAuth, a heavy premium was placed on extensibility.
- Strive for great access control functionality out-of-the-box, but recognize that others might have different needs or ideas about what works for them.
- Users are free to extend or modify the default behavior of @deepAuth by creating their own TranslationRules.
- This TranslationRule pattern/approach is also not limited to directives. Get creative with it!

Enhancement Roadmap

~~Object-level @deepAuth directive support.~~ Complete
~~Remove client-defined filter arguments on GraphQL queries~~ Complete
Field-level @deepAuth directive support.
- Path argument will define path to a fieldPermissions node.
- TranslationRule will add this fieldPermissions node to selectionSet.
- Apollo tooling will be used to validate field-level permissions based on this extra data.
Nested filter support.
- Restore client ability to supply filter arguments.
- Use additional TranslationRule visitors to traverse existing filter arguments.
- Wrap components of the existing filter argument with applicable @deepAuth filter.
Mutation support.
- Attach newly-created nodes to a defined access control structure.
- Use an OperationDefinition visitor in the TranslationRule to generate additional dependent mutations.
- Submit all dependent mutations as a single database transaction.

Demonstration of Intended Flow

1. Add schema definition for `@deepAuth` directive to your SDL.

Your type definitions should include the following:

const typeDefs = `
  # Other TypeDefs you defined before

  directive @deepAuth(
    path: String
    variables: [String]
  ) on OBJECT
`

Note that, under its current implementation, the behavior of @deepAuth will only be applied to Objects. Field-level access control will be the next topic I cover and implement. For forward-compatibility, you can safely use on OBJECT | FIELD_DEFINITION.

2. Add directive to user-defined types.

Modify your previously-defined type definitions by including @deepAuth on any Object you want it to apply to. Using our To-Do example, that might look like:

const typeDefs = `

type User @deepAuth(
  path: """OR: [{userId: "$user_id"},
                {friends_some: {userId: "$user_id"}}]""",
  variables: ["$user_id"]
){
  userId: ID!
  firstName: String
  lastName: String
  email: String!
  friends: [User] @relation(name: "FRIENDS_WITH", direction: "OUT")
  taskList: [Task] @relation(name: "TO_DO", direction: "OUT")
  visibleTasks: [Task] @relation(name: "CAN_READ", direction: "IN")
}

type Task @deepAuth(
  path: """visibleTo_some: {userId: "$user_id"}"""
  variables: ["$user_id"]
) {
  taskId: ID!
  name: String!
  details: String
  location: Point
  complete: Boolean!
  assignedTo: User @relation(name: "TO_DO", direction: "IN")
  visibleTo: [User] @relation(name: "CAN_READ", direction: "OUT")
}

# ...Directive definition from above
`

Please note that, while the path argument generally corresponds to the filter argument that would define the existence of the ACL structure, it must be written without being enclosed by brackets at the outermost level (i.e. just path not { path }).

3. Modify resolvers and request context

Unfortunately, unless or until @deepAuth is integrated as a broader feature into neo4j-graphql-js, we will not be able to rely on the automatically-generated resolvers. We will have to modify them ourselves.

import { neo4jgraphql } from "neo4j-graphql-js";

const resolvers = {
  // entry point to GraphQL service
  Query: {
    User(object, params, ctx, resolveInfo) {
      return neo4jgraphql(object, params, ctx, resolveInfo);
    },
    Task(object, params, ctx, resolveInfo) {
      return neo4jgraphql(object, params, ctx, resolveInfo);
    },
  }
};

import { neo4jgraphql } from "neo4j-graphql-js";
import { applyDeepAuth } from "../neo4j-graphql-deepauth";

const resolvers = {
  // entry point to GraphQL service
  Query: {
    User(object, params, ctx, resolveInfo) {
      const authResolveInfo = applyDeepAuth(params, ctx, resolveInfo);
      return neo4jgraphql(object, params, ctx, authResolveInfo);
    },
    Task(object, params, ctx, resolveInfo) {
      const authResolveInfo = applyDeepAuth(params, ctx, resolveInfo);
      return neo4jgraphql(object, params, ctx, authResolveInfo);
    },
  }
};

const server = new ApolloServer({
  context: ({req}) => ({
    driver,
    deepAuthParams: {
      $user_id: req.user.id
    }
  })
})

Where do we go from here?

Hmmm, good question. I still need to build a lot of tests for the code I've written. Of the three items on my "Enhancement Roadmap", getting nested filter functionality restored is probably the most important, but it's also the most technically challenging.

Field-level access control is probably the easiest, and mutations are fairly straightforward but to introduce database transactions requires re-implementing some parts of neo4jgraphql(). So who knows. I'm leaning towards field-level access control so I can focus on tests.

Thanks for joining me on my journey. We're in a pretty good spot, but there's a fair distance we have yet to travel. Till next time!

GRANDstack Access Control - Generating the Filter Argument

Ian Kleats — Thu, 27 Feb 2020 19:17:44 +0000

Hi there. This is the fourth stop on my journey to implement discretionary access control for GRANDstack applications. Today, we are going to embark on a mission to generate the filter arguments we need for to modify our GraphQL request ASTs.

If you're joining me for the first time, welcome and thank you! I strongly encourage you to check out the previous articles in this series.

Last time on "As the Graph Turns"...

We started jumping right into applying the pattern I introduced in the second article for GraphQL AST translation/transformation (here's a link to the repo that lays this out):

We defined the @deepAuth directive on our schema.
We envisioned the structure of our post-traversal AstMap, which allowed us to define an AstCoalescer function to string our final, modified GraphQL request AST together.
We also established a skeleton of the TranslationRule that would lead to our idealized AstMap.

As I mentioned then, I'm outpacing the code I've developed. The bright side? We get to spend time digging a little more deeply into the actual implementation of the TranslationRule. Let's remind ourselves of that skeleton:

// Definition of our Rule to add an authorization filter.

export function AuthorizationFilterRule(
  context   // The TranslationContext class we instantiate in translate().
) {
  // Returns an ASTVisitor
  return {
    Field(node, key, parent, path, ancestors) {

      const ToDoList = """
         1a) Check for directive on field's type in schema.
         1b) Check for filter arguments on Field node.
         2a) Modify or remove existing filter arguments.
         2b) If 1a is true, wrap 2a with the ACL filter.
         3)  Discern appropriate path for new/modified filter arguments.
         4a) Get current authFilters list from AstMap using `context`.
         4b) Append object with {path: results_of_3, node: results_of_2}
             to 4a (with a higher order function or something similar).
         4c) Post result of 4b to AstMap using `context`.
      """;

      // The @return value of visitor functions elicit special behavior.
      // In most cases, we just want to return undefined.
    }
  }
}

Our goal for this leg of the journey is to work on step (2b) from the list above. We are going to lay the foundation for making the ACL filter referenced there.

Going back, way back

We should probably circle back to something we talked about in the first article. Our goal was to dynamically add filter arguments to our GraphQL queries so that they looked more like:

query aclTasks($user_id: ID!){
  Task(filter: {visibleTo_some: {userId: $user_id}}) {
    ...task fields
  }
}

First of all, I need to say something: I hate that first part. If I were to stick true to that, I would need to open up my TranslationRule to visit those variable definitions and modify them. It sounds like more work than I should need to do, and I'm lazy.

But more importantly... where will this access control list path come from? And how do we handle the dynamic parts (i.e. user/group identifiers) if we aren't using query variables? We need some way for our backend developer to tell us that {visibleTo_some: {userId: $user_id}} is the right access control filter to apply to the Task object type and which part of that path is a variable.

Here's what I am going to propose. We require the user to provide the following arguments and data types for those arguments:

const deepAuthArgsForTask = {
  aclPath: "{visibleTo_some: {userId: $user_id}}", // String
  variables: ["$user_id"] // Array of String
}

If we have this payload of arguments (still being agnostic about how we get them), we can do the following:

const MetaCode = """
  1) Pull the value of variable arguments from some available options/context.
      -- This can be accessible from our TranslationContext.

  2) Use regex to replace instances of the variable arguments in the aclPath
     string with the values obtained in Step 1.

  3) Use a string literal of a very simple GraphQL query to put the string
     generated by Step 2 into a filter argument.

  4) Use the `parse` function from graphql-js to parse that string into a
     Document AST.

  5) Returned the filter Argument node value from the parsed AST for our uses.
"""

Now where do we get those arguments?

We've laid out the arguments we need and how those arguments will be used, but we've been agnostic as to how we are going to deliver those arguments. There might be more choices, but two of the most obvious are:

Attaching them to the same available options/context that we would be using in Step 1 of the meta-code I've written above.
- This might have some benefit in that it obfuscates the access control structure from your GraphQL schema.
- One possible downside is that we've continued to remain agnostic as to whether this query document transformation will occur as middleware prior to hitting the GraphQL server or within our root resolver functions. I don't know how that might complicate things.
Adding these as directive arguments in our GraphQL schema.
- Basically the opposite pros-cons from the previous choice.

This isn't really an either-or choice. We can implement both, I think, as long as we are mindful of precedence when we get both. Since the process of adding an options object to a request context is fairly well documented, I will focus solely on the directive arguments. We need to revise our directive definition in our type definitions to be more like:

const typeDefs = `
  # Other TypeDefs you defined before...

  directive @deepAuth(
    aclPath: String
    variables: [String]
  ) on OBJECT | FIELD_DEFINITION
`

Wrapping up

Thanks for joining me in my digital white-boarding exercise. It was a little shorter than our last few adventures together, but I think we've made progress nonetheless, don't you? We can continue our efforts to implement the AuthorizationFilterRule with our heads held high.

As always, as you continue to digest this material, if you have any questions / comments / contributions, please do share them. Till next time!

GRANDstack Access Control - Query Translation Strategy

Ian Kleats — Thu, 27 Feb 2020 02:09:11 +0000

Howdy! Welcome back to Part 3 of my series on discretionary access control in the GRANDstack. If you're still with me after that last article, mil gracias. As promised, we are going to define and empower a schema directive to lock down our assets.

Recapping our journey so far...

We motivated our work by thinking about a GRANDstack To-do app.
- Our first to-do? Keep Bob from down the street out of our to-do list.
We identified that the powerful nested/relational filtering from neo4j-graphql-js could be used to restrict our query results based on some arbitrary access control structure.
- Our second to-do? Automate that filter behavior using a schema directive.
Then, we needed to explore how GraphQL processes an operation (i.e. query or mutation) from request through result to understand potential implementations.
We learned that the JavaScript reference implementation's graphql/language module and its validate function contain utilities and patterns that "fit" the query transformation problem we're trying to solve.

Today, we'll apply the pattern we described by writing a TranslationRule to add a filter argument to our Document ASTs for every type/field that we put this new directive on within our type definitions.

This endeavor will assume you're familiar with (or can reference on the fly) the repository I shared last time that lays out the pattern we'll be using:

imkleats / graphql-ast-tools

Rule-based translation of GraphQL Document ASTs to ASTs of other query languages

Full disclosure:

I'm developing best practices as I write this, so feel free to offer different opinions in the comments or as issues in the above repo.

The other thing is that this is a hobby for me. My biggest well of time to work on this is the weekend... only after devoting time to family and household obligations. In the sake of keeping up the cadence of this series, though, I'm going to be out-pacing some of the code I've already written.

Some code samples might reference utility functions that I haven't created yet, others might be more like meta programming. If you see where I'm coming from / going to and want to fill in the blanks yourself, I welcome it. Just don't expect my code blocks to be copy-pastable and working.

Where do we start?

In thinking through how to approach transformations, let's remind ourselves of the steps involved in the pattern we are going to apply:

Receive an incoming GraphQL request, parse it into an AST, and feed it into translate.
translate traverses the AST and applies a set of visitor functions that are supplied as TranslationRules to each AST node it visits.
These visitor functions, subject to whatever logic you define, emit information that is stored at a specified location in an AstMap.
- This information may include references to pending values in other locations in the AstMap.
Upon traversal completion, a function is invoked to build a new AST (not necessarily a GraphQL AST) from the components of the AstMap.

I am going to propose that we should start with thinking about the state that needs to exist at the end of Step 3 before heading into Step 4.

In this exercise, we are going to be transforming one GraphQL query into another GraphQL query. Let's think about what that means for the structure of our finalized AstMap.

Scoping our AstMap and Final Coalescer

The first thing that comes to mind as I think about a GraphQL-to-GraphQL transformation is that we could "clone" an entire Document AST with our AstMap.

Did I mention I'm lazy, though? Did I? To misquote one of my favorite mercantilist philosophers, C.J. Sparrow:

You can always trust a lazy person to conduct your business with the utmost efficiency. Honestly. It's the industrious ones you want to watch out for.

(Isn't there inherent value in knowing how to replicate the full-fledged structure of a GraphQL AST?!? Of course there is! But meh...)

To save myself some work, I'm going to ask:

What parts of the AST are we interested in changing?
- Argument nodes with Field node parents.
Do we need to care about any of the child nodes of those Argument nodes?
- The Name and Value nodes tell us if there is an existing "filter" argument.
- None of those children will hold a subsequent Field Node, so we can kind of treat the entire Argument Node as a leaf.

Ok, why did I ask those questions? It's because I wanted to save myself some work, silly. It sounds like we can get away only needing a list of objects that contain:

A new or modified Argument Node for our ACL filter; and
The location in the Document/Operation AST in which to insert that node.

Our final AstMap (that is generated by our visitor functions, so not actually a piece of code we have to define) might look like:

const AstMap = {
  originalQuery: () => {
    return original_document_ast;
  },
  authFilters: () => {
    return [{path: [path_to_filter_arg_1], node: {new_Argument_Node_1},
            {path: [path_to_filter_arg_2], node: {new_Argument_Node_2},
            ...
            {path: [path_to_filter_arg_N], node: {new_Argument_Node_N}];
  },
}

This could naturally lead to a final AstCoalescer function (which we do have to define for ourselves) that looks something like this:

import set from 'lodash/set';

const finalCoalescer = (astmap) => {

  const requestAst = astmap['originalQuery'] ? astmap.originalQuery() : {};
  const authFilters = astmap['authFilters'] ? astmap.authFilters() : [];

  authFilters.map( authFilter => set(requestAst, authFilter.path, authFilter.node) );

  return requestAst;
}

Writing a TranslationRule to make that happen

Mmkay, we know what we want at the end. Now we need to think about which visitor function or set of visitor functions will be necessary to create that structure.

Populating originalQuery

If we were going to use a visitor function to produce a copy of the original Document AST, it might make sense to do that at the first node we enter.

Can we stop to ask ourselves why we would do this through a visitor function?

Honestly, having the capacity to produce an original version of our AST is probably going to be needed fairly frequently for other applications. Maybe we should just revise translate to populate this into our AstMap under a reserved key before any visitation.

Populating authFilters

If the originalQuery is taken care of without any TranslationRule, our primary concern is now limited to authFilters. Here's a part -- like I mentioned above -- that I am getting a little ahead of my actual codebase. This next part will be a little more conceptual, and I'll spend more time in the next article to complete the implementation.

Ok, let's take a second to think: Each visitor function could apply to a specific Kind of node. What kind of node(s) are we interested in?

(Duh, we want to modify Argument nodes in the final AST, so we should write an Argument visitor! ...and that is why I am writing this article and not you. Just kidding... mostly. ;p )

Back to reality. Why would we not use an Argument visitor? Because there are some Fields that we will visit which will not currently have any Argument nodes but will need the schema directive applied to them. Uh-oh, visitors can't visit a node that is undefined.

However, nothing prevents us from accessing the Argument node array when stopping at the Field. We want to do our work when visiting each Field node.

Are there any other node Kinds we need to visit? Nope.

So, let's put some bones in our Field visitor.

// Definition of our Rule to add an authorization filter.

export function AuthorizationFilterRule(
  context   // The TranslationContext class we instantiate in translate().
) {
  // Returns an ASTVisitor
  return {
    Field(node, key, parent, path, ancestors) {

      const ToDoList = """
         1a) Check for directive on field's type in schema.
         1b) Check for filter arguments on Field node.
         2a) Modify or remove existing filter arguments.
         2b) If 1a is true, wrap 2a with the ACL filter.
         3)  Discern appropriate path for new/modified filter arguments.
         4a) Get current authFilters list from AstMap using `context`.
         4b) Append object with {path: results_of_3, node: results_of_2}
             to 4a (with a higher order function or something similar).
         4c) Post result of 4b to AstMap using `context`.
      """;

      // The @return value of visitor functions elicits special behavior.
      // In most cases, we just want to return undefined.
    }
  }
}

Adding the Directive to our Schema

Alright, we kinda sorta have a skeleton for how we are going to implement our AuthorizationFilterRule. That was a doozy. Take a breath. We've got some momentously difficult work ahead of us ("srs bzns" if you're into the whole brevity thing).

const typeDefs = `
  # Other TypeDefs you defined before
  directive @deepAuth on OBJECT | FIELD_DEFINITION
`

Done. That was it. Seriously. We might think about arguments for that directive, or we might not. I haven't decided yet.

Wrapping Up

That's a wrap on this installment of the series. I wish I could say I wasn't a little bummed out. I really wanted to have an MVP AuthorizationFilterRule to share with you, and I fell short.

But hey! We did cover a lot anyway! Let's choose to be happy. It's probably all for the best in any case since we'll be able to take a deeper dive into those implementation details in the next post. Till next time!

GRANDstack Access Control - Query Transformations

Ian Kleats — Sun, 23 Feb 2020 21:47:38 +0000

Welcome back to this exploratory series on discretionary access control with the GRANDstack! First off, I need to fess up about something.

I lied to you in the last article. I told you we were going to jump right into crafting a schema directive. We are not. That's because I didn't want to have lied again.

I told you this series would assume "some basic familiarity with GraphQL concepts." We are actually going to be digging into certain parts of the GraphQL reference implementation that you might never see even if you were highly proficient in developing GraphQL backends.

Hold up. Can't you just use some Apollo tooling to do a query document transformation and skip this? Probably for this use-case, but I'm not going to take that route.

It's selfish, really. I have a pattern for document transformations that I want to riff on because I believe it will elegantly solve some problems when we move on to mutations. I don't want to throw this pattern at you without giving you some background knowledge, though.

Where do we start?

Let's start at the beginning. Take a look at the GraphQL JavaScript reference implementation's Getting Started section. Notice how the "Hello World" response is generated:

// Run the GraphQL query '{ hello }' and print out the response
graphql(schema, '{ hello }', root).then((response) => {
  console.log(response);
});

Ok, so we can see that there is an argument for 'schema' and 'root'. With GRANDstack, both of these are taken care of by makeAugmentedSchema from neo4j-graphql-js, so let's ignore 'em for now and maybe later too.

The middle argument is a query string. Our end goal is to stifle to machinations of your nosy neighbor nemesis, Bob. We talked about how he could circumvent the filter arguments by submitting his own queries that didn't include them. Let's see where that rabbit hole leads.

If we click on the API reference link for the graphql function, we'd find this description:

graphql
graphql(
  schema: GraphQLSchema,
  requestString: string,
  rootValue?: ?any,
  contextValue?: ?any,
  variableValues?: ?{[key: string]: any},
  operationName?: ?string
): Promise<GraphQLResult>
The graphql function lexes, parses, validates and executes a GraphQL request. It requires a schema and a requestString. Optional arguments include a rootValue, which will get passed as the root value to the executor, a contextValue, which will get passed to all resolve functions, variableValues, which will get passed to the executor to provide values for any variables in requestString, and operationName, which allows the caller to specify which operation in requestString will be run, in cases where requestString contains multiple top-level operations.

And you may ask yourself How do I work this?

We've pulled back a layer of the GraphQL onion and found that there are four primary concerns for the main entrypoint to the reference implementation: lexing, parsing, validating, and executing. BUT WHAT DOES IT MEAN? Let's dig in to each of those at a high level.

Lexing turns the strings into tokens that are used by the parser.
Parsing turns the tokens from the lexer into a Document AST.
Validating traverses the Document AST to ensure proper AST structure and enforce the type system.
Executing executes the validated Document AST.

So, if you had the "basic familiarity with GraphQL concepts" I was assuming last article, you have probably not spent much time in the graphql/language module that is pivotal to those first three concerns. Let's change that.

Fun with Parsing

Have you heard about AST explorer (site and github)? It's a'ight, you know, if you like being able to see how your GraphQL queries get parsed into Document ASTs. We can go ahead and copy over the query we came up with last time.

query aclTasks($user_id: ID!){
  Task(filter: {visibleTo_some: {userId: $user_id}}) {
    taskId
    name
    details
  }
}

Cool! Take a few minutes, hours, days, or weeks to wrap your head around what your queries become. Play around with it. Parsing works with more than query/mutation operations. Try throwing your type, directive, and schema definitions at it, too.

Depending how deep down the rabbit hole you want to go, you can consult a mix of the GraphQL Specification and the actual definitions of AST nodes in the JavaScript reference implementation.

Back to business

Alright, what did we notice? Here are a few of my takeaways:

The root node of whatever you're parsing is the DocumentNode, and its only children are DefinitionNodes in an array labeled definitions.
Our queries, mutations, and subscriptions show up as OperationDefinition nodes.
Some of the arguments from graphql() make a little more sense. For instance, if you add multiple query or mutation blocks, you see more than one OperationDefinition nodes. Your executor needs you to tell it which one to run.
- This could be pretty cool down the road. Imagine what we might do if we could define and use extraneous query blocks for some other purpose in the background or even as inputs into resolving the primary operation? IMAGINE! That might be a topic for another series.
The first selectionSet within the OperationDefinition will hold Fields that are representative of the fields defined in our schema's root Query, Mutation, and Subscription types.
Each Field has an optional attribute of arguments, which contains an array of ArgumentNodes. This is where our filter arguments show up.
The value of our filter arguments are of type ObjectFieldNode, which are a kind of key-value data structure. The keys of these objects are NameNodes, and the values are ValueNodes. Complex filter arguments might be nested several levels deep.
Our OperationDefinition nodes don't give us any schema-related type info for the Fields it contains. If we want to define a schema directive on our type definitions to trigger this filter behavior, we are going to have to find a way to somehow access that type info.

Thinking About a Potential Implementation

We're getting very close to fully conceptualizing the steps that will need to occur in the implementation of our discretionary access control directive. Let's lay them out.

By looking at the internals of neo4jgraphql, we can see it uses the resolveInfo argument. That thing seems to have the pieces we need to get this done.
- We could use the resolveInfo from the resolver functions, or we could preemptively create the parts we need by applying middleware that somehow feeds into the resolver context.
GraphQL queries can be written in all sorts of shapes, sizes, and permutations. That's kinda the point. We're going to need some sort of recursion to hit all relevant parts of the OperationDefinition.
- Bad Joke Break: What did the recursive process say to the AST? I'll get to the bottom of this!
As we're traversing, we could create a parallel OperationDefinition AST with modified filter arguments. We can use the schema field of resolveInfo to identify which types have the schema directive we'd like to indicate this behavior.
Replace the old operation value of resolveInfo with the transformed OperationDefinition node when passing it to neo4jgraphql in your root resolvers, and let neo4jgraphql do its thing without interference.

Saving yourself some work

Hey! You know who's lazy? Me.

It turns out that #2 and #3 are problems that have already been solved. Remember how I said:

Validating traverses the Document AST to ensure proper AST structure and enforce the type system.

Sounds kinda, sorta, a little bit like what we're wanting to do, no? Let's put it side-by-side.

Validation traverses the AST, examines the contents of each node relative to the type system, identifies features that need to exist or not exist in each node, and collects a record of that identification in the form of error values.
Transformation traverses the AST, examines the contents of each node relative to the type system, identifies features that need to exist or not exist in each node, and collects a record of that identification in the form of modified nodes.

Yep. Checks out to me. Let's take a look, and...

That might just work!

Now we circle back to the comments I made up top about being a little selfish by not just using some existing Apollo tooling. I've taken the liberty of porting over the validation implementation to a transformation context.

imkleats / graphql-ast-tools

Rule-based translation of GraphQL Document ASTs to ASTs of other query languages

This is the pattern I'm going to use to implement our filter argument transformations next time. At a very high level:

It uses visit() for depth first traversal, visitWithTypeInfo() for access to the type info from our schema, and visitInParallel() to run multiple visitor functions.
These visitor functions allow for separation of concerns within and across certain kinds of AST nodes.
Instead of collecting an array of error values, we can collect pieces of a transformed AST in a map that allows for lazy evaluation once traversal is complete.

The road goes ever on and on.

Thanks for joining me on this foray into some GraphQL concepts and implementation details that you might never have wanted to see! We've gone end-to-end to identify some key considerations in query transformation, and I've introduced the structure of a solution I will continue fleshing out.

Now, when we start building the transformation rules and visitor functions we need, I hope you're able to understand what we're doing and why we're doing it. Till next time!

GRANDstack Access Control - Basics and Concepts

Ian Kleats — Fri, 21 Feb 2020 06:39:04 +0000

Hey there. Thank you for joining me on a journey of exploration and discovery into unlocking some of the most powerful features of the GRANDstack! By the end of this series, we'll be able to implement fine-grained discretionary access control features into the GraphQL endpoint generated by neo4j-graphql-js.

Cool, right? I thought so too.

Before we dive in...

First off, this series assumes some basic familiarity with GraphQL concepts and the GRANDstack itself (GraphQL, React, Apollo, Neo4j Database). Most important of those GRANDstack topics will be its support for complex nested filtering. Luckily, there's a good blog post to get you up to speed.

Second, this is not a full-fledged tutorial. . . yet. The posts in this series are as much a learning log to document these concepts being developed in real time as they are to invite others to think about and share their own approaches. Learning can be messy. Let's get messy together.

And back to the action...

Ok, let's start small. You know what's small? A boring old To-Do app.

(Wait, you promised an epic journey of awesomeness and are giving me some crappy To-Do app?!?!? For now at least, yes.)

We've heard about this thing called the GRANDstack. It has a lot of synergy out of the box. All you really need to get your backend up is your GraphQL type definitions (i.e. the data model). neo4j-graphql-js will generate the executable schema from there, which can be served by apollo-server.

Ignoring the custom mutation you might use for user login, your type definitions might look like:

const typeDefs = `
type User {
  ID: ID!
  firstName: String
  lastName: String
  email: String!
  todoList: [Task] @relation(name: "TO_DO", direction: "OUT")
}
type Task {
  ID: ID!
  name: String!
  details: String
  location: Point
  complete: Boolean!
  assignedTo: User @relation(name: "TO_DO", direction: "IN")
}
`;

Cool beans. We have Users that can be assigned Tasks. Our tasks even take advantage of neo4j-graphql-js Spatial Types that could be useful in the future!

Let's run it and...

What went wrong?

Oh, your app works great. That is, if you wanted Bob down the street to see that you need to stop by the pharmacy to pick up some hemorrhoid cream.

We could use the @additionalLabels directive on Task to keep them accessible to only one User, but that's kind of limited. What if your mom was going to the pharmacy anyway? Maybe you want certain people to be able to see certain tasks.

Maybe you want discretionary access control.

Unfortunately, I am not aware of any clear cut fine-grained access control options for GRANDstack out of the box. If I were, this post would not exist. On the bright side, we get to explore the possibilities together!

Filter to the rescue!

I might have mentioned how GRANDstack does have out-of-the-box support for complex nested filtering. Could this be the answer we seek? (HINT: I think so.)

Nested filtering means that we can filter the results of any field within our query by the fields of its related types. Those fields of its related types could lead to yet other filterable related types. Ad infinitum.

I don't actually think we need to go on forever. We just need to realize that the access control list for our business data is itself a graph connected to our primary data model.

We could do this with an arbitrarily complex authorization layer, but instead we're going to keep it simple. Let's reduce the access control structure to a single relationship that sits between the User and Task types. Our updated type definitions might look like:

const typeDefs = `
type User {
  userId: ID!
  firstName: String
  lastName: String
  email: String!
  taskList: [Task] @relation(name: "TO_DO", direction: "OUT")
  visibleTasks: [Task] @relation(name: "CAN_READ", direction: "IN")
}
type Task {
  taskId: ID!
  name: String!
  details: String
  location: Point
  complete: Boolean!
  assignedTo: User @relation(name: "TO_DO", direction: "IN")
  visibleTo: [User] @relation(name: "CAN_READ", direction: "OUT")
}
`;

The following filter arguments could then form the basis for locking down our assets:

query aclTasks($user_id: ID!){
  Task(filter: {visibleTo_some: {userId: $user_id}}) {
    ...task fields
  }
  User {
    taskList(filter: {visibleTo_some: {userId: $user_id}} {
      ...task fields
    }
  }
}

If there are other filters that need to be applied, we can wrap them all with an AND clause:

query aclTasks($user_id: ID!){
  Task(filter: {AND: [{visibleTo_some: {userId: $user_id}},
                     {location_distance_lt: {...}}]}) {
    ...task fields
  }
}

Moving ahead in our journey

Oh, I'm sorry. Did I miss something? Your nosy neighbor Bob can still see your pharmaceutical needs can't he because he's savvy enough to submit his own queries without those filters. That dog!

Next time we'll need to figure out how to use a new schema directive to automate the transformation of our GraphQL filter arguments. This will do more to keep Bob out and also keep the queries on the client side a little cleaner. Till then!

DEV Community: Ian Kleats

Easy GraphQL Access Control with GRANDstack

This article might be for you if you're interested in...

Long ago in a galaxy far, far away...

Introducing: neo4j-deepauth v0.2.0 release

Using the neo4j-deepauth package

1. Install package via NPM or Yarn

2. Add schema definition for @deepAuth directive to your SDL.

3. Add directive to user-defined types.

4. Modify resolvers and request context

5. Update Custom Mutations

Examples

imkleats / neo4j-deepauth-example

ApolloServer example with neo4j-graphql-js and neo4j-deepauth

Issues and Contributions

imkleats / neo4j-graphql-deepauth

Directive-based support for fine-grained access control in neo4j-graphql-js GraphQL endpoints

GRANDstack Access Control - Checking out the MVP

imkleats / neo4j-graphql-deepauth

Directive-based support for fine-grained access control in neo4j-graphql-js GraphQL endpoints

Disclaimer and Reminder

@deepAuth MVP build

Minimum Viable Features

Enhancement Roadmap

Demonstration of Intended Flow

1. Add schema definition for @deepAuth directive to your SDL.

2. Add directive to user-defined types.

3. Modify resolvers and request context

Where do we go from here?

GRANDstack Access Control - Generating the Filter Argument

Last time on "As the Graph Turns"...

Going back, way back

Now where do we get those arguments?

Wrapping up

GRANDstack Access Control - Query Translation Strategy

Recapping our journey so far...

imkleats / graphql-ast-tools

Rule-based translation of GraphQL Document ASTs to ASTs of other query languages

Full disclosure:

Where do we start?

Scoping our AstMap and Final Coalescer

Writing a TranslationRule to make that happen

Populating originalQuery

Populating authFilters

Adding the Directive to our Schema

Wrapping Up

GRANDstack Access Control - Query Transformations

Where do we start?

graphql

And you may ask yourself How do I work this?

Fun with Parsing

Back to business

Thinking About a Potential Implementation

Saving yourself some work

That might just work!

imkleats / graphql-ast-tools

Rule-based translation of GraphQL Document ASTs to ASTs of other query languages

The road goes ever on and on.

GRANDstack Access Control - Basics and Concepts

Before we dive in...

And back to the action...

What went wrong?

Filter to the rescue!

Moving ahead in our journey

Introducing: `neo4j-deepauth` v0.2.0 release

Using the `neo4j-deepauth` package

2. Add schema definition for `@deepAuth` directive to your SDL.

1. Add schema definition for `@deepAuth` directive to your SDL.