npm package: @opuscapita/bouncer
Description: API and express middleware for OpusCapita ACl service based access security.
Latest version: 1.3.0

**Expect this library to be split into front-end and back-end implementations in the near future**

![](https://img.shields.io/bundlephobia/min/@opuscapita/bouncer)
![](https://img.shields.io/node/v/@opuscapita/bouncer)
![](https://img.shields.io/npm/types/@opuscapita/bouncer)

# @opuscapita/bouncer
OpusCapita bouncer JS library provides security APIs interface for Andariel platform.

Bouncer can be used to define two different types of resources:

 * [REST](#defining-rest-resource-groups-for-bouncer) (Server side resources)
 * [UI](#defining-ui-resource-groups-for-bouncer) (Client side resources)

## Using Bouncer

* In order to use Bouncer in your project, you can either use Bouncer directly as an express middleware or through [web-init](https://github.com/OpusCapita/web-init).
* For using Bouncer directly via API, please have a look at the API documentation [wiki](https://github.com/OpusCapita/bouncer/wiki).

To use Bouncer with express, simply use the prepared middleware:

```JS
const Bouncer = require('@opuscapita/bouncer');

const bouncer = new Bouncer();
await bouncer.registerPermissions(); // Use this only on the initial startup as it will register all local permissions via Andariel event at the platform.

const app = express();
app.use(bouncer.middleware());
```

> Bouncer requires the *opuscapita* namespace to be available inside the request object passed to the middleware by express. It ueses opuscapita.logger, opuscapita.serviceClient and opuscapita.userData() which, if used, also requires [useridentity-middleware](https://github.com/OpusCapita/useridentity-middleware).

---

## req.opuscapita methods
Bouncer extends the **req.opuscapita** namespace with several, request bound methods where some of which can only be used if [useridentity-middleware](https://github.com/OpusCapita/useridentity-middleware) is available.

Returns a list of users that have access to a certain resource group (permission) on a certain tenant.

`req.opuscapita.getUsersByPermissionAndTenant(serviceName, resourceGroupId, tenantId) : Promise`

Returns an array of tenants a user has access to on the current endpoint.

`req.opuscapita.getUserTenants() : Promise`

Returns an array of tenants a user has access to on a specific endpoint even in a foreign service.

`req.opuscapita.getUserTenantsByUrl(url, serviceName = null) : Promise`

Returns an array of objects containing either a supplierId or a customerId field depending on whenever
a tenant is a supplier or a customer.

`req.opuscapita.splitUserTenants(tenants)`

> The getUserTenants() functions are using the xroles feature of the user token (jwt) in order to provide this functionality. If the token is not available e.g. on a public resource, getUserTenants() will always return an empty array.

> As of October 2018, a user's tenants can be configured using the user role editor in the BNP front end.

##### Usage example
```JS
async function myEndpoint(req, res)
{
    // Get all user tenants for the current endpoint.
    const tenants = await req.opuscapita.getUserTenants();

    // If the tenants array contains a *, access to all tenants is granted.
    if(tenants.includes('*'))
    {
        res.json({ message : 'Wildcard access granted.' });
    }
    else
    {
        // Split the list of tenants into customer and supplier IDs.
        // Returns [ { supplierId, customerId }, { supplierId, customerId }, ... ]
        const split = req.opuscapita.splitUserTenants(tenants);

        // Filter and map down to the raw IDs.
        const supplierIds = split.filter(split => split.supplierId).map(split => split.supplierId);
        const customerIds = split.filter(split => split.customerId).map(split => split.customerId);

        res.json({ supplierIds, customerIds });
    }
}
```

---

## Defining REST resource groups for Bouncer.

By default, Bouncer tries to load the **src/server/acl.json** file to get its resource groups. The file has to be in JSON format and should contain the following structure:

```JSON
{
    "my-resource-group-read": {
        "name": {
            "en": "My resource group.",
            "de": "Meine Resource Group."
        },
        "description": {
            "en": "A full description of my resrouce group e.g. for UI permission editors.",
            "de": "Eine komplette Beschreibung meiner Resource Group z.B. für UI Editoren."
        },
        "resources": [{
            "type": [ "rest", "ui" ],
            "resourceId": "^/api/myEndpoint$",
            "actions": ["view"],
            "requestFields": {
                "allow": ["field1", "field3", "field4"]                
            },
            "responseFields": {
                "allow" : ["field1", "field2"]
            }
        }]
    },
    "my-resource-group-write": {
        "name": {
            "en": "My resource group.",
            "de": "Meine Resource Group."
        },
        "description": {
            "en": "A full description of my resrouce group e.g. for UI permission editors.",
            "de": "Eine komplette Beschreibung meiner Resource Group z.B. für UI Editoren."
        },
        "resources": [{
            "type": "rest",
            "resourceId": "^/api/myEndpoint(/.*)?$",
            "actions": ["create", "edit"],
            "requestFields": {
                "remove": ["createdBy", "updatedBy", "createdAt", "updatedAt"]                
            },
            "responseFields": {
                "allow" : ["field1", "field2"]
            }
        }]
    },
    "foreign-service-group": {
        "service": "foreign-service",
        "name": {
            "en": "Foreign resource group.",
            "de": "Fremde Resource Group."
        },
        "description": {
            "en": "A full description of my resrouce group e.g. for UI permission editors.",
            "de": "Eine komplette Beschreibung meiner Resource Group z.B. für UI Editoren."
        },
        "resources": [{
            "type": "rest",
            "resourceId": "^/api/enpoint$",
            "actions": ["create"],
            "requestFields": {
                "remove": ["createdBy", "updatedBy", "createdAt", "updatedAt"]                
            }
        }]
    }
}
```

The **first level** of this structure defines the actual resource group. The key set here is the so called `resourceGroupId`.

On the **second level** you have the resource group's readable `name` and `description`. Both translated to all languages supported by the system. If the `service` property is defined, this resource group will be assigned to the service named there and will not be used for the local service. This feature allows defining resource groups for other services.

The **same level** defines the resources (**endpoints**) the resource group applies to. These resources can be defined using `type, resourceId, actions, [requestFields [allow], [remove]], [responseFields [allow], [remove]], [service]`. The type field can either define "rest" or "ui" types or both as an array definition `["rest", "ui"]`. The last three are optional. The `resourceId` field is used to describe the actual endpoint using **RegExp**.

The resource group Actions can either be **create (POST), view (GET), edit (PUT), delete (DELETE), head (HEAD), options (OPTIONS), patch (PATCH)**. The `requestFields` and `responseFields` definition can contain a list of allowed (whitelisted) or removed (blacklisted) fields. These functionality only applies to **objects** and **arrays of objects**. Keys can also describe **nested** properties e.g. 'key1.key2.key3'. Blacklisted keys will always outweigh whitelisted.

> **ATTENTION:** In case a user has access to multiple resource groups within the same service and the requested resource matches multiple resource groups, these groups get merged internally in order to grant the sum of all permissions on that resource.

---

## Defining UI resource groups for Bouncer.

By default, Bouncer tries to load the **src/server/acl.json** file to get its resource groups. The file has to be in JSON format and should contain the following structure. The main differences to the REST resource definition is located in the `type` property and the not existing `requestFields` and `responseFields` properties. If desired, you can also define the type as an array containing both "rest" and "ui" (`["rest", "ui"]`).

```JS
{
    "my-resource-group": {
        "name": {
            "en": "My resource group.",
            "de": "Meine Resource Group."
        },
        "description": {
            "en": "A full description of my resrouce group e.g. for UI permission editors.",
            "de": "Eine komplette Beschreibung meiner Resource Group z.B. für UI Editoren."
        },
        "resources": [{
            "type": "ui",
            "resourceId": "^/(?!api).*",
            "actions": ["view", "create", "edit", "delete"]
        }]
    }
}
```

---

## Services required to use Bouncer

In order to use Bouncer, the following **additional services** have to be available in a productive environment.

* Consul
* ACL
* RabbitMQ

For detailed service definitions, please have a look at the [docker-compose.yml](docker-compose.yml) file.

---

## Consul keys required

The following consul configuration (kv) keys have to be set in order to use bouncer:

* mq/user
* mq/password

---

## Events raised by Bouncer

* bouncer.permissionsReady

---

## Events subscribed by Bouncer

None

---

## Default configuration
```JS
{
    serviceName : config.serviceName,
    permissions : process.cwd() + '/src/server/acl.json',
    aclServiceName : 'acl',
    logger : new Logger(),
    roles : {
        alwaysAllow : [ ],
        alwaysDeny : [ ]
    },
    publicPaths : [
        '^/public',
        '^/static',
        '^/api/health/check$',
        '^/api/list/apis$'
    ]
}
```