Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/romainlanz/adonis-guard
🔰 Authorization provider built on top of @slynova/fence
https://github.com/romainlanz/adonis-guard
acl adonis adonisjs authorization
Last synced: 2 months ago
JSON representation
🔰 Authorization provider built on top of @slynova/fence
- Host: GitHub
- URL: https://github.com/romainlanz/adonis-guard
- Owner: RomainLanz
- License: mit
- Created: 2018-03-20T14:46:39.000Z (almost 7 years ago)
- Default Branch: develop
- Last Pushed: 2022-12-07T10:36:07.000Z (about 2 years ago)
- Last Synced: 2024-10-14T20:55:34.907Z (3 months ago)
- Topics: acl, adonis, adonisjs, authorization
- Language: JavaScript
- Homepage:
- Size: 392 KB
- Stars: 54
- Watchers: 4
- Forks: 9
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Adonis Guard 🔰
This package is an **authorization provider** built on top of [@slynova/fence](https://github.com/Slynova-Org/fence).
## Getting Started
Install the package using the `adonis` CLI.
```bash
> adonis install adonis-guard
```
Follow instruction that are displayed ([or read them here](https://github.com/RomainLanz/adonis-guard/blob/master/instructions.md)).
## Defining your authorization
### Gate
Gates must be defined inside the `start/acl.js` file. This file will be loaded only once when the server is launch.
To define a gate, use the `Gate` facade.
```js
// start/acl.js
const Gate = use('Gate')
Gate.define('gateName', (user, resource) => {
// Payload
// e.g. return user.id === resource.author_id
})
```
### Policy
You can generate a new policy by using the command `adonis make:policy {name}`.
This will generate a file in `app/Policies/{Name}Policy.js`.
To attach a policy to a resource, you need to call the `policy` method of the `Gate` facade.
```js
// start/acl.js
const Gate = use('Gate')
Gate.policy('App/Models/MyResource', 'App/Policies/MyPolicy')
```
## Usage
Adonis Guard automaticaly share an instance of the `guard` in the context of each request.
To validate the authorization of a user you simply need to extract it from the context and run the gate/policy.
```js
// Controller
async show ({ guard, params }) {
const post = await Post.find(params.id)
if (guard.denies('show', post)) {
// abort 401
}
// ...
}
```
```js
// RouteValidator
async authorize () {
const post = await Post.find(this.ctx.params.id)
if (this.ctx.guard.denies('show', post)) {
// abort 401
}
// ...
}
```
You can also use it in your view to choose to display or not an element.
```html
@if(guard.allows('edit', post))
Edit
@endif
@can('edit', post)
Edit
@endcan
@cannot('edit', post)
Not allowed!
@endcannot
```
The `@can` and `@cannot` tags have the same signature as `guard.allows()` and `guard.denies()`.
You can also use the middleware `can` in your route.
Notice that this middleware doesn't work with resource. It will execute a gate with the loggedIn user only.
```js
Route.get('/admin/posts', 'Admin/PostController.index')
.middleware('can:viewAdminPosts')
```
A second argument can be supplied that will replace a resource in your gate. This is useful when you want to have dynamic route rules.
```js
Route.get('/admin/posts', 'Admin/PostController.index')
.middleware('can:hasRole,admin,editor')
```
`admin,editor` will be extracted into an array that you can retrieve as the second parameter in your gate.
**Public API**
```js
guard.allows('gateName/Policy Method', resource) // It will use per default the authenticated user or return false if not authenticated
guard.denies('gateName/Policy Method', resource) // It will use per default the authenticated user or return true if not authenticated
guard.allows('gateName/Policy Method', resource, user)
guard.denies('gateName/Policy Method', resource, user)
guard.can(user).pass('gateName').for(resource)
guard.can(user).callPolicy('Policy Method', resource)
```