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
314323TABPY_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+
328393To authenticate a request, send the JWT as a Bearer token:
329394
330395``` sh
0 commit comments