Role-based access control (RBAC)

The role-based access control feature is available in the Developer portal to Enterprise customers. The Developer portal must be deployed using Docker for this feature to work.

With RBAC, you can define permissions for accessing specific parts of your Developer portal. Permissions are actions that a user with a particular role is allowed to perform (for example: read, modify, or delete data).

Roles usually correspond to positions within an organization (for example: administrator, employee, contractor). In other words, a role is a set of permissions that applies to a specific type of user. It's possible to assign more than one role to a user.

Roles can relate to each other, and these relationships between roles are represented as a hierarchy. This allows a role to inherit all permissions of its "subordinate" roles in the hierarchy. In practice, this means that a role can contain other roles and their permissions, in addition to its own permissions.

Permissions are not pre-defined and you can set up them yourself. For example, you can configure the following permissions:

• read-partner-docs
• read-internal-docs
• see-experimental-pages
• read-secrets

The required permissions can be defined globally (for all pages in the Developer portal), or for each individual page, including OpenAPI definition files.

The RBAC configuration involves the following steps:

• configure roles and permissions hierarchy in the rbac.yaml file in the portal root directory
• add permission labels to your .md(x) pages and .page.yaml files
• if necessary, provide a custom JWT (JSON Web Token) claims preprocessor

Configure OIDC server app

In the settings of your OIDC IdP provider, set the following URL for "Allowed Callback URLs":

http://your.server.com/_auth/oidc

localhost is supported as well:

http://localhost/_auth/oidc

Configure roles

Add the rbac.yaml file to the Developer portal root directory and define the hierarchy of roles in your project.

Here is an example rbac.yaml file:

roles:
  Trainee:
    permissions:
      - read-partner-docs
      - see-experimental-pages
  Employee:
    roles:
      - Trainee
    permissions:
      - read-internal-docs
  Admin:
    roles:
      - Employee
    permissions:
      - read-secrets

As shown in the example, a role can contain other roles, in which case it inherits the permissions of the containing roles.

Also, by default, every visitor will have a role guest with a single permission guest.

Warning: the guest role cannot be extended with permissions yet.

Set required permissions for pages

If permissions are not specified, all pages get the guest permission by default.

To set a per-page permission in a Markdown file, add permission: value to its front matter, for example:

---
title: My Getting Started Page
permission: read-partner-docs
---

To set permissions for Reference docs, add the permission entry to the .page.yaml configuration file:

title: API Reference
type: redoc
definitionId: test
permission:  read-internal-docs

Set permissions for directories

You can set permissions for all pages (or static assets) in any directory. To protect all files in a directory and all its child directories, create a permissions.rbac.yaml file in that directory, containing the following:

permission: your-permission

Configure custom claims preprocessing

Redocly uses the roles claim of JWT token to get a list of user roles.

In some cases, it might be necessary to preprocess JWT claims received from the IdP (for example, if roles claim is not returned and you need to infer it based on other claims, or if you need to map roles from IdP to internal roles).

You can provide a claimPreprocessor - a JavaScript function to process claims from IdP.

The function is called at runtime and accepts two arguments:

• claims - JST claims from your IdP provider
• context - contains a name of the claim Redocly uses to extract roles (roles by default).

Example preprocessor:

const ROLES_MAP = {
  'admin': 'DocsAdmin',
  'ext': 'Partner'
}

exports.default = async (claims, { ROLES_CLAIM_NAME }) => {
  if (claims.issuer === 'auth0') {
    return {
      ...claims, # return original claims
      [ROLES_CLAIM_NAME]: ['ExternalUser'] # and roles list
    }
  }

  return {
    ...claims,
    [ROLES_CLAIM_NAME]: claims.roles.map(role => ROLES_MAP[role])
  };
};

Then, set the claimPreprocessor parameter in the auth section of your siteConfig.yaml.

claimPreprocessor: ./claims.js

Protect menu elements

By default, if OIDC is enabled, menu items (header and footer only) will be hidden if the authenticated user doesn't have access to the corresponding pages/API definitions.

You can override this behavior to either hide or show a menu item. Keep in mind that modifying the appearance of an item does not change its access control.

Header

To change the header RBAC configuration, edit the nav section of your siteConfig.yaml as in the following example:

nav:
  - page: getting-started.md
    permission: read-docs

Adding the permission key here overrides the permission set in the getting-started.md file, or the default permission. It does not change the page permission though.

Footer

To change the footer RBAC configuration, edit the footer section of your siteConfig.yaml as in the following example:

footer:
  copyrightText: © Copyright Redocly 2018. All right reserved
  columns:
    - group: Docs
      permission: read:docs
      items:
        - label: Examples
          page: md-examples.md
        - separator: Some Group
        - label: Documentation
          href: 'http://github.com'

As shown in the example above, you can add permission either for group or for item entries.