role-based-access-control-rbac.md

description
This page provides the technical details of the RBAC policy

Role-based Access Control (RBAC)

{% hint style="warning" %} This feature requires Gravitee's Enterprise Edition. {% endhint %}

Overview

You can use the role-based-access-control policy (RBAC policy) to control access to a resource by specifying the required roles to access it. The roles are checked against request attribute gravitee.attribute.user.roles. The policy can be configured to either:

• Allow only incoming requests with roles exactly matching the configured roles (strict mode)
• Allow incoming requests with at least one role matching the configured roles

Functional and implementation information for the role-based-access-control policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 HTTP proxy APIs. It cannot be applied to v4 message APIs or v4 TCP proxy APIs. {% endhint %}

{% tabs %} {% tab title="HTTP proxy API example" %} Sample policy configuration:

{
  "rbac": {
    "roles": ["read", "write", "admin"],
    "strict": true
  }
}

{% endtab %} {% endtabs %}

Configuration

Phases

The phases checked below are supported by the role-based-access-control policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

The role-based-access-control policy can be configured with the following options:

Property	Required	Description	Type	Default
roles	true	The list of required roles	Array of strings
strict	true	Validation mode — strict or not (must or should)	boolean	true

Compatibility matrix

The following is the compatibility matrix for APIM and the role-based-access-control policy:

Plugin version	Supported APIM versions
1.x	All

Errors

HTTP status code	Message
400	* The roles associated with the request are not valid
403	* No roles are associated with the current request * Role(s) associated with the request do not match required role(s)

You can use the response template feature to override the default responses provided by the policy. These templates must be defined at the API level (see the API Console Response Templates option in the API Proxy menu).

The error keys sent by this policy are as follows:

Key	Parameters
RBAC_NO_USER_ROLE (403)	-
RBAC_INVALID_USER_ROLES (400)	-
RBAC_FORBIDDEN (403)	-

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-role-based-access-control/blob/master/CHANGELOG.md" %}