README.md

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:

x-exegesis-roles:
  - a
  - b

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

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:

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

npm install exegesis-plugin-roles

Example

Add this to your Exegesis options:

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:

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