Authentication

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.

The GraphQL Library offers the @authentication directive to configure authentication for certain operations and for different parts of your schema.

Explicit authentication, configured with the @authentication directive, is only evaluated during Cypher translation time. Unauthenticated requests with queries requiring authentication never reach the database.

Operations

Authentication can be configured to only be validated on certain operations:

  • CREATE

  • READ

  • AGGREGATE

  • UPDATE

  • DELETE

  • CREATE_RELATIONSHIP

  • DELETE_RELATIONSHIP

  • SUBSCRIBE

For instance, to only require authentication for the update or deletion of a user:

type User @authentication(operations: [UPDATE, DELETE]) @node {
    id: ID!
    name: String!
    password: String!
}

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

Scope

Global authentication

Authentication can be applied to the entire schema. This ensures authentication is checked for every matching request.

Extend the schema:

extend schema @authentication

The operations and jwt arguments can also be used when the directive is applied to a schema extension, for example:

extend schema @authentication(operations: [UPDATE, DELETE], jwt: { roles_INCLUDES: "admin" })

Authentication for types

Authentication can be configured for an entire type:

type User @authentication {
    id: ID!
    name: String!
    password: String!
}

With this configuration, authentication is validated when any of the following operations are attempted:

  • Create: createUsers mutation, create, or connectOrCreate nested operation via a related type.

  • Read: users, usersConnection, usersAggregate query, or access via related type.

  • Update: updateUsers mutation or update nested operation via a related type.

  • Delete: deleteUsers mutation or delete nested operation via a related type.

  • Create relationship: connect or connectOrCreate nested operation via a related type.

  • Delete relationship: disconnect nested operation via a related type.

  • Subscribe: all subscription operations related to type User.

Authentication for fields

Authentication can be configured on a per-field basis, for example:

type User {
    id: ID!
    name: String!
    password: String! @authentication
}

This is only evaluated under the following circumstances:

  • The password field is set on either create or update.

  • The password field is present in a selection set.

Additional verification

Additional checks against JWT claims can be performed together with authentication. For instance, if it was a requirement that only users with the admin role can delete users:

type User @authentication(operations: [DELETE], jwt: { roles_INCLUDES: "admin" }) @node {
    id: ID!
    name: String!
    password: String!
}