Skip to content

Commit 82e1f70

Browse files
Make OAuth endpoint scope names configurable
1 parent 2061e64 commit 82e1f70

10 files changed

Lines changed: 308 additions & 28 deletions

File tree

‎CHANGELOG‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@
1010
- Add optional global JWT scope checks (`TABPY_OAUTH_REQUIRED_SCOPES`) and
1111
opt-in per-endpoint scopes (`TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES`) for
1212
`tabpy:query` on `/query`, `tabpy:evaluate` on `/evaluate`, and
13-
`tabpy:deploy` on mutating `/endpoints` operations.
13+
`tabpy:deploy` on mutating `/endpoints` operations. Endpoint scope names
14+
are configurable for identity providers with different naming conventions.
1415
- Add optional per-user logging of the JWT `sub` claim when
1516
`TABPY_OAUTH_LOG_USER` is enabled (requires `TABPY_LOG_DETAILS`).
1617

‎docs/server-config.md‎

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,9 @@ at [`logging.config` documentation page](https://docs.python.org/3.6/library/log
7676
section. Default value - not set.
7777
- `TABPY_OAUTH_ENABLED`, `TABPY_OAUTH_ISSUER`, `TABPY_OAUTH_JWKS_URI`,
7878
`TABPY_OAUTH_AUDIENCE`, `TABPY_OAUTH_REQUIRED_SCOPES`,
79-
`TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES`, `TABPY_OAUTH_LOG_USER` - configure
80-
OAuth/JWT Bearer token authentication.
79+
`TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES`, `TABPY_OAUTH_QUERY_SCOPE`,
80+
`TABPY_OAUTH_EVALUATE_SCOPE`, `TABPY_OAUTH_DEPLOY_SCOPE`,
81+
`TABPY_OAUTH_LOG_USER` - configure OAuth/JWT Bearer token authentication.
8182
See [OAuth / JWT Bearer Token Authentication](#oauth--jwt-bearer-token-authentication).
8283
- `TABPY_TRANSFER_PROTOCOL` - transfer protocol. Default value - `http`. If
8384
set to `https` two additional parameters have to be specified:
@@ -311,35 +312,41 @@ service (e.g. a cloud metadata endpoint).
311312
the signing keys used to verify JWT signatures.
312313
- `TABPY_OAUTH_AUDIENCE` is the expected `aud` claim on incoming JWTs.
313314

314-
Three additional parameters are optional:
315+
Six additional parameters are optional:
315316

316317
```sh
317318
TABPY_OAUTH_REQUIRED_SCOPES = tabpy
318319
TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES = true
320+
TABPY_OAUTH_QUERY_SCOPE = tabpy:query
321+
TABPY_OAUTH_EVALUATE_SCOPE = tabpy:evaluate
322+
TABPY_OAUTH_DEPLOY_SCOPE = tabpy:deploy
319323
TABPY_OAUTH_LOG_USER = true
320324
```
321325

322326
- `TABPY_OAUTH_REQUIRED_SCOPES` is a comma-separated list of scopes that
323327
must all be present in the JWT's `scope` claim on **every** request,
324328
including `/info`. If unset, no global scope check is performed. A
325329
missing global scope is rejected with HTTP 401 (Flight:
326-
`UNAUTHENTICATED`). Do not put `tabpy:query`, `tabpy:evaluate`, or
327-
`tabpy:deploy` here if you want them bound to specific paths; use
330+
`UNAUTHENTICATED`). Do not put the configured endpoint scope names here
331+
if you want them bound only to their specific paths; use
328332
`TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES` for that.
329333

330-
For example, an organization could restrict a finance team's TabPy
331-
deployment with:
334+
Scope names are IdP-defined and compared exactly. For example, Amazon
335+
Cognito custom scopes use
336+
`<resource-server-identifier>/<scope-name>`. A Cognito resource server
337+
named `tabpy` with `access` and `finance` scopes could restrict a finance
338+
team's TabPy deployment with:
332339

333340
```sh
334-
TABPY_OAUTH_REQUIRED_SCOPES = tabpy,org:finance
341+
TABPY_OAUTH_REQUIRED_SCOPES = tabpy/access,tabpy/finance
335342
```
336343

337-
A token whose `scope` claim is `openid tabpy org:finance` would pass the
338-
global scope check, while one containing `openid tabpy org:marketing`
339-
would be rejected. When multiple scopes are configured, the token must
340-
contain **all** of them.
344+
A token whose `scope` claim is `openid tabpy/access tabpy/finance` would
345+
pass the global scope check, while one containing
346+
`openid tabpy/access tabpy/marketing` would be rejected. When multiple
347+
scopes are configured, the token must contain **all** of them.
341348
- `TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES` (default `false`) requires
342-
well-known scopes on specific HTTP paths after the JWT itself is valid:
349+
scopes on specific HTTP paths after the JWT itself is valid: by default,
343350
`/query` needs `tabpy:query`, `/evaluate` needs `tabpy:evaluate`, and
344351
mutating management operations need `tabpy:deploy` (`POST /endpoints`,
345352
`PUT`/`DELETE /endpoints/{name}`, and
@@ -352,6 +359,23 @@ TABPY_OAUTH_LOG_USER = true
352359
forwards the original token. Arrow Flight is not per-endpoint scoped;
353360
it still uses only `TABPY_OAUTH_REQUIRED_SCOPES`. Basic Auth is
354361
unaffected.
362+
- `TABPY_OAUTH_QUERY_SCOPE`, `TABPY_OAUTH_EVALUATE_SCOPE`, and
363+
`TABPY_OAUTH_DEPLOY_SCOPE` configure the exact scope names used by
364+
endpoint enforcement and advertised by `/info`. Their defaults are
365+
`tabpy:query`, `tabpy:evaluate`, and `tabpy:deploy`. For an Amazon Cognito
366+
resource server with identifier `tabpy`, configure its slash-form custom
367+
scopes with:
368+
369+
```sh
370+
TABPY_OAUTH_QUERY_SCOPE = tabpy/query
371+
TABPY_OAUTH_EVALUATE_SCOPE = tabpy/evaluate
372+
TABPY_OAUTH_DEPLOY_SCOPE = tabpy/deploy
373+
```
374+
375+
Each configured value must be a valid, non-empty OAuth scope token.
376+
Assigning the same value to multiple endpoint groups gives a token with
377+
that scope access to all of those groups; TabPy logs a warning when it
378+
detects this configuration.
355379
- `TABPY_OAUTH_LOG_USER` (default `false`) sets the JWT's `sub` claim as the
356380
authenticated user for logging purposes. The `sub` claim is often a
357381
user's email or SSO ID, so leave this disabled unless that's an
@@ -360,8 +384,8 @@ TABPY_OAUTH_LOG_USER = true
360384
enabled -- that's what actually logs the authenticated user, for both
361385
basic auth and OAuth.
362386

363-
When OAuth is enabled, `/info` advertises `tabpy:query`, `tabpy:evaluate`,
364-
and `tabpy:deploy` under
387+
When OAuth is enabled, `/info` advertises the configured endpoint scopes
388+
(by default, `tabpy:query`, `tabpy:evaluate`, and `tabpy:deploy`) under
365389
`versions.v1.features.authentication.methods.oauth-jwt`
366390
so an IdP or Tableau connection can request those scopes even when
367391
endpoint enforcement is off.

‎tabpy/tabpy_server/app/app.py‎

Lines changed: 62 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
import logging
55
import multiprocessing
66
import os
7+
import re
78
import shutil
89
import signal
910
import socket
@@ -23,7 +24,12 @@
2324
from tabpy.tabpy_server.handlers.basic_auth_server_middleware_factory import (
2425
BasicAuthServerMiddlewareFactory,
2526
)
26-
from tabpy.tabpy_server.handlers.jwt_auth import WELL_KNOWN_ENDPOINT_SCOPES
27+
from tabpy.tabpy_server.handlers.jwt_auth import (
28+
SCOPE_DEPLOY,
29+
SCOPE_EVALUATE,
30+
SCOPE_QUERY,
31+
endpoint_scope_names,
32+
)
2733
from tabpy.tabpy_server.handlers.jwt_server_middleware_factory import (
2834
JwtAuthServerMiddlewareFactory,
2935
)
@@ -400,12 +406,24 @@ def _parse_config(self, config_file):
400406
None, None),
401407
(SettingsParameters.OAuthEnforceEndpointScopes,
402408
ConfigParameters.TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES, False, parser.getboolean),
409+
(SettingsParameters.OAuthQueryScope,
410+
ConfigParameters.TABPY_OAUTH_QUERY_SCOPE, SCOPE_QUERY, None),
411+
(SettingsParameters.OAuthEvaluateScope,
412+
ConfigParameters.TABPY_OAUTH_EVALUATE_SCOPE, SCOPE_EVALUATE, None),
413+
(SettingsParameters.OAuthDeployScope,
414+
ConfigParameters.TABPY_OAUTH_DEPLOY_SCOPE, SCOPE_DEPLOY, None),
403415
(SettingsParameters.OAuthLogUser, ConfigParameters.TABPY_OAUTH_LOG_USER, False, parser.getboolean),
404416
]
405417

406418
for setting, parameter, default_val, parse_function in settings_parameters:
407419
self._set_parameter(parser, setting, parameter, default_val, parse_function)
408420

421+
self.settings[SettingsParameters.OAuthEndpointScopes] = {
422+
SCOPE_QUERY: self.settings[SettingsParameters.OAuthQueryScope],
423+
SCOPE_EVALUATE: self.settings[SettingsParameters.OAuthEvaluateScope],
424+
SCOPE_DEPLOY: self.settings[SettingsParameters.OAuthDeployScope],
425+
}
426+
409427
if not os.path.exists(self.settings[SettingsParameters.UploadDir]):
410428
os.makedirs(self.settings[SettingsParameters.UploadDir])
411429

@@ -577,6 +595,44 @@ def _validate_oauth_settings(self):
577595
logger.critical(msg)
578596
raise RuntimeError(msg)
579597

598+
endpoint_scopes = [
599+
(SettingsParameters.OAuthQueryScope,
600+
ConfigParameters.TABPY_OAUTH_QUERY_SCOPE),
601+
(SettingsParameters.OAuthEvaluateScope,
602+
ConfigParameters.TABPY_OAUTH_EVALUATE_SCOPE),
603+
(SettingsParameters.OAuthDeployScope,
604+
ConfigParameters.TABPY_OAUTH_DEPLOY_SCOPE),
605+
]
606+
invalid_scopes = [
607+
config_key for setting, config_key in endpoint_scopes
608+
if not re.fullmatch(
609+
r"[\x21\x23-\x5B\x5D-\x7E]+", self.settings[setting]
610+
)
611+
]
612+
if invalid_scopes:
613+
msg = (
614+
f"{', '.join(invalid_scopes)} must be valid, non-empty OAuth "
615+
"scope tokens"
616+
)
617+
logger.critical(msg)
618+
raise RuntimeError(msg)
619+
620+
scope_counts = {}
621+
for setting, _ in endpoint_scopes:
622+
value = self.settings[setting]
623+
scope_counts[value] = scope_counts.get(value, 0) + 1
624+
duplicated = [
625+
f"{config_key}={self.settings[setting]}"
626+
for setting, config_key in endpoint_scopes
627+
if scope_counts[self.settings[setting]] > 1
628+
]
629+
if duplicated:
630+
logger.warning(
631+
"OAuth endpoint scope settings contain duplicate values "
632+
f"({', '.join(duplicated)}); a token with a shared scope "
633+
"can access multiple endpoint groups"
634+
)
635+
580636
# JWKS/issuer are the trust anchor for JWT verification, so both must
581637
# be fetched over https to prevent an on-path attacker from substituting
582638
# their own keys/issuer.
@@ -642,7 +698,11 @@ def _get_features(self):
642698
methods["basic-auth"] = {}
643699
if self.settings[SettingsParameters.OAuthEnabled]:
644700
methods["oauth-jwt"] = {
645-
"scopes": list(WELL_KNOWN_ENDPOINT_SCOPES),
701+
"scopes": list(
702+
endpoint_scope_names(
703+
self.settings[SettingsParameters.OAuthEndpointScopes]
704+
)
705+
),
646706
"endpoint_scopes_enforced": bool(
647707
self.settings.get(
648708
SettingsParameters.OAuthEnforceEndpointScopes, False

‎tabpy/tabpy_server/app/app_parameters.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ class ConfigParameters:
2929
TABPY_OAUTH_AUDIENCE = "TABPY_OAUTH_AUDIENCE"
3030
TABPY_OAUTH_REQUIRED_SCOPES = "TABPY_OAUTH_REQUIRED_SCOPES"
3131
TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES = "TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES"
32+
TABPY_OAUTH_QUERY_SCOPE = "TABPY_OAUTH_QUERY_SCOPE"
33+
TABPY_OAUTH_EVALUATE_SCOPE = "TABPY_OAUTH_EVALUATE_SCOPE"
34+
TABPY_OAUTH_DEPLOY_SCOPE = "TABPY_OAUTH_DEPLOY_SCOPE"
3235
TABPY_OAUTH_LOG_USER = "TABPY_OAUTH_LOG_USER"
3336

3437

@@ -64,4 +67,8 @@ class SettingsParameters:
6467
OAuthAudience = "oauth_audience"
6568
OAuthRequiredScopes = "oauth_required_scopes"
6669
OAuthEnforceEndpointScopes = "oauth_enforce_endpoint_scopes"
70+
OAuthQueryScope = "oauth_query_scope"
71+
OAuthEvaluateScope = "oauth_evaluate_scope"
72+
OAuthDeployScope = "oauth_deploy_scope"
73+
OAuthEndpointScopes = "oauth_endpoint_scopes"
6774
OAuthLogUser = "oauth_log_user"

‎tabpy/tabpy_server/common/default.conf‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,8 @@
5454

5555
# Comma-separated list of scopes that must all be present in the JWT's
5656
# `scope` claim on every request (including /info). Leave unset to skip
57-
# this global check. Do not put tabpy:query / tabpy:evaluate /
58-
# tabpy:deploy here if you want them bound to specific paths; use
57+
# this global check. Do not put the configured endpoint scope names here
58+
# if you want them bound only to their specific paths; use
5959
# TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES for that.
6060
# TABPY_OAUTH_REQUIRED_SCOPES = tabpy
6161

@@ -67,6 +67,13 @@
6767
# not per-endpoint scoped; it still uses TABPY_OAUTH_REQUIRED_SCOPES only.
6868
# TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES = true
6969

70+
# Scope names advertised by /info and required when endpoint enforcement is
71+
# enabled. Override these when the IdP uses a different naming convention.
72+
# Amazon Cognito custom scopes commonly use names such as tabpy/query.
73+
# TABPY_OAUTH_QUERY_SCOPE = tabpy:query
74+
# TABPY_OAUTH_EVALUATE_SCOPE = tabpy:evaluate
75+
# TABPY_OAUTH_DEPLOY_SCOPE = tabpy:deploy
76+
7077
# Log the JWT subject as the authenticated user for OAuth requests.
7178
# TABPY_OAUTH_LOG_USER = true
7279

‎tabpy/tabpy_server/handlers/base_handler.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -537,7 +537,10 @@ def _endpoint_scope_error(self):
537537
if self.request.method == "OPTIONS":
538538
return None
539539
required = endpoint_scope_for_path(
540-
self.request.path, self.subdirectory, self.request.method
540+
self.request.path,
541+
self.subdirectory,
542+
self.request.method,
543+
self.settings.get(SettingsParameters.OAuthEndpointScopes),
541544
)
542545
if not required:
543546
return None

‎tabpy/tabpy_server/handlers/jwt_auth.py‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -372,10 +372,16 @@ def _check_scopes(claims: dict, required_scopes: str) -> None:
372372
("/endpoints", _MUTATING_METHODS, SCOPE_DEPLOY),
373373
)
374374

375-
# Derive advertised scopes from the enforced rules while preserving rule order.
376-
WELL_KNOWN_ENDPOINT_SCOPES = tuple(
377-
dict.fromkeys(scope for _, _, scope in _ENDPOINT_SCOPE_RULES)
378-
)
375+
376+
def endpoint_scope_names(scope_overrides: dict[str, str] | None = None) -> tuple[str, ...]:
377+
"""Return endpoint scope names in advertisement order."""
378+
overrides = scope_overrides or {}
379+
return tuple(
380+
dict.fromkeys(
381+
overrides.get(default_scope) or default_scope
382+
for _, _, default_scope in _ENDPOINT_SCOPE_RULES
383+
)
384+
)
379385

380386

381387
def token_has_scope(claims: dict, scope: str) -> bool:
@@ -387,12 +393,16 @@ def token_has_scope(claims: dict, scope: str) -> bool:
387393

388394

389395
def endpoint_scope_for_path(
390-
path: str, subdirectory: str = "", method: str = "GET"
396+
path: str,
397+
subdirectory: str = "",
398+
method: str = "GET",
399+
scope_overrides: dict[str, str] | None = None,
391400
) -> str | None:
392401
"""
393402
Return the well-known scope required for `path` + HTTP `method`, or None.
394403
395404
`subdirectory` is TabPy's optional URL prefix (e.g. `/tabpy`).
405+
`scope_overrides` maps default well-known scopes to configured names.
396406
OPTIONS is not mapped here; callers skip CORS preflight separately.
397407
"""
398408
rel = path or "/"
@@ -404,8 +414,9 @@ def endpoint_scope_for_path(
404414
elif rel.startswith(prefix + "/"):
405415
rel = rel[len(prefix):]
406416
verb = (method or "GET").upper()
407-
for path_prefix, methods, scope in _ENDPOINT_SCOPE_RULES:
417+
overrides = scope_overrides or {}
418+
for path_prefix, methods, default_scope in _ENDPOINT_SCOPE_RULES:
408419
if rel == path_prefix or rel.startswith(path_prefix + "/"):
409420
if methods is None or verb in methods:
410-
return scope
421+
return overrides.get(default_scope) or default_scope
411422
return None

‎tests/unit/server_tests/test_config.py‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -472,6 +472,72 @@ def test_oauth_enforce_endpoint_scopes_can_be_enabled(self, mock_getaddrinfo):
472472
self.assertTrue(oauth["endpoint_scopes_enforced"])
473473
self.assertEqual(oauth["scopes"], ["tabpy:query", "tabpy:evaluate", "tabpy:deploy"])
474474

475+
@patch(
476+
"tabpy.tabpy_server.app.app.socket.getaddrinfo",
477+
return_value=PUBLIC_JWKS_ADDRINFO,
478+
)
479+
def test_oauth_endpoint_scope_names_can_be_configured(self, mock_getaddrinfo):
480+
self.fp.write(
481+
"[TabPy]\n"
482+
"TABPY_OAUTH_ENABLED = true\n"
483+
"TABPY_OAUTH_ISSUER = https://idp.example.com/\n"
484+
"TABPY_OAUTH_JWKS_URI = https://idp.example.com/.well-known/jwks.json\n"
485+
"TABPY_OAUTH_AUDIENCE = tabpy\n"
486+
"TABPY_OAUTH_QUERY_SCOPE = tabpy/query\n"
487+
"TABPY_OAUTH_EVALUATE_SCOPE = tabpy/evaluate\n"
488+
"TABPY_OAUTH_DEPLOY_SCOPE = tabpy/deploy\n"
489+
)
490+
self.fp.close()
491+
492+
app = TabPyApp(self.fp.name)
493+
oauth = app._get_features()["authentication"]["methods"]["oauth-jwt"]
494+
self.assertEqual(
495+
oauth["scopes"], ["tabpy/query", "tabpy/evaluate", "tabpy/deploy"]
496+
)
497+
498+
@patch(
499+
"tabpy.tabpy_server.app.app.socket.getaddrinfo",
500+
return_value=PUBLIC_JWKS_ADDRINFO,
501+
)
502+
def test_oauth_endpoint_scope_names_reject_whitespace(self, mock_getaddrinfo):
503+
self.fp.write(
504+
"[TabPy]\n"
505+
"TABPY_OAUTH_ENABLED = true\n"
506+
"TABPY_OAUTH_ISSUER = https://idp.example.com/\n"
507+
"TABPY_OAUTH_JWKS_URI = https://idp.example.com/.well-known/jwks.json\n"
508+
"TABPY_OAUTH_AUDIENCE = tabpy\n"
509+
"TABPY_OAUTH_QUERY_SCOPE = tabpy query\n"
510+
)
511+
self.fp.close()
512+
513+
with self.assertRaises(RuntimeError) as err:
514+
TabPyApp(self.fp.name)
515+
self.assertIn("TABPY_OAUTH_QUERY_SCOPE", err.exception.args[0])
516+
517+
@patch(
518+
"tabpy.tabpy_server.app.app.socket.getaddrinfo",
519+
return_value=PUBLIC_JWKS_ADDRINFO,
520+
)
521+
def test_oauth_duplicate_endpoint_scope_names_log_the_keys(self, mock_getaddrinfo):
522+
self.fp.write(
523+
"[TabPy]\n"
524+
"TABPY_OAUTH_ENABLED = true\n"
525+
"TABPY_OAUTH_ISSUER = https://idp.example.com/\n"
526+
"TABPY_OAUTH_JWKS_URI = https://idp.example.com/.well-known/jwks.json\n"
527+
"TABPY_OAUTH_AUDIENCE = tabpy\n"
528+
"TABPY_OAUTH_QUERY_SCOPE = tabpy/access\n"
529+
"TABPY_OAUTH_EVALUATE_SCOPE = tabpy/evaluate\n"
530+
"TABPY_OAUTH_DEPLOY_SCOPE = tabpy/access\n"
531+
)
532+
self.fp.close()
533+
534+
with self.assertLogs("tabpy.tabpy_server.app.app", level="WARNING") as log_ctx:
535+
TabPyApp(self.fp.name)
536+
logged = " ".join(log_ctx.output)
537+
self.assertIn("TABPY_OAUTH_QUERY_SCOPE=tabpy/access", logged)
538+
self.assertIn("TABPY_OAUTH_DEPLOY_SCOPE=tabpy/access", logged)
539+
self.assertNotIn("TABPY_OAUTH_EVALUATE_SCOPE=tabpy/evaluate", logged)
540+
475541
def test_oauth_enabled_missing_issuer_raises(self):
476542
self.fp.write(
477543
"[TabPy]\n"

0 commit comments

Comments
 (0)