fix(oidc): allow OrgRoleIDScope downscoping in token exchange (#12563)

# Which Problems Are Solved

- Token exchange rejects `urn:zitadel:iam:org:roles🆔{orgID}` when
that scope is not already present on the subject or actor token
(`invalid_scope`).
- A documented least-privilege pattern — exchanging a broad access token
for one whose roles claims are limited to a single organization — has
been broken since the v4.15.3 token-exchange hardening and was not
restored by #12312.
- A naive allow-any-`roles:id` exception would let a previously narrowed
token widen again (switch org filter, or drop the filter and get all
role orgs), including via an actor token's filter on actor-path
exchanges.
- A client-requested bare `urn:zitadel:iam:org:roles🆔` (empty org id)
is not a meaningful filter and should be rejected on exchange.

# How the Problems Are Solved

- Treats `OrgRoleIDScope` as a restriction filter with downscope-only
semantics via `applyOrgRoleIDScopeDownscoping(requested,
ceilingScopes)`:
- union / standard exchange passes the **subject** token scopes as the
ceiling (actor filters ignored)
- impersonation (scopeless `user_id` / `id_token` subject) passes the
**actor** token scopes as the ceiling
- ceiling unfiltered → any requested `roles:id` is allowed (broad →
narrow)
  - ceiling filtered → requested filters must be ⊆ that set
- ceiling filtered but request omits them → inherit the ceiling (omit
must not re-widen)
- Rejects a **client-requested** bare `urn:zitadel:iam:org:roles🆔` in
`validateTokenExchangeScopes` after normalize (before empty-request
fallback). Input tokens may still carry the bare prefix as a degenerate
ceiling; empty-request / omit inherit does not re-trigger the rejection.
- Keeps non-restriction scopes on the existing subject ∪ actor presence
checks.
- Adds unit coverage for downscope, further downscope, widen rejection,
omit-inherit, mixed subject/actor filters, empty-scope access/JWT
subjects, and bare-prefix request/ceiling cases.
- Adds an integration test for broad → `roles:id` filtered roles, plus a
second exchange that rejects widening to another org.
- Documents downscope-only and omit-inherit behavior in the reserved
scopes table and the token exchange guide.

# Additional Changes

- Updates the token-exchange guide Scope section to reflect that
authorization-related reserved scopes must already be present on input
tokens (aligned with the v4.15.3 hardening), rather than suggesting
scope can be freely extended.

# Additional Context

- Closes #12413
- Follow-up for PR #12312
- Related discussion in #11869 (recommended `roles:id` workaround; this
restores that path for token exchange without allowing filter widening)
- Behavior note for release notes: during token exchange, an existing
`urn:zitadel:iam:org:roles🆔*` filter on the subject is inherited when
omitted from the request, so role claims cannot re-widen.

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Livio Spring <[email protected]>
This commit is contained in:
Livio Spring
2026-08-28 16:27:56 +02:00
committed by GitHub
co-authored by Cursor Agent Livio Spring
parent 94f53145da
commit 8e442ed4bc
5 changed files with 371 additions and 12 deletions
@@ -24,6 +24,7 @@ import (
"github.com/zitadel/zitadel/pkg/grpc/admin"
"github.com/zitadel/zitadel/pkg/grpc/app"
"github.com/zitadel/zitadel/pkg/grpc/management"
oidc_pb "github.com/zitadel/zitadel/pkg/grpc/oidc/v2"
)
func setImpersonationPolicy(t *testing.T, instance *integration.Instance, value bool) {
@@ -740,3 +741,95 @@ func TestImpersonation_API_Call(t *testing.T) {
assert.Equal(t, codes.PermissionDenied, status.Code())
assert.Equal(t, "Errors.TokenExchange.Token.NotForAPI (APP-Shi0J)", status.Message())
}
// TestServer_TokenExchange_OrgRoleIDScopeDownscope covers #12413: a broad access
// token can be exchanged with urn:zitadel:iam:org:roles:id:{orgID} even when that
// scope was not present on the subject token, and roles claims are filtered.
func TestServer_TokenExchange_OrgRoleIDScopeDownscope(t *testing.T) {
const (
roleFoo = "foo"
roleBar = "bar"
)
project := Instance.CreateProject(CTX, t, "", integration.ProjectName(), false, false)
client, keyData, err := Instance.CreateOIDCWebClientJWT(CTX, redirectURI, logoutRedirectURI, project.GetId(),
app.OIDCGrantType_OIDC_GRANT_TYPE_TOKEN_EXCHANGE,
app.OIDCGrantType_OIDC_GRANT_TYPE_AUTHORIZATION_CODE,
app.OIDCGrantType_OIDC_GRANT_TYPE_REFRESH_TOKEN,
)
require.NoError(t, err)
_, err = Instance.Client.Mgmt.UpdateProject(CTX, &management.UpdateProjectRequest{
Id: project.GetId(),
Name: integration.ProjectName(),
ProjectRoleAssertion: true,
})
require.NoError(t, err)
addProjectRolesGrants(t, User.GetUserId(), project.GetId(), roleFoo, roleBar)
grantedOrgID := addProjectOrgGrant(t, User.GetUserId(), project.GetId(), roleFoo, roleBar)
authRequestID := createAuthRequest(t, Instance, client.GetClientId(), redirectURI, oidc.ScopeOpenID, oidc.ScopeProfile)
sessionID, sessionToken, _, _ := Instance.CreateVerifiedWebAuthNSession(t, CTXLOGIN, User.GetUserId())
linkResp, err := Instance.Client.OIDCv2.CreateCallback(CTXLOGIN, &oidc_pb.CreateCallbackRequest{
AuthRequestId: authRequestID,
CallbackKind: &oidc_pb.CreateCallbackRequest_Session{
Session: &oidc_pb.Session{
SessionId: sessionID,
SessionToken: sessionToken,
},
},
})
require.NoError(t, err)
provider, err := rp.NewRelyingPartyOIDC(CTX, Instance.OIDCIssuer(), client.GetClientId(), "", redirectURI, []string{oidc.ScopeOpenID},
rp.WithJWTProfile(rp.SignerFromKeyFile(keyData)))
require.NoError(t, err)
code := assertCodeResponse(t, linkResp.GetCallbackUrl())
broadTokens, err := rp.CodeExchange[*oidc.IDTokenClaims](context.Background(), code, provider, codeExchangeOptions(t, provider)...)
require.NoError(t, err)
broadUserinfo, err := rp.Userinfo[*oidc.UserInfo](CTX, broadTokens.AccessToken, broadTokens.TokenType, User.GetUserId(), provider)
require.NoError(t, err)
assertProjectRoleClaims(t, project.GetId(), broadUserinfo.Claims, true, []string{roleFoo, roleBar}, []string{Instance.DefaultOrg.Id, grantedOrgID})
signer, err := rp.SignerFromKeyFile(keyData)()
require.NoError(t, err)
exchanger, err := tokenexchange.NewTokenExchangerJWTProfile(CTX, Instance.OIDCIssuer(), client.GetClientId(), signer)
require.NoError(t, err)
orgRoleScope := domain.OrgRoleIDScope + grantedOrgID
exchanged, err := tokenexchange.ExchangeToken(
CTX,
exchanger,
broadTokens.AccessToken,
oidc.AccessTokenType,
"",
"",
nil,
nil,
[]string{oidc.ScopeOpenID, orgRoleScope},
oidc.AccessTokenType,
)
require.NoError(t, err)
assert.Contains(t, []string(exchanged.Scopes), orgRoleScope)
narrowUserinfo, err := rp.Userinfo[*oidc.UserInfo](CTX, exchanged.AccessToken, exchanged.TokenType, User.GetUserId(), provider)
require.NoError(t, err)
assertProjectRoleClaims(t, project.GetId(), narrowUserinfo.Claims, true, []string{roleFoo, roleBar}, []string{grantedOrgID})
// Widening to another org after downscoping must fail.
_, err = tokenexchange.ExchangeToken(
CTX,
exchanger,
exchanged.AccessToken,
oidc.AccessTokenType,
"",
"",
nil,
nil,
[]string{oidc.ScopeOpenID, domain.OrgRoleIDScope + Instance.DefaultOrg.Id},
oidc.AccessTokenType,
)
require.Error(t, err)
}