@opuscapita/bouncer
OpusCapita Bouncer is a module providing several security APIs for securing endpoints in REST services.
Bouncer can be used to define two different types of resources:
- REST (Server side resources)
- UI (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 @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:
const Bouncer = require('@opuscapita/bouncer');
const bouncer = new Bouncer();
const app = express();
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() which, if used, also require 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 is available.
- req.opuscapita.getUserTenants()
- Returns an array of tenants a user has access to on the current endpoint.
- req.opuscapita.getUserTenantsByUrl(url, serviceName = null)
- Returns an array of tenants a user has access to on a specific endpoint.
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:
{
"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 [allow], [remove]], [responseFields [allow], [remove]], [service]
. The type field can either define "rest" or "ui" types. 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.
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.
{
"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.
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:
Events raised by Bouncer
Events subscribed by Bouncer
None