{"id":19410058,"url":"https://github.com/nicolasdao/graphql-authorize","last_synced_at":"2025-06-11T16:32:43.527Z","repository":{"id":57253353,"uuid":"122905181","full_name":"nicolasdao/graphql-authorize","owner":"nicolasdao","description":"Authorization middleware for graphql-serverless. Add inline authorization straight into your GraphQl schema. ","archived":false,"fork":false,"pushed_at":"2018-03-07T07:03:19.000Z","size":17,"stargazers_count":9,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-01T17:53:54.589Z","etag":null,"topics":["authentication","authorization","graphql","graphql-serverless","neap","serverless","webfunc"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicolasdao.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-26T03:03:57.000Z","updated_at":"2023-09-30T00:39:43.000Z","dependencies_parsed_at":"2022-08-31T22:20:17.252Z","dependency_job_id":null,"html_url":"https://github.com/nicolasdao/graphql-authorize","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasdao%2Fgraphql-authorize","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasdao%2Fgraphql-authorize/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasdao%2Fgraphql-authorize/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasdao%2Fgraphql-authorize/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicolasdao","download_url":"https://codeload.github.com/nicolasdao/graphql-authorize/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasdao%2Fgraphql-authorize/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258695557,"owners_count":22742676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authorization","graphql","graphql-serverless","neap","serverless","webfunc"],"created_at":"2024-11-10T12:14:42.485Z","updated_at":"2025-06-11T16:32:43.510Z","avatar_url":"https://github.com/nicolasdao.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# graphql-authorize \u0026middot;  [![NPM](https://img.shields.io/npm/v/graphql-authorize.svg?style=flat)](https://www.npmjs.com/package/graphql-authorize) [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) [![Neap](https://neap.co/img/made_by_neap.svg)](#this-is-what-we-re-up-to)\nAuthorization middleware for [_graphql-serverless_](https://github.com/nicolasdao/graphql-serverless). Add inline authorization straight into the GraphQl schema to restrict access to certain fields based on the user's rights. __*graphql-serverless*__ allows to deploy [GraphQL](http://graphql.org/learn/) apis (including an optional [GraphiQL interface](https://github.com/graphql/graphiql)) to the most popular serverless platforms:\n- [Zeit Now](https://zeit.co/now) (using express under the hood)\n- [Google Cloud Functions](https://cloud.google.com/functions/) (incl. Firebase Function)\n- [AWS Lambdas](https://aws.amazon.com/lambda)\n- [Azure Functions](https://azure.microsoft.com/en-us/services/functions/) (COMING SOON...)\n\nDecorate your fields with something similar to this in your GraphQl schema:\n```js\ntype Product {\n  id: ID!\n  @auth\n  name: String!\n  shortDescription: String\n}\n```\n\nThen define a rule similar to this one:\n```js\n{\n  authenticationFields: field =\u003e field.metadata \u0026\u0026 field.metadata.name == 'auth'\n}\n```\n\nIf the user is not authenticated (more about this below), then a GraphQl query similar to this:\n```js\n{\n  products(id:2) {\n    id\n    name\n  }\n}\n```\n\nwill return an HTTP response with status 200 similar to this:\n```js\n{\n  \"data\": {\n    \"products\": [\n      {\n        \"id\": \"2\"\n      }\n    ]\n  },\n  \"warnings\": [\n    {\n      \"message\": \"Access denied for certain fields. The current response is incomplete.\",\n      \"path\": [\n        \"products.name\"\n      ]\n    }\n  ]\n}\n```\n\n\u003e TIP - It is also possible to configure the middleware to nullify the `name` field rather than omitting it (refer to section [Returning `null` Rather Than Removing Fields](#returning-null-rather-than-removing-fields)). This is usually rather important client libraries using caching like the [apollo-client](https://github.com/apollographql/apollo-client) which would break otherwise.\n\n# Table Of Contents\n\u003e * [Install](#install)\n\u003e * [How To Use It](#how-to-use-it)\n\u003e \t- [Basics](#basics)\n\u003e \t- [Managing Authorizations](#managing-authorizations)\n\u003e\t- [Returning `null` Rather Than Removing Fields](#returning-null-rather-than-removing-fields)\n\u003e\t- [Not Returning Partial Response](#not-returning-partial-response)\n\n# Install\n### node\n```js\nnpm install graphql-authorize --save\n```\n\n# How To Use It\n## Basics\nAn example will worth a thousand words. Follow those steps:\n1. Create a new npm project: `npm init`\n2. Install the following packages: `npm install graphql-s2s graphql-serverless graphql-authorize webfunc lodash --save` \n3. Create a new `index.js` as follow:\n\n\t```js\n\tconst graphqlAuth = require('graphql-authorize')\n\tconst { getSchemaAST, transpileSchema } = require('graphql-s2s').graphqls2s\n\tconst { graphqlHandler } = require('graphql-serverless')\n\tconst { app } = require('webfunc')\n\tconst { makeExecutableSchema } = require('graphql-tools')\n\tconst _ = require('lodash')\n\n\t// STEP 1. Mock some data for this demo.\n\tconst productMocks = [\n\t\t{ id: 1, name: 'Product A', shortDescription: 'First product.', owner: 'Marc Stratfield' }, \n\t\t{ id: 2, name: 'Product B', shortDescription: 'Second product.', owner: 'Nic Dao' }]\n\n\tconst variantMocks = [\n\t\t{ id: 1, name: 'Variant A', shortDescription: 'First variant.' }, \n\t\t{ id: 2, name: 'Variant B', shortDescription: 'Second variant.' }]\n\n\t// STEP 2. Creating a basic GraphQl Schema augmented with some non-standard authorizaion metadata\n\t//         thanks to the 'graphql-s2s' package (https://github.com/nicolasdao/graphql-s2s). \n\tconst schema = `\n\ttype Product {\n\t\tid: ID!\n\t\t@auth\n\t\tname: String!\n\t\tshortDescription: String\n\t\towner: String\n\t}\n\ttype Variant {\n\t\tid: ID!\n\t\tname: String!\n\t\tshortDescription: String\n\t}\n\ttype Query {\n\t\tproducts(id: Int): [Product]\n\t\tvariants(id: Int): [Variant]\n\t}\n\t`\n\n\tconst productResolver = {\n\t\tQuery: {\n\t\t\tproducts(root, { id }, context) {\n\t\t\t\tconst results = id ? productMocks.filter(p =\u003e p.id == id) : productMocks\n\t\t\t\tif (results.length \u003e 0)\n\t\t\t\t\treturn results\n\t\t\t\telse\n\t\t\t\t\tthrow new Error(`Product with id ${id} does not exist.`)\n\t\t\t}\n\t\t}\n\t}\n\n\tconst variantResolver = {\n\t\tQuery: {\n\t\t\tvariants(root, { id }, context) {\n\t\t\t\tconst results = id ? variantMocks.filter(p =\u003e p.id == id) : variantMocks\n\t\t\t\tif (results.length \u003e 0)\n\t\t\t\t\treturn results\n\t\t\t\telse\n\t\t\t\t\tthrow new Error(`Variant with id ${id} does not exist.`)\n\t\t\t}\n\t\t}\n\t}\n\n\t// STEP 3. Transpiling our schema on steroid to a standard schema using the 'transpileSchema'\n\t//         function from the 'graphql-s2s' package (https://github.com/nicolasdao/graphql-s2s). \n\tconst executableSchema = makeExecutableSchema({\n\t\ttypeDefs: transpileSchema(schema),\n\t\tresolvers: _.merge(productResolver, variantResolver) \n\t})\n\n\t// STEP 4. Creating the Express-like middleware that will define the authorization rules that will give\n\t//         access or not to certain fields.\n\tconst schemaAST = getSchemaAST(schema)\n\tconst authorize = graphqlAuth(\n\t\t// AST of the Graphql schema augmented with metadata\n\t\tschemaAST, \n\t\t// Function that must terminate by a call to the 'next' callback with 2 required arguments:\n\t\t// @param  {Object} err   Potential error object useful for identifying the source of the \n\t\t//                        authentication failure.\n\t\t// @param  {Object} user  If this object exists, then the authentication based on data contained \n\t\t//                        in the 'req' object is successfull, otherwise it is not.\n\t\t(req, res, next) =\u003e {\n\t\t\t// This example below simulates a situation where all request will always be\n\t\t\t// unauthenticated.\n\t\t\tconst err = null\n\t\t\tconst user = null\n\t\t\tnext(err, user)\n\t\t}, \n\t\t// Defines the authentication rules, i.e. the rule on each field that determines\n\t\t// whether that field requires authentication.\n\t\t{\n\t\t\tauthenticationFields: field =\u003e field.metadata \u0026\u0026 field.metadata.name.indexOf('auth') == 0\n\t\t})\n\n\t// STEP 5. Creating a GraphQL and a GraphiQl endpoint\n\tconst graphqlOptions = {\n\t\tschema: executableSchema,\n\t\tgraphiql: {\n\t\t\tendpoint: '/graphiql'\n\t\t}\n\t}\n\n\tapp.all(['/', '/graphiql'], authorize, graphqlHandler(graphqlOptions))\n\n\t// STEP 5. Starting the server \n\tapp.listen(4000)\n\t```\n\n4. Run `node index.js`\n5. Browse to [`http://localhost:4000/graphiql`](http://localhost:4000/graphiql)\n6. Execute a query similar to this in graphiql:\n\t```js\n\t{\n\t  products(id:2) {\n\t    id\n\t      name\n\t  }\n\t}\n\t```\n\n\tBecause we've hardcoded that all requests are unauthenticated (ref. STEP 4. `user = null`), this request above will yield the following result HTTP 200 response:\n\n\t```js\n\t{\n\t  \"data\": {\n\t    \"products\": [\n\t      {\n\t        \"id\": \"2\"\n\t      }\n\t    ]\n\t  },\n\t  \"warnings\": [\n\t    {\n\t      \"message\": \"Access denied for certain fields. The current response is incomplete.\",\n\t      \"path\": [\n\t        \"products.name\"\n\t      ]\n\t    }\n\t  ]\n\t}\n\t```\n\n\u003e NOTICE that you're not forced to use the metadata `@auth` to defined what field is restricted to authenticated user. You can do what ever you want. We just thought it made sense based on our own experience.\n\n\u003e TIP - It is also possible to configure the middleware to nullify the `name` field rather than omitting it (refer to section [Returning `null` Rather Than Removing Fields](#returning-null-rather-than-removing-fields)). This is usually rather important client libraries using caching like the [apollo-client](https://github.com/apollographql/apollo-client) which would break otherwise.\n\n## Managing Authorizations\n\nIn the previous example, we introduced how to restrict access to unauthenticated users. Now we'll see how we can restrict access based on roles of authenticated users. \n\nIn STEP 2, updates the schema as follow:\n```js\ntype Product {\n  id: ID!\n  @auth\n  name: String!\n  shortDescription: String\n  @auth(admin)\n  owner: String\n}\n```\n\nIn STEP 4, update the code as follow:\n```js\nconst authorize = graphqlAuth(\n  schemaAST, \n  (req, res, next) =\u003e {\n    const err = null\n    const user = { role: 'standard' }\n    next(err, user)\n  }, \n  {\n    authenticationFields: field =\u003e field.metadata \u0026\u0026 field.metadata.name.indexOf('auth') == 0,\n    authorizationFields: (field, user) =\u003e \n       field.metadata \u0026\u0026 \n       ((field.metadata.name == 'auth' \u0026\u0026 !field.metadata.body) || field.metadata.name == 'auth' \u0026\u0026 field.metadata.body == `(${user.role})`)\n  })\n```\n\nThe code above restricts the access to the `Product.owner` field to user with an `admin` role. For the sake of this demo, all requests are now being hardcoded so that the user is authenticated (i.e. the `user` object exists) and its role is `standard`. \n\nThe following request:\n```js\n{\n  products(id:2) {\n    id\n    name\n    owner\n  }\n}\n```\n\nwill now return:\n```js\n{\n  \"data\": {\n    \"products\": [\n      {\n        \"id\": \"2\",\n        \"name\": \"Product B\"\n      }\n    ]\n  },\n  \"warnings\": [\n    {\n      \"message\": \"Access denied for certain fields. The current response is incomplete.\",\n      \"path\": [\n        \"products.owner\"\n      ]\n    }\n  ]\n}\n```\n\nAs you can see, now that the request is authenticated, the `name` field is accessible, but because the user's role is `standard` rather tha admin, the `owner` property is not accessible.\n\nUpdate the role above to `admin` and see what happens.\n\n## Returning `null` Rather Than Removing Fields\n\nThe previous examples have demonstrated fields not being returned when the request is either not authenticated or lacking the adequate rights. However, this behavior might break some client libraries like the [apollo-client](https://github.com/apollographql/apollo-client) which expect the schema of the response to conform to the request schema. To allow support for such use cases, it is possible to nullify fields rather than removing them, thanks to the `nullifyUnauthorizedFields` property:\n\n```js\nconst authorize = graphqlAuth(\n  schemaAST, \n  (req, res, next) =\u003e {\n    const err = null\n    const user = { role: 'standard' }\n    next(err, user)\n  }, \n  {\n    authenticationFields: field =\u003e field.metadata \u0026\u0026 field.metadata.name.indexOf('auth') == 0,\n    authorizationFields: (field, user) =\u003e \n       field.metadata \u0026\u0026 \n       ((field.metadata.name == 'auth' \u0026\u0026 !field.metadata.body) || field.metadata.name == 'auth' \u0026\u0026 field.metadata.body == `(${user.role})`),\n       nullifyUnauthorizedFields: true\n  })\n```\n\n## Not Returning Partial Response\n\nSo far, all previous examples have demonstrated partial response being returned in case of missing authentication or missing rights. However, one other desired behavior could to fail completely with an HTTP 403 forbidden. This can be done using the `partialAccess` property.\n\n```js\nconst authorize = graphqlAuth(\n  schemaAST, \n  (req, res, next) =\u003e {\n    const err = null\n    const user = { role: 'standard' }\n    next(err, user)\n  }, \n  {\n    authenticationFields: field =\u003e field.metadata \u0026\u0026 field.metadata.name.indexOf('auth') == 0,\n    authorizationFields: (field, user) =\u003e \n       field.metadata \u0026\u0026 \n       ((field.metadata.name == 'auth' \u0026\u0026 !field.metadata.body) || field.metadata.name == 'auth' \u0026\u0026 field.metadata.body == `(${user.role})`),\n       nullifyUnauthorizedFields: true,\n       partialAccess: false\n  })\n```\n\n\n# This Is What We re Up To\nWe are Neap, an Australian Technology consultancy powering the startup ecosystem in Sydney. We simply love building Tech and also meeting new people, so don't hesitate to connect with us at [https://neap.co](https://neap.co).\n\nOur other open-sourced projects:\n#### Web Framework \u0026 Deployment Tools\n* [__*webfunc*__](https://github.com/nicolasdao/webfunc): Write code for serverless similar to Express once, deploy everywhere. \n* [__*now-flow*__](https://github.com/nicolasdao/now-flow): Automate your Zeit Now Deployments.\n\n#### GraphQL\n* [__*graphql-serverless*__](https://github.com/nicolasdao/graphql-serverless): GraphQL (incl. a GraphiQL interface) middleware for [webfunc](https://github.com/nicolasdao/webfunc).\n* [__*schemaglue*__](https://github.com/nicolasdao/schemaglue): Naturally breaks down your monolithic graphql schema into bits and pieces and then glue them back together.\n* [__*graphql-s2s*__](https://github.com/nicolasdao/graphql-s2s): Add GraphQL Schema support for type inheritance, generic typing, metadata decoration. Transpile the enriched GraphQL string schema into the standard string schema understood by graphql.js and the Apollo server client.\n* [__*graphql-authorize*__](https://github.com/nicolasdao/graphql-authorize.git): Authorization middleware for [graphql-serverless](https://github.com/nicolasdao/graphql-serverless). Add inline authorization straight into your GraphQl schema to restrict access to certain fields based on your user's rights.\n\n#### React \u0026 React Native\n* [__*react-native-game-engine*__](https://github.com/bberak/react-native-game-engine): A lightweight game engine for react native.\n* [__*react-native-game-engine-handbook*__](https://github.com/bberak/react-native-game-engine-handbook): A React Native app showcasing some examples using react-native-game-engine.\n\n#### Tools\n* [__*aws-cloudwatch-logger*__](https://github.com/nicolasdao/aws-cloudwatch-logger): Promise based logger for AWS CloudWatch LogStream.\n\n\n# License\nCopyright (c) 2018, Neap Pty Ltd.\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n* Neither the name of Neap Pty Ltd nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL NEAP PTY LTD BE LIABLE FOR ANY\nDIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND\nON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://neap.co\" target=\"_blank\"\u003e\u003cimg src=\"https://neap.co/img/neap_color_horizontal.png\" alt=\"Neap Pty Ltd logo\" title=\"Neap\" height=\"89\" width=\"200\"/\u003e\u003c/a\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolasdao%2Fgraphql-authorize","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicolasdao%2Fgraphql-authorize","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolasdao%2Fgraphql-authorize/lists"}