@opuscapita/bouncer

@opuscapita/bouncer

OpusCapita Bouncer is a module providing several security APIs for securing endpoints and data based on users, roles and resource identifiers.

Using Bouncer

• In order to use Bouncer in your project you can either use Bouncer directly, as express middleware or through @opuscapita/web-init.

• For using Bouncer directly via API, please have a look at the API documentation wiki.

• To use Bouncer with express, simply use the prepared middleware.

Middleware example:

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

...

app.use(bouncer.middleware());

Attention: 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().

Defining resource groups (access 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:

{
    "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",
            "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], [responseFields] and [service]. 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). 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.

---

Services required to use Bouncer

In order to use Bouncer, the following additional services have to be available.

• Consul
• ACL
• Redis
• [User]
• [RabbitMQ]

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

---

Consul keys required

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

• redis/password
• mq/user
• mq/password

---

Events raised by Bouncer

• bouncer.permissionsReady

---

Events subscribed by Bouncer

None

---