Some providers (e.g. Okta employee access tokens) only carry openid profile email groups in the JWT;
the scopes that authorize a caller appear only on the OIDC userinfo response.
oidcauthlib.auth.userinfo.oidc_userinfo_manager.OidcUserInfoManager resolves a token's effective
scopes from the token's own claims plus the userinfo endpoint, and caches the userinfo-derived scopes in
a key-value store.
manager = OidcUserInfoManager(
auth_config_reader=auth_config_reader,
well_known_configuration_manager=well_known_configuration_manager,
store=store, # py-key-value-aio store; yours, not shared with other services
cache_collection="oidc-user-info-cache",
cache_ttl_seconds=86400,
fetch_timeout_seconds=30,
scope_claims=["custom:scope"], # optional extra claims holding scopes
group_claims=["groups"], # optional claims holding group names, used whole as scopes
scope_remove_prefixes=["fhir/prod/"],
)
scopes = await manager.get_scopes_from_user_info_async(access_token=token)- Scope derivation follows fhir-server-ui's
jwtParser: thescopeclaim (plusscp), thenscope_claims, thengroup_claims(each value taken whole). Commas separate like spaces, results are de-duplicated, andscope_remove_prefixesare stripped (first match wins). Nothing beyondscope/scpis read unless configured. - Provider is matched to the token's
iss: an exactissuer, else awell_known_urion the same scheme, host and port whose path segments start with the issuer's. Only a token with noissat all is matched by its client id. A token matching no provider raisesValueError; it is never sent to another provider. - Subject check: for a token that has a
sub, the userinfo response must carry the samesub(OIDC Core 5.3.2); a missing or different one raisesValueErrorand nothing is cached. - Cache key is
oidc-userinfo-scopes:<issuer>:<client_id>:<sub>|v1with each segment percent-encoded (so values containing:cannot collide, and two providers never share an entry); only the userinfo-derived scopes are stored, never the userinfo response. The token's own scopes are re-derived on every call. A token withoutsubor without an issuer, or an empty scope list, is not cached. Changes to a user's entitlements are visible after at mostcache_ttl_seconds. - Failures: the cache never fails a lookup. A write failure is logged and swallowed; a read failure or a malformed entry is logged and treated as a miss, and the refetched scopes overwrite the bad entry. A userinfo HTTP error, a missing provider or a mismatched subject is raised, so each service decides whether to fail closed or degrade.