Last updated

Configure RBAC for pages and content

By default, all pages of your project are public and do not require authorization to be accessed. However, you can configure RBAC to limit access based on team assignment. You can also override globally assigned project permission requirements in the redocly.yaml file on a per-page basis for the entire page and for only certain sections of content on the page.

The types of pages you can limit access to include the following:

  • Markdown pages
  • React pages
  • API documents

Markdown pages

Configuring RBAC in front matter only affects the running project and only for the pages that include it in the front matter. To set permissions for a Markdown page in the front matter, add the rbac configuration to its front matter and provide team access settings.

For example, in the following front matter configuration example, only members of the Admin team can access the page and all other users are redirected to the 404 page:

---
title: My Getting Started Page
rbac:
  'Admin': admin
  '*': none
---

React pages

To set permissions for specific React pages (*.page.tsx), you need to export a special constant, frontmatter, and add the rbac configuration to it, as illustrated in the following example:

export const frontmatter = {
  rbac: {
    Admin: 'admin',
    '*': 'none',
  },
  seo: {
    title: 'Custom React page',
  },
};

In the example, only members of the Admin team can access the page and all other users are redirected to the 404 page.

API documents

You can set permissions for an entire API definition in the apis section of the redocly.yaml file.

For example, in the following example, the openapi/api-definition.yaml API definition is accessible only to users that are assigned to the Admin group:

apis:
  sample@default:
    root: 'openapi/api-definition.yaml'
    rbac:
      'Admin': 'admin'
      '*': 'none'

Set permissions for content

By default, when you set RBAC permissions for a page, authorized users are able to see all the content on that page. However, sometimes you may need to hide a section of content on the page from certain teams. You can set permissions by teams for specific content on Markdown and React pages.

Markdown pages

You can use the if Markdoc tag to conditionally render content on a Markdown page, based on a user's teams.

For example, in the following example, the project renders the text between the Markdoc tags only if the authenticated user is assigned to the Admin team:

{% if includes($rbac.teams, "Admin") %}
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
{% /if %}

React pages

You can use a convenient React hook that can be accessed in the React pages of the project to access the current user's teams. You can then use this hook to conditionally render certain content or perform other actions, as in the following example:

import { useCurrentUserTeams } from '@project/hooks';

export default function () {
  const userTeams = useCurrentUserTeams();

  return <div>{userTeams.includes('Admin') ? 'You are an admin' : 'You are not an admin'}</div>;
}

In the example, the text the project renders between the div tags depends on if the authenticated user is assigned to the Admin team.

Resources