Files
coder/coderd/rbac/scopes_test.go
T
07f9018c61 feat: re-check the app allowlist at OAuth2 code redemption (#28740)
**TL;DR**

Second of the PLAT-480 stack. #28237 made the negotiated scope bound the
issued token; this PR makes a narrowing of an app's registered scopes
apply to codes that were already issued.

| PR | What it does |
|---|---|
| #28237 (merged) | Mints access tokens with the negotiated scope, so a
grant for one scope stops behaving as full access, and reports the
granted scope per RFC 6749 §5.1. |
| **#28740 (this)** | Re-checks the code's scope against the app's
registered scopes at redemption, closing the ten minute window in which
a narrowing was ignored. |
| #28744 | Makes code redemption single-use under concurrency. Carries
no scope logic and is independent of this PR. |

- #28237 has merged, so this targets main.
- No new endpoints and no schema change.

---

An authorization code is valid for ten minutes, and its scope is checked
against the app's registered scopes exactly once, when the code is
issued. A registration narrowed inside that window had the narrowing
ignored: the code still redeemed for a token carrying the wider scope.

- The token exchange re-checks the code's scope against the registration
as it stands at redemption and refuses with `invalid_grant`. RFC 6749
§5.2 reserves `invalid_scope` for the scope the client asked for, and
this one comes from the stored grant.
- The check is coverage rather than membership, and reuses the
comparison the authorize endpoint already runs. That comparison now goes
through a new `rbac.FirstScopeNotCovered`, which expands the allowlist
once rather than once per granted scope.
- Only the client can change its registered `scope`, through RFC 7592;
no administrator surface writes the column. The re-check reflects the
registration at redemption rather than constraining the client.
- Refresh keeps the scope originally granted. That is a product choice,
not an RFC requirement: a narrowing applies at the next authorization
rather than mid-session, so tightening an app's scopes does not break
integrations already running.
- Codes issued before migration 000569 carry `coder:all`. For an app
registered with a narrower `scope` those are refused at redemption until
they expire, at most ten minutes.

Stack: #28237 (merged), this PR, #28744.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Steven Masley <Emyrk@users.noreply.github.com>
2026-09-03 18:29:11 -07:00

350 lines
12 KiB
Go

package rbac_test
import (
"testing"
"github.com/stretchr/testify/require"
"github.com/coder/coder/v2/coderd/rbac"
"github.com/coder/coder/v2/coderd/rbac/policy"
)
func TestExpandScope(t *testing.T) {
t.Parallel()
t.Run("low_level_pairs", func(t *testing.T) {
t.Parallel()
cases := []struct {
name string
resource string
action policy.Action
}{
{name: "workspace:start", resource: rbac.ResourceWorkspace.Type, action: policy.ActionWorkspaceStart},
{name: "workspace:ssh", resource: rbac.ResourceWorkspace.Type, action: policy.ActionSSH},
{name: "template:use", resource: rbac.ResourceTemplate.Type, action: policy.ActionUse},
{name: "api_key:read", resource: rbac.ResourceApiKey.Type, action: policy.ActionRead},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
s, err := rbac.ScopeName(tc.name).Expand()
require.NoError(t, err)
// site-only single permission
require.Len(t, s.Site, 1)
require.Equal(t, tc.resource, s.Site[0].ResourceType)
require.Equal(t, tc.action, s.Site[0].Action)
require.Empty(t, s.ByOrgID)
require.Empty(t, s.User)
require.Equal(t, []rbac.AllowListElement{rbac.AllowListAll()}, s.AllowIDList)
})
}
})
t.Run("invalid_low_level", func(t *testing.T) {
t.Parallel()
invalid := []string{
"", // empty
"workspace:", // missing action
":read", // missing resource
"unknown:read", // unknown resource
"workspace:bogus", // unknown action
"a:b:c", // too many parts
}
for _, name := range invalid {
t.Run(name, func(t *testing.T) {
t.Parallel()
_, err := rbac.ScopeName(name).Expand()
require.Error(t, err)
})
}
})
}
func TestFirstScopeNotCovered(t *testing.T) {
t.Parallel()
tests := []struct {
name string
allowed []rbac.ScopeName
requested []rbac.ScopeName
want rbac.ScopeName
// wantErrContains names the side that could not be expanded, as in
// TestScopesCover.
wantErrContains string
}{
{
name: "EmptyRequestIsCovered",
allowed: []rbac.ScopeName{"workspace:read"},
requested: nil,
},
{
name: "EveryRequestedScopeCovered",
allowed: []rbac.ScopeName{"coder:workspaces.access"},
requested: []rbac.ScopeName{"workspace:read", "workspace:ssh"},
},
{
// The answer names which scope failed, not merely that one did.
name: "NamesTheFirstUncovered",
allowed: []rbac.ScopeName{"coder:workspaces.access"},
requested: []rbac.ScopeName{"workspace:read", "workspace:delete", "user_secret:delete"},
want: "workspace:delete",
},
{
name: "UnexpandableRequestedScopeNamed",
allowed: []rbac.ScopeName{"coder:workspaces.access"},
requested: []rbac.ScopeName{"workspace:read", "not_a_real_scope"},
want: "not_a_real_scope",
wantErrContains: "expand requested scope",
},
{
name: "UnexpandableAllowedScopeNamed",
allowed: []rbac.ScopeName{"not_a_real_scope"},
requested: []rbac.ScopeName{"workspace:read"},
want: "not_a_real_scope",
wantErrContains: "expand allowed scope",
},
{
// The alias validates but is not an expandable name, so callers
// must canonicalize first. Pinned because the allowed side is
// expanded once now, outside the per-scope loop.
name: "LegacyAliasIsNotExpandable",
allowed: []rbac.ScopeName{"all"},
requested: []rbac.ScopeName{"workspace:read"},
want: "all",
wantErrContains: "expand allowed scope",
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
got, err := rbac.FirstScopeNotCovered(test.allowed, test.requested)
if test.wantErrContains != "" {
require.ErrorContains(t, err, test.wantErrContains)
require.Equal(t, test.want, got, "an undecidable comparison must name the scope it could not decide")
return
}
require.NoError(t, err)
require.Equal(t, test.want, got)
})
}
}
// The two answer the same question, so a row that disagrees means one of them
// changed alone.
func TestFirstScopeNotCoveredAgreesWithScopesCover(t *testing.T) {
t.Parallel()
allowed := []rbac.ScopeName{"coder:workspaces.access", "coder:templates.build"}
for _, name := range rbac.ExternalScopeNames() {
canonical := rbac.CanonicalScopeName(rbac.ScopeName(name))
covered, err := rbac.ScopesCover(allowed, canonical)
require.NoError(t, err, "scope %q", name)
outside, err := rbac.FirstScopeNotCovered(allowed, []rbac.ScopeName{canonical})
require.NoError(t, err, "scope %q", name)
require.Equal(t, covered, outside == "", "scope %q", name)
}
}
func TestScopesCover(t *testing.T) {
t.Parallel()
tests := []struct {
name string
allowed []rbac.ScopeName
requested rbac.ScopeName
want bool
// wantErrContains names the side that could not be expanded. Asserting
// the side keeps rows that fail through different paths from passing
// on each other's errors.
wantErrContains string
}{
{
name: "IdenticalName",
allowed: []rbac.ScopeName{"workspace:read"},
requested: "workspace:read",
want: true,
},
{
// Name matching alone cannot decide this: coder:workspaces.access
// never mentions workspace:ssh by name, but its expansion covers it.
name: "CompositeCoversItsMember",
allowed: []rbac.ScopeName{"coder:workspaces.access"},
requested: "workspace:ssh",
want: true,
},
{
// The composite grants no permission on this resource at all.
name: "CompositeDoesNotCoverUnrelatedResource",
allowed: []rbac.ScopeName{"coder:workspaces.access"},
requested: "user_secret:delete",
want: false,
},
{
// Same resource, action the composite does not grant. Coverage
// compares the pair, not the resource alone.
name: "CompositeDoesNotCoverUngrantedActionOnSameResource",
allowed: []rbac.ScopeName{"coder:workspaces.access"},
requested: "workspace:delete",
want: false,
},
{
name: "AllCoversEverything",
allowed: []rbac.ScopeName{rbac.ScopeAll},
requested: "user_secret:delete",
want: true,
},
{
name: "NarrowScopeDoesNotCoverAll",
allowed: []rbac.ScopeName{"workspace:read"},
requested: rbac.ScopeAll,
want: false,
},
{
name: "ResourceWildcardCoversOneAction",
allowed: []rbac.ScopeName{"workspace:*"},
requested: "workspace:ssh",
want: true,
},
{
name: "OneActionDoesNotCoverResourceWildcard",
allowed: []rbac.ScopeName{"workspace:ssh"},
requested: "workspace:*",
want: false,
},
{
// A composite is covered only when every permission it expands
// to is granted, so a strict subset of them is not enough.
name: "PartialUnionDoesNotCoverComposite",
allowed: []rbac.ScopeName{"template:read", "file:create"},
requested: "coder:templates.build",
want: false,
},
{
// The allowed side is a union rather than a set of independent
// candidates, so one composite's permissions may be drawn from
// several allowed entries at once.
name: "UnionOfAllowedScopesCoversComposite",
allowed: []rbac.ScopeName{"template:read", "file:*", "provisioner_jobs:read"},
requested: "coder:templates.build",
want: true,
},
{
name: "EmptyAllowedCoversNothing",
allowed: nil,
requested: "workspace:read",
want: false,
},
{
// Not a false: a caller cannot distinguish "known and not
// covered" from "we could not tell", so an undecidable
// comparison is surfaced rather than answered.
name: "UnknownRequestedScopeErrors",
allowed: []rbac.ScopeName{rbac.ScopeAll},
requested: "not_a_real_scope",
wantErrContains: "expand requested scope",
},
{
name: "UnknownAllowedScopeErrors",
allowed: []rbac.ScopeName{"not_a_real_scope"},
requested: "workspace:read",
wantErrContains: "expand allowed scope",
},
{
// An implementation answering on the first match never reaches it.
name: "UnknownAllowedScopeErrorsBesideCoveringScope",
allowed: []rbac.ScopeName{rbac.ScopeAll, "not_a_real_scope"},
requested: "workspace:read",
wantErrContains: "expand allowed scope",
},
{
// The aliases IsExternalScope accepts are not expandable names,
// so callers must canonicalize before asking about coverage.
name: "NonCanonicalAliasErrorsRequestedAll",
allowed: []rbac.ScopeName{rbac.ScopeAll},
requested: "all",
wantErrContains: "expand requested scope",
},
{
name: "NonCanonicalAliasErrorsRequestedApplicationConnect",
allowed: []rbac.ScopeName{rbac.ScopeAll},
requested: "application_connect",
wantErrContains: "expand requested scope",
},
{
// The only row that would catch someone canonicalizing inside the
// allowed loop, which would silently widen what an allow list
// accepts without any caller asking for it.
name: "NonCanonicalAliasErrorsAllowedApplicationConnect",
allowed: []rbac.ScopeName{"application_connect"},
requested: rbac.ScopeApplicationConnect,
wantErrContains: "expand allowed scope",
},
{
name: "NonCanonicalAliasErrorsAllowedAll",
allowed: []rbac.ScopeName{"all"},
requested: rbac.ScopeAll,
wantErrContains: "expand allowed scope",
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
got, err := rbac.ScopesCover(test.allowed, test.requested)
if test.wantErrContains != "" {
require.ErrorContains(t, err, test.wantErrContains)
require.False(t, got, "an undecided comparison must not report coverage")
return
}
require.NoError(t, err)
require.Equal(t, test.want, got)
})
}
}
// TestCanonicalScopeName pins the alias mapping. Without it the two case arms
// could be swapped, so that requesting `all` persisted application_connect and
// the reverse, and the suite would stay green.
func TestCanonicalScopeName(t *testing.T) {
t.Parallel()
require.Equal(t, rbac.ScopeAll, rbac.CanonicalScopeName("all"))
require.Equal(t, rbac.ScopeApplicationConnect, rbac.CanonicalScopeName("application_connect"))
// Canonical names and low-level names are returned unchanged, so callers
// can canonicalize unconditionally.
require.Equal(t, rbac.ScopeAll, rbac.CanonicalScopeName(rbac.ScopeAll))
require.Equal(t, rbac.ScopeApplicationConnect, rbac.CanonicalScopeName(rbac.ScopeApplicationConnect))
require.Equal(t, rbac.ScopeName("workspace:read"), rbac.CanonicalScopeName("workspace:read"))
require.Equal(t, rbac.ScopeName("not_a_real_scope"), rbac.CanonicalScopeName("not_a_real_scope"))
}
// TestScopesCoverEveryExternalScope asserts the property the OAuth2 allowlist
// check depends on: coder:all is a ceiling over the whole external catalog, and
// every catalog name covers itself. A name that cannot be compared at all would
// otherwise reject every request naming it, which is a rejection no app owner
// could act on.
func TestScopesCoverEveryExternalScope(t *testing.T) {
t.Parallel()
// The aliases inherit this without being named here: TestScopeAliases pins
// that each one canonicalizes to a name this list offers.
for _, name := range rbac.ExternalScopeNames() {
scope := rbac.ScopeName(name)
covered, err := rbac.ScopesCover([]rbac.ScopeName{rbac.ScopeAll}, scope)
require.NoErrorf(t, err, "coder:all vs %q", scope)
require.Truef(t, covered, "coder:all must cover %q", scope)
covered, err = rbac.ScopesCover([]rbac.ScopeName{scope}, scope)
require.NoErrorf(t, err, "%q vs itself", scope)
require.Truef(t, covered, "%q must cover itself", scope)
}
}