feat: Add scope forwarding to go-processor for per-user access control

[mrsabath]

Summary

The go-processor (AuthProxy ext_proc) currently uses a static TARGET_SCOPES environment variable for all outbound token exchanges. This means every exchanged token gets the same set of scopes regardless of what scopes the original user token contained.

For scope-based access control to work (e.g., Alice with public access vs Bob with privileged access), the go-processor must forward the original token's scopes through the token exchange, not use a fixed set.

Current Behavior

1. TARGET_SCOPES is set in the authbridge-config ConfigMap (e.g., "openid github-tool-aud github-full-access")
2. When any user's request reaches the agent, AuthBridge exchanges the token using the static TARGET_SCOPES
3. The exchanged token always contains github-full-access, even if the original user (e.g., Alice) did not have that scope
4. The downstream tool always sees github-full-access and uses the privileged PAT for all users

Expected Behavior

The go-processor should extract the scope claim from the incoming JWT (subject token) and intersect it with TARGET_SCOPES before making the token exchange request:

• If the incoming token has scope: "openid email profile" and TARGET_SCOPES is "openid github-tool-aud github-full-access", the exchange should request scope=openid github-tool-aud (intersection, plus required scopes like github-tool-aud)
• If the incoming token has scope: "openid email profile github-full-access", the exchange should request scope=openid github-tool-aud github-full-access

This preserves per-user scope differentiation through the exchange.

Proposed Implementation

Add a new configuration option to go-processor:

• SCOPE_FORWARDING (env var, default: "disabled")
  • "disabled" — current behavior: use static TARGET_SCOPES for all exchanges
  • "intersect" — extract scopes from subject token, intersect with TARGET_SCOPES
  • "forward" — extract scopes from subject token, merge with TARGET_SCOPES

Implementation in handleOutbound():

1. Parse the incoming JWT's scope claim (decode without full validation — the token was already validated inbound)
2. Split into a set of scopes
3. Apply the selected strategy (intersect or forward) with TARGET_SCOPES
4. Pass the resulting scope set to exchangeToken()

Use Case

The GitHub Issue Agent demo Step 10 shows two users:

• Alice gets a token without github-full-access — should result in PUBLIC_ACCESS_PAT at the tool
• Bob gets a token with github-full-access — should result in PRIVILEGED_ACCESS_PAT at the tool

Without scope forwarding, both users get github-full-access in the exchanged token because TARGET_SCOPES is static.

Affected Files

• AuthBridge/AuthProxy/go-processor/main.go — handleOutbound() and loadConfig()
• AuthBridge/demos/github-issue/k8s/configmaps.yaml — add SCOPE_FORWARDING: "intersect" to authbridge-config

[huang195]

Alternative Approach: Keycloak Role-Based Scope Gating

Thanks for the detailed write-up — the problem statement is spot-on. Static TARGET_SCOPES breaks per-user access control through token exchange.

I wanted to suggest an alternative approach that avoids adding scope-parsing logic to the go-processor entirely, by leveraging Keycloak's native role-based access control instead.

Core Idea

Rather than having the go-processor inspect the subject token's scopes and decide what to request, let Keycloak make that decision. Keycloak already knows the user identity during token exchange (it's in the subject_token) — it just needs to be told which users are entitled to which scopes.

How It Works

1. Create a github-privileged realm role in Keycloak
2. Assign the role to Bob (but not Alice)
3. Remove github-full-access from TARGET_SCOPES — set it to just "openid github-tool-aud" (the infrastructure scopes needed for the exchange mechanism itself)
4. Add a protocol mapper on the github-tool client that exposes the user's roles (e.g., via realm_access.roles or a custom claim)
5. The downstream tool checks for the role in the exchanged token instead of the scope

The go-processor continues to request the same static scopes for every exchange — but the exchanged token now carries per-user role information that the downstream tool can use for authorization.

User	Exchange requests	Exchanged token contains	Tool behavior
Alice	scope=openid github-tool-aud	Alice's roles (no github-privileged)	PUBLIC_ACCESS_PAT
Bob	scope=openid github-tool-aud	Bob's roles (has github-privileged)	PRIVILEGED_ACCESS_PAT

Changes Required

Component	Change
setup_keycloak.py	Create github-privileged realm role, assign to Bob, ensure role mapper on github-tool client
configmaps.yaml	TARGET_SCOPES: "openid github-tool-aud"
github-tool deployment	Check realm_access.roles for github-privileged (instead of scope claim)
go-processor	None

The setup_keycloak.py additions would be roughly:

# Create realm role
keycloak_admin.create_realm_role({
    "name": "github-privileged",
    "description": "Privileged GitHub API access",
})

# Assign to Bob only
bob_id = get_or_create_user(keycloak_admin, DEMO_USERS[1])  # bob
role = keycloak_admin.get_realm_role("github-privileged")
keycloak_admin.assign_realm_roles(user_id=bob_id, roles=[role])

Trade-offs

Advantages:

• No code changes to go-processor — it stays a transparent token exchanger
• Authorization decisions live in Keycloak, which has native tooling for role management (admin UI, RBAC, group mappings, etc.)
• Scales naturally — adding a third user with different access is just a role assignment in Keycloak, no config or code changes
• Aligns with the note already in setup_keycloak.py: "In a production system you would enforce per-user scope access via role-based policies"

Considerations:

• Requires the downstream tool to check roles instead of scopes (a config change, not a code change, if the tool supports configurable claim checks)
• Shifts complexity from go-processor code to Keycloak configuration

Happy to discuss or help with implementation if this direction is interesting.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. If this issue is still relevant, please comment or remove the stale label.

[github-actions]

This issue was closed because it has been stale for 14 days with no activity. Feel free to reopen if this is still relevant.

[omerboehm]

I've implemented a similar approach to the one proposed above by Hai Huang, on branch fix/github-issue-demo "Keycloak Role-Based Scope Gating") that achieves the same end-to-end behavior without modifying the go-processor:

Move scope gating into Keycloak rather than the AuthProxy. Realm roles (regular, privileged) are assigned to users (alice → regular, bob → privileged) and mapped to client roles / client scopes via a declarative policy.yaml.
Proxy requests only openid — authbridge/demos/github-issue/k8s/configmaps.yaml drops token_scopes from "openid github-tool-aud github-full-access" to "openid". Keycloak then issues only the scopes the user's role authorizes, so alice gets github-tool-aud while bob also gets github-full-access.
No code changes in the go-processor. The new config.yaml and policy.yaml plus an updated setup_keycloak.py express the access model declaratively.