Access Control
Access control can be configured at a variety of levels, as described below. These controls can be used either individually or in combination. If you have any questions, please reach out.
Global Authentication
Where enabled, this setting requires every user to log in before they can even reach the landing/home page. If you’re looking for a completely sealed-off portal, this is the setting for you.
This is a fixed, global setting that FixSpec will set during onboarding. It can be changed over time; just drop us a line.
Page-Level Control
If you would like guest (unauthenticated) users to be able to hit your landing page and view some content without being authenticated, then you can configure the portal to allow this. This is done by setting the guestVisibility, authenticatedVisibility and/or roles attributes in the portal.yaml (for top-level navigation) and sidebar.yaml (within sections) configurations.
| Attribute | Accepted values |
|---|---|
guestVisibility |
show: This item should always be visible and accessible (default). |
| hide: This item should be completely hidden for unauthenticated (guest) users. | |
| invite: The link item is visible but with a padlock icon next to it. If a user clicks on it, they are directed to the login page as opposed to the normal URL | |
authenticatedVisibility |
show: This item should always be visible (default). |
| hide: always hide even though they are logged in. | |
roles |
The set of roles that are permitted to view this item. In YAML files, this is a YAML array; within the :::visibility fence, use a comma-separated list instead. |
Note that if a user directly types or pastes a URL which requires authentication, they will be blocked from viewing it until they log in.
On-Page Authentication Control
There may be certain sections within a page that you would like to show or hide from unauthenticated users, or only show to users with a certain role. This is achieved using the :::visibility gate which accepts the same guestVisibility, authenticatedVisibility and roles attributes described above.
md:::visibility guestVisibility="hide"
This content would be hidden from guest users but visible for logged-in users.
:::
md:::visibility guestVisibility="invite"
This content is hidden from guests and instead they are invited to log in (see banner below).
:::
Cascading Access
Note that the visibility and role requirements cascade down the sidebar hierarchy. This means that if the top-level item is hidden or requires a role that the user does not have, all of its children will be hidden as well, regardless of their own settings. If, additionally, a child-level (nested) item has further visibility constraints, then a user must satisfy BOTH in order to see the content.
markdown// In this example fragment from `sidebars.yaml`, users need the "portal"
// role to see the group-level item, and each of the child pages. Access
// to "Whitelabelling" would ALSO require the "content" role.
- label: Detailed Reference
page: reference/whitelabelling.md
roles: [portal]
items:
- page: reference/whitelabelling.md
label: Portal White Labelling
roles: [content]
- page: reference/navigation.md
label: Header & Sidebar Navigation # Users only need "portal" to see this item
The picture is less clear, however, for top-level navigation items defined in portal.yaml, as the navbar element points to the starting URL of a section; it has no knowledge of the sidebar hierarchy underneath. It will therefore control the first page of a section, but not the children - you must control these using sidebars.yaml.
markdown// In this example `portal.yaml` fragment, guest users will be restricted
// from viewing `/platform/concepts/architecture.md` without first logging in,
// but other pages within this section (controlled by `sidebars.yaml`)
// would be accessible unless they had similar marking in that YAML file.
- navbar:
items:
- page: platform/concepts/architecture.md
label: API Conformance Platform
guestVisibility: invite
- page: portal/index.md
label: White-Labelled Portal
Frequently Asked Questions
You need Global Authentication enabled. This is a configuration that only FixSpec can manage, so just drop us a line.
Roles can be set in the admin dashboard. See Setting Firm Roles for more details.
There is no pre-defined or set list of roles; a role is simply a string “tag” that you can associate and remove from customers as you wish. You can make a list of roles which suits your business needs and extend them as you wish.