Authorization

This is the documentation of the GraphQL Library version 6. For the long-term support (LTS) version 5, refer to GraphQL Library version 5 LTS.

Authorization rules cover what specific data a generated Cypher query is allowed to access. They use predicates to evaluate the data accessed by the Cypher generated from a GraphQL query, thus allowing or disallowing execution within the context of nodes and their properties.

All authorization rules have an implied requirement for authentication, given that the rules are normally evaluated against values in the JWT payload.

In the case of explicit authentication, configured using the @authentication directive, it is only evaluated during Cypher translation time. Unauthenticated requests with queries requiring authentication never reach the database.

The @authorization directive does not apply to subscriptions, it only applies to queries and mutations. Instead, use @subscriptionsAuthorization to configure the authorization for subscriptions if you intend to use subscriptions in your API and want the events protected.

Filtering rules

Filtering rules filter out data which users do not have access to, without throwing any errors. These rules are translated into filtering predicates, which are evaluated against matched data in the database.

Filtering rules protect data as well as obfuscate the information on the existence of that data to unauthorized users.

For instance, here is how to filter out Post nodes which don’t belong to the current User:

type User @node {
    id: ID!
}

type Post @node @authorization(filter: [
    { where: { node: { author: { id_EQ: "$jwt.sub" } } } }
]) {
    title: String!
    content: String!
    author: User! @relationship(type: "AUTHORED", direction: IN)
}

Operations

Filtering can be configured to only be performed on certain operations:

  • READ

  • AGGREGATE

  • UPDATE

  • DELETE

  • CREATE_RELATIONSHIP

  • DELETE_RELATIONSHIP

For instance, to only require filtering for the reading and aggregating posts:

type Post @node @authorization(filter: [
    { operations: [READ, AGGREGATE], where: { node: { author: { id_EQ: "$jwt.sub" } } } }
]) {
    title: String!
    content: String!
    author: User! @relationship(type: "AUTHORED", direction: IN)
}

In case there is no operations argument with a list of operations, the GraphQL Library treats the authorization configuration as if the full list of operations had been provided.

Validating rules

Validating rules throw an error if a query is executed against data which users do not have access to. These rules are evaluated in the database via filtering predicates containing calls to apoc.util.validatePredicate.

For instance, here is how to throw an error if a User is accessed by anyone but the user themselves or an admin:

type JWT @jwt {
    roles: [String!]!
}

type User @node @authorization(validate: [
    { where: { node: { id_EQ: "$jwt.sub" } } }
    { where: { jwt: { roles_INCLUDES: "admin" } } }
]) {
    id: ID!
}

Operations

Validation can be configured to only be performed on certain operations:

  • READ

  • AGGREGATE

  • CREATE

  • UPDATE

  • DELETE

  • CREATE_RELATIONSHIP

  • DELETE_RELATIONSHIP

For instance, to only require validation for the update or deletion of a post:

type Post @node @authorization(validate: [
    { operations: [UPDATE, DELETE], where: { node: { author: { id_EQ: "$jwt.sub" } } } }
]) {
    title: String!
    content: String!
    author: User! @relationship(type: "AUTHORED", direction: IN)
}

In case there is no operations argument with a list of operations, the GraphQL Library treats the authorization configuration as if the full list of operations had been provided.

When

Validation can be configured to only be performed before or after an operation is executed. This is done using the when argument which accepts an array of the following values:

  • BEFORE

  • AFTER

Additionally, some operations only support validation either before or after them, which is summarised in this table:

operation when

READ

BEFORE

AGGREGATE

BEFORE

CREATE

AFTER

UPDATE

BEFORE, AFTER

DELETE

BEFORE

CREATE_RELATIONSHIP

BEFORE, AFTER

DELETE_RELATIONSHIP

BEFORE, AFTER

As an example, let’s say you want someone to be able to update a post. If you want to check that after the update the author of the post is still the current user, do the following:

type Post @node @authorization(validate: [
    { operations: [UPDATE], when: [AFTER], where: { node: { author: { id: "$jwt.sub" } } } }
]) {
    title: String!
    content: String!
    author: User! @relationship(type: "AUTHORED", direction: IN)
}

Authorization on fields

The @authorization directive can be used either on object types or their fields, with the former being used in examples for the most part on this page. When applied to a field, the authorization rules are only evaluated if the matching operations are performed on that field. For example, consider a User type with a password field:

type User @node {
    id: ID!
    username: String!
    password: String! @authorization(where: [{ operations: [READ, UPDATE], where: { node: { id: "$jwt.sub" } } }])
}

When executing the following query, a valid identity is not needed:

{
    users {
        username
    }
}

However, consider the following query:

{
    users {
        username
        password
    }
}

This will require a valid JWT to have been provided with the request, and the matching users will be filtered down according to the JWT subject. The same applies for attempting to update the password field, the update will only apply to the user matching the JWT.

Authorization without authentication

Authentication is implicitly required for every authorization check by default, but this can be disabled on a per-rule basis. This could be the case, for instance, when a node has a property which flags whether the node should be public or not.

For instance, in the case where some Post nodes are private and belong to a particular User, while other Post nodes are public and readable by any user, here is how to set this up:

type User @node {
    id: ID!
}

type Post @node @authorization(filter: [
    { where: { node: { author: { id_EQ: "$jwt.sub" } } } }
    { requireAuthentication: false, operations: [READ], where: { node: { public_EQ: true } } }
]) {
    title: String!
    content: String!
    public: Boolean!
    author: User! @relationship(type: "AUTHORED", direction: IN)
}

Ordering of rules

In each ruleset (filter and validate), rules are joined with an OR. The two rulesets are joined with an AND.

For example, the following would allow for the update of a User node if the JWT roles claim includes admin or if the locked property on the node is false:

type User @node @authorization(validate: [
    { operations: [UPDATE], where: { jwt: { roles_INCLUDES: "admin" } } }
    { operations: [UPDATE], where: { node: { locked: false } } }
]) {
    id: ID!
    locked: Boolean!
}

If you want to combine the rule that a user must be an admin with the rule that the locked property must be false in order to update a User node, add them both to the where field using AND in a single rule:

type User @node @authorization(validate: [
    { operations: [UPDATE], where: { AND: [{ jwt: { roles_INCLUDES: "admin" } }, { node: { locked: false } }] } }
]) {
    id: ID!
    locked: Boolean!
}