Subscriptions 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.

Subscriptions require their own authorization rules, which are configured with the @subscriptionsAuthorization directive. These rules are different to authorization rules for queries and mutations because they use filtering rules available for subscriptions events.

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

Filtering rules

Filtering rules prevent events which contain information that users don’t have access to from reaching them - they will receive no indication that this is the case. These rules are evaluated when the events are returned from the database, before they are broadcasted out to subscribing GraphQL clients.

For instance, here is how to filter out User events which don’t match the JWT of the user listening for events:

type User @node @subscriptionsAuthorization(filter: [
    { where: { node: { id_EQ: "$jwt.sub" } } }
]) {
    id: ID!
}

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

  • CREATED

  • UPDATED

  • DELETED

  • RELATIONSHIP_CREATED

  • RELATIONSHIP_DELETED

For instance, to only require filtering for mutations to a type itself and not its relationships:

type User @node @subscriptionsAuthorization(filter: [
    { events: [CREATED, UPDATED, DELETED], where: { node: { id_EQ: "$jwt.sub" } } }
]) {
    id: ID!
}

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 whilst other Post nodes are public, here is how to set this up:

type Post @node @subscriptionsAuthorization(filter: [
    { requireAuthentication: false, where: { node: { public_EQ: true } } }
]) {
    title: String!
    content: String!
    public: Boolean!
}