Repository navigation
bug(python): OIDC refresh drops the gateway's oidc_scopes #4919
Description
User Story
As a student building a personal project that creates and drives OpenShell sandboxes from the Python SDK (SandboxClient.from_active_cluster), I want the SDK to refresh my OIDC session the same way the CLI does, so that my scripts keep working after the access token expires without me running a CLI command to renew it.
I noticed the Python refresh behaving differently from the CLI while working on the project. Comparing the two refresh paths showed that the Python refresher never sends the gateway's oidc_scopes, and I then reproduced it with a unit test.
Problem Statement
_OidcRefresher._refresh in python/openshell/sandbox.py posts the refresh_token grant with only grant_type, refresh_token, and client_id. It never sends the gateway's oidc_scopes. The CLI does send them (ensure_valid_oidc_token_bundle → oidc_refresh_token(..., scopes)), and the docs say refresh uses "the OIDC scopes saved in the gateway metadata". The Python client-credentials provider in the same file already reads oidc_scopes / oidc_audience from metadata; only the refresh path omits them.
Impact / Why This Matters
With identity providers that require scope on the refresh grant, or that pick the token's resource from it (for example Microsoft Entra ID), the Python SDK's first automatic refresh fails or returns a token the gateway rejects. The same gateway works with the CLI. The current workaround is to run openshell gateway login or a CLI command before the token expires so the CLI rewrites oidc_token.json. That does not work for long-running Python processes.
Acceptance Criteria
- When gateway metadata has
oidc_scopes, the Python refresh request includesscope=<space-separated scopes>, matching the CLI. - Without
oidc_scopes, the refresh request is unchanged. - A unit test covers both cases.
Reproduction Steps
- Register a gateway whose
metadata.jsonhas"auth_mode": "oidc"and"oidc_scopes": "openid api://openshell/.default", with an expired access token and a valid refresh token inoidc_token.json. - Build the provider with
_make_cluster_bearer_provider(gateway_dir, name)(the pathSandboxClient.from_active_clusteruses) and call it once, with the refresher'shttpx.Clientbound to anhttpx.MockTransportthat records the token request. - The posted form contains
grant_type,refresh_token, andclient_id, but noscope. The CLI's refresh for the same gateway sendsscope=openid api://openshell/.default.
Suggested UX (if applicable)
No response
Environment
- OpenShell:
main@ c4688aa - SDK: Python (
python/openshell/sandbox.py,_OidcRefresher)
Logs
FAILED python/openshell/sandbox_test.py::test_refresher_sends_gateway_oidc_scopes
E AssertionError: assert None == 'openid api://openshell/.default'
Activity
jyotir07 commentedon Oct 26, 2026
Hey, I'd like to work on this issue. I plan to trace how the CLI handles OIDC scopes during token refresh, align the Python SDK's
_OidcRefresherwith that behavior, and add regression tests for configured and missing scopes. Is this issue available to take on?O96a commentedon Oct 26, 2026
The refresh_token grant doesn't inherit scopes — you have to send
scopeexplicitly on the refresh request, and the value has to be a subset of what was originally granted.Which means the SDK needs to persist the granted scopes from the initial token response, not read them from the gateway config at refresh time:
Second thing, and this is the one that fails silently: RFC 6749 §6 says that if the refresh response omits
scope, the client must assume the originally granted scope. A lot of SDKs overwrite their stored scope with the empty response field, so the first refresh works and the second one sends nothing — which matches "works until the token expires" only if you're rotating twice.Since the CLI path works, diff what it sends on the refresh call against what the SDK sends. The
scopeparameter and the stored-scope handling are the two places they'll diverge.jyotir07 commentedon Oct 26, 2026
Thanks for pointing that out! I’ll compare the CLI and SDK implementations and check how scopes are handled across multiple refreshes, especially when the response doesn’t include them. And i’ll add tests to make sure we don’t lose the originally granted scopes.