The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
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.ednindex e3229cc455b..73e9650bd92 100644--- a/.clj-kondo/config/modules/config.edn+++ b/.clj-kondo/config/modules/config.edn@@ -152,6 +152,7 @@metabase.api.docsmetabase.api.initmetabase.api.macros+ metabase.api.macros.scopemetabase.api.open-apimetabase.api.responsemetabase.api.routes.commondiff --git a/enterprise/backend/src/metabase_enterprise/agent_api/api.clj b/enterprise/backend/src/metabase_enterprise/agent_api/api.cljindex 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 usingReciprocal 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-paramsbody :- ::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 Metabasesession 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.cljindex 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.cljindex 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 :- ::handlerdiff --git a/src/metabase/api/macros/scope.clj b/src/metabase/api/macros/scope.cljnew file mode 100644index 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.cljnew file mode 100644index 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 #{}})))))))