Simple RBAC filter

Purpose

The Simple Role Based Access Control (RBAC) filter provides a way to get API validation for services without the need to create a WADL. 

General filter information

Filter name: simple-rbac

Filter configuration file: simple-rbac.cfg.xml

Filter configuration example: simple-rbac.xsd

Release: 7.1.2.0

Prerequisites

Headers: By default the X-Roles header is used, but this is configurable.

Preceding filters: This filter has no required preceding filters.

Proceeding filters: This filter has no required proceeding filters.

Basic configuration

Configure the Simple RBAC filter by editing the simple-rbac.cfg.xml file. 

1. Set Up Repose 

Configure Repose using either a cluster or a single instance configuration.

2. Add the Simple RBAC filter 
Add to Repose by including <filter name="simple-rbac"/> in your filter chain in the system-model.cfg.xml and include the simple-rbac.cfg.xml in your Repose configuration directory.

3. Configure the Simple RBAC filter 

Within the simple-rbac element, configure the following element:

  • Configure the role-header-name attribute to match requests according to the x-roles header.
  • Configure the resources element to hold a CDATA block that specifies resources, HTTP methods, and the roles that are allowed to access the resources or to point to a resource file.
  • If you need to point to your resource file, configure the href attribute to specify the name of the file. 

 

The following example shows a basic configuration for the Simple RBAC filter.

As of v7.1.7.0 the WADL parameter syntax (e.g. curly braces) allows for wildcarding a path segment.

Optional configurations

Delegation

In some cases, you may want to delegate the validation of a request down the chain to either another filter or to the origin service. Delegation prevents the Simple RBAC filter from failing the request by forwarding the request with the X-Delegated header that is set with a value which indicates how the filter would have failed if not in delegating mode. 

To place the filter in delegating mode, add the delegating element to the filter configuration with a quality that determines the delegation priority.

The format for the X-Delegated header value is “status_code={status-code}`component={filter-name}`message={failure message};q={delegating-quality}”.

Configurable parameters

XML schema definition

Example configuration

The simple-rbac file contains the following elements and attributes. Add the filter to your Repose deployment through the system model configuration.

ElementsAttributes

Required/

Optional

Description
<simple-rbac>-RequiredSpecifies the sub-elements and attributes to define your Simple RBAC configuration.
roles-header-nameOptional

Specifies the name of the header that passes the roles.

Default header name is X-Roles.

mask-rax-roles-403sOptional

If set to trueinstead of returning a FORBIDDEN (403), the response will be a NOT FOUND (404) if no methods are accessible or a METHOD NOT ALLOWED (405) if some methods are available.

Default value is false.

enable-api-coverageOptional

If set to true, this filter will record, via JMX, the number of times each state in the generated state machine (the underlying mechanism) is accessed. These values may be used to determine API usage and coverage. The path taken by each request is also logged to the named "api-coverage-logger" logger in the Log4J configuration. If that logger is not configured, then they are logged to the default handler.

Default value is false.

dot-outputOptional

Specifies the DOT output file for this validator. DOT is a plain text graph description language.

This is a simple way of describing graphs that both humans and computer programs can use.

wadl-outputOptional

Specifies the Web Application Description Language (WADL) output file for this validator.

This is a way of describing the API of a Web Application that both humans and computer programs can use.

<resources>-RequiredSpecifies a list of resources and HTTP methods and specifies the roles that are allowed to access those resources.
hrefOptional

Specifies a location to an external file which contains the Simple RBAC resources.

If the message element has a value and the href attribute is configured, the Simple RBAC will use what is configured in the value.

If the file that the href attribute points to is modified, the Simple RBAC will not reload the configuration. So the new RBAC file should be placed in a new file name (e.g. Dated) and the simple-rbac.cfg.xml file updated to point to it in order to guarantee the changes are utilized.

<delegating>-OptionalInclude this this element if you want this filter to populate the delegation headers.
qualityOptional

Specifies the quality of specific output headers.

When setting up a chain of delegating filters, the highest quality number will be the one that is eventually output.

Default value is 0.3.

component-nameOptionalThe component name used in the delegation header. This is particularly useful when multiple instances of an API-Checker based filter are used in the same filter chain. Default up to and including v7.1.7.0 is "api-checker", but was changed in v7.2.0.0 to "simple-rbac".

Return codes and conditions

Response Code
Description
Returned When:
403ForbiddenA requested resource or method requires a specific X-Roles header and HTTP Method combination, and that combination was not found.
404Not FoundThe Validation filter determines that the URI is invalid.
405Method Not AllowedThe URI is valid, but the method is not appropriate for the URI.

Request headers created

If you use delegation, the Simple RBAC filter will create the X-Delegated header. Otherwise, no request headers are created.