|
1 | | -# graphql-authz |
| 1 | +# graphql-authz |
| 2 | + |
| 3 | +graphql-authz is a Casbin authorization middleware for graphql-js |
| 4 | + |
| 5 | +[![NPM version][npm-image]][npm-url] |
| 6 | +[![NPM download][download-image]][download-url] |
| 7 | +[](https://packagephobia.now.sh/result?p=graphql-authz) |
| 8 | +[](https://github.com/node-casbin/graphql-authz/actions) |
| 9 | +[](https://coveralls.io/github/node-casbin/graphql-authz?branch=master) |
| 10 | +[](https://github.com/node-casbin/graphql-authz/releases/latest) |
| 11 | +[](https://gitter.im/casbin/lobby) |
| 12 | + |
| 13 | +[npm-image]: https://img.shields.io/npm/v/graphql-authz.svg?style=flat-square |
| 14 | +[npm-url]: https://npmjs.org/package/graphql-authz |
| 15 | +[download-image]: https://img.shields.io/npm/dm/graphql-authz.svg?style=flat-square |
| 16 | +[download-url]: https://npmjs.org/package/graphql-authz |
| 17 | + |
| 18 | +## Installation |
| 19 | + |
| 20 | +```shell |
| 21 | +npm install graphql-authz |
| 22 | +// or |
| 23 | +yarn add graphql-authz |
| 24 | +``` |
| 25 | + |
| 26 | +## Get Started |
| 27 | + |
| 28 | +This package should use with `graphql` and `graphql-middleware` |
| 29 | + |
| 30 | +To limit access to each endpoint, you can use casbin policy or graphql directive. |
| 31 | + |
| 32 | +In the policy method, you can use casbin policy like |
| 33 | +```csv |
| 34 | +p,user,project.members,query |
| 35 | +p,roleb,project.members.tickets.id,query |
| 36 | +``` |
| 37 | +to restricted access to each endpoint. |
| 38 | + |
| 39 | +In the directive method, you can use directive `can` to do the same thing. |
| 40 | + |
| 41 | +Here's a minimal example. You can find the full example in the `tests/server.test.ts` |
| 42 | +```typescript |
| 43 | +import { applyMiddleware } from 'graphql-middleware'; |
| 44 | +import { newMiddleware, CanDirective } from 'graphql-authz'; |
| 45 | +import { newEnforcer } from 'casbin'; |
| 46 | +import { ApolloServer } from 'apollo-server'; |
| 47 | +import { makeExecutableSchema } from '@graphql-tools/schema'; |
| 48 | +import { CasbinContextEnforcerKey } from '../src'; |
| 49 | +// After graphql-js 14.0.0, you should manually define directive in the SDL. |
| 50 | +const typeDefs = ` |
| 51 | +directive @can(who: String!) on FIELD_DEFINITION |
| 52 | +
|
| 53 | +type User { |
| 54 | + id: ID! @can(who: "user") |
| 55 | + name: String @can(who: "someone") |
| 56 | +} |
| 57 | +`; |
| 58 | + |
| 59 | + const resolvers = { |
| 60 | + // something |
| 61 | + }; |
| 62 | + const schemaWithDirective = makeExecutableSchema({ |
| 63 | + typeDefs, |
| 64 | + resolvers, |
| 65 | + schemaDirectives: { |
| 66 | + can: CanDirective, |
| 67 | + }, |
| 68 | + }); |
| 69 | + // If you want to use directive, this is necessary. |
| 70 | + // You can ignore this in the policy only method. |
| 71 | + |
| 72 | + const enforcer = await newEnforcer('tests/casbin.conf', 'tests/policy.csv'); |
| 73 | + // As for now, you should use model tests/casbin.conf to initialize enforcer. |
| 74 | + // For more info about enforcer, plz refer to https://github.com/casbin/node-casbin |
| 75 | + |
| 76 | + const middleware = await newMiddleware({ |
| 77 | + ctxMember: 'user', // middleware will get current user role from the graphql context[ctxMember] |
| 78 | + enforcer: enforcer, // Casbin Instance |
| 79 | + }); |
| 80 | + |
| 81 | + // Apply middlware to graphql schema |
| 82 | + const schemaWithDirectiveMiddleware = applyMiddleware(schemaWithDirective, middleware); |
| 83 | + |
| 84 | + const server = new ApolloServer({ |
| 85 | + schema: schemaWithDirectiveMiddleware, |
| 86 | + context: ({ req }) => { |
| 87 | + // Provide necessary info in the context. |
| 88 | + const token = req.headers.authorization || ''; |
| 89 | + |
| 90 | + // Try to retrieve a user with the token |
| 91 | + const user = getUser(token); |
| 92 | + |
| 93 | + const a: any = {}; |
| 94 | + a[CasbinContextEnforcerKey] = enforcer; |
| 95 | + a['user'] = user; |
| 96 | + return a; |
| 97 | + }, |
| 98 | + }); |
| 99 | +``` |
| 100 | + |
| 101 | +## Getting Help |
| 102 | + |
| 103 | +- [Node-Casbin](https://github.com/casbin/node-casbin) |
| 104 | + |
| 105 | +## License |
| 106 | + |
| 107 | +This project is under Apache 2.0 License. See the [LICENSE](LICENSE) file for the full license text. |
0 commit comments