{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"role-based-access-control-rbac","__idx":0},"children":["Role-based access control (RBAC)"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Deprecated docs"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The developer portal beta is ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/product-timelines"},"children":["approaching end of life"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Realm and Reunite instead. Read the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/migrate-from-legacy-portal"},"children":["migration guide"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The RBAC feature is supported starting with version 1.0.0-beta.90 of the Developer portal."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The role-based access control feature is available in the Developer portal to Enterprise customers."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With RBAC, you can define permissions for 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). You can make some content on your portal completely private, or make it visible only to a restricted group (for example: partners, developers, or administrators)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To achieve this, your developer portal must integrate with an identity provider (IdP) that lets you map user identities to roles and permissions on the portal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction-to-roles-and-permissions","__idx":1},"children":["Introduction to roles and permissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Role names and permission names are not predefined in the portal configuration, and you can set them to any custom name. For example, you can configure the following roles:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["developer"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Partner"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-editor"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["and set custom names for permissions:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read-partner-docs"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read:internal-docs"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Experimental"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access-secrets"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["However, role names must match the user identity configuration from your IdP settings, so they are not entirely arbitrary. If a \"Partner\" role is configured in IdP and has permissions mapped to it in the portal configuration, users with that role can access restricted content when they log into the portal. If the \"Partner\" role mapping is undefined on the portal side, users with that role are not able to access restricted content."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can define permissions globally (for all pages in the Developer portal), or for each individual page. When setting permissions for individual pages, you only have to specify the permission name, not the role name. For example, setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission:'read-internal-docs'"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.md"]}," means that all roles with that permission are able to access the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.md"]}," page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Permissions also affect search results. The search scope automatically adjusts to the user's role. In the search results, the users only get the content they are permitted to access."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To configure RBAC:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your developer portal must be:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["either ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/on-premise#host-the-portal-on-premise"},"children":["deployed using Docker"]}," on-premise"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["or ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/on-premise#host-the-portal-in-redocly-workflows"},"children":["hosted in Redocly Workflows with an OIDC identity provider"]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You must create the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rbac.yaml"]}," configuration file in the root of your developer portal project. In this file, configure the roles and permissions hierarchy, and set the default role."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You need access to your identity provider settings, where you must ensure the claim names, scopes, and roles match the configuration on the developer portal side. Use this information to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["[On-premise only]"]}," configure OIDC-related settings in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]}," file"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["[Workflows only]"]}," set up the OIDC identity provider and access control for the portal"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration-steps","__idx":3},"children":["Configuration steps"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#define-the-roles-and-permissions-hierarchy"},"children":["Define roles and permissions hierarchy"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rbac.yaml"]}," file. You may also want to ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#set-permissions-for-pages"},"children":["set per-page permissions"]}," in your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".md(x)"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," files to override the defaults and restrict access to specific content."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set up the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#configure-the-oidc-authorization-server"},"children":["authorization server URL"]}," in your identity provider settings. Additional configuration may be necessary on the IdP side, such as setting up claims. Consult the relevant administrator in your enterprise for help."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure OIDC on the portal side."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["[On-premise only]"]}," ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/on-premise#host-the-portal-on-premise"},"children":["Add OIDC settings"]}," to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth"]}," section of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]}," file"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["[Workflows only]"]}," Configure OIDC on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Org settings > Identity providers"]}," page, then set up OIDC login on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Portal settings > Manage access"]}," page"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You have to use a custom component to override the default navbar. Redocly provides the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/developer-portal-starter/pull/27/files"},"children":["custom login component example"]}," that you can modify and implement according to your needs. The component allows you to display a login link in the portal navbar and makes it possible for users to log into the portal via the configured identity provider."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["[On-premise only]"]}," It may be necessary to provide a custom JWT (JSON Web Token) ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#configure-custom-claims-preprocessing"},"children":["claims preprocessor"]}," depending on your identity provider configuration."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"define-the-roles-and-permissions-hierarchy","__idx":4},"children":["Define the roles and permissions hierarchy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rbac.yaml"]}," file, define the hierarchy of roles in your portal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is an example of how to set roles and permissions in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rbac.yaml"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"roles:\n  Trainee:\n    permissions:\n      - read-partner-docs\n      - see-experimental-pages\n  Employee:\n    roles:\n      - Trainee\n    permissions:\n      - read:internal-docs\n  Admin:\n    roles:\n      - Employee\n    permissions:\n      - read-secrets\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As shown in the example, a role can contain other roles, in which case it inherits the permissions of the containing roles."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The portal comes with the following default roles:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guest"]}," - every visitor has this role with a single permission to read all public content on the portal."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authenticated-user"]}," - every logged in user has this role regardless of IdP claims."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You cannot extend the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guest"]}," role with additional permissions."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-permissions-for-pages","__idx":5},"children":["Set permissions for pages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a page doesn't have any specific permission, that means the page uses the default permission from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rbac.yaml"]}," file. By default, all pages use the permissions from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guest"]}," role."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a permission is specified for a page, it is treated as a \"required permission\". That means all visitors must have the specified permission mapped to their role in order to access the page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can override the default permission on a per-page basis. This is supported in Markdown and MDX pages, as well as in reference docs pages (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," files)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To set permissions for Markdown and MDX pages, add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission: your-permission"]}," to their front matter, for example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"md","header":{"controls":{"copy":{}}},"source":"---\ntitle: My Getting Started Page\npermission: read-partner-docs\n---\n","lang":"md"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To set permissions for reference docs pages, add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission: your-permission"]}," entry to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," configuration file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"title: API Reference\ntype: reference-docs\ndefinitionId: test\npermission: 'read:internal-docs'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that permissions configured in this way apply to the entire API reference docs page. Setting permissions for specific operations, tags, or tag groups is not supported."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-permissions-for-directories","__idx":6},"children":["Set permissions for directories"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can set permissions for all pages (and other files like static assets) in any directory at once. To configure permissions for all files in a directory and all its child directories, create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissions.rbac.yaml"]}," file in that directory."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The file must contain the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission: your-permission"]}," entry like in the example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"permission: read-partner-docs\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that any per-page permissions set in files in the directory always take precedence over directory-level permissions. For example, if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read-partner-docs"]}," is set on the directory level, but a file has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read-internal-docs"]},", the directory permission does not overwrite the file permission. The file keeps its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read-internal-docs"]}," permission."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configure-the-oidc-authorization-server","__idx":7},"children":["Configure the OIDC authorization server"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["On-premise"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In your OIDC identity provider settings, set the following URL for \"Allowed Callback URLs\":"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http://your-developer-portal.example.com/_auth/oidc"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["localhost"]}," is supported as well:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http://localhost/_auth/oidc"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workflows"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The URL for \"Allowed Callback URLs\" in your OIDC IdP settings should match the following pattern:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://your-developer-portal-project.redoc.ly/_auth/oidc"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you have configured a custom domain for your developer portal in Workflows, the URL should match it:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://your-custom-domain.example.com/_auth/oidc"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can find the exact URL in the Workflows interface on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings > Access control"]}," page of your portal project. The option ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OIDC Members only"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Public > Allow login > OIDC"]}," must be enabled."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configure-custom-claims-preprocessing","__idx":8},"children":["Configure custom claims preprocessing"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Applies only to on-premise Developer portal deployments."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["roles"]}," claim of JWT token to get a list of user roles."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In some cases, it might be necessary to preprocess JWT claims received from the IdP (for example, if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can provide a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["claimPreprocessor"]}," - a JavaScript function to process claims from IdP."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The function is called at runtime and accepts two arguments:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["claims"]}," - JST claims from your IdP provider"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["context"]}," - contains a name of the claim Redocly uses to extract roles (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["roles"]}," by default)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example preprocessor:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const ROLES_MAP = {\n  'admin': 'DocsAdmin',\n  'ext': 'Partner'\n}\n\nexports.default = async (claims, { ROLES_CLAIM_NAME }) => {\n  if (claims.issuer === 'auth0') {\n    return {\n      ...claims, # return original claims\n      [ROLES_CLAIM_NAME]: ['ExternalUser'] # and roles list\n    }\n  }\n\n  return {\n    ...claims,\n    [ROLES_CLAIM_NAME]: claims.roles.map(role => ROLES_MAP[role])\n  };\n};\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["claimPreprocessor"]}," parameter in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth"]}," section of your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"auth:\n  claimsPreprocessor: ./claims.js\n  idps:\n    main:\n      type: oidc\n      loginWith: OIDC\n      configurationUrl: https://redoc-ly.auth0.com/.well-known/openid-configuration\n      clientId: your-id\n      scopes:\n        - openid\n        - name\n        - family_name\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-permissions-for-navigation-items","__idx":9},"children":["Set permissions for navigation items"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, if OIDC is enabled, navigation menu items (in navbar and footer only) are hidden if the authenticated user doesn't have access to the corresponding pages."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can override this behavior to either hide or show a navigation menu item. Keep in mind that modifying the appearance of an item does not change its access control. In other words, permissions for menu items can be different from permissions for pages those items link to. That way, users can still see all the items in a menu, but they can't access the pages that are restricted for their role."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"navbar-item-permissions","__idx":10},"children":["Navbar item permissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To change the navbar RBAC configuration, edit the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nav"]}," section of your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]}," as in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"nav:\n  - page: getting-started.md\n    permission: read-docs\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission"]}," key here overrides the permission set in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getting-started.md"]}," file (or the default permission) for the purpose of displaying the menu item. It does not change the permission for accessing the page, or modify the permission value if it's defined in the file."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"footer-item-permissions","__idx":11},"children":["Footer item permissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To change the footer RBAC configuration, edit the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["footer"]}," section of your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]}," as in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"footer:\n  copyrightText: © Copyright Redocly 2018. All right reserved\n  columns:\n    - group: Docs\n      permission: read:docs\n      items:\n        - label: Examples\n          page: md-examples.md\n        - separator: Some Group\n        - label: Documentation\n          href: 'http://github.com'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the footer, you can add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission"]}," key either for the entire ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["group"]}," or for individual ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item"]}," entries."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configure-rbac-in-workflows","__idx":12},"children":["Configure RBAC in Workflows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your developer portal is hosted in Workflows, you can control some of the RBAC settings from the Workflows interface. The majority of the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#configuration-steps"},"children":["configuration steps"]}," are the same as for on-premise developer portals."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"limitations","__idx":13},"children":["Limitations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Redocly Workflows does not support custom claims preprocessing. However, you may define the scope claim name used inside of the identity provider configuration. For example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n   \"id\": \"123\",\n   \"exp\": \"expiration_date\",\n   \"https://redocly.com/roles\": [\n   \"Employee\",\n   ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prerequisites-1","__idx":14},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rbac.yaml"]}," configuration file in the developer portal repository. Redocly Workflows uses the settings and applies the permissions defined in the file. In addition, you can ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#set-permissions-for-pages"},"children":["set permissions for individual pages or specific directories"]}," in the developer portal repository."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identity provider configured in your Redocly Workflows organization. The RBAC feature currently only supports OIDC, and organization owners can configure it on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Org settings > Identity providers"]}," page. Use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["RBAC roles claim name"]}," field to set a specific claim name depending on how it's configured on the identity provider side. This allows the developer portal to map the roles configured in the identity provider to the roles and permissions configured for the RBAC feature."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"enable-rbac-in-workflows","__idx":15},"children":["Enable RBAC in Workflows"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log into Workflows, and select the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Portals"]}," tab."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["From the list of portals, select the portal for which you want to enable RBAC."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings > Manage access"]}," page."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["From the docs section, for either production or previews, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Manage"]}," to view the corresponding ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Manage docs access"]}," dialog."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set the value to \"Protected\" with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SSO login"]}," or to \"Public\" with the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Allow SSO login"]}," option selected. Select the identity provider from the dropdown. Your identity provider ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must allow"]}," the corresponding callback URL. Contact your identity provider administrator for help."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To define how the developer portal behaves when a user doesn't have permissions to access specific content and attempts to access it, select one of the options under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Access denied behavior for RBAC"]},". Supported options are ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Forbidden"]}," and ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Not found"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save"]}," button to save changes."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/access-control-923f61a6e0036d24.png","alt":"Set up access control"},"children":[]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Configuration"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Roles and permissions settings are taken from configuration files and individual pages in the developer portal repository. You cannot configure them through the Workflows interface."]}]}]},"frontmatter":{"excludeFromSearch":true},"tagList":["admonition","partial"],"title":"Role-based access control (RBAC)","lastModified":"2025-05-28T16:01:32.000Z"}