Subscriptions authorization

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

Data APIs created in Aura Console currently do not support the subscriptionsAuthorization directive.

Subscriptions require their own authorization rules, which you can configure with the @subscriptionsAuthorization directive. These rules are different to authorization rules for queries and mutations because they use filtering rules available for subscriptions events. These filtering rules can only be used to filter against the properties of the nodes impacted by the 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 from being broadcasted to users who do not have access to the information contained in the events. The users don’t receive an indication at all: the rules are evaluated when the events are returned from the database, before they are broadcasted 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!
}

You can configure filtering to only be performed on certain events:

  • CREATED

  • UPDATED

  • DELETED

For instance, to only require filtering for mutations of 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. You can disable this behavior on a per-rule basis. This can be desirable, for instance, when a node has a property which flags whether the node should be public or not.

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!
}