项目作者: nicolasdao

项目描述 :
Authorization middleware for graphql-serverless. Add inline authorization straight into your GraphQl schema.
高级语言: JavaScript
项目地址: git://github.com/nicolasdao/graphql-authorize.git
创建时间: 2018-02-26T03:03:57Z
项目社区:https://github.com/nicolasdao/graphql-authorize

开源协议:Other

下载


graphql-authorize · NPM License Neap

Authorization middleware for 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 apis (including an optional GraphiQL interface) to the most popular serverless platforms:

Decorate your fields with something similar to this in your GraphQl schema:

  1. type Product {
  2. id: ID!
  3. @auth
  4. name: String!
  5. shortDescription: String
  6. }

Then define a rule similar to this one:

  1. {
  2. authenticationFields: field => field.metadata && field.metadata.name == 'auth'
  3. }

If the user is not authenticated (more about this below), then a GraphQl query similar to this:

  1. {
  2. products(id:2) {
  3. id
  4. name
  5. }
  6. }

will return an HTTP response with status 200 similar to this:

  1. {
  2. "data": {
  3. "products": [
  4. {
  5. "id": "2"
  6. }
  7. ]
  8. },
  9. "warnings": [
  10. {
  11. "message": "Access denied for certain fields. The current response is incomplete.",
  12. "path": [
  13. "products.name"
  14. ]
  15. }
  16. ]
  17. }

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). This is usually rather important client libraries using caching like the apollo-client which would break otherwise.

Table Of Contents

Install

node

  1. npm install graphql-authorize --save

How To Use It

Basics

An example will worth a thousand words. Follow those steps:

  1. Create a new npm project: npm init
  2. Install the following packages: npm install graphql-s2s graphql-serverless graphql-authorize webfunc lodash --save
  3. Create a new index.js as follow:

    1. const graphqlAuth = require('graphql-authorize')
    2. const { getSchemaAST, transpileSchema } = require('graphql-s2s').graphqls2s
    3. const { graphqlHandler } = require('graphql-serverless')
    4. const { app } = require('webfunc')
    5. const { makeExecutableSchema } = require('graphql-tools')
    6. const _ = require('lodash')
    7. // STEP 1. Mock some data for this demo.
    8. const productMocks = [
    9. { id: 1, name: 'Product A', shortDescription: 'First product.', owner: 'Marc Stratfield' },
    10. { id: 2, name: 'Product B', shortDescription: 'Second product.', owner: 'Nic Dao' }]
    11. const variantMocks = [
    12. { id: 1, name: 'Variant A', shortDescription: 'First variant.' },
    13. { id: 2, name: 'Variant B', shortDescription: 'Second variant.' }]
    14. // STEP 2. Creating a basic GraphQl Schema augmented with some non-standard authorizaion metadata
    15. // thanks to the 'graphql-s2s' package (https://github.com/nicolasdao/graphql-s2s).
    16. const schema = `
    17. type Product {
    18. id: ID!
    19. @auth
    20. name: String!
    21. shortDescription: String
    22. owner: String
    23. }
    24. type Variant {
    25. id: ID!
    26. name: String!
    27. shortDescription: String
    28. }
    29. type Query {
    30. products(id: Int): [Product]
    31. variants(id: Int): [Variant]
    32. }
    33. `
    34. const productResolver = {
    35. Query: {
    36. products(root, { id }, context) {
    37. const results = id ? productMocks.filter(p => p.id == id) : productMocks
    38. if (results.length > 0)
    39. return results
    40. else
    41. throw new Error(`Product with id ${id} does not exist.`)
    42. }
    43. }
    44. }
    45. const variantResolver = {
    46. Query: {
    47. variants(root, { id }, context) {
    48. const results = id ? variantMocks.filter(p => p.id == id) : variantMocks
    49. if (results.length > 0)
    50. return results
    51. else
    52. throw new Error(`Variant with id ${id} does not exist.`)
    53. }
    54. }
    55. }
    56. // STEP 3. Transpiling our schema on steroid to a standard schema using the 'transpileSchema'
    57. // function from the 'graphql-s2s' package (https://github.com/nicolasdao/graphql-s2s).
    58. const executableSchema = makeExecutableSchema({
    59. typeDefs: transpileSchema(schema),
    60. resolvers: _.merge(productResolver, variantResolver)
    61. })
    62. // STEP 4. Creating the Express-like middleware that will define the authorization rules that will give
    63. // access or not to certain fields.
    64. const schemaAST = getSchemaAST(schema)
    65. const authorize = graphqlAuth(
    66. // AST of the Graphql schema augmented with metadata
    67. schemaAST,
    68. // Function that must terminate by a call to the 'next' callback with 2 required arguments:
    69. // @param {Object} err Potential error object useful for identifying the source of the
    70. // authentication failure.
    71. // @param {Object} user If this object exists, then the authentication based on data contained
    72. // in the 'req' object is successfull, otherwise it is not.
    73. (req, res, next) => {
    74. // This example below simulates a situation where all request will always be
    75. // unauthenticated.
    76. const err = null
    77. const user = null
    78. next(err, user)
    79. },
    80. // Defines the authentication rules, i.e. the rule on each field that determines
    81. // whether that field requires authentication.
    82. {
    83. authenticationFields: field => field.metadata && field.metadata.name.indexOf('auth') == 0
    84. })
    85. // STEP 5. Creating a GraphQL and a GraphiQl endpoint
    86. const graphqlOptions = {
    87. schema: executableSchema,
    88. graphiql: {
    89. endpoint: '/graphiql'
    90. }
    91. }
    92. app.all(['/', '/graphiql'], authorize, graphqlHandler(graphqlOptions))
    93. // STEP 5. Starting the server
    94. app.listen(4000)
  4. Run node index.js

  5. Browse to http://localhost:4000/graphiql
  6. Execute a query similar to this in graphiql:

    1. {
    2. products(id:2) {
    3. id
    4. name
    5. }
    6. }

    Because we’ve hardcoded that all requests are unauthenticated (ref. STEP 4. user = null), this request above will yield the following result HTTP 200 response:

    1. {
    2. "data": {
    3. "products": [
    4. {
    5. "id": "2"
    6. }
    7. ]
    8. },
    9. "warnings": [
    10. {
    11. "message": "Access denied for certain fields. The current response is incomplete.",
    12. "path": [
    13. "products.name"
    14. ]
    15. }
    16. ]
    17. }

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.

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). This is usually rather important client libraries using caching like the apollo-client which would break otherwise.

Managing Authorizations

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

In STEP 2, updates the schema as follow:

  1. type Product {
  2. id: ID!
  3. @auth
  4. name: String!
  5. shortDescription: String
  6. @auth(admin)
  7. owner: String
  8. }

In STEP 4, update the code as follow:

  1. const authorize = graphqlAuth(
  2. schemaAST,
  3. (req, res, next) => {
  4. const err = null
  5. const user = { role: 'standard' }
  6. next(err, user)
  7. },
  8. {
  9. authenticationFields: field => field.metadata && field.metadata.name.indexOf('auth') == 0,
  10. authorizationFields: (field, user) =>
  11. field.metadata &&
  12. ((field.metadata.name == 'auth' && !field.metadata.body) || field.metadata.name == 'auth' && field.metadata.body == `(${user.role})`)
  13. })

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

The following request:

  1. {
  2. products(id:2) {
  3. id
  4. name
  5. owner
  6. }
  7. }

will now return:

  1. {
  2. "data": {
  3. "products": [
  4. {
  5. "id": "2",
  6. "name": "Product B"
  7. }
  8. ]
  9. },
  10. "warnings": [
  11. {
  12. "message": "Access denied for certain fields. The current response is incomplete.",
  13. "path": [
  14. "products.owner"
  15. ]
  16. }
  17. ]
  18. }

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

Update the role above to admin and see what happens.

Returning null Rather Than Removing Fields

The 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 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:

  1. const authorize = graphqlAuth(
  2. schemaAST,
  3. (req, res, next) => {
  4. const err = null
  5. const user = { role: 'standard' }
  6. next(err, user)
  7. },
  8. {
  9. authenticationFields: field => field.metadata && field.metadata.name.indexOf('auth') == 0,
  10. authorizationFields: (field, user) =>
  11. field.metadata &&
  12. ((field.metadata.name == 'auth' && !field.metadata.body) || field.metadata.name == 'auth' && field.metadata.body == `(${user.role})`),
  13. nullifyUnauthorizedFields: true
  14. })

Not Returning Partial Response

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

  1. const authorize = graphqlAuth(
  2. schemaAST,
  3. (req, res, next) => {
  4. const err = null
  5. const user = { role: 'standard' }
  6. next(err, user)
  7. },
  8. {
  9. authenticationFields: field => field.metadata && field.metadata.name.indexOf('auth') == 0,
  10. authorizationFields: (field, user) =>
  11. field.metadata &&
  12. ((field.metadata.name == 'auth' && !field.metadata.body) || field.metadata.name == 'auth' && field.metadata.body == `(${user.role})`),
  13. nullifyUnauthorizedFields: true,
  14. partialAccess: false
  15. })

This Is What We re Up To

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

Our other open-sourced projects:

Web Framework & Deployment Tools

  • webfunc: Write code for serverless similar to Express once, deploy everywhere.
  • now-flow: Automate your Zeit Now Deployments.

GraphQL

  • graphql-serverless: GraphQL (incl. a GraphiQL interface) middleware for webfunc.
  • schemaglue: Naturally breaks down your monolithic graphql schema into bits and pieces and then glue them back together.
  • 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.
  • graphql-authorize: Authorization middleware for graphql-serverless. Add inline authorization straight into your GraphQl schema to restrict access to certain fields based on your user’s rights.

React & React Native

Tools

License

Copyright (c) 2018, Neap Pty Ltd.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • 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.
  • 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.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NEAP PTY LTD BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Neap Pty Ltd logo