docs(contextual-access): document group-based tool access - #1185
Draft
andrewconnor-arcade wants to merge 4 commits into
Draft
docs(contextual-access): document group-based tool access#1185andrewconnor-arcade wants to merge 4 commits into
andrewconnor-arcade wants to merge 4 commits into
Conversation
Adds the public configuration page for the group_access extension, alongside the existing rate-limiting page: how visibility gating is enforced, tool matcher precedence, the three identity backends, Dashboard and API setup, the staleness model, and fail-closed behavior. Two things get more space than their size suggests, because both fail silently rather than loudly: - identity matching. The backend looks a caller up by the identity the request carries, so an Arcade user ID that does not equal the directory login matches nothing, and fail-closed turns that into tools quietly missing. - SailPoint's API client rights. `idn:access-profiles:read` and `idn:roles:read` sound correct and are not sufficient; they authorize reading definitions rather than assignments, so a client with only those authenticates and then fails every lookup. Also records that a tool no rule matches stays visible, so a mistyped matcher governs nothing instead of hiding everything. Refs PLT-3234. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The page said a required group is a group name for both Okta and Entra ID. That is no longer accurate for Entra: a rule may carry the group's object ID, and a display name is honoured only for a security group that is not a Microsoft 365 group. The reason is worth an operator's attention rather than a footnote. Entra does not require display names to be unique and many tenants let ordinary members create groups, so a display-name rule can be satisfied by someone who creates a group with that name and joins it. Restricting the match to ordinary security groups removes the surface most members can add to but is not a guarantee, so the page recommends the object ID for anything sensitive and says where to copy it from. Also notes that this does not apply to Okta or SailPoint, where creating a group, access profile, or role is an administrative action. Refs PLT-3234. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
andrewconnor-arcade
force-pushed
the
andrewconnor/plt-3234-group-access-docs
branch
from
September 8, 2026 19:03
c27cff2 to
3b43986
Compare
The page said rules match access profile and role names. That is right for a role and wrong for an access profile, and wrong in a way that would send an operator to configure something that cannot work. SailPoint's access-items response documents `displayName` as the role display name on a role, but as the identity's display name on an access profile, and it carries no access profile name at all. There is nothing for a profile-name rule to match, so the rule carries the profile's ID. The page now states which value each rule shape matches, says where to copy the ID from, and explains why we do not resolve names for you: it would need `idn:access-profiles:read`, which the required-rights section deliberately excludes. Refs PLT-3234. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
andrewconnor-arcade
marked this pull request as ready for review
September 8, 2026 20:00
andrewconnor-arcade
marked this pull request as draft
September 8, 2026 20:01
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Public configuration page for the
group_accesscontextual-access extension, alongside the existing rate limiting page and following its structure.Draft until the engine work merges. The feature ships as a stack in the monorepo (PLT-3229 through PLT-3234); this page describes behavior that is built and green but not yet on
main. Holding it in draft so the docs never describe something a customer cannot use yet.What it covers
Enforcement at the tool access hook point and why it governs both discovery and execution, tool matcher precedence, the three identity backends and what access each needs, Dashboard and API setup, the staleness model, and fail-closed behavior with the per-rule opt-out.
Two things given deliberate weight
Both fail silently rather than loudly, which is what makes them worth a customer's attention up front:
idn:access-profiles:readandidn:roles:readsound like the right rights and are not sufficient: they authorize reading access profile and role definitions, not which identity holds them. A client granted only those authenticates successfully and then fails every membership lookup. This is the single most likely misconfiguration, so it gets a warning callout rather than a footnote.The page also states that a tool no rule matches stays visible, so a mistyped matcher governs nothing instead of hiding everything, and recommends gating on the provisioned Okta or Entra group where SailPoint provisions into one, since that is simpler to operate and closer to real time.
Checks
Vale is clean of errors on the new page. The remaining warnings are Microsoft's own field names (
application (client) ID,GroupMember.Read.Allapplication permission) and heading-case rules the sibling rate-limiting page also trips; I matched the section's existing conventions rather than diverging from its neighbor. Pre-commit hooks (Vale,_meta.tsxkey validation, redirect check, Ultracite) passed.Refs PLT-3234.
Note
Low Risk
Documentation-only changes; no application or engine code in this diff.
Overview
Adds a Group-Based Tool Access doc under contextual access, wired into the section nav via
_meta.tsxand listed inpublic/llms.txt.The new page documents the native
group_accessextension: enforcement at the tool access hook (discovery and execution), tool matcher precedence, Okta / Entra / SailPoint backends and credentials, Dashboard and plugins API setup, cache staleness, and fail-closed behavior with per-ruleallow_on_unavailable. It highlights operational pitfalls—Arcade user ID must match directory login, Entra object IDs for sensitive rules, SailPoint API scopes that look correct but are insufficient, and that unmatched tools stay visible.Reviewed by Cursor Bugbot for commit f1e4853. Bugbot is set up for automated code reviews on this repo. Configure here.