Implement role-based access control (RBAC)
You can implement role-based access control with Repose with the Header Normalization, the Authorization, and the API Validator filters. This guide takes you through the process of setting up RBAC with Repose.
1. Configure the Header Normalization filter
To prevent users from submitting their own roles, you will need to blacklist headers using the Header Normalization filter.
For more information about the configuration options in the Header Normalization filter, see Header Normalization filter.
2. Configure then Authentication filter
The Authentication filter will grab the user's roles from their authentication token and return those roles to Repose.
For more information about the configuration options in the Keystone v2 filter, see Keystone v2 filter.
3. Configure the RBAC filter
There are two mechanisms for doing the authorization side. If your API is minimal or your just getting started with it, then you might find the Simple RBAC filter most useful. It uses a very simple Domain Specific Language (DSL) that is similar to what other tools use for this basic mechanism. If on the other had your API is large and/or your authorizations are complex, then you will need the heavy lifting of the API Validation filter. Since the Simple way is very self explanatory, we will only dive into the more complex way here.
You will do most of your RBAC configuration here.
- We recommend that you build a table similar to the example below that contains endpoints and the roles that you wish to allow access to those endpoints.
|Method name||API action||a:creator||a:observer||a:admin|
|Create New Widget||POST /a/||x||x|
|List Widgets||GET /a/||x||x|
|Replace Widget||PUT /a/||x||x||x|
2. In the API Validator filter, set the enable-rax-roles attribute to true.
When the enable-rax-roles attribute is set to true, the check-headers attribute will also be enabled regardless of your setting.
3. In the WADL, include rax:roles with appropriate values to ensure access is controlled as expected.
- When defining rax:roles at the resource level, be aware that all sub-resources and methods will inherit the roles allowed at the resource level.
- Multiple roles can be specified by separating the role names with a space. If multiple roles are authorized for a resource and method, the user must have one of the allowed roles but is not required to have all roles.
Example API Validator filter configuration for RBAC.
The following example shows a section of the API Validator filter and WADL that is configured for RBAC.
With the above WADL and API Validator filter configuration, the following behavior will apply with a request with a user that has the a:observer role.
- GET or PUT is allowed.
- DELETE will return 403 Forbidden as the DELETE method inherits the a:admin role from its parent resource.
- PATCH will return 405 MethodNotAllowed.
- POST will return a 403 Forbidden, as the method is allowed for the resource but the user does not have the a:admin or the a:creator role.
For more information about the configuration options in the API Validator filter, see API Validation filter.
Return codes and conditions
|403||Forbidden||A requested resource or method requires a specific X-Roles header and that header is not found.|
|405||Method Not Allowed||The URI is valid, but the method is not appropriate for the URI.|
The status codes returned by authorization failures, via rax:roles extensions (403), differs from the statuses returned when roles are defined directly in the validator.cfg.xml (404 and 405).