exegesis-plugin-roles


Description

Adds support for the "x-exegesis-roles" vendor extension, which adds support for
restricting which operations are available to which users after they have been
authenticated. Authenticators can optionally return "roles" for a user.
"x-exegesis-roles" can be specified either as an array of "role" strings, or as
an array of such arrays.

For example:

``yaml
x-exegesis-roles:
- a
- b
`

would only allow access to an operation if a user has both the 'a' and 'b'
role, or:

`yaml
x-exegesis-roles:
- [a]
- [b, c]
`

would only allow access to an operation if a user has the 'a' role, or has
both the 'b' and 'c' role.

"x-exegesis-roles" can be defined on the root OpenAPI object, in which case
all operations in the document will require those roles. This can be overridden
by specifying "x-exegesis-roles" in an individual operation. An empty array
indicates a user requires no roles:

`yaml
x-exegesis-roles: []
`

If "x-exegesis-roles" is defined on an operation which has no security
requirements defined, this will throw an error.

Roles do not apply to security schemes with the "oauth2" type; scopes apply
there instead.

Allowed in:

* OpenAPI Object
* Operation Object

Installation

`sh
npm install exegesis-plugin-roles
`

Example

Add this to your Exegesis options:

`js
import exegesisRolesPlugin from 'exegesis-plugin-roles';

options = {
plugins: [
exegesisRolesPlugin({
// List of all allowed roles. If you try to use any roles that
// aren't in this list in your document, an error will be thrown.
allowedRoles: ['user', 'admin', 'ops']
})
]
};
`

In your OpenAPI 3.x document:

`yaml
paths:
'/kittens':
get:
description: Get a list of kittens
security:
- basicAuth: []
- oauth: ['readOnly']
post:
description: Add a new kitten
security:
- basicAuth: []
- oauth: ['readWrite']
x-exegesis-roles: ['admin'] # Only users with the "admin" role may call this.
``

The "get" operation can only be executed if the request matches one of the two
listed security requirements. The "post" operation can only be executed if
the security requirements are matched, and the current "user" has the "admin"
role.

Copyright 2018 Jason Walton