Skip to content

Commit f8d03e8

Browse files
Add opt-in OAuth endpoint scopes and bump to 2.15.0 (#666)
* Add opt-in OAuth endpoint scopes for query, evaluate, and deploy * Bump TabPy version to 2.15.0 * Update server-config docs TOC. * Refactor endpoint scope mapping into a single source of truth * Clarify global OAuth scope configuration with an example * Document global OAuth scope requirements with an organization example * Make OAuth endpoint scope names configurable * Assert the expected response for configured query scopes
1 parent 56e9f3b commit f8d03e8

12 files changed

Lines changed: 838 additions & 11 deletions

File tree

‎CHANGELOG‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,20 @@
11
# Changelog
22

3+
## v2.15.0
4+
5+
### Improvements
6+
7+
- Add optional OAuth 2.0 / JWT Bearer token authentication on HTTP and
8+
Arrow Flight. Configure it with `TABPY_OAUTH_ENABLED` plus issuer, JWKS
9+
URI, and audience. Basic Auth is unchanged and can run alongside OAuth.
10+
- Add optional global JWT scope checks (`TABPY_OAUTH_REQUIRED_SCOPES`) and
11+
opt-in per-endpoint scopes (`TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES`) for
12+
`tabpy:query` on `/query`, `tabpy:evaluate` on `/evaluate`, and
13+
`tabpy:deploy` on mutating `/endpoints` operations. Endpoint scope names
14+
are configurable for identity providers with different naming conventions.
15+
- Add optional per-user logging of the JWT `sub` claim when
16+
`TABPY_OAUTH_LOG_USER` is enabled (requires `TABPY_LOG_DETAILS`).
17+
318
## v2.14.0
419

520
### Improvements

‎docs/server-config.md‎

Lines changed: 69 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@
1414
* [Adding an Account](#adding-an-account)
1515
* [Updating an Account](#updating-an-account)
1616
* [Deleting an Account](#deleting-an-account)
17+
* [OAuth / JWT Bearer Token Authentication](#oauth--jwt-bearer-token-authentication)
18+
* [Endpoint Security](#endpoint-security)
19+
- [Arrow Flight](#arrow-flight)
1720
- [Logging](#logging)
1821
* [Request Context Logging](#request-context-logging)
1922

@@ -73,6 +76,8 @@ at [`logging.config` documentation page](https://docs.python.org/3.6/library/log
7376
section. Default value - not set.
7477
- `TABPY_OAUTH_ENABLED`, `TABPY_OAUTH_ISSUER`, `TABPY_OAUTH_JWKS_URI`,
7578
`TABPY_OAUTH_AUDIENCE`, `TABPY_OAUTH_REQUIRED_SCOPES`,
79+
`TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES`, `TABPY_OAUTH_QUERY_SCOPE`,
80+
`TABPY_OAUTH_EVALUATE_SCOPE`, `TABPY_OAUTH_DEPLOY_SCOPE`,
7681
`TABPY_OAUTH_LOG_USER` - configure OAuth/JWT Bearer token authentication.
7782
See [OAuth / JWT Bearer Token Authentication](#oauth--jwt-bearer-token-authentication).
7883
- `TABPY_TRANSFER_PROTOCOL` - transfer protocol. Default value - `http`. If
@@ -307,16 +312,70 @@ service (e.g. a cloud metadata endpoint).
307312
the signing keys used to verify JWT signatures.
308313
- `TABPY_OAUTH_AUDIENCE` is the expected `aud` claim on incoming JWTs.
309314

310-
Two additional parameters are optional:
315+
Six additional parameters are optional:
311316

312317
```sh
313-
TABPY_OAUTH_REQUIRED_SCOPES = tabpy:query,tabpy:evaluate
318+
TABPY_OAUTH_REQUIRED_SCOPES = tabpy
319+
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
314323
TABPY_OAUTH_LOG_USER = true
315324
```
316325

317326
- `TABPY_OAUTH_REQUIRED_SCOPES` is a comma-separated list of scopes that
318-
must all be present in the JWT's `scope` claim for the request to be
319-
accepted. If unset, no scope check is performed.
327+
must all be present in the JWT's `scope` claim on **every** request,
328+
including `/info`. If unset, no global scope check is performed. A
329+
missing global scope is rejected with HTTP 401 (Flight:
330+
`UNAUTHENTICATED`). Do not put the configured endpoint scope names here
331+
if you want them bound only to their specific paths; use
332+
`TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES` for that.
333+
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:
339+
340+
```sh
341+
TABPY_OAUTH_REQUIRED_SCOPES = tabpy/access,tabpy/finance
342+
```
343+
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.
348+
- `TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES` (default `false`) requires
349+
scopes on specific HTTP paths after the JWT itself is valid: by default,
350+
`/query` needs `tabpy:query`, `/evaluate` needs `tabpy:evaluate`, and
351+
mutating management operations need `tabpy:deploy` (`POST /endpoints`,
352+
`PUT`/`DELETE /endpoints/{name}`, and
353+
`GET /configurations/endpoint_upload_destination`). Insufficient
354+
endpoint scope is rejected with HTTP 403 and
355+
`WWW-Authenticate: Bearer error="insufficient_scope"`. `/info`,
356+
`/status`, and `GET /endpoints` are not gated by those scopes. A
357+
`SCRIPT_*` that calls `tabpy.query()` from `/evaluate` needs **both**
358+
`tabpy:evaluate` and `tabpy:query`, because the nested `/query` call
359+
forwards the original token. Arrow Flight is not per-endpoint scoped;
360+
it still uses only `TABPY_OAUTH_REQUIRED_SCOPES`. Basic Auth is
361+
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.
320379
- `TABPY_OAUTH_LOG_USER` (default `false`) sets the JWT's `sub` claim as the
321380
authenticated user for logging purposes. The `sub` claim is often a
322381
user's email or SSO ID, so leave this disabled unless that's an
@@ -325,6 +384,12 @@ TABPY_OAUTH_LOG_USER = true
325384
enabled -- that's what actually logs the authenticated user, for both
326385
basic auth and OAuth.
327386

387+
When OAuth is enabled, `/info` advertises the configured endpoint scopes
388+
(by default, `tabpy:query`, `tabpy:evaluate`, and `tabpy:deploy`) under
389+
`versions.v1.features.authentication.methods.oauth-jwt`
390+
so an IdP or Tableau connection can request those scopes even when
391+
endpoint enforcement is off.
392+
328393
To authenticate a request, send the JWT as a Bearer token:
329394

330395
```sh

‎tabpy/VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
2.14.0
1+
2.15.0

‎tabpy/tabpy_server/app/app.py‎

Lines changed: 71 additions & 1 deletion
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,6 +24,12 @@
2324
from tabpy.tabpy_server.handlers.basic_auth_server_middleware_factory import (
2425
BasicAuthServerMiddlewareFactory,
2526
)
27+
from tabpy.tabpy_server.handlers.jwt_auth import (
28+
SCOPE_DEPLOY,
29+
SCOPE_EVALUATE,
30+
SCOPE_QUERY,
31+
endpoint_scope_names,
32+
)
2633
from tabpy.tabpy_server.handlers.jwt_server_middleware_factory import (
2734
JwtAuthServerMiddlewareFactory,
2835
)
@@ -397,12 +404,26 @@ def _parse_config(self, config_file):
397404
(SettingsParameters.OAuthAudience, ConfigParameters.TABPY_OAUTH_AUDIENCE, None, None),
398405
(SettingsParameters.OAuthRequiredScopes, ConfigParameters.TABPY_OAUTH_REQUIRED_SCOPES,
399406
None, None),
407+
(SettingsParameters.OAuthEnforceEndpointScopes,
408+
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),
400415
(SettingsParameters.OAuthLogUser, ConfigParameters.TABPY_OAUTH_LOG_USER, False, parser.getboolean),
401416
]
402417

403418
for setting, parameter, default_val, parse_function in settings_parameters:
404419
self._set_parameter(parser, setting, parameter, default_val, parse_function)
405420

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+
406427
if not os.path.exists(self.settings[SettingsParameters.UploadDir]):
407428
os.makedirs(self.settings[SettingsParameters.UploadDir])
408429

@@ -574,6 +595,44 @@ def _validate_oauth_settings(self):
574595
logger.critical(msg)
575596
raise RuntimeError(msg)
576597

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+
577636
# JWKS/issuer are the trust anchor for JWT verification, so both must
578637
# be fetched over https to prevent an on-path attacker from substituting
579638
# their own keys/issuer.
@@ -638,7 +697,18 @@ def _get_features(self):
638697
if ConfigParameters.TABPY_PWD_FILE in self.settings:
639698
methods["basic-auth"] = {}
640699
if self.settings[SettingsParameters.OAuthEnabled]:
641-
methods["oauth-jwt"] = {}
700+
methods["oauth-jwt"] = {
701+
"scopes": list(
702+
endpoint_scope_names(
703+
self.settings[SettingsParameters.OAuthEndpointScopes]
704+
)
705+
),
706+
"endpoint_scopes_enforced": bool(
707+
self.settings.get(
708+
SettingsParameters.OAuthEnforceEndpointScopes, False
709+
)
710+
),
711+
}
642712
features["authentication"] = {
643713
"required": True,
644714
"methods": methods,

‎tabpy/tabpy_server/app/app_parameters.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,10 @@ class ConfigParameters:
2828
TABPY_OAUTH_JWKS_URI = "TABPY_OAUTH_JWKS_URI"
2929
TABPY_OAUTH_AUDIENCE = "TABPY_OAUTH_AUDIENCE"
3030
TABPY_OAUTH_REQUIRED_SCOPES = "TABPY_OAUTH_REQUIRED_SCOPES"
31+
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"
3135
TABPY_OAUTH_LOG_USER = "TABPY_OAUTH_LOG_USER"
3236

3337

@@ -62,4 +66,9 @@ class SettingsParameters:
6266
OAuthJwksUri = "oauth_jwks_uri"
6367
OAuthAudience = "oauth_audience"
6468
OAuthRequiredScopes = "oauth_required_scopes"
69+
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"
6574
OAuthLogUser = "oauth_log_user"

‎tabpy/tabpy_server/common/default.conf‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,26 @@
5353
# TABPY_OAUTH_AUDIENCE = tabpy
5454

5555
# Comma-separated list of scopes that must all be present in the JWT's
56-
# `scope` claim. Leave unset to skip scope enforcement.
57-
# TABPY_OAUTH_REQUIRED_SCOPES = tabpy:query,tabpy:evaluate
56+
# `scope` claim on every request (including /info). Leave unset to skip
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
59+
# TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES for that.
60+
# TABPY_OAUTH_REQUIRED_SCOPES = tabpy
61+
62+
# When true, /query requires tabpy:query, /evaluate requires
63+
# tabpy:evaluate, and mutating /endpoints plus the upload-destination
64+
# path require tabpy:deploy. Default false. Independent of
65+
# TABPY_OAUTH_REQUIRED_SCOPES. GET /endpoints stays readable. A SCRIPT_*
66+
# that calls tabpy.query() needs both query and evaluate. Arrow Flight is
67+
# not per-endpoint scoped; it still uses TABPY_OAUTH_REQUIRED_SCOPES only.
68+
# TABPY_OAUTH_ENFORCE_ENDPOINT_SCOPES = true
69+
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
5876

5977
# Log the JWT subject as the authenticated user for OAuth requests.
6078
# TABPY_OAUTH_LOG_USER = true

‎tabpy/tabpy_server/handlers/base_handler.py‎

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,12 @@
55
import logging
66
import tornado.web
77
from tabpy.tabpy_server.app.app_parameters import SettingsParameters
8-
from tabpy.tabpy_server.handlers.jwt_auth import JwtValidationError, validate_jwt
8+
from tabpy.tabpy_server.handlers.jwt_auth import (
9+
JwtValidationError,
10+
endpoint_scope_for_path,
11+
token_has_scope,
12+
validate_jwt,
13+
)
914
from tabpy.tabpy_server.handlers.util import hash_password
1015
from tabpy.tabpy_server.handlers.util import AuthErrorStates
1116
import uuid
@@ -139,9 +144,11 @@ def initialize(self, app):
139144
self.username = None
140145
self.password = None
141146
self.jwt_token = None
147+
self.jwt_claims = None
142148
self.auth_method = None
143149
self.eval_timeout = self.settings[SettingsParameters.EvaluateTimeout]
144150
self.max_request_size = app.max_request_size
151+
self.subdirectory = getattr(app, "subdirectory", "") or ""
145152

146153
self.logger = ContextLoggerWrapper(self.request)
147154
self.logger.enable_context_logging(
@@ -434,6 +441,8 @@ def _validate_jwt_credentials(self) -> bool:
434441
self.logger.log(logging.ERROR, str(ex))
435442
return False
436443

444+
self.jwt_claims = claims
445+
437446
if self.settings.get(SettingsParameters.OAuthLogUser, False):
438447
subject = claims.get("sub")
439448
if subject:
@@ -511,8 +520,34 @@ def handle_authentication(self, api_version):
511520
if not self._validate_credentials(method):
512521
return AuthErrorStates.NotAuthorized
513522

523+
if method == "oauth-jwt":
524+
scope_error = self._endpoint_scope_error()
525+
if scope_error is not None:
526+
return scope_error
527+
514528
return AuthErrorStates.NONE
515529

530+
def _endpoint_scope_error(self):
531+
"""
532+
After a valid JWT, optionally require well-known endpoint scopes
533+
on the matching HTTP path and method. Returns InsufficientScope or None.
534+
"""
535+
if not self.settings.get(SettingsParameters.OAuthEnforceEndpointScopes, False):
536+
return None
537+
if self.request.method == "OPTIONS":
538+
return None
539+
required = endpoint_scope_for_path(
540+
self.request.path,
541+
self.subdirectory,
542+
self.request.method,
543+
self.settings.get(SettingsParameters.OAuthEndpointScopes),
544+
)
545+
if not required:
546+
return None
547+
if token_has_scope(self.jwt_claims or {}, required):
548+
return None
549+
return AuthErrorStates.InsufficientScope
550+
516551
def should_fail_with_auth_error(self):
517552
"""
518553
Checks if authentication is required:
@@ -558,6 +593,19 @@ def fail_with_auth_error(self):
558593
info="Unauthorized request.",
559594
log_message="Invalid credentials provided.",
560595
)
596+
elif self.auth_error == AuthErrorStates.InsufficientScope:
597+
self.logger.log(logging.ERROR, "Failing with 403 for insufficient scope")
598+
self.set_status(403)
599+
self.set_header(
600+
"WWW-Authenticate",
601+
f'{scheme} realm="{self.tabpy_state.name}", '
602+
'error="insufficient_scope"',
603+
)
604+
self.error_out(
605+
403,
606+
info="Forbidden request.",
607+
log_message="Token is missing a required endpoint scope.",
608+
)
561609
else:
562610
self.logger.log(logging.ERROR, "Failing with 406 for Not Acceptable")
563611
self.set_status(406)

0 commit comments

Comments
 (0)