Securing a Graphql API by rsill-neo4j · Pull Request #280 · neo4j/docs-graphql

rsill-neo4j · 2025-09-22T12:05:46Z

this PR is kinda dependent on #274 now
would be good to publish them simultaneously
274 has two js examples missing

neo4j-docops-agent · 2025-10-24T08:27:18Z

This PR includes documentation updates
View the updated docs at https://neo4j-docs-graphql-280.surge.sh

New pages:

Securing your GraphQL API

modules/ROOT/pages/security/securing-a-graphql-api.adoc

keremgocen

It's looking good so far and has valuable information. However there are a few typos and I think we can make it more practical with some code examples. I left a few comments.

modules/ROOT/pages/security/securing-a-graphql-api.adoc

keremgocen · 2025-11-07T12:32:41Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+
+For the same reason it is advisable to avoid introspection and data field suggestions, it can make your API more secure to catch internal errors and redact which information you want to pass on to the end user.
+
+For example, the following error reveals information XY:


Was this also a placeholder XY? feels like the JSON example here could be more illustrative?

keremgocen · 2025-11-07T12:33:24Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+
+[source, graphql, indent=0]
+----
+// example


missing example here I think?

keremgocen · 2025-11-07T12:33:45Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+There are many ways and places to use timeouts.
+Here are a few examples.
+
+// examples


missing example?

keremgocen · 2025-11-07T12:34:03Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+
+Follow the input validation methods summarized in the link:https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html#input-validation[OWASP Cheat Sheet Series].
+
+// Examples?


also here, do we want an actual example?

modules/ROOT/pages/security/securing-a-graphql-api.adoc

keremgocen · 2025-11-07T12:39:31Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+----
+import depthLimit from 'graphql-depth-limit'
+import express from 'express'
+import graphqlHTTP from 'express-graphql'


should we maybe use a more up to date example here? we could replace the deprecated express-graphql with graphql-http, apparently. (cc: @mjfwebb)

We'll replace this example with an example using GraphQL Armor

Co-authored-by: kerem <kerem.gocen@neo4j.com>

modules/ROOT/pages/security/securing-a-graphql-api.adoc

rsill-neo4j · 2025-11-17T13:51:18Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+Returning large query result lists can negatively affect server performance.
+For example, a query like the following would return a siginificant number of nodes:
+
+[source, graphql, indent=0]
+----
+query {
+  order(first: 1000) {
+    orderID
+    products(last: 100) {
+      productName
+      productCategory
+    }
+  }
+}
+----
+
+To avoid this, you can cap the input number directly in your resolvers, for example like this:
+
+[source, graphql, indent=0]
+----
+// example
+----
+
+Alternatively, use a library such as link:https://github.com/joonhocho/graphql-input-number[graphql-input-number]:
+
+[source, typescript, indent=0]
+----
+import {
+  GraphQLInputInt,
+  GraphQLInputFloat,
+} from 'graphql-input-number';
+
+const argType = GraphQLInputInt({
+  name: 'OneToNineInt',
+  min: 1,
+  max: 9,
+});
+
+new GraphQLObjectType({
+  name: 'Query',
+  fields: {
+    input: {
+      type: GraphQLInt,
+      args: {
+        number: {
+          type: argType,
+        },
+      },
+      resolve: (_, {number}) => {
+
+        // 'number' IS AN INT BETWEEN 1 to 9.
+
+      };
+    },
+  },
+});
+----


replace with type definition solution (server side)
mention: denial of service prevention

rsill-neo4j · 2025-11-17T13:56:13Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+==== Query cost points
+
+The link:https://shopify.dev/docs/api/usage/limits#the-leaky-bucket-algorithm[leaky bucket algorithm].
+
+==== Query cost analysis
+
+link:https://github.com/pa-bru/graphql-cost-analysis[graphql-cost-analysis]


link to graphql armor

rsill-neo4j · 2025-11-17T13:58:11Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+To prevent the API from not responding or falling victim to denial of service attacks, it is feasible to make use of timeouts.
+This way, subsequent queries will not be blocked by a long-running previous query.
+
+There are many ways and places to use timeouts.
+Here are a few examples.
+
+// examples


refer to transaction config in context

modules/ROOT/pages/security/securing-a-graphql-api.adoc

angrykoala · 2025-12-15T14:08:13Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+. Set up a new AuraDB instance.
+Refer to link:https://neo4j.com/docs/aura/getting-started/create-instance/[Creating a Neo4j Aura instance].
+. Populate the instance with the Northwind data set.


Are we sure we want to make this a pre-requisite? This can also be done with an on-prem db

it's the same in graphql-modeling.adoc, following the "aura first" approach (making aura the default UX journey)

angrykoala · 2025-12-15T14:22:23Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+
+=== Authentication
+
+The xref:security/authentication.adoc[`@authentication` directive] can be applied globally, only to certain fields or only to certain types, and only for certain operations.


can be applied globally but only to certain elements?

Is there a typo? I'm not sure I understand this

rephrased
it's either ... or ... or (added "either" and made it active voice)

angrykoala · 2025-12-15T14:25:38Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+
+The xref:security/authentication.adoc[`@authentication` directive] can be applied globally, only to certain fields or only to certain types, and only for certain operations.
+
+Add admin authorization for operations on customers, orders, products, categories and suppliers:


We use different directives to differentiate between authentication (we can identify who you are) and authorization (you have the correct rights to access the data)

While this particular example is a bit on the edge, I would avoid using the word "authorization" when trying to add examples of authentication to avoid confusion

In this case, we are validating your tokens are valid, including the role

rephrased a bit

angrykoala · 2025-12-15T14:28:21Z

modules/ROOT/content-nav.adoc


 * *Reference*
 * xref:security/index.adoc[]
+** xref:security/securing-a-graphql-api.adoc[]


Is reference the right place for this? this feels more like a tutorial

you're right
security is in reference, but we have this nearly empty how-to section (we're going to tackle that next)
let's put it there for now 👍

angrykoala · 2025-12-15T14:34:50Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+----
+type Customer
+    @node
+    @authentication( <1>


These points in the code are referenced with numbers, but I'm not sure what the reference to these are. Is this just to mark the code changes form the previous version?

i think i was going to do something with them, but then did not.
removed :)

angrykoala · 2025-12-15T14:43:41Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+For instance, if the server side is trying to parse the `roles` field that was introduced in xref:#_authentication[], then the JWT should contain that.
+With `@jwtClaim`, you can specify a path to a customer ID in a nested location.
+For example:


@jwtClaim is explained, but the directive @jwt is not mentioned anywhere, maybe worth mentioning that this directive allows to define the types of the jwt data?

angrykoala · 2025-12-15T15:22:55Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+While the xref:getting-started/graphql-aura.adoc[Getting started page for GraphQL and Aura Console] advocates to both **Enable introspection** as well as **Enable field suggestions**, this is not recommended when considering security.
+
+Both potentially expose information that can be used to gain insight on specifics of your GraphQL schema and execute targeted malicious operations.
+Be sure to deactivate both in a customer-facing real-life scenario.


While this is definitely recommended in production systems. Introspection and field suggestions are not necessarily insecure, and some applications, such as public APIs may want these features, may be worth rewording this to make sure these are recommendations, but not critical steps?

rephrased a bit

angrykoala · 2025-12-15T15:25:46Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+
+You can prevent denial of service attacks based on queries such as this by paginating query results.
+
+A server-side pagination solution based on type definitions could look like this:


mmm, it feels like this example is missing the @limit directive that enforces limit

Or this is covering a different point?

where would you place it?

TBH, I'm not sure what this example is covering, but if it is indeed server-side enforced pagination (https://neo4j.com/docs/graphql/current/directives/custom-logic/#_limit)

I'd say that we can add a @limit to any of the nodes of the initial typeDefinitions?

added the @limit on the Order type definition

angrykoala · 2025-12-15T15:26:41Z

modules/ROOT/pages/security/securing-a-graphql-api.adoc

+You can set a timeout via the GraphQL Library driver, see xref:driver-configuration.adoc#_transaction_configuration_in_context[Transaction configuration in context].
+
+
+== Further reading


I would recommend reading the GraphQL security section: https://www.graphql.org/learn/security/

This covers up to date best practices for GraphQL in general

modules/ROOT/pages/security/securing-a-graphql-api.adoc

rsill-neo4j added 4 commits July 30, 2025 13:59

converted graphql middleware blog post

f4ab1d1

changes

c35374f

structure + some text, missing examples

2ccaca9

more text, draft

a8b9c7f

rsill-neo4j requested a review from mjfwebb September 22, 2025 12:05

rsill-neo4j and others added 2 commits September 22, 2025 14:05

Merge branch '7.x' into securing-a-graphql-api

efd8267

WiP new type defs

9932cda

luffy1727 marked this pull request as draft October 21, 2025 12:08

rsill-neo4j and others added 3 commits October 21, 2025 15:37

some updates for sections

671cbec

adjusted structure, explained directives

6891e80

Merge branch '7.x' into securing-a-graphql-api

f6fca1a

rsill-neo4j marked this pull request as ready for review October 24, 2025 08:22

added two xrefs

13d26ce

rsill-neo4j commented Nov 7, 2025

View reviewed changes

modules/ROOT/pages/security/securing-a-graphql-api.adoc Outdated Show resolved Hide resolved

rsill-neo4j added 2 commits November 7, 2025 09:29

Update modules/ROOT/pages/security/securing-a-graphql-api.adoc

e6743bd

Merge branch '7.x' into securing-a-graphql-api

5a53048

keremgocen reviewed Nov 7, 2025

View reviewed changes

Apply suggestions from code review

4bd172a

Co-authored-by: kerem <kerem.gocen@neo4j.com>

rsill-neo4j commented Nov 17, 2025

View reviewed changes

modules/ROOT/pages/security/securing-a-graphql-api.adoc Outdated Show resolved Hide resolved

rsill-neo4j commented Nov 17, 2025

View reviewed changes

modules/ROOT/pages/security/securing-a-graphql-api.adoc Outdated Show resolved Hide resolved

rsill-neo4j and others added 2 commits November 20, 2025 17:36

Apply suggestions from code review

aa4fbf9

updates

174b276

angrykoala reviewed Dec 15, 2025

View reviewed changes

rsill-neo4j and others added 3 commits December 16, 2025 15:55

review suggestions

351759a

Merge branch '7.x' into securing-a-graphql-api

cbb5aa7

test

db1a770

added @limit directive on orders

9400dc0

rsill-neo4j commented Jan 12, 2026

View reviewed changes

modules/ROOT/pages/security/securing-a-graphql-api.adoc Outdated Show resolved Hide resolved

rsill-neo4j commented Jan 12, 2026

View reviewed changes

modules/ROOT/pages/security/securing-a-graphql-api.adoc Outdated Show resolved Hide resolved

rsill-neo4j and others added 2 commits January 16, 2026 10:04

Apply suggestions from code review

889b5f5

added some explanation for server-side pagination

64e42a3

angrykoala approved these changes Jan 19, 2026

View reviewed changes

rsill-neo4j merged commit 9e039ac into 7.x Jan 19, 2026

rsill-neo4j deleted the securing-a-graphql-api branch January 19, 2026 12:46


		For the same reason it is advisable to avoid introspection and data field suggestions, it can make your API more secure to catch internal errors and redact which information you want to pass on to the end user.

		For example, the following error reveals information XY:


		Follow the input validation methods summarized in the link:https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html#input-validation[OWASP Cheat Sheet Series].

		// Examples?


		=== Authentication

		The xref:security/authentication.adoc[`@authentication` directive] can be applied globally, only to certain fields or only to certain types, and only for certain operations.


		The xref:security/authentication.adoc[`@authentication` directive] can be applied globally, only to certain fields or only to certain types, and only for certain operations.

		Add admin authorization for operations on customers, orders, products, categories and suppliers:


		You can prevent denial of service attacks based on queries such as this by paginating query results.

		A server-side pagination solution based on type definitions could look like this:

		You can set a timeout via the GraphQL Library driver, see xref:driver-configuration.adoc#_transaction_configuration_in_context[Transaction configuration in context].


		== Further reading

Conversation

rsill-neo4j commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

neo4j-docops-agent commented Oct 24, 2025

Uh oh!

Uh oh!

keremgocen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

rsill-neo4j commented Sep 22, 2025 •

edited

Loading