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
Semantic layer agent API groundwork + auth (#68163)
Noah Moss731688891322
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.ednindex 4664bfe75f5..f766004d44f 100644--- a/.clj-kondo/config/modules/config.edn+++ b/.clj-kondo/config/modules/config.edn@@ -2081,7 +2081,8 @@enterprise/metabot-v3{:team "Metabot"- :api #{metabase-enterprise.metabot-v3.api+ :api #{metabase-enterprise.metabot-v3.agent-api.api+ metabase-enterprise.metabot-v3.apimetabase-enterprise.metabot-v3.clientmetabase-enterprise.metabot-v3.coremetabase-enterprise.metabot-v3.init@@ -2090,6 +2091,7 @@apiapp-dbaudit-app+ auth-identitycollectionsconfigdocumentsdiff --git a/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj b/enterprise/backend/src/metabase_enterprise/api_routes/routes.cljindex bdf10d368ec..94de4477478 100644--- a/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj+++ b/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj@@ -26,6 +26,7 @@[metabase-enterprise.gsheets.api :as gsheets.api][metabase-enterprise.library.api][metabase-enterprise.llm.api]+ [metabase-enterprise.metabot-v3.agent-api.api][metabase-enterprise.metabot-v3.api][metabase-enterprise.metabot-v3.tools.api][metabase-enterprise.permission-debug.api]@@ -45,7 +46,8 @@[metabase.util.i18n :refer [deferred-tru]]))(comment metabase-enterprise.advanced-config.api.logs/keep-me- metabase-enterprise.llm.api/keep-me)+ metabase-enterprise.llm.api/keep-me+ metabase-enterprise.metabot-v3.agent-api.api/keep-me)(def ^:private required-feature->message{:advanced-permissions (deferred-tru "Advanced Permissions")@@ -87,7 +89,8 @@`/ee/<feature>/`).TODO -- Please fix them! See #22687"- {"/moderation-review" metabase-enterprise.content-verification.api.routes/routes+ {"/agent" (premium-handler metabase-enterprise.metabot-v3.agent-api.api/routes :metabot-v3)+ "/moderation-review" metabase-enterprise.content-verification.api.routes/routes"/mt" metabase-enterprise.sandbox.api.routes/sandbox-routes"/table" metabase-enterprise.sandbox.api.routes/sandbox-table-routes})diff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.cljnew file mode 100644index 00000000000..8b2bf026baa--- /dev/null+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.clj@@ -0,0 +1,121 @@+(ns metabase-enterprise.metabot-v3.agent-api.api+ "Customer-facing Agent API for headless BI applications.+ Endpoints are versioned (e.g., /v1/search) and use standard HTTP semantics."+ (:require+ [clojure.string :as str]+ [metabase.api.macros :as api.macros]+ [metabase.api.routes.common :as api.routes.common]+ [metabase.auth-identity.core :as auth-identity]+ [metabase.request.core :as request]+ [metabase.util :as u]+ [toucan2.core :as t2]))++;;; --------------------------------------------------- Endpoints ----------------------------------------------------++(api.macros/defendpoint :get "/v1/ping" :- [:map [:message :string]]+ "Health check endpoint for the Agent API."+ []+ {:message "pong"})++;;; ------------------------------------------------- Authentication -------------------------------------------------+;;+;; The Agent API supports two authentication modes:+;;+;; 1. **Session-based**: Client exchanges JWT at `/auth/sso` endpoint to get a session token,+;; then passes it via `X-Metabase-Session` header. The standard Metabase session middleware+;; handles validation and expiration checking automatically.+;;+;; 2. **Stateless JWT**: Client passes a JWT via `Authorization: Bearer <jwt>` header.+;; The JWT is validated using the configured shared secret and max-age settings.+;; Good for simple integrations and one-off API calls.++(defn- extract-bearer-token+ "Extract the token from a Bearer authorization header."+ [auth-header]+ (when (and auth-header (str/starts-with? (u/lower-case-en auth-header) "bearer "))+ (str/trim (subs auth-header 7))))++(defn- error-response+ "Create a 401 error response with structured JSON body."+ [error-type message]+ {:status 401+ :headers {"Content-Type" "application/json"}+ :body {:error error-type+ :message message}})++;;; -------------------------------------------- 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.++ Uses auth-identity/authenticate to validate the JWT, which reuses the same+ implementation as the /auth/sso endpoint and handles all settings validation."+ [token]+ (let [result (auth-identity/authenticate :provider/jwt {:token token})]+ (if (:success? result)+ ;; JWT is valid - look up user from the email extracted by the JWT provider+ ;; 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}+ ;; Don't reveal whether the user exists or not - use same error as invalid JWT+ {:error "invalid_jwt"+ :message "Invalid or expired JWT token."})+ ;; Authentication failed - map error to agent API format+ (case (:error result)+ :jwt-not-enabled {:error "jwt_not_configured"+ :message "JWT authentication is not configured. Set the JWT shared secret in admin settings."}+ ;; Default: use generic invalid JWT message (don't leak details)+ {:error "invalid_jwt"+ :message "Invalid or expired JWT token."}))))++;;; -------------------------------------------------- Middleware ----------------------------------------------------++(defn- enforce-authentication+ "Middleware that ensures requests are authenticated.++ 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+ request, the user is already authenticated.+ - **Stateless JWT**: Uses `Authorization: Bearer <jwt>` header. The JWT is validated+ using the same auth-identity system as the /auth/sso endpoint."+ [handler]+ (fn [{:keys [headers metabase-user-id] :as request} respond raise]+ (cond+ ;; Already authenticated via X-Metabase-Session (standard middleware handled it)+ metabase-user-id+ (handler request respond raise)++ ;; Not authenticated via session - check for Bearer JWT+ :else+ (let [auth-header (get headers "authorization")+ bearer-token (extract-bearer-token auth-header)]+ (cond+ ;; No authorization header and no session+ (nil? auth-header)+ (respond (error-response "missing_authorization"+ "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."))++ ;; Authorization header present but not Bearer format+ (nil? bearer-token)+ (respond (error-response "invalid_authorization_format"+ "Authorization header must use Bearer scheme: Authorization: Bearer <jwt>"))++ ;; Validate JWT+ :else+ (let [result (authenticate-with-jwt bearer-token)]+ (if-let [user (:user result)]+ (request/with-current-user (:id user)+ (handler request respond raise))+ (respond (error-response (:error result) (:message result))))))))))++(def ^:private +auth+ (api.routes.common/wrap-middleware-for-open-api-spec-generation enforce-authentication))++;;; ---------------------------------------------------- Routes ------------------------------------------------------++(def ^{:arglists '([request respond raise])} routes+ "`/api/agent/` routes."+ (api.macros/ns-handler *ns* +auth))diff --git a/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.clj b/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.cljnew file mode 100644index 00000000000..af737206a32--- /dev/null+++ b/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.clj@@ -0,0 +1,141 @@+(ns metabase-enterprise.metabot-v3.agent-api.api-test+ (:require+ [buddy.sign.jwt :as jwt]+ [clojure.test :refer :all]+ [environ.core :as env]+ [java-time.api :as t]+ [metabase-enterprise.sso.test-setup :as sso.test-setup]+ [metabase.session.models.session :as session.models]+ [metabase.test :as mt]+ [metabase.test.fixtures :as fixtures]+ [metabase.test.http-client :as client]+ [toucan2.core :as t2]))++(set! *warn-on-reflection* true)++(use-fixtures :once (fixtures/initialize :db :test-users))++(defn- current-epoch-seconds []+ (int (/ (System/currentTimeMillis) 1000)))++(defn- sign-jwt+ "Sign a JWT with the test secret. Automatically adds `iat` claim if not present,+ which is required for max-age validation."+ [claims]+ (jwt/sign (merge {:iat (current-epoch-seconds)} claims) sso.test-setup/default-jwt-secret))++(defmacro with-agent-api-setup!+ "Sets up JWT authentication for Agent API tests.+ Reuses the SSO JWT test setup which handles premium features and settings correctly."+ [& body]+ `(sso.test-setup/with-jwt-default-setup!+ (mt/with-additional-premium-features #{:metabot-v3}+ ~@body)))++(defn- auth-headers+ "Create authorization headers with a signed JWT for the given email."+ ([]+ (auth-headers "[email protected]"))+ ([email]+ {"authorization" (str "Bearer " (sign-jwt {:email email}))}))++(deftest agent-api-jwt-auth-test+ (with-agent-api-setup!+ (testing "Valid JWT with email claim succeeds"+ (is (= {:message "pong"}+ (client/client :get 200 "agent/v1/ping"+ {:request-options {:headers (auth-headers)}}))))++ (testing "Email case insensitivity - uppercase email in token"+ (is (= {:message "pong"}+ (client/client :get 200 "agent/v1/ping"+ {:request-options {:headers (auth-headers "[email protected]")}}))))++ (testing "Email case insensitivity - mixed case email in token"+ (is (= {:message "pong"}+ (client/client :get 200 "agent/v1/ping"+ {:request-options {:headers (auth-headers "[email protected]")}}))))++ (testing "Bearer scheme is case-insensitive (uppercase BEARER)"+ (let [token (sign-jwt {:email "[email protected]"})+ response (client/client :get 200 "agent/v1/ping"+ {:request-options {:headers {"authorization" (str "BEARER " token)}}})]+ (is (= {:message "pong"}+ response))))++ (testing "Bearer scheme is case-insensitive (mixed case)"+ (let [token (sign-jwt {:email "[email protected]"})+ response (client/client :get 200 "agent/v1/ping"+ {:request-options {:headers {"authorization" (str "BeArEr " token)}}})]+ (is (= {:message "pong"}+ response))))))++(deftest agent-api-error-responses-test+ (with-agent-api-setup!+ (testing "Missing authorization header (no session, no JWT)"+ (let [response (client/client :get 401 "agent/v1/ping")]+ (is (= {:error "missing_authorization"+ :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}+ response))))++ (testing "Invalid authorization header format (not Bearer)"+ (let [response (client/client :get 401 "agent/v1/ping"+ {:request-options {:headers {"authorization" "Basic xyz"}}})]+ (is (= {:error "invalid_authorization_format"+ :message "Authorization header must use Bearer scheme: Authorization: Bearer <jwt>"}+ response))))++ (testing "Token with non-existent user returns same error as invalid token (no information disclosure)"+ (is (= {:error "invalid_jwt"+ :message "Invalid or expired JWT token."}+ (client/client :get 401 "agent/v1/ping"+ {:request-options {:headers (auth-headers "[email protected]")}}))))))++(deftest agent-api-session-token-auth-test+ (mt/test-helpers-set-global-values!+ (mt/with-additional-premium-features #{:metabot-v3}+ (testing "Session tokens via X-Metabase-Session header authenticate successfully"+ (let [session-key (session.models/generate-session-key)+ _ (t2/insert! :model/Session+ {:id (session.models/generate-session-id)+ :user_id (mt/user->id :rasta)+ :session_key session-key})+ response (client/client :get 200 "agent/v1/ping"+ {:request-options {:headers {"x-metabase-session" session-key}}})]+ (is (= {:message "pong"} response))))++ (testing "Invalid session token returns 401"+ (let [fake-session-key (str (random-uuid))+ response (client/client :get 401 "agent/v1/ping"+ {:request-options {:headers {"x-metabase-session" fake-session-key}}})]+ ;; Invalid session means standard middleware doesn't set metabase-user-id,+ ;; so our middleware sees no auth and returns missing_authorization+ (is (= {:error "missing_authorization"+ :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}+ response)))))))++(deftest agent-api-inactive-user-test+ (with-agent-api-setup!+ (testing "JWT for deactivated user returns same error as invalid token (no information disclosure)"+ (mt/with-temp [:model/User {email :email} {:is_active false}]+ (is (= {:error "invalid_jwt"+ :message "Invalid or expired JWT token."}+ (client/client :get 401 "agent/v1/ping"+ {:request-options {:headers (auth-headers email)}})))))))++(deftest agent-api-expired-session-test+ (testing "Expired sessions are rejected by the standard session middleware"+ (mt/test-helpers-set-global-values!+ (mt/with-additional-premium-features #{:metabot-v3}+ ;; Set max-session-age to 1 minute for this test+ (with-redefs [env/env (assoc env/env :max-session-age "1")]+ (let [session-key (session.models/generate-session-key)+ old-time (t/minus (t/instant) (t/minutes 2))]+ (mt/with-temp [:model/Session _ {:user_id (mt/user->id :rasta)+ :session_key session-key+ :created_at old-time}]+ (testing "Session older than max-session-age is rejected"+ (is (= {:error "missing_authorization"+ :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}+ (client/client :get 401 "agent/v1/ping"+ {:request-options {:headers {"x-metabase-session" session-key}}})))))))))))