Admin section access#
Squareone’s /admin section collects the operator-facing pages: sending user notifications, managing Gafaelfawr service tokens, managing OpenID Connect clients, and the Sentry tools page.
Each of those pages calls a different API, and each of those APIs is guarded by its own Gafaelfawr scope — scopes that are set per Phalanx environment and are not discoverable at runtime.
Squareone therefore does not hard-code which scope guards which page.
Instead every admin page has a fixed page id, and the adminPageScopes configuration key maps those ids to the scopes that grant access to them in your environment.
adminPageScopes:
notifications: ['admin:notifications']
serviceTokens: ['admin:token']
oidcClients: ['admin:oidc']
sentry: ['exec:admin']
The values above are also the defaults, so a deployment that uses Gafaelfawr’s standard admin scopes can omit adminPageScopes entirely — or name only the pages whose scopes it changes, leaving the rest at their defaults.
Page ids#
The keys are fixed by the application; an unrecognized key fails configuration validation at startup rather than being silently ignored.
Page id |
Route |
Purpose |
|---|---|---|
|
|
Compose and browse the user notifications sent through Semaphore. |
|
|
Create, search, and revoke Gafaelfawr service tokens. |
|
|
Manage Gafaelfawr’s OpenID Connect clients. |
|
|
Link to the Sentry dashboard and exercise error and log reporting. |
How the mapping is applied#
Access is any-of: a user may use a page when they hold at least one of the scopes listed for it. That mapping drives the whole section:
The header user menu offers an “Admin” link to anyone who can reach at least one admin page.
The admin sidebar lists only the pages the signed-in user holds a scope for, so nobody is offered a page that would answer
403./adminredirects to the first page in that filtered list. Someone holding onlyadmin:oidclands directly on/admin/oidc-clients.A user who can reach no admin page at all sees a “No admin pages are available for your account” message instead of a redirect, and no “Admin” link in the user menu.
Each admin page gates on its own entry. Someone who arrives at a page directly — from a bookmark, or a link shared by a colleague with different scopes — without a scope that page lists sees an “Unauthorized” note naming the scopes that would have granted access, in place of the page. There is no redirect: the person asked for that page, so the answer is about that page.
There is no single “admin” scope.
exec:admin opens the admin section only because the sentry page’s default scope list happens to name it; point sentry at another scope and exec:admin grants nothing on its own.
Navigation order is code-defined and not configurable, so the redirect target for a user who can see several pages follows the order in the sidebar.
Which admin pages exist is likewise fixed by the application: adminPageScopes controls access to pages, not their presence.
Hiding a page#
Configuring a page with an empty scope list hides it from everyone, which is the supported way to switch a page off in an environment where the underlying service is not deployed:
adminPageScopes:
oidcClients: []
Relationship to the ingress#
This mapping is a client-side gate.
The authoritative restriction on the /admin prefix is the Gafaelfawr-authenticated ingress in Squareone’s Phalanx chart, which admits users holding any of the admin scopes.
Keep the ingress’s scope list and adminPageScopes in agreement: a scope that adminPageScopes grants a page but the ingress does not admit leaves the user unable to reach the page at all.