Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Implement scoped authorization to limit API surface (#70372)

Chris Truter0e1325ba1e11
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index e3229cc455b..73e9650bd92 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -152,6 +152,7 @@
metabase.api.docs
metabase.api.init
metabase.api.macros
+ metabase.api.macros.scope
metabase.api.open-api
metabase.api.response
metabase.api.routes.common
diff --git a/enterprise/backend/src/metabase_enterprise/agent_api/api.clj b/enterprise/backend/src/metabase_enterprise/agent_api/api.clj
index 3cf10bc6c5f..7b464cf1c71 100644
--- a/enterprise/backend/src/metabase_enterprise/agent_api/api.clj
+++ b/enterprise/backend/src/metabase_enterprise/agent_api/api.clj
@@ -13,6 +13,7 @@
[metabase-enterprise.metabot-v3.util :as metabot-v3.u]
[metabase.api.common :as api]
[metabase.api.macros :as api.macros]
+ [metabase.api.macros.scope :as scope]
[metabase.api.routes.common :as api.routes.common]
[metabase.auth-identity.core :as auth-identity]
[metabase.query-processor :as qp]
@@ -190,11 +191,13 @@
(api.macros/defendpoint :get "/v1/ping" :- [:map [:message :string]]
"Health check endpoint for the Agent API."
+ {:scope :unchecked}
[]
{:message "pong"})
(api.macros/defendpoint :get "/v1/table/:id" :- ::table
"Get details for a table by ID."
+ {:scope "agent:table:read"}
[{:keys [id]} :- [:map [:id ms/PositiveInt]]
{:keys [with-fields with-field-values with-related-tables with-metrics with-measures with-segments]
:or {with-fields true, with-field-values false, with-related-tables true,
@@ -218,6 +221,7 @@
(api.macros/defendpoint :get "/v1/table/:id/field/:field-id/values" :- ::field-values
"Get statistics and sample values for a table field."
+ {:scope "agent:table:read"}
[{:keys [id field-id]} :- [:map
[:id ms/PositiveInt]
[:field-id ms/NonBlankString]]]
@@ -230,6 +234,7 @@
(api.macros/defendpoint :get "/v1/metric/:id" :- ::metric
"Get details for a metric by ID."
+ {:scope "agent:metric:read"}
[{:keys [id]} :- [:map [:id ms/PositiveInt]]
{:keys [with-default-temporal-breakout with-field-values with-queryable-dimensions with-segments]
:or {with-default-temporal-breakout true, with-field-values false,
@@ -249,6 +254,7 @@
(api.macros/defendpoint :get "/v1/metric/:id/field/:field-id/values" :- ::field-values
"Get statistics and sample values for a metric field."
+ {:scope "agent:metric:read"}
[{:keys [id field-id]} :- [:map
[:id ms/PositiveInt]
[:field-id ms/NonBlankString]]]
@@ -264,6 +270,7 @@
Supports both term-based and semantic search queries. Results are ranked using
Reciprocal Rank Fusion when both query types are provided."
+ {:scope "agent:search"}
[_route-params
_query-params
{term-queries :term_queries
@@ -354,6 +361,7 @@
For tables, supports: filters, fields, aggregations, group_by, order_by, limit.
For metrics, supports: filters, group_by (aggregation is defined by the metric)."
+ {:scope "agent:query:construct"}
[_route-params
_query-params
body :- ::construct-query-request]
@@ -401,6 +409,7 @@
- On failure: {:status :failed :error \"message\" ...}
Standard userspace query limits are enforced (2000 rows for simple queries, 10000 for aggregated)."
+ {:scope "agent:query:execute"}
[_route-params
_query-params
{encoded-query :query} :- ::execute-query-request]
@@ -446,11 +455,14 @@
;;; -------------------------------------------- Stateless JWT Authentication --------------------------------------------
(defn- authenticate-with-jwt
- "Authenticate a request using a stateless JWT. Returns {:user <user>} on success,
- or {:error <type> :message <msg>} on failure. Does NOT create a session.
+ "Authenticate a request using a stateless JWT. Returns `{:user <user>}` on success, or
+ `{:error <type> :message <msg>}` on failure. Does NOT create a session.
- Uses auth-identity/authenticate to validate the JWT, which reuses the same
- implementation as the /auth/sso endpoint and handles all settings validation."
+ Uses auth-identity/authenticate to validate the JWT, which reuses the same implementation as the /auth/sso endpoint
+ and handles all settings validation.
+
+ When the JWT contains a `\"scope\"` claim, the result includes `:scopes` — a parsed set of scope strings — so that
+ [[enforce-authentication]] can attach it to the request for downstream scope enforcement."
[token]
(let [result (auth-identity/authenticate :provider/jwt {:token token})]
(if (:success? result)
@@ -458,7 +470,10 @@
;; The provider uses jwt-attribute-email setting to extract the email from claims
(if-let [user (when-let [email (get-in result [:user-data :email])]
(t2/select-one :model/User :%lower.email (u/lower-case-en email) :is_active true))]
- {:user user}
+ (let [scope-entry (-> result :jwt-data (find :scope))]
+ (cond-> {:user user}
+ scope-entry
+ (assoc :scopes (or (scope/parse-scopes (val scope-entry)) #{}))))
;; Don't reveal whether the user exists or not - use same error as invalid JWT
{:error "invalid_jwt"
:message "Invalid or expired JWT token."})
@@ -475,6 +490,10 @@
(defn- enforce-authentication
"Middleware that ensures requests are authenticated.
+ Always sets `:token-scopes` on authenticated requests — `#{::scope/unrestricted}` for unrestricted access
+ (session auth or unscoped JWTs), or the parsed scope set for scoped JWTs. This ensures downstream scope
+ enforcement never has to special-case nil within the agent API.
+
Supports two authentication modes:
- **Session-based**: Uses `X-Metabase-Session` header, validated by standard Metabase
session middleware (which runs before this). If `:metabase-user-id` is set on the
@@ -486,7 +505,7 @@
(cond
;; Already authenticated via X-Metabase-Session (standard middleware handled it)
metabase-user-id
- (handler request respond raise)
+ (handler (assoc request :token-scopes #{::scope/unrestricted}) respond raise)
;; Not authenticated via session - check for Bearer JWT
:else
@@ -508,9 +527,9 @@
(let [result (authenticate-with-jwt bearer-token)]
(if-let [user (:user result)]
(request/with-current-user (:id user)
- (handler request respond raise))
+ (handler (assoc request :token-scopes (or (:scopes result) #{::scope/unrestricted}))
+ respond raise))
(respond (error-response (:error result) (:message result))))))))))
-
(def ^:private +auth
(api.routes.common/wrap-middleware-for-open-api-spec-generation enforce-authentication))
diff --git a/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj b/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj
index 865274708d9..5478d0ce68a 100644
--- a/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj
@@ -492,6 +492,55 @@
:name "Total Revenue"}]
(:measures table)))))))))
+(deftest agent-api-scope-enforcement-test
+ (with-agent-api-setup!
+ (let [table-id (mt/id :orders)]
+ (testing "No scope claim — unscoped JWT can access all endpoints (backwards compat)"
+ (let [headers {"authorization" (str "Bearer " (sign-jwt {:email "[email protected]"}))}]
+ (is (= {:message "pong"}
+ (client/client :get 200 "agent/v1/ping"
+ {:request-options {:headers headers}})))
+ (is (=? {:type "table" :id table-id}
+ (client/client :get 200 (str "agent/v1/table/" table-id)
+ {:request-options {:headers headers}})))))
+
+ (testing "Matching scope — agent:table:read can access /v1/table/:id"
+ (let [headers {"authorization" (str "Bearer " (sign-jwt {:email "[email protected]"
+ :scope "agent:table:read"}))}]
+ (is (=? {:type "table" :id table-id}
+ (client/client :get 200 (str "agent/v1/table/" table-id)
+ {:request-options {:headers headers}})))))
+
+ (testing "Wildcard scope — agent:* can access any scoped endpoint"
+ (let [headers {"authorization" (str "Bearer " (sign-jwt {:email "[email protected]"
+ :scope "agent:*"}))}]
+ (is (=? {:type "table" :id table-id}
+ (client/client :get 200 (str "agent/v1/table/" table-id)
+ {:request-options {:headers headers}})))))
+
+ (testing "Wrong scope — agent:search gets 403 on /v1/table/:id"
+ (let [headers {"authorization" (str "Bearer " (sign-jwt {:email "[email protected]"
+ :scope "agent:search"}))}]
+ (is (= {:error "unsupported_scope"
+ :message "Token does not have required scope: agent:table:read"}
+ (client/client :get 403 (str "agent/v1/table/" table-id)
+ {:request-options {:headers headers}})))))
+
+ (testing "Scoped JWT on unchecked endpoint — agent:table:read can access /v1/ping"
+ (let [headers {"authorization" (str "Bearer " (sign-jwt {:email "[email protected]"
+ :scope "agent:table:read"}))}]
+ (is (= {:message "pong"}
+ (client/client :get 200 "agent/v1/ping"
+ {:request-options {:headers headers}})))))
+
+ (testing "Empty scope string — gets 403 on scoped endpoints"
+ (let [headers {"authorization" (str "Bearer " (sign-jwt {:email "[email protected]"
+ :scope ""}))}]
+ (is (= {:error "unsupported_scope"
+ :message "Token does not have required scope: agent:table:read"}
+ (client/client :get 403 (str "agent/v1/table/" table-id)
+ {:request-options {:headers headers}}))))))))
+
(deftest search-finds-metrics-test
(with-agent-api-setup!
(binding [search.ingestion/*force-sync* true]
diff --git a/src/metabase/api/macros.clj b/src/metabase/api/macros.clj
index 5d18a49a802..a89e4d0a711 100644
--- a/src/metabase/api/macros.clj
+++ b/src/metabase/api/macros.clj
@@ -27,6 +27,7 @@
[medley.core :as m]
[metabase.api.common.internal]
[metabase.api.macros.defendpoint.open-api]
+ [metabase.api.macros.scope]
[metabase.api.open-api :as open-api]
[metabase.config.core :as config]
[metabase.events.core :as events]
@@ -583,13 +584,25 @@
body))))
(mu/defn- middleware-forms
- "Middleware to apply to base handler. Currently the only option is middleware for handling multipart requests, applied
- if the handler metadata contains
+ "Middleware to apply to base handler. Supports:
- {:multipart true}"
+ {:multipart true} — wraps with multipart-params middleware
+ {:scope \"agent:workspaces\"} — wraps with scope enforcement middleware
+ {:scope :unchecked} — skips both enforce-scope and ensure-scopes-checked
+
+ Endpoints without `:scope` get [[metabase.api.macros.scope/ensure-scopes-checked]] to prevent scoped
+ tokens from reaching endpoints that haven't opted in."
[{:keys [metadata], :as _args} :- ::parsed-args]
- (when (:multipart metadata)
- '[ring.middleware.multipart-params/wrap-multipart-params]))
+ (let [scope (:scope metadata)
+ scope-middleware (cond
+ (string? scope) [(list 'metabase.api.macros.scope/enforce-scope scope)]
+ (= scope :unchecked) []
+ :else (do (when (some? scope)
+ (log/warnf "Unrecognized :scope value %s — expected a string or :unchecked" (pr-str scope)))
+ ['metabase.api.macros.scope/ensure-scopes-checked]))]
+ (cond-> (vec scope-middleware)
+ (:multipart metadata)
+ (conj 'ring.middleware.multipart-params/wrap-multipart-params))))
(mu/defn- apply-middleware :- ::handler
[handler :- ::handler
diff --git a/src/metabase/api/macros/scope.clj b/src/metabase/api/macros/scope.clj
new file mode 100644
index 00000000000..9b5356dfeda
--- /dev/null
+++ b/src/metabase/api/macros/scope.clj
@@ -0,0 +1,83 @@
+(ns metabase.api.macros.scope
+ "OAuth-style scope enforcement for API endpoints.
+
+ Endpoints declare their required scope via `defendpoint` metadata (e.g. `{:scope \"agent:workspaces\"}`).
+ A per-endpoint middleware rejects requests whose token doesn't carry the required scope.
+
+ Endpoints that do NOT declare `:scope` automatically reject requests carrying `:token-scopes`,
+ ensuring that scoped tokens can only reach endpoints that explicitly opt in.
+
+ Scopes are space-delimited strings (mirroring OAuth's `scope` semantics) and support hierarchical
+ wildcards: `agent:*` covers `agent:workspaces`.
+
+ The `::unrestricted` keyword is used as a sentinel in `:token-scopes` to indicate an unrestricted token
+ (session auth or unscoped JWT). Unlike `\"*\"` which is a valid wildcard scope that could appear in a
+ JWT claim, this keyword can never be confused with an externally-supplied scope string."
+ (:require
+ [clojure.string :as str]))
+
+(defn parse-scopes
+ "Parse a space-delimited OAuth scope string into a set of scope strings.
+ Returns nil if `scope-string` is nil, blank, or not a string."
+ [scope-string]
+ (when (string? scope-string)
+ (when-not (str/blank? scope-string)
+ (into #{} (str/split (str/trim scope-string) #"\s+")))))
+
+(defn scope-satisfied?
+ "Check if `token-scopes` (a set) satisfies `required-scope` (a string).
+ Supports hierarchical wildcards: `\"agent:*\"` covers `\"agent:workspaces\"`."
+ [token-scopes required-scope]
+ (boolean
+ (or (contains? token-scopes required-scope)
+ (contains? token-scopes "*")
+ (some (fn [token-scope]
+ (and (str/ends-with? token-scope ":*")
+ (str/starts-with? required-scope (subs token-scope 0 (dec (count token-scope))))))
+ token-scopes))))
+
+(defn enforce-scope
+ "Returns a Ring middleware that checks `:token-scopes` on the request against `required-scope` (a string).
+ Passes through when `:token-scopes` is nil (normal session auth) or contains `::unrestricted`
+ (session auth or unscoped JWT).
+
+ On success, sets `:token-scopes-checked` on the request so that downstream [[ensure-scopes-checked]]
+ middleware knows scope enforcement already happened. This allows `enforce-scope` to be applied at the
+ namespace level while individual endpoints use `ensure-scopes-checked` as a safety net."
+ [required-scope]
+ (fn [handler]
+ (fn [request respond raise]
+ (let [token-scopes (:token-scopes request)]
+ (if (or (nil? token-scopes)
+ (contains? token-scopes ::unrestricted)
+ (scope-satisfied? token-scopes required-scope))
+ (handler (cond-> request
+ token-scopes (assoc :token-scopes-checked true))
+ respond raise)
+ (respond {:status 403
+ :headers {"Content-Type" "application/json"}
+ :body {:error "unsupported_scope"
+ :message (str "Token does not have required scope: " required-scope)}}))))))
+
+(defn ensure-scopes-checked
+ "Security middleware that prevents scoped authorization tokens from accessing endpoints that have not
+ declared a required scope. When authorization is scoped (i.e. `:token-scopes` is present on the request),
+ only endpoints with an explicit `:scope` in their metadata — or that sit behind a namespace-level
+ [[enforce-scope]] middleware — should be reachable. This middleware is applied automatically by
+ `defendpoint` to any endpoint without `:scope` metadata to enforce that invariant.
+
+ Passes through when:
+ - `:token-scopes` is nil (request did not go through scope-aware auth)
+ - `:token-scopes` contains `::unrestricted` (session auth or unscoped JWT)
+ - `:token-scopes-checked` is true ([[enforce-scope]] already ran, e.g. at the namespace level)"
+ [handler]
+ (fn [request respond raise]
+ (let [token-scopes (:token-scopes request)]
+ (if (or (nil? token-scopes)
+ (contains? token-scopes ::unrestricted)
+ (:token-scopes-checked request))
+ (handler request respond raise)
+ (respond {:status 403
+ :headers {"Content-Type" "application/json"}
+ :body {:error "scope_not_permitted"
+ :message "Scoped tokens cannot access this endpoint."}})))))
diff --git a/test/metabase/api/macros/scope_test.clj b/test/metabase/api/macros/scope_test.clj
new file mode 100644
index 00000000000..ca58d0cbb08
--- /dev/null
+++ b/test/metabase/api/macros/scope_test.clj
@@ -0,0 +1,107 @@
+(ns metabase.api.macros.scope-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.api.macros.scope :as scope]))
+
+(defn- invoke-handler
+ "Invoke an async Ring handler and return the response, with a generous timeout in case things go wrong.
+ Note: Clojure promises implement IFn via `deliver`, so they work directly as Ring `respond` callbacks."
+ [handler request]
+ (let [result (promise)]
+ (handler request result identity)
+ (let [response (deref result 10000 ::timeout)]
+ (is (not= ::timeout response) "Handler did not respond within 10s")
+ response)))
+
+(deftest ^:parallel parse-scopes-test
+ (testing "nil input returns nil"
+ (is (nil? (scope/parse-scopes nil))))
+ (testing "empty string returns nil"
+ (is (nil? (scope/parse-scopes ""))))
+ (testing "blank string returns nil"
+ (is (nil? (scope/parse-scopes " "))))
+ (testing "single scope"
+ (is (= #{"agent:workspaces"}
+ (scope/parse-scopes "agent:workspaces"))))
+ (testing "multiple scopes"
+ (is (= #{"agent:workspaces" "agent:queries" "read:users"}
+ (scope/parse-scopes "agent:workspaces agent:queries read:users"))))
+ (testing "trims whitespace"
+ (is (= #{"agent:workspaces"}
+ (scope/parse-scopes " agent:workspaces "))))
+ (testing "wildcard scope"
+ (is (= #{"*"}
+ (scope/parse-scopes "*")))))
+
+(deftest ^:parallel scope-satisfied?-test
+ (testing "exact match"
+ (is (scope/scope-satisfied? #{"agent:workspaces"} "agent:workspaces"))
+ (is (not (scope/scope-satisfied? #{"agent:queries"} "agent:workspaces"))))
+ (testing "global wildcard"
+ (is (scope/scope-satisfied? #{"*"} "agent:workspaces"))
+ (is (scope/scope-satisfied? #{"*"} "anything")))
+ (testing "hierarchical wildcard"
+ (is (scope/scope-satisfied? #{"agent:*"} "agent:workspaces"))
+ (is (scope/scope-satisfied? #{"agent:*"} "agent:queries"))
+ (is (not (scope/scope-satisfied? #{"agent:*"} "read:users"))))
+ (testing "deeper hierarchy"
+ (is (scope/scope-satisfied? #{"a:*"} "a:b:c"))
+ (is (scope/scope-satisfied? #{"a:b:*"} "a:b:c"))
+ (is (not (scope/scope-satisfied? #{"a:b:*"} "a:x:c"))))
+ (testing "empty scopes set never satisfies"
+ (is (not (scope/scope-satisfied? #{} "agent:workspaces"))))
+ (testing "multiple scopes in set"
+ (is (scope/scope-satisfied? #{"read:users" "agent:workspaces"} "agent:workspaces"))
+ (is (not (scope/scope-satisfied? #{"read:users" "agent:queries"} "agent:workspaces")))))
+
+(deftest ^:parallel enforce-scope-test
+ (let [ok-handler (fn [_request respond _raise]
+ (respond {:status 200 :body "ok"}))
+ middleware (scope/enforce-scope "agent:workspaces")]
+ (testing "nil token-scopes (normal session auth) passes through"
+ (is (= {:status 200 :body "ok"}
+ (invoke-handler (middleware ok-handler) {}))))
+ (testing "matching scope passes through"
+ (is (= {:status 200 :body "ok"}
+ (invoke-handler (middleware ok-handler) {:token-scopes #{"agent:workspaces"}}))))
+ (testing "wildcard scope passes through"
+ (is (= {:status 200 :body "ok"}
+ (invoke-handler (middleware ok-handler) {:token-scopes #{"agent:*"}}))))
+ (testing "insufficient scope returns 403"
+ (let [response (invoke-handler (middleware ok-handler) {:token-scopes #{"agent:queries"}})]
+ (is (= 403 (:status response)))
+ (is (= "unsupported_scope" (get-in response [:body :error])))))
+ (testing "empty scopes set returns 403"
+ (is (= 403 (:status (invoke-handler (middleware ok-handler) {:token-scopes #{}}))))))
+ (testing "sets :token-scopes-checked on the request"
+ (let [seen-request (promise)
+ spy-handler (fn [request respond _raise]
+ (deliver seen-request request)
+ (respond {:status 200}))
+ middleware (scope/enforce-scope "agent:workspaces")]
+ (invoke-handler (middleware spy-handler) {:token-scopes #{"agent:workspaces"}})
+ (is (true? (:token-scopes-checked (deref seen-request 1000 ::timeout)))))))
+
+(deftest ^:parallel ensure-scopes-checked-test
+ (let [ok-handler (fn [_request respond _raise]
+ (respond {:status 200 :body "ok"}))]
+ (testing "nil token-scopes (not in scope context) passes through"
+ (is (= {:status 200 :body "ok"}
+ (invoke-handler (scope/ensure-scopes-checked ok-handler) {}))))
+ (testing "unrestricted token passes through"
+ (is (= {:status 200 :body "ok"}
+ (invoke-handler (scope/ensure-scopes-checked ok-handler) {:token-scopes #{::scope/unrestricted}}))))
+ (testing "wildcard string scope does NOT pass through (must use sentinel)"
+ (is (= 403
+ (:status (invoke-handler (scope/ensure-scopes-checked ok-handler) {:token-scopes #{"*"}})))))
+ (testing "scoped request without prior check is rejected with 403"
+ (let [response (invoke-handler (scope/ensure-scopes-checked ok-handler) {:token-scopes #{"agent:workspaces"}})]
+ (is (= 403 (:status response)))
+ (is (= "scope_not_permitted" (get-in response [:body :error])))))
+ (testing "scoped request with :token-scopes-checked passes through"
+ (is (= {:status 200 :body "ok"}
+ (invoke-handler (scope/ensure-scopes-checked ok-handler)
+ {:token-scopes #{"agent:workspaces"} :token-scopes-checked true}))))
+ (testing "empty token-scopes set without prior check is rejected"
+ (is (= 403
+ (:status (invoke-handler (scope/ensure-scopes-checked ok-handler) {:token-scopes #{}})))))))