2 |
3 | # Gateman.js
4 |
5 | Gatemanjs is an authorization system designed to manage roles and claims in node applications that use mongodb for data storage. It works together with mongoose to provide a fluent approach to managing roles and claims.
6 |
7 | ## Installation
8 |
9 | You can install gateman using npm package manager.
10 |
11 | ```
12 | npm install gatemanjs
13 | ```
14 |
15 | ## Usage
16 |
17 | Before using gateman in your node application, you'll have to import the gateman package and setup the gateman class by passing in a valid mongoose connection object
18 |
19 | ```
20 | var mongoose = require('mongoose');
21 | var gateman = require("gatemanjs").GateMan(mongoose);
22 | ```
23 |
24 | ### Creating roles & claims
25 | You have to create a role before using it in your application, Gateman provides an easy way of doing that.
26 |
27 | ```
28 | //Syntax
29 | gateman.createRole(roleName);
30 |
31 | //Example
32 | let role = await gateman.createRole("rolename");
33 | ```
34 | Creating claims is similar to creating roles
35 |
36 | ```
37 | //Syntax
38 | gateman.createClaim(claimName);
39 |
40 | //Example
41 | let role = await gateman.createRole("claimname");
42 | ```
43 |
44 | ##### Note: To get a collection of existing roles, you can use
45 | ```
46 | //Syntax
47 | gateman.getRoles(callback);
48 |
49 | //Example
50 | let roles = await gateman.getRoles();
51 | ```
52 |
53 | ### Allowing members of a role to perform a claim
54 | Adding claims to roles is made extremely easy. You do not have to create a claim in advance. Simply pass the name of the claim, and Gateman will create it if it doesn't exist.
55 |
56 | ```
57 | gateman.allow('role').to('claim'); //for an existing role
58 | ```
59 | You can also assign a claim to a role immediately after creating it
60 |
61 | ```
62 | let role = await gateman.createRole("admin");
63 | await gateman.allow("admin").to("delete");
64 |
65 | //this provides every member of the admin role the claim to delete
66 | ```
67 |
68 | ### Disallowing members of a role from performing a claim
69 | Retracting claims from a role is very easy, you just need the rolename and claimname
70 |
71 | ```
72 | await gateman.disallow('role').from('claim');
73 |
74 | //Gateman does nothing if the role doesn't possess the claim
75 | ```
76 |
77 | ### Checking for Role claims
78 | Checking if a Claim has been assigned to a Role can be done this way
79 |
80 | ```
81 | let result = await gateman.role('rolename').can('claimname');
82 | //result is true if the claim has been assigned, else it will be false
83 |
84 | ```
85 |
86 | ### Using gateman with user models
87 |
88 | It is important to set up your User model to extend the HasRolesAndClaims class from the gateman package.
89 |
90 | ```
91 | const mongoose = require('mongoose');
92 | const hasRolesAndClaims = require('gatemanjs').hasRolesAndClaims(mongoose);
93 |
94 | var UserSchema = mongoose.Schema({
95 | name: String,
96 | email: String
97 | });
98 |
99 | UserSchema.loadClass(hasRolesAndClaims);
100 | module.exports = mongoose.model('User', UserSchema)
101 | ```
102 |
103 | After setting up your user model, you can call gateman methods on your mongoose user model.
104 |
105 | ### Allowing users to perform a claim
106 | ```
107 | //Example
108 |
109 | let user = await UserModel.findOne({name: "chioma"});
110 | await user.allow("claim");
111 |
112 | /*
113 | The Gateman hasRolesAndClaims class is loaded into a valid mongoose model which means that the methods are only accessible to valid user objects.
114 | */
115 |
116 | //Disallowing a user from performing a claim
117 |
118 | let user = await UserModel.findOne({name: "chioma"});
119 | await user.disallow("claim");
120 |
121 | ```
122 |
123 | ### Assigning a role to a user
124 | Before assigning a role to a user, make sure it has been created.
125 | ```
126 | //Example
127 |
128 | let user = await UserModel.findOne({name: "chioma"});
129 | await user.assign("role");
130 |
131 | /*
132 | The Gateman hasRolesAndClaims class is loaded into a valid mongoose model which means that the methods are only accessible to valid user objects.
133 | */
134 |
135 | //Retracting a role from a user
136 |
137 | let user = await UserModel.findOne({name: "chioma"});
138 | await user.retract("role");
139 |
140 | ```
141 |
142 | ### Checking for User claims and Roles
143 | Gateman provides an easy way of verifying if a user belongs to a role or can perform a claim
144 |
145 | ```
146 | //To verify if a User belongs to a Role
147 |
148 | let user = await User.findOne({name: "chioma"});
149 | let userHasRole = await user.isA("role");
150 | if (userHasRole){
151 | //user belongs to role
152 | }
153 |
154 | //To verify if a User can perform a claim
155 |
156 | let user = await User.findOne({name: "chioma"});
157 | let userHasClaim = await user.can("claim");
158 | if (userHasClaim){
159 | //user can perform claim
160 | }
161 | ```
162 |
163 | ### Retrieving User Roles and Claims
164 | Gateman provides an easy way of retrieving a User's roles and/or claims
165 |
166 | ```
167 | //Returns a collection of Roles assigned to a User
168 |
169 | let user = await User.findOne({name: "chioma"});
170 | let roles = await user.getRolesForUser();
171 | console.log(roles);
172 |
173 | //Returns a collection of Claims a User can perform
174 |
175 | let user = await User.findOne({name: "chioma"}, (err, user)=>{
176 | let claims = await user.getClaimsForUser();
177 | console.log(claims);
178 | ```
179 |
180 | ## Documentation
181 | * [Usage](http://htmlpreview.github.com/?https://github.com/NwangwuOsitadinma/gateman/master/docs/out/index.html): Gateman methods
182 |
183 |
184 | ## Contributing
185 |
186 | Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
187 |
188 |
189 | ## Authors
190 |
191 | * **Ositadinma Nwangwu** - [NwangwuOsitadinma](https://github.com/NwangwuOsitadinma)
192 | * **Ibe Ogele** - [Ibesoft11](https://github.com/Ibesoft11)
193 |
194 | ## License
195 |
196 | This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details
197 |
198 | ## Acknowledgments
199 | * This project was inspired by Joseph Silber's [Bouncer](https://github.com/JosephSilber/bouncer)
200 | * Mongoose was used to build this
201 |
--------------------------------------------------------------------------------
/docs/assets/gatema.jpeg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/NwangwuOsitadinma/gateman/75bb7dcc9a2d3edf5e8417a136086628656d6d70/docs/assets/gatema.jpeg
--------------------------------------------------------------------------------
/docs/out/AllowOperations.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
81 |
111 |
82 |
108 |
109 |
110 | Constructor
83 |
84 |
107 |
85 |
106 | 86 | # 87 | 88 | 89 | new AllowOperations() 91 | 92 |
93 |
94 | Contains methods for managing application roles and claims
95 |
96 | -
97 |
98 | View Source 99 | 100 | AllowOperations.js, line 10 102 | 103 |
104 |
112 |
180 | Methods
113 |
114 |
115 |
179 |
116 |
117 |
118 |
119 |
142 |
143 |
163 |
177 |
178 | 120 | # 121 | 122 | 123 | async 124 | 125 | 126 | 127 | 128 | to(claimName) 130 | 131 | 132 |
133 | 134 | 135 | 136 | 137 |
138 | pass in the claim to be assigned to a role
139 |
140 | Parameters:
141 || Name | 145 |Type | 146 |Description | 147 |
|---|---|---|
claimName |
152 | 153 | String 154 | | 155 | 156 |pass a claim as a string if you called 157 | allow 158 | | 159 |
-
164 |
165 |
166 | View Source 167 | 168 | AllowOperations.js, line 24 170 | 171 |
172 |Usage
173 | 174 |await gateman.allow("rolename").to("claim");