Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(mcp): answer refused refresh grants with invalid_grant, not 502 (#9594)

teo634d75ca3431
diff --git a/Cargo.lock b/Cargo.lock
index 22e4875618..6f6322eb81 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -8608,6 +8608,7 @@ dependencies = [
"thiserror 2.0.18",
"tokio",
"tracing",
+ "tracing-subscriber",
"upstream_error",
"urlencoding",
"uuid",
@@ -12864,6 +12865,7 @@ dependencies = [
"tower 0.5.3",
"tower-http",
"tracing",
+ "upstream_error",
"url",
"urlencoding",
"uuid",
diff --git a/crates/fusionauth/AGENTS.md b/crates/fusionauth/AGENTS.md
index 8f09bf956a..7a188a9e44 100644
--- a/crates/fusionauth/AGENTS.md
+++ b/crates/fusionauth/AGENTS.md
@@ -48,6 +48,16 @@ passwordless/password flows against the FusionAuth HTTP API.
the body). They turn outages, throttling, timeouts, and undecodable bodies
into `Upstream` (502/503 via `crates/upstream_error`); a hand-written
`Generic` becomes a 500.
+- `#[tracing::instrument]` records every argument it does not skip as a span
+ field, and span fields reach the logs. Skip codes, tokens, and other
+ credentials by name.
+- The OAuth2 token endpoint (`src/oauth.rs`) turns an RFC 6749 error body on
+ 400/401 into `OAuth2TokenRefused`; callers check `is_invalid_grant()` to tell
+ a dead code or refresh token from an outage. A dead refresh token is
+ `invalid_grant`, but a dead code is `invalid_request` with the reason
+ `auth_code_not_found`.
+- `DELETE /api/jwt/refresh` takes its token as a JSON body; a form body is
+ refused with `[InvalidContentType]`.
- Calls to Google or Microsoft name the provider:
`FusionAuthClientError::provider_transport("Google", e)`.
- Link lookup and unlink map HTTP 400 `userId` / `[invalid]userId` errors to
diff --git a/crates/fusionauth/Cargo.toml b/crates/fusionauth/Cargo.toml
index 0df3ecb6cb..76af4575e9 100644
--- a/crates/fusionauth/Cargo.toml
+++ b/crates/fusionauth/Cargo.toml
@@ -24,4 +24,5 @@ workspace-hack = { version = "0.1", path = "../workspace-hack" }
[dev-dependencies]
tokio = { workspace = true, features = ["test-util", "net", "io-util", "sync"] }
+tracing-subscriber = { workspace = true }
wiremock = { workspace = true }
diff --git a/crates/fusionauth/src/apple.rs b/crates/fusionauth/src/apple.rs
index 8dc919f8d5..d51408e403 100644
--- a/crates/fusionauth/src/apple.rs
+++ b/crates/fusionauth/src/apple.rs
@@ -63,7 +63,7 @@ async fn login(
impl FusionAuthClient {
/// Performs an Apple login using the provided identity provider ID, id token, and code.
- #[tracing::instrument(skip(self), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
+ #[tracing::instrument(skip(self, id_token, code), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
pub async fn apple_login(
&self,
apple_identity_provider_id: &str,
diff --git a/crates/fusionauth/src/error.rs b/crates/fusionauth/src/error.rs
index f211b4195f..10b05221fe 100644
--- a/crates/fusionauth/src/error.rs
+++ b/crates/fusionauth/src/error.rs
@@ -59,6 +59,11 @@ pub enum FusionAuthClientError {
/// The grant is invalid - user may have revoked access.
#[error("Invalid grant - user may have revoked access")]
InvalidGrant,
+ /// FusionAuth's OAuth2 token endpoint refused the request with an
+ /// RFC 6749 section 5.2 error, such as `invalid_grant` for a refresh
+ /// token it no longer holds.
+ #[error("{SERVICE_NAME} refused the OAuth2 token request: {0}")]
+ OAuth2TokenRefused(OAuth2TokenError),
/// The provider refused to refresh this user's grant by policy, such as a
/// Google Workspace admin not approving Macro. Retrying will not help
/// until the user's organization allows access.
@@ -69,6 +74,44 @@ pub enum FusionAuthClientError {
},
}
+/// An RFC 6749 section 5.2 error from FusionAuth's `/oauth2/token`. Carries no
+/// credential, so it is safe to log.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct OAuth2TokenError {
+ /// The RFC 6749 error code, e.g. `invalid_grant` or `invalid_client`.
+ pub error: String,
+ /// FusionAuth's finer-grained cause, e.g. `refresh_token_not_found`.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub error_reason: Option<String>,
+ /// FusionAuth's human-readable description.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub error_description: Option<String>,
+}
+
+impl OAuth2TokenError {
+ /// Whether the grant itself (code or refresh token) was refused as
+ /// invalid, expired, or revoked. Only the user signing in again fixes
+ /// that; every other code means the request or our client is wrong.
+ /// FusionAuth answers a dead authorization code with `invalid_request` and
+ /// the reason `auth_code_not_found`, not with `invalid_grant`.
+ pub fn is_invalid_grant(&self) -> bool {
+ self.error == "invalid_grant" || self.error_reason.as_deref() == Some("auth_code_not_found")
+ }
+}
+
+impl std::fmt::Display for OAuth2TokenError {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str(&self.error)?;
+ if let Some(reason) = &self.error_reason {
+ write!(f, " ({reason})")?;
+ }
+ if let Some(description) = &self.error_description {
+ write!(f, ": {description}")?;
+ }
+ Ok(())
+ }
+}
+
/// Google OAuth error codes for a grant the user's organization does not let
/// Macro use, such as a Workspace admin who has not approved the app. Only
/// that organization can lift them. `invalid_client` and `unauthorized_client`
diff --git a/crates/fusionauth/src/identity_provider.rs b/crates/fusionauth/src/identity_provider.rs
index 1074bae73f..c161121428 100644
--- a/crates/fusionauth/src/identity_provider.rs
+++ b/crates/fusionauth/src/identity_provider.rs
@@ -63,7 +63,7 @@ impl FusionAuthClient {
}
/// Completes the identity provider login
- #[tracing::instrument(skip(self), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
+ #[tracing::instrument(skip(self, code), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
pub async fn complete_identity_provider_login(
&self,
idp_id: &str,
diff --git a/crates/fusionauth/src/jwt.rs b/crates/fusionauth/src/jwt.rs
index 4a198b8dac..3a0e98c33e 100644
--- a/crates/fusionauth/src/jwt.rs
+++ b/crates/fusionauth/src/jwt.rs
@@ -7,7 +7,7 @@ mod test;
impl FusionAuthClient {
/// Refreshes a JWT token using the provided access and refresh tokens.
- #[tracing::instrument(skip(self), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
+ #[tracing::instrument(skip(self, access_token, refresh_token), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
pub async fn refresh_token(
&self,
access_token: &str,
diff --git a/crates/fusionauth/src/jwt/revoke.rs b/crates/fusionauth/src/jwt/revoke.rs
index 1357121aa8..d590ab731d 100644
--- a/crates/fusionauth/src/jwt/revoke.rs
+++ b/crates/fusionauth/src/jwt/revoke.rs
@@ -2,9 +2,9 @@ use crate::{AuthedClient, Result, error::FusionAuthClientError};
/// Revokes a single refresh token. A token FusionAuth does not know (already
/// revoked or expired) counts as revoked, so callers can retry.
-/// The token goes in a form-encoded body, which FusionAuth accepts in place of
-/// the `token` query parameter, so it stays out of URLs and request logs.
-/// FusionAuth does not read a JSON body here.
+/// The token goes in a JSON body, which FusionAuth accepts in place of the
+/// `token` query parameter, so it stays out of URLs and request logs.
+/// FusionAuth rejects a form-encoded body here with `[InvalidContentType]`.
/// https://fusionauth.io/docs/apis/jwt/revoke-refresh-tokens
/// Valid responses: 200, 400, 401, 404, 500, 503
pub(crate) async fn revoke_refresh_token(
@@ -15,7 +15,7 @@ pub(crate) async fn revoke_refresh_token(
let res = client
.client()
.delete(format!("{base_url}/api/jwt/refresh"))
- .form(&[("token", refresh_token)])
+ .json(&serde_json::json!({ "token": refresh_token }))
.send()
.await
.map_err(FusionAuthClientError::transport)?;
diff --git a/crates/fusionauth/src/jwt/test.rs b/crates/fusionauth/src/jwt/test.rs
index 8a1c46fa26..0497682060 100644
--- a/crates/fusionauth/src/jwt/test.rs
+++ b/crates/fusionauth/src/jwt/test.rs
@@ -1,4 +1,4 @@
-use wiremock::matchers::{body_string, header, method, path};
+use wiremock::matchers::{body_json, header, method, path, query_param_is_missing};
use wiremock::{Mock, MockServer, ResponseTemplate};
use crate::FusionAuthClient;
@@ -16,13 +16,14 @@ fn client(base_url: String) -> FusionAuthClient {
}
#[tokio::test]
-async fn revoke_refresh_token_sends_the_token_form_encoded() {
+async fn revoke_refresh_token_sends_the_token_as_json() {
let server = MockServer::start().await;
Mock::given(method("DELETE"))
.and(path("/api/jwt/refresh"))
.and(header("authorization", "api-key"))
- .and(header("content-type", "application/x-www-form-urlencoded"))
- .and(body_string("token=refresh-token"))
+ .and(header("content-type", "application/json"))
+ .and(body_json(serde_json::json!({ "token": "refresh-token" })))
+ .and(query_param_is_missing("token"))
.respond_with(ResponseTemplate::new(200))
.expect(1)
.mount(&server)
diff --git a/crates/fusionauth/src/oauth.rs b/crates/fusionauth/src/oauth.rs
index 6256f484a2..7f6e61f039 100644
--- a/crates/fusionauth/src/oauth.rs
+++ b/crates/fusionauth/src/oauth.rs
@@ -3,9 +3,12 @@ use std::borrow::Cow;
use crate::{
FusionAuthClient, Result, UnauthedClient,
- error::{FusionAuthClientError, GenericErrorResponse},
+ error::{FusionAuthClientError, GenericErrorResponse, OAuth2TokenError},
};
+#[cfg(test)]
+mod test;
+
#[derive(serde::Serialize, Debug)]
#[serde(rename_all = "snake_case")]
struct RefreshTokenGrantCompleteRequest<'a> {
@@ -99,13 +102,30 @@ async fn complete(
expires_in: body.expires_in,
})
}
+ status @ (reqwest::StatusCode::BAD_REQUEST | reqwest::StatusCode::UNAUTHORIZED) => {
+ let headers = res.headers().clone();
+ let body = res.text().await.map_err(FusionAuthClientError::transport)?;
+ match serde_json::from_str::<OAuth2TokenError>(&body) {
+ Ok(refusal) => {
+ tracing::warn!(
+ %status,
+ error = %refusal.error,
+ error_reason = refusal.error_reason.as_deref(),
+ error_description = refusal.error_description.as_deref(),
+ "fusionauth refused the oauth2 token request"
+ );
+ Err(FusionAuthClientError::OAuth2TokenRefused(refusal))
+ }
+ Err(_) => Err(FusionAuthClientError::unexpected(status, &headers, body)),
+ }
+ }
_ => Err(FusionAuthClientError::unexpected_response(res).await),
}
}
impl FusionAuthClient {
/// Completes the OAuth2 authorization code grant flow.
- #[tracing::instrument(skip(self), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
+ #[tracing::instrument(skip(self, code), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
pub async fn complete_authorization_code_grant(&self, code: &str) -> Result<OAuth2Grant> {
complete(
&self.unauth_client,
@@ -122,7 +142,7 @@ impl FusionAuthClient {
}
/// complete the OAuth2 Refresh token grant flow.
- #[tracing::instrument(skip(self), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
+ #[tracing::instrument(skip(self, refresh_token), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
pub async fn complete_refresh_token_grant(&self, refresh_token: &str) -> Result<OAuth2Grant> {
complete(
&self.unauth_client,
diff --git a/crates/fusionauth/src/oauth/test.rs b/crates/fusionauth/src/oauth/test.rs
new file mode 100644
index 0000000000..2dcd4387ad
--- /dev/null
+++ b/crates/fusionauth/src/oauth/test.rs
@@ -0,0 +1,202 @@
+use std::sync::{Arc, Mutex};
+
+use serde_json::json;
+use upstream_error::UpstreamFailure;
+use wiremock::matchers::{body_string_contains, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use crate::FusionAuthClient;
+use crate::error::{FusionAuthClientError, OAuth2TokenError};
+
+const REFRESH_TOKEN: &str = "refresh-token-value";
+
+fn client(base_url: String) -> FusionAuthClient {
+ FusionAuthClient::new(
+ "api-key".into(),
+ "application-id".into(),
+ "client-secret".into(),
+ base_url,
+ "http://localhost:28011/oauth/redirect".into(),
+ "google-client-id".into(),
+ "google-client-secret".into(),
+ )
+}
+
+async fn refresh_answering(response: ResponseTemplate) -> crate::Result<crate::oauth::OAuth2Grant> {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/oauth2/token"))
+ .and(body_string_contains("grant_type=refresh_token"))
+ .respond_with(response)
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ client(server.uri())
+ .complete_refresh_token_grant(REFRESH_TOKEN)
+ .await
+}
+
+#[tokio::test]
+async fn refresh_grant_returns_the_tokens() {
+ let grant = refresh_answering(ResponseTemplate::new(200).set_body_json(json!({
+ "access_token": "access",
+ "refresh_token": "rotated",
+ "expires_in": 3600,
+ })))
+ .await
+ .expect("a 200 is a grant");
+
+ assert_eq!(grant.access_token, "access");
+ assert_eq!(grant.refresh_token, "rotated");
+ assert_eq!(grant.expires_in, 3600);
+}
+
+#[tokio::test]
+async fn refresh_grant_reports_a_refresh_token_fusionauth_no_longer_holds() {
+ let error = refresh_answering(ResponseTemplate::new(400).set_body_json(json!({
+ "error": "invalid_grant",
+ "error_description": "The refresh_token is invalid.",
+ "error_reason": "refresh_token_not_found",
+ })))
+ .await
+ .expect_err("a 400 is a refusal");
+
+ let FusionAuthClientError::OAuth2TokenRefused(refusal) = error else {
+ panic!("expected a refusal, got {error:?}");
+ };
+ assert!(refusal.is_invalid_grant());
+ assert_eq!(
+ refusal,
+ OAuth2TokenError {
+ error: "invalid_grant".into(),
+ error_reason: Some("refresh_token_not_found".into()),
+ error_description: Some("The refresh_token is invalid.".into()),
+ }
+ );
+ assert_eq!(
+ refusal.to_string(),
+ "invalid_grant (refresh_token_not_found): The refresh_token is invalid."
+ );
+}
+
+#[tokio::test]
+async fn refresh_grant_reports_a_rejected_client_as_a_refusal_that_is_not_invalid_grant() {
+ let error = refresh_answering(ResponseTemplate::new(401).set_body_json(json!({
+ "error": "invalid_client",
+ "error_description": "Invalid client authentication.",
+ "error_reason": "invalid_client_authentication",
+ })))
+ .await
+ .expect_err("a 401 is a refusal");
+
+ let FusionAuthClientError::OAuth2TokenRefused(refusal) = error else {
+ panic!("expected a refusal, got {error:?}");
+ };
+ assert!(!refusal.is_invalid_grant());
+ assert_eq!(refusal.error, "invalid_client");
+}
+
+#[tokio::test]
+async fn refresh_grant_keeps_a_400_without_an_oauth_body_generic() {
+ let error = refresh_answering(ResponseTemplate::new(400).set_body_string("<html>bad</html>"))
+ .await
+ .expect_err("a 400 is an error");
+
+ assert!(
+ matches!(&error, FusionAuthClientError::Generic(body) if body.message == "<html>bad</html>"),
+ "got {error:?}"
+ );
+}
+
+#[tokio::test]
+async fn refresh_grant_reports_an_outage_as_upstream() {
+ let error = refresh_answering(ResponseTemplate::new(503).set_body_string("unavailable"))
+ .await
+ .expect_err("a 503 is an error");
+
+ assert_eq!(
+ error.upstream().map(|upstream| upstream.failure),
+ Some(UpstreamFailure::Unavailable)
+ );
+}
+
+#[tokio::test]
+async fn authorization_code_grant_reports_a_spent_code_as_invalid_grant() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/oauth2/token"))
+ .and(body_string_contains("grant_type=authorization_code"))
+ .respond_with(ResponseTemplate::new(400).set_body_json(json!({
+ "error": "invalid_request",
+ "error_description": "Invalid Authorization Code",
+ "error_reason": "auth_code_not_found",
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let error = client(server.uri())
+ .complete_authorization_code_grant("spent-code")
+ .await
+ .expect_err("a 400 is a refusal");
+
+ assert!(
+ matches!(&error, FusionAuthClientError::OAuth2TokenRefused(refusal) if refusal.is_invalid_grant()),
+ "got {error:?}"
+ );
+}
+
+#[derive(Clone, Default)]
+struct CapturedLogs(Arc<Mutex<Vec<u8>>>);
+
+impl std::io::Write for CapturedLogs {
+ fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+ self.0.lock().expect("log buffer").extend_from_slice(buf);
+ Ok(buf.len())
+ }
+
+ fn flush(&mut self) -> std::io::Result<()> {
+ Ok(())
+ }
+}
+
+#[tokio::test]
+async fn refresh_grant_never_records_the_refresh_token_in_logs() {
+ let refusal = || {
+ ResponseTemplate::new(400).set_body_json(json!({
+ "error": "invalid_grant",
+ "error_reason": "refresh_token_not_found",
+ }))
+ };
+ let logs = CapturedLogs::default();
+ let writer = logs.clone();
+ let subscriber = tracing_subscriber::fmt()
+ .with_max_level(tracing::Level::TRACE)
+ .with_ansi(false)
+ .with_writer(move || writer.clone())
+ .finish();
+ let _guard = tracing::subscriber::set_default(subscriber);
+
+ // While this is the only subscriber, a callsite first hit on another test's
+ // thread is cached as disabled, because that thread has no subscriber. Hit
+ // the callsites so they exist, then recompute them on this thread.
+ refresh_answering(refusal())
+ .await
+ .expect_err("a 400 is a refusal");
+ tracing::callsite::rebuild_interest_cache();
+
+ refresh_answering(refusal())
+ .await
+ .expect_err("a 400 is a refusal");
+
+ let logs = String::from_utf8(logs.0.lock().expect("log buffer").clone()).expect("utf-8 logs");
+ assert!(
+ logs.contains("refresh_token_not_found"),
+ "the refusal is logged: {logs}"
+ );
+ assert!(
+ !logs.contains(REFRESH_TOKEN),
+ "the refresh token leaked into logs: {logs}"
+ );
+}
diff --git a/crates/fusionauth/src/passwordless.rs b/crates/fusionauth/src/passwordless.rs
index c8c3b28c16..d8b3d59b09 100644
--- a/crates/fusionauth/src/passwordless.rs
+++ b/crates/fusionauth/src/passwordless.rs
@@ -133,7 +133,7 @@ async fn send(
/// Returns the access token, refresh token, and redirect uri
/// https://fusionauth.io/docs/apis/passwordless#complete-a-passwordless-login
/// Valid respones: 200, 202, 203, 212, 213, 242, 400, 404, 409, 410, 423, 500, 503, 504
-#[tracing::instrument(ret, err, level = tracing::Level::TRACE)]
+#[tracing::instrument(skip_all, err, level = tracing::Level::TRACE)]
async fn complete(
client: &AuthedClient,
base_url: &str,
@@ -198,7 +198,7 @@ impl FusionAuthClient {
}
/// Sends the passwordless login code to the user.
- #[tracing::instrument(skip(self), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
+ #[tracing::instrument(skip(self, code), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
pub async fn send_passwordless_login(&self, code: &str) -> Result<()> {
send(
&self.auth_client,
diff --git a/crates/fusionauth/src/user.rs b/crates/fusionauth/src/user.rs
index 1f6de24b0e..9628b3da49 100644
--- a/crates/fusionauth/src/user.rs
+++ b/crates/fusionauth/src/user.rs
@@ -22,7 +22,7 @@ impl FusionAuthClient {
/// Creates a new user in FusionAuth.
/// This will automatically trigger the api::webhooks::user::create_user_webhook to be called
/// from within FusionAuth as well.
- #[tracing::instrument(skip(self), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
+ #[tracing::instrument(skip(self, user), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
pub async fn create_user(
&self,
user: create::User<'_>,
@@ -42,7 +42,7 @@ impl FusionAuthClient {
/// Creates a new user in FusionAuth with a caller-specified id, so the FusionAuth id
/// can match an externally minted identifier. Triggers the create-user webhook like
/// [`Self::create_user`].
- #[tracing::instrument(skip(self), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
+ #[tracing::instrument(skip(self, user), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
pub async fn create_user_with_id(
&self,
user_id: &str,
@@ -123,7 +123,7 @@ impl FusionAuthClient {
}
/// Verifies a user's email with the given verification ID.
- #[tracing::instrument(skip(self), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
+ #[tracing::instrument(skip(self, verification_id), fields(application_id=%self.client_id, fusion_auth_base_url=%self.fusion_auth_base_url))]
pub async fn verify_email(&self, verification_id: &str, client_ip: IpAddr) -> Result<()> {
verify::verify_email(
&self.auth_client,
diff --git a/deny.toml b/deny.toml
index 858e199ac3..424903f4ac 100644
--- a/deny.toml
+++ b/deny.toml
@@ -233,6 +233,7 @@ deny = [
"email_api_client", # Outlook transport span tests only
"email_db_client", # Purge phase span tests only
"forms", # Anonymous-response span and log leak tests only (dev-dependency)
+ "fusionauth", # Credential log leak tests only (dev-dependency)
"genai_telemetry", # GenAI span tests
"graphql_email", # Unavailable-thread warning field and span tests only
"graphql_entity_mutation", # Batch failure span field tests only
diff --git a/services/mcp_auth_proxy/AGENTS.md b/services/mcp_auth_proxy/AGENTS.md
index 8ec5d35a14..b06ef82e60 100644
--- a/services/mcp_auth_proxy/AGENTS.md
+++ b/services/mcp_auth_proxy/AGENTS.md
@@ -86,6 +86,10 @@ and other library consumers. Both retain OAuth metadata, CORS, and bearer auth.
- A binding carries the grant id of its token family; rotation must copy it
and refresh must check the revoked-grant marker, or `/revoke` stops covering
rotated tokens. Bindings stored as a bare client id are their own family.
+- Upstream grants fail with `UpstreamGrantError` (`domain/ports.rs`). Keep a
+ grant FusionAuth refused as `InvalidGrant` so `/token` answers
+ `400 invalid_grant`; a 5xx tells clients to retry a token that can never
+ work. See README "Token endpoint errors".
- Redis is legacy. Write new state to Postgres only; the cutover module's
Redis mirroring exists solely for replicas on the previous build. Remove it
only after a deploy that started once no replica ran the Redis-only build
diff --git a/services/mcp_auth_proxy/Cargo.toml b/services/mcp_auth_proxy/Cargo.toml
index c32bd2f397..fac95e0b86 100644
--- a/services/mcp_auth_proxy/Cargo.toml
+++ b/services/mcp_auth_proxy/Cargo.toml
@@ -23,6 +23,7 @@ outbound = [
"dep:cursor_api_key",
"dep:fusionauth",
"dep:sqlx",
+ "dep:upstream_error",
"dep:zeroize",
]
@@ -51,6 +52,7 @@ thiserror = { workspace = true }
tower = { workspace = true, features = ["util"], optional = true }
tower-http = { workspace = true, optional = true }
tracing = { workspace = true }
+upstream_error = { path = "../../crates/upstream_error", default-features = false, optional = true }
url = { workspace = true }
urlencoding = { workspace = true }
uuid = { workspace = true }
diff --git a/services/mcp_auth_proxy/README.md b/services/mcp_auth_proxy/README.md
index 629857a8ba..056daaa56e 100644
--- a/services/mcp_auth_proxy/README.md
+++ b/services/mcp_auth_proxy/README.md
@@ -146,6 +146,24 @@ holding them authorize once more. Rate limiting of `/register` belongs at the
edge; the broker bounds each registration's size but not how many a caller may
create.
+## Token endpoint errors
+
+`/token` answers errors in the RFC 6749 section 5.2 JSON shape
+(`{"error", "error_description"}`, `Cache-Control: no-store`). The status says
+who has to act:
+
+- `400 invalid_request` or `unsupported_grant_type`: the request is malformed.
+- `400 invalid_grant`: the code or refresh token is unusable, whether the
+ broker refused it (unbound, another client's, revoked grant) or FusionAuth
+ did (for example `refresh_token_not_found`). Retrying cannot help; the client
+ must authorize again.
+- `503 temporarily_unavailable`: FusionAuth is down or throttling. A `Retry-After`
+ from a throttling response (429) is passed on; one on a 5xx is not.
+- `502 server_error`: FusionAuth answered with something else.
+
+FusionAuth's error and reason are logged with the client and grant ids,
+never the token itself, and are not returned to the client.
+
## Disconnecting a client
`/revoke` implements RFC 7009 and is advertised as `revocation_endpoint` in
diff --git a/services/mcp_auth_proxy/src/domain/ports.rs b/services/mcp_auth_proxy/src/domain/ports.rs
index ce2c64a2da..3d45e22fe9 100644
--- a/services/mcp_auth_proxy/src/domain/ports.rs
+++ b/services/mcp_auth_proxy/src/domain/ports.rs
@@ -1,6 +1,6 @@
//! Domain ports for upstream OAuth providers.
-use std::{future::Future, pin::Pin};
+use std::{future::Future, pin::Pin, time::Duration};
use super::models::{
RefreshToken, RefreshTokenBinding, RegisteredClient, SignInMethod, UpstreamTokens,
@@ -8,7 +8,31 @@ use super::models::{
/// Boxed future returning a token grant from the upstream provider.
pub type UpstreamTokensFuture<'a> =
- Pin<Box<dyn Future<Output = anyhow::Result<UpstreamTokens>> + Send + 'a>>;
+ Pin<Box<dyn Future<Output = Result<UpstreamTokens, UpstreamGrantError>> + Send + 'a>>;
+
+/// Why the upstream provider issued no tokens for a grant. Carries no
+/// credential, so it is safe to log.
+#[derive(Debug, thiserror::Error)]
+pub enum UpstreamGrantError {
+ /// The provider refused the code or refresh token itself as invalid,
+ /// expired, or revoked. Only the user authorizing again fixes it.
+ #[error("upstream refused the grant: {detail}")]
+ InvalidGrant {
+ /// The provider's reason, for logs.
+ detail: String,
+ },
+ /// The provider was unreachable or throttling requests; retrying later
+ /// can succeed.
+ #[error("upstream is unavailable")]
+ Unavailable {
+ /// How long the provider asked callers to wait, when it said.
+ retry_after: Option<Duration>,
+ },
+ /// Anything else: a request or client credential the provider rejected,
+ /// which is ours to fix, or an answer we could not use.
+ #[error("upstream grant request failed: {0:#}")]
+ Failed(anyhow::Error),
+}
/// Boxed future returning nothing on success.
pub type StoreWriteFuture<'a> = Pin<Box<dyn Future<Output = anyhow::Result<()>> + Send + 'a>>;
diff --git a/services/mcp_auth_proxy/src/domain/service.rs b/services/mcp_auth_proxy/src/domain/service.rs
index f9b514aff1..1708278693 100644
--- a/services/mcp_auth_proxy/src/domain/service.rs
+++ b/services/mcp_auth_proxy/src/domain/service.rs
@@ -20,7 +20,7 @@ use super::{
RefreshToken, RefreshTokenBinding, RegisteredClient, RevocationRequest, TokenRequest,
TokenResponse, UserConsent,
},
- ports::{ClientRegistrationStore, OAuthProvider, RefreshTokenBindingStore},
+ ports::{ClientRegistrationStore, OAuthProvider, RefreshTokenBindingStore, UpstreamGrantError},
redirect_uri::{RedirectTrust, RedirectUriPolicy},
};
@@ -278,7 +278,24 @@ where
.oauth_provider
.refresh_access_token(&refresh_token)
.await
- .map_err(TokenExchangeError::RefreshFailed)?;
+ .map_err(|error| {
+ if let UpstreamGrantError::InvalidGrant { .. } = error {
+ tracing::warn!(
+ %client_id,
+ grant_id = %binding.grant_id,
+ %error,
+ "upstream refused the refresh token; the client must authorize again"
+ );
+ } else {
+ tracing::error!(
+ %client_id,
+ grant_id = %binding.grant_id,
+ %error,
+ "upstream refresh token exchange failed"
+ );
+ }
+ TokenExchangeError::RefreshFailed(error)
+ })?;
let rotated_digest = refresh_token_digest(&tokens.refresh_token);
// The upstream token is already issued at this point. A binding write
@@ -642,9 +659,8 @@ where
let access_token_expires_at = SystemTime::now()
.checked_add(Duration::from_secs(tokens.expires_in))
.ok_or_else(|| {
- CompleteCallbackError::AuthorizationCodeExchangeFailed(anyhow::anyhow!(
- "upstream expires_in {} is out of range",
- tokens.expires_in
+ CompleteCallbackError::AuthorizationCodeExchangeFailed(UpstreamGrantError::Failed(
+ anyhow::anyhow!("upstream expires_in {} is out of range", tokens.expires_in),
))
})?;
@@ -893,8 +909,8 @@ pub enum CompleteCallbackError {
#[error("failed to access inflight auth state")]
InflightStore(anyhow::Error),
/// Upstream code exchange failed.
- #[error("authorization code exchange failed")]
- AuthorizationCodeExchangeFailed(anyhow::Error),
+ #[error("authorization code exchange failed: {0}")]
+ AuthorizationCodeExchangeFailed(UpstreamGrantError),
}
/// Errors returned when exchanging a broker-issued code for a bearer token.
@@ -943,9 +959,11 @@ pub enum TokenExchangeError {
/// Refresh token bindings could not be read or written.
#[error("failed to access refresh token bindings")]
RefreshTokenBindingStore(anyhow::Error),
- /// Upstream refresh failed.
- #[error("refresh token exchange failed")]
- RefreshFailed(anyhow::Error),
+ /// Upstream refresh failed. An [`UpstreamGrantError::InvalidGrant`] is
+ /// the client's to fix by authorizing again; the rest are upstream or
+ /// broker faults.
+ #[error("refresh token exchange failed: {0}")]
+ RefreshFailed(UpstreamGrantError),
}
/// Errors returned when revoking a token.
diff --git a/services/mcp_auth_proxy/src/domain/service/test.rs b/services/mcp_auth_proxy/src/domain/service/test.rs
index 7d1db1fb85..97591ccea8 100644
--- a/services/mcp_auth_proxy/src/domain/service/test.rs
+++ b/services/mcp_auth_proxy/src/domain/service/test.rs
@@ -735,6 +735,118 @@ async fn revoked_refresh_token_cannot_mint_access_tokens() {
assert!(matches!(error, TokenExchangeError::UnboundRefreshToken));
}
+#[tokio::test]
+async fn a_refresh_token_the_upstream_refuses_is_an_invalid_grant() {
+ let harness = Harness::with_provider(FakeOAuthProvider::new().failing_refresh(|| {
+ UpstreamGrantError::InvalidGrant {
+ detail: "invalid_grant (refresh_token_not_found)".to_owned(),
+ }
+ }));
+ let client_id = harness.register(&[TRUSTED_REDIRECT_URI]).await;
+ let refresh_token = obtain_refresh_token(&harness, &client_id).await;
+
+ let error = harness
+ .service
+ .exchange_token(refresh_request(refresh_token, &client_id))
+ .await
+ .expect_err("a refused refresh token must not mint an access token");
+
+ match error {
+ TokenExchangeError::RefreshFailed(UpstreamGrantError::InvalidGrant { detail }) => {
+ assert_eq!(detail, "invalid_grant (refresh_token_not_found)");
+ }
+ other => panic!("expected an upstream invalid grant, got {other:?}"),
+ }
+}
+
+#[tokio::test]
+async fn an_upstream_outage_during_refresh_is_reported_as_unavailable() {
+ let harness = Harness::with_provider(FakeOAuthProvider::new().failing_refresh(|| {
+ UpstreamGrantError::Unavailable {
+ retry_after: Some(Duration::from_secs(30)),
+ }
+ }));
+ let client_id = harness.register(&[TRUSTED_REDIRECT_URI]).await;
+ let refresh_token = obtain_refresh_token(&harness, &client_id).await;
+
+ let error = harness
+ .service
+ .exchange_token(refresh_request(refresh_token, &client_id))
+ .await
+ .expect_err("an outage must fail the refresh");
+
+ assert!(matches!(
+ error,
+ TokenExchangeError::RefreshFailed(UpstreamGrantError::Unavailable {
+ retry_after: Some(retry_after),
+ }) if retry_after == Duration::from_secs(30)
+ ));
+}
+
+#[tokio::test]
+async fn a_failed_upstream_refresh_keeps_its_cause() {
+ let harness = Harness::with_provider(
+ FakeOAuthProvider::new()
+ .failing_refresh(|| UpstreamGrantError::Failed(anyhow::anyhow!("unexpected 500"))),
+ );
+ let client_id = harness.register(&[TRUSTED_REDIRECT_URI]).await;
+ let refresh_token = obtain_refresh_token(&harness, &client_id).await;
+
+ let error = harness
+ .service
+ .exchange_token(refresh_request(refresh_token, &client_id))
+ .await
+ .expect_err("an upstream failure must fail the refresh");
+
+ assert!(matches!(
+ error,
+ TokenExchangeError::RefreshFailed(UpstreamGrantError::Failed(_))
+ ));
+ assert!(
+ error.to_string().contains("unexpected 500"),
+ "the cause must survive into the message: {error}"
+ );
+}
+
+#[tokio::test]
+async fn a_refused_upstream_code_fails_the_callback_without_issuing_a_code() {
+ let harness = Harness::with_provider(FakeOAuthProvider::new().failing_code_exchange(|| {
+ UpstreamGrantError::InvalidGrant {
+ detail: "invalid_request (auth_code_not_found)".to_owned(),
+ }
+ }));
+ let client_id = harness.register(&[TRUSTED_REDIRECT_URI]).await;
+ harness
+ .service
+ .start_authorization(
+ harness.authorize_request(
+ &client_id,
+ TRUSTED_REDIRECT_URI,
+ &code_challenge_for(VICTIM_CODE_VERIFIER),
+ ),
+ harness.browser.clone(),
+ UserConsent::NotAsked,
+ )
+ .await
+ .expect("authorize should succeed");
+
+ let error = harness
+ .service
+ .complete_callback(
+ upstream_callback(&harness.inflight.only_pending_session_id()),
+ Some(harness.browser.clone()),
+ )
+ .await
+ .expect_err("a refused upstream code must fail the callback");
+
+ assert!(matches!(
+ error,
+ CompleteCallbackError::AuthorizationCodeExchangeFailed(
+ UpstreamGrantError::InvalidGrant { .. }
+ )
+ ));
+}
+
#[tokio::test]
async fn revoking_twice_succeeds() {
let harness = Harness::new();
diff --git a/services/mcp_auth_proxy/src/inbound/axum_router.rs b/services/mcp_auth_proxy/src/inbound/axum_router.rs
index 8c4f958e74..231086b128 100644
--- a/services/mcp_auth_proxy/src/inbound/axum_router.rs
+++ b/services/mcp_auth_proxy/src/inbound/axum_router.rs
@@ -8,8 +8,8 @@ use std::time::Duration;
use askama::Template;
use axum::{
Router,
- extract::{Query, RawQuery, State},
- http::{HeaderMap, HeaderName, Method, header},
+ extract::{Query, RawQuery, State, rejection::FormRejection},
+ http::{HeaderMap, HeaderName, HeaderValue, Method, StatusCode, header},
middleware as axum_mw,
response::{Html, IntoResponse, Json, Redirect, Response},
routing,
@@ -25,6 +25,7 @@ use crate::domain::{
AuthorizationStart, AuthorizeRequest, CallbackRequest, ClientRegistrationRequest,
ConsentPrompt, RevocationRequest, TokenRequest, UserConsent,
},
+ ports::UpstreamGrantError,
service::{
CompleteCallbackError, InflightAuthStore, McpAuthProxyService, McpAuthProxyServiceImpl,
RegisterClientError, RevokeTokenError, StartAuthorizationError, TokenExchangeError,
@@ -434,10 +435,32 @@ async fn oauth_callback<I: InflightAuthStore + 'static>(
)
.into_response()
}
- Err(CompleteCallbackError::AuthorizationCodeExchangeFailed(error)) => {
- tracing::error!(error=?error, "upstream authorization code grant failed");
+ Err(CompleteCallbackError::AuthorizationCodeExchangeFailed(
+ error @ UpstreamGrantError::InvalidGrant { .. },
+ )) => {
+ tracing::warn!(%error, "upstream refused the authorization code");
(
- axum::http::StatusCode::BAD_GATEWAY,
+ StatusCode::BAD_REQUEST,
+ "sign-in could not be completed; start the connection again",
+ )
+ .into_response()
+ }
+ Err(CompleteCallbackError::AuthorizationCodeExchangeFailed(
+ error @ UpstreamGrantError::Unavailable { .. },
+ )) => {
+ tracing::error!(%error, "upstream authorization code grant failed");
+ (
+ StatusCode::SERVICE_UNAVAILABLE,
+ "the sign-in service is temporarily unavailable; try again shortly",
+ )
+ .into_response()
+ }
+ Err(CompleteCallbackError::AuthorizationCodeExchangeFailed(
+ error @ UpstreamGrantError::Failed(_),
+ )) => {
+ tracing::error!(%error, "upstream authorization code grant failed");
+ (
+ StatusCode::BAD_GATEWAY,
"authorization code exchange failed",
)
.into_response()
@@ -445,89 +468,132 @@ async fn oauth_callback<I: InflightAuthStore + 'static>(
}
}
+/// An RFC 6749 section 5.2 error response.
+fn oauth_error(status: StatusCode, error: &str, description: &str) -> Response {
+ (
+ status,
+ [(header::CACHE_CONTROL, "no-store")],
+ Json(serde_json::json!({ "error": error, "error_description": description })),
+ )
+ .into_response()
+}
+
+/// Token endpoint. Errors use the RFC 6749 section 5.2 JSON shape so clients
+/// can tell a grant they must discard (`invalid_grant`, 400) from a fault
+/// worth retrying (5xx).
async fn token<I: InflightAuthStore + 'static>(
State(auth_proxy): State<McpAuthProxyServiceImpl<I>>,
- axum::Form(params): axum::Form<TokenRequest>,
+ params: Result<axum::Form<TokenRequest>, FormRejection>,
) -> Response {
- match auth_proxy.exchange_token(params).await {
- Ok(response) => Json(response).into_response(),
+ let Ok(axum::Form(params)) = params else {
+ return oauth_error(
+ StatusCode::BAD_REQUEST,
+ "invalid_request",
+ "the request must be a form with a grant_type",
+ );
+ };
+ let (status, error, description) = match auth_proxy.exchange_token(params).await {
+ Ok(response) => return Json(response).into_response(),
Err(TokenExchangeError::UnsupportedGrantType) => (
- axum::http::StatusCode::BAD_REQUEST,
+ StatusCode::BAD_REQUEST,
+ "unsupported_grant_type",
"unsupported grant_type",
- )
- .into_response(),
+ ),
Err(TokenExchangeError::CodeRequired) => {
- (axum::http::StatusCode::BAD_REQUEST, "code required").into_response()
- }
- Err(TokenExchangeError::InvalidOrExpiredCode) => (
- axum::http::StatusCode::BAD_REQUEST,
- "invalid or expired code",
- )
- .into_response(),
- Err(TokenExchangeError::RedirectUriMismatch) => {
- (axum::http::StatusCode::BAD_REQUEST, "redirect_uri mismatch").into_response()
- }
- Err(TokenExchangeError::RedirectUriRequired) => {
- (axum::http::StatusCode::BAD_REQUEST, "redirect_uri required").into_response()
+ (StatusCode::BAD_REQUEST, "invalid_request", "code required")
}
+ Err(TokenExchangeError::RedirectUriRequired) => (
+ StatusCode::BAD_REQUEST,
+ "invalid_request",
+ "redirect_uri required",
+ ),
Err(TokenExchangeError::CodeVerifierRequired) => (
- axum::http::StatusCode::BAD_REQUEST,
+ StatusCode::BAD_REQUEST,
+ "invalid_request",
"code_verifier required",
- )
- .into_response(),
- Err(TokenExchangeError::PkceVerificationFailed) => (
- axum::http::StatusCode::BAD_REQUEST,
- "PKCE verification failed",
- )
- .into_response(),
+ ),
Err(TokenExchangeError::RefreshTokenRequired) => (
- axum::http::StatusCode::BAD_REQUEST,
+ StatusCode::BAD_REQUEST,
+ "invalid_request",
"refresh_token required",
- )
- .into_response(),
- Err(TokenExchangeError::ClientIdRequired) => {
- (axum::http::StatusCode::BAD_REQUEST, "client_id required").into_response()
- }
+ ),
+ Err(TokenExchangeError::ClientIdRequired) => (
+ StatusCode::BAD_REQUEST,
+ "invalid_request",
+ "client_id required",
+ ),
+ Err(TokenExchangeError::InvalidOrExpiredCode) => (
+ StatusCode::BAD_REQUEST,
+ "invalid_grant",
+ "invalid or expired code",
+ ),
+ Err(TokenExchangeError::RedirectUriMismatch) => (
+ StatusCode::BAD_REQUEST,
+ "invalid_grant",
+ "redirect_uri mismatch",
+ ),
+ Err(TokenExchangeError::PkceVerificationFailed) => (
+ StatusCode::BAD_REQUEST,
+ "invalid_grant",
+ "PKCE verification failed",
+ ),
Err(TokenExchangeError::ClientMismatch) => (
- axum::http::StatusCode::BAD_REQUEST,
+ StatusCode::BAD_REQUEST,
+ "invalid_grant",
"grant was not issued to this client",
- )
- .into_response(),
+ ),
Err(TokenExchangeError::UnboundRefreshToken) => (
- axum::http::StatusCode::BAD_REQUEST,
+ StatusCode::BAD_REQUEST,
+ "invalid_grant",
"refresh token is not bound to a client",
- )
- .into_response(),
+ ),
Err(TokenExchangeError::RevokedGrant) => (
- axum::http::StatusCode::BAD_REQUEST,
+ StatusCode::BAD_REQUEST,
+ "invalid_grant",
"refresh token has been revoked",
- )
- .into_response(),
+ ),
+ Err(TokenExchangeError::RefreshFailed(UpstreamGrantError::InvalidGrant { .. })) => (
+ StatusCode::BAD_REQUEST,
+ "invalid_grant",
+ "refresh token is no longer valid; authorize again",
+ ),
+ Err(TokenExchangeError::RefreshFailed(UpstreamGrantError::Unavailable { retry_after })) => {
+ let mut response = oauth_error(
+ StatusCode::SERVICE_UNAVAILABLE,
+ "temporarily_unavailable",
+ "the sign-in service is temporarily unavailable; try again shortly",
+ );
+ if let Some(retry_after) = retry_after {
+ response.headers_mut().insert(
+ header::RETRY_AFTER,
+ HeaderValue::from(retry_after.as_secs()),
+ );
+ }
+ return response;
+ }
+ Err(TokenExchangeError::RefreshFailed(UpstreamGrantError::Failed(_))) => (
+ StatusCode::BAD_GATEWAY,
+ "server_error",
+ "refresh token exchange failed",
+ ),
Err(TokenExchangeError::InflightStore(error)) => {
tracing::error!(error=?error, "failed to access inflight auth state");
(
- axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+ StatusCode::INTERNAL_SERVER_ERROR,
+ "server_error",
"failed to access inflight auth state",
)
- .into_response()
}
Err(TokenExchangeError::RefreshTokenBindingStore(error)) => {
tracing::error!(error=?error, "failed to access refresh token bindings");
(
- axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+ StatusCode::INTERNAL_SERVER_ERROR,
+ "server_error",
"failed to access refresh token bindings",
)
- .into_response()
- }
- Err(TokenExchangeError::RefreshFailed(error)) => {
- tracing::error!(error=?error, "upstream refresh token exchange failed");
- (
- axum::http::StatusCode::BAD_GATEWAY,
- "refresh token exchange failed",
- )
- .into_response()
}
- }
+ };
+ oauth_error(status, error, description)
}
/// RFC 7009 revocation endpoint. Errors use the RFC 6749 section 5.2 JSON
@@ -575,11 +641,7 @@ async fn revoke<I: InflightAuthStore + 'static>(
)
}
};
- (
- status,
- Json(serde_json::json!({ "error": error, "error_description": description })),
- )
- .into_response()
+ oauth_error(status, error, description)
}
/// Builds the unauthenticated OAuth broker routes: discovery metadata,
diff --git a/services/mcp_auth_proxy/src/inbound/axum_router/test.rs b/services/mcp_auth_proxy/src/inbound/axum_router/test.rs
index 04017ee837..01c65d46c2 100644
--- a/services/mcp_auth_proxy/src/inbound/axum_router/test.rs
+++ b/services/mcp_auth_proxy/src/inbound/axum_router/test.rs
@@ -1,6 +1,8 @@
//! Drives the reported attack and the legitimate flow over the real router, so
//! the checks are exercised through the same HTTP surface an attacker uses.
+use std::time::Duration;
+
use axum::{
body::Body,
http::{Request, StatusCode, header},
@@ -9,10 +11,11 @@ use tower::ServiceExt;
use super::{health, mcp_router, mount_at_root_and_prefix, oauth_router};
use crate::domain::browser_binding::BrowserBinding;
+use crate::domain::ports::UpstreamGrantError;
use crate::test_support::{
- ATTACKER_CODE_VERIFIER, ATTACKER_REDIRECT_URI, GATEWAY_REDIRECT_URI, Harness,
- TRUSTED_REDIRECT_URI, UPSTREAM_ACCESS_TOKEN, UPSTREAM_REFRESH_TOKEN, VICTIM_CODE_VERIFIER,
- code_challenge_for, query_param,
+ ATTACKER_CODE_VERIFIER, ATTACKER_REDIRECT_URI, FakeOAuthProvider, GATEWAY_REDIRECT_URI,
+ Harness, TRUSTED_REDIRECT_URI, UPSTREAM_ACCESS_TOKEN, UPSTREAM_REFRESH_TOKEN,
+ VICTIM_CODE_VERIFIER, code_challenge_for, query_param,
};
use axum::{Router, routing::get};
use macro_auth::middleware::decode_jwt::JwtValidationArgs;
@@ -23,6 +26,8 @@ struct Response {
status: StatusCode,
location: Option<String>,
referrer_policy: Option<String>,
+ cache_control: Option<String>,
+ retry_after: Option<String>,
set_cookie: Option<String>,
csp: Option<String>,
x_frame_options: Option<String>,
@@ -53,6 +58,8 @@ async fn send(harness: &Harness, request: Request<Body>) -> Response {
let set_cookie = header_text(header::SET_COOKIE);
let csp = header_text(header::CONTENT_SECURITY_POLICY);
let x_frame_options = header_text(header::X_FRAME_OPTIONS);
+ let cache_control = header_text(header::CACHE_CONTROL);
+ let retry_after = header_text(header::RETRY_AFTER);
let bytes = axum::body::to_bytes(response.into_body(), BODY_LIMIT)
.await
.expect("body should be readable");
@@ -61,6 +68,8 @@ async fn send(harness: &Harness, request: Request<Body>) -> Response {
status,
location,
referrer_policy,
+ cache_control,
+ retry_after,
set_cookie,
csp,
x_frame_options,
@@ -712,7 +721,11 @@ async fn token_endpoint_refuses_a_code_presented_by_another_client() {
)
.await;
assert_eq!(stolen.status, StatusCode::BAD_REQUEST);
- assert_eq!(stolen.body, "grant was not issued to this client");
+ assert_eq!(stolen.json()["error"], "invalid_grant");
+ assert_eq!(
+ stolen.json()["error_description"],
+ "grant was not issued to this client"
+ );
let retried = send(
&harness,
@@ -723,7 +736,11 @@ async fn token_endpoint_refuses_a_code_presented_by_another_client() {
)
.await;
assert_eq!(retried.status, StatusCode::BAD_REQUEST);
- assert_eq!(retried.body, "invalid or expired code");
+ assert_eq!(retried.json()["error"], "invalid_grant");
+ assert_eq!(
+ retried.json()["error_description"],
+ "invalid or expired code"
+ );
}
fn revoke_request(form: &str) -> Request<Body> {
@@ -798,7 +815,161 @@ async fn client_disconnects_by_revoking_its_refresh_token() {
)
.await;
assert_eq!(refresh.status, StatusCode::BAD_REQUEST);
- assert_eq!(refresh.body, "refresh token is not bound to a client");
+ assert_eq!(refresh.json()["error"], "invalid_grant");
+ assert_eq!(
+ refresh.json()["error_description"],
+ "refresh token is not bound to a client"
+ );
+}
+
+/// Takes a fresh client through the whole flow and presents its refresh token
+/// to `/token`, so the upstream refresh grant decides the answer.
+async fn refresh_over_http(harness: &Harness) -> Response {
+ let client_id = harness.register(&[TRUSTED_REDIRECT_URI]).await;
+ let code = harness
+ .complete_flow_to_code(&client_id, TRUSTED_REDIRECT_URI, VICTIM_CODE_VERIFIER)
+ .await;
+ let exchange = send(
+ harness,
+ token_request(&format!(
+ "grant_type=authorization_code&code={code}&code_verifier={VICTIM_CODE_VERIFIER}\
+ &redirect_uri={}&client_id={client_id}",
+ urlencoding::encode(TRUSTED_REDIRECT_URI)
+ )),
+ )
+ .await;
+ assert_eq!(exchange.status, StatusCode::OK);
+
+ send(
+ harness,
+ token_request(&format!(
+ "grant_type=refresh_token&refresh_token={UPSTREAM_REFRESH_TOKEN}&client_id={client_id}"
+ )),
+ )
+ .await
+}
+
+/// A refresh token the upstream no longer holds is the client's problem, not
+/// an outage: it gets `invalid_grant`, which tells it to authorize again
+/// instead of retrying.
+#[tokio::test]
+async fn token_endpoint_answers_an_upstream_refused_refresh_with_invalid_grant() {
+ let harness = Harness::with_provider(FakeOAuthProvider::new().failing_refresh(|| {
+ UpstreamGrantError::InvalidGrant {
+ detail: "invalid_grant (refresh_token_not_found)".to_owned(),
+ }
+ }));
+
+ let refresh = refresh_over_http(&harness).await;
+
+ assert_eq!(refresh.status, StatusCode::BAD_REQUEST);
+ assert_eq!(refresh.json()["error"], "invalid_grant");
+ assert_eq!(
+ refresh.json()["error_description"],
+ "refresh token is no longer valid; authorize again"
+ );
+ assert_eq!(refresh.cache_control.as_deref(), Some("no-store"));
+ assert!(
+ !refresh.body.contains("refresh_token_not_found"),
+ "upstream detail is logged, not returned"
+ );
+}
+
+#[tokio::test]
+async fn token_endpoint_answers_an_upstream_outage_with_temporarily_unavailable() {
+ let harness = Harness::with_provider(FakeOAuthProvider::new().failing_refresh(|| {
+ UpstreamGrantError::Unavailable {
+ retry_after: Some(Duration::from_secs(30)),
+ }
+ }));
+
+ let refresh = refresh_over_http(&harness).await;
+
+ assert_eq!(refresh.status, StatusCode::SERVICE_UNAVAILABLE);
+ assert_eq!(refresh.json()["error"], "temporarily_unavailable");
+ assert_eq!(refresh.retry_after.as_deref(), Some("30"));
+}
+
+#[tokio::test]
+async fn token_endpoint_answers_an_unknown_upstream_failure_with_server_error() {
+ let harness = Harness::with_provider(
+ FakeOAuthProvider::new()
+ .failing_refresh(|| UpstreamGrantError::Failed(anyhow::anyhow!("unexpected 500"))),
+ );
+
+ let refresh = refresh_over_http(&harness).await;
+
+ assert_eq!(refresh.status, StatusCode::BAD_GATEWAY);
+ assert_eq!(refresh.json()["error"], "server_error");
+ assert_eq!(refresh.retry_after, None);
+ assert!(
+ !refresh.body.contains("unexpected 500"),
+ "upstream detail is logged, not returned"
+ );
+}
+
+#[tokio::test]
+async fn token_endpoint_names_missing_parameters_as_invalid_request() {
+ let harness = Harness::new();
+
+ let missing_code = send(
+ &harness,
+ token_request("grant_type=authorization_code&client_id=some-client"),
+ )
+ .await;
+ assert_eq!(missing_code.status, StatusCode::BAD_REQUEST);
+ assert_eq!(missing_code.json()["error"], "invalid_request");
+
+ let unsupported = send(&harness, token_request("grant_type=password")).await;
+ assert_eq!(unsupported.status, StatusCode::BAD_REQUEST);
+ assert_eq!(unsupported.json()["error"], "unsupported_grant_type");
+
+ let no_grant_type = send(&harness, token_request("client_id=some-client")).await;
+ assert_eq!(no_grant_type.status, StatusCode::BAD_REQUEST);
+ assert_eq!(no_grant_type.json()["error"], "invalid_request");
+ assert_eq!(no_grant_type.cache_control.as_deref(), Some("no-store"));
+}
+
+async fn callback_with_failing_code_exchange(failure: fn() -> UpstreamGrantError) -> Response {
+ let harness = Harness::with_provider(FakeOAuthProvider::new().failing_code_exchange(failure));
+ let client_id = harness.register(&[TRUSTED_REDIRECT_URI]).await;
+ let authorize = send(
+ &harness,
+ authorize_request(&client_id, TRUSTED_REDIRECT_URI, VICTIM_CODE_VERIFIER),
+ )
+ .await;
+ assert_eq!(authorize.status, StatusCode::TEMPORARY_REDIRECT);
+ let cookie = cookie_pair(
+ authorize
+ .set_cookie
+ .as_deref()
+ .expect("authorize sets the binding cookie"),
+ );
+
+ let session_id = harness.inflight.only_pending_session_id();
+ send(&harness, callback_request(&session_id, Some(&cookie))).await
+}
+
+#[tokio::test]
+async fn callback_separates_a_refused_code_from_an_upstream_fault() {
+ let refused = callback_with_failing_code_exchange(|| UpstreamGrantError::InvalidGrant {
+ detail: "invalid_request (auth_code_not_found)".to_owned(),
+ })
+ .await;
+ assert_eq!(refused.status, StatusCode::BAD_REQUEST);
+ assert_eq!(refused.location, None);
+
+ let unavailable = callback_with_failing_code_exchange(|| UpstreamGrantError::Unavailable {
+ retry_after: None,
+ })
+ .await;
+ assert_eq!(unavailable.status, StatusCode::SERVICE_UNAVAILABLE);
+
+ let failed = callback_with_failing_code_exchange(|| {
+ UpstreamGrantError::Failed(anyhow::anyhow!("unexpected 500"))
+ })
+ .await;
+ assert_eq!(failed.status, StatusCode::BAD_GATEWAY);
}
async fn ok() -> &'static str {
diff --git a/services/mcp_auth_proxy/src/outbound/fusionauth.rs b/services/mcp_auth_proxy/src/outbound/fusionauth.rs
index 4db317b90e..02f1d8de75 100644
--- a/services/mcp_auth_proxy/src/outbound/fusionauth.rs
+++ b/services/mcp_auth_proxy/src/outbound/fusionauth.rs
@@ -1,12 +1,17 @@
//! FusionAuth adapter for the MCP OAuth broker.
+#[cfg(test)]
+mod test;
+
use anyhow::Context;
+use fusionauth::error::FusionAuthClientError;
use std::sync::Arc;
use tracing::Instrument;
+use upstream_error::UpstreamFailure;
use crate::domain::{
models::{RefreshToken, SignInMethod, UpstreamTokens},
- ports::{OAuthProvider, UpstreamRevocationFuture, UpstreamTokensFuture},
+ ports::{OAuthProvider, UpstreamGrantError, UpstreamRevocationFuture, UpstreamTokensFuture},
};
/// FusionAuth-backed OAuth provider for the MCP auth proxy.
@@ -33,6 +38,27 @@ impl FusionAuthOAuthProvider {
}
}
+/// Sorts a FusionAuth token endpoint failure into the broker's outcomes: a
+/// grant FusionAuth refused, an outage, or a fault of ours.
+fn grant_error(error: FusionAuthClientError) -> UpstreamGrantError {
+ match error {
+ FusionAuthClientError::OAuth2TokenRefused(refusal) if refusal.is_invalid_grant() => {
+ UpstreamGrantError::InvalidGrant {
+ detail: refusal.to_string(),
+ }
+ }
+ FusionAuthClientError::Upstream {
+ failure: UpstreamFailure::Unavailable,
+ ..
+ } => UpstreamGrantError::Unavailable { retry_after: None },
+ FusionAuthClientError::Upstream {
+ failure: UpstreamFailure::RateLimited { retry_after },
+ ..
+ } => UpstreamGrantError::Unavailable { retry_after },
+ error => UpstreamGrantError::Failed(anyhow::Error::from(error)),
+ }
+}
+
impl OAuthProvider for FusionAuthOAuthProvider {
#[tracing::instrument(skip(self), err)]
fn construct_authorize_url(
@@ -60,7 +86,7 @@ impl OAuthProvider for FusionAuthOAuthProvider {
.client
.complete_authorization_code_grant(code)
.await
- .map_err(anyhow::Error::from)?;
+ .map_err(grant_error)?;
Ok(UpstreamTokens {
access_token: grant.access_token.into(),
@@ -83,7 +109,7 @@ impl OAuthProvider for FusionAuthOAuthProvider {
.client
.complete_refresh_token_grant(refresh_token.as_str())
.await
- .map_err(anyhow::Error::from)?;
+ .map_err(grant_error)?;
Ok(UpstreamTokens {
access_token: grant.access_token.into(),
diff --git a/services/mcp_auth_proxy/src/outbound/fusionauth/test.rs b/services/mcp_auth_proxy/src/outbound/fusionauth/test.rs
new file mode 100644
index 0000000000..15196dd09f
--- /dev/null
+++ b/services/mcp_auth_proxy/src/outbound/fusionauth/test.rs
@@ -0,0 +1,96 @@
+use std::time::Duration;
+
+use fusionauth::error::{FusionAuthClientError, GenericErrorResponse, OAuth2TokenError};
+use upstream_error::UpstreamFailure;
+
+use super::grant_error;
+use crate::domain::ports::UpstreamGrantError;
+
+fn refused(error: &str, reason: &str) -> FusionAuthClientError {
+ FusionAuthClientError::OAuth2TokenRefused(OAuth2TokenError {
+ error: error.to_owned(),
+ error_reason: Some(reason.to_owned()),
+ error_description: Some("The refresh_token is invalid.".to_owned()),
+ })
+}
+
+#[test]
+fn a_refresh_token_fusionauth_no_longer_holds_is_an_invalid_grant() {
+ let error = grant_error(refused("invalid_grant", "refresh_token_not_found"));
+
+ let UpstreamGrantError::InvalidGrant { detail } = error else {
+ panic!("expected an invalid grant, got {error:?}");
+ };
+ assert_eq!(
+ detail,
+ "invalid_grant (refresh_token_not_found): The refresh_token is invalid."
+ );
+}
+
+#[test]
+fn a_rejected_client_credential_is_our_fault_and_keeps_its_detail() {
+ let error = grant_error(refused("invalid_client", "invalid_client_authentication"));
+
+ assert!(
+ matches!(error, UpstreamGrantError::Failed(_)),
+ "got {error:?}"
+ );
+ assert!(
+ error
+ .to_string()
+ .contains("invalid_client (invalid_client_authentication)"),
+ "the upstream reason must survive into logs: {error}"
+ );
+}
+
+#[test]
+fn an_outage_is_unavailable() {
+ let error = grant_error(FusionAuthClientError::Upstream {
+ service: fusionauth::error::SERVICE_NAME,
+ failure: UpstreamFailure::Unavailable,
+ });
+
+ assert!(
+ matches!(error, UpstreamGrantError::Unavailable { retry_after: None }),
+ "got {error:?}"
+ );
+}
+
+#[test]
+fn throttling_is_unavailable_and_keeps_retry_after() {
+ let error = grant_error(FusionAuthClientError::Upstream {
+ service: fusionauth::error::SERVICE_NAME,
+ failure: UpstreamFailure::RateLimited {
+ retry_after: Some(Duration::from_secs(7)),
+ },
+ });
+
+ assert!(
+ matches!(
+ error,
+ UpstreamGrantError::Unavailable {
+ retry_after: Some(retry_after)
+ } if retry_after == Duration::from_secs(7)
+ ),
+ "got {error:?}"
+ );
+}
+
+#[test]
+fn an_unusable_answer_is_a_failure() {
+ for error in [
+ FusionAuthClientError::Upstream {
+ service: fusionauth::error::SERVICE_NAME,
+ failure: UpstreamFailure::InvalidResponse,
+ },
+ FusionAuthClientError::Generic(GenericErrorResponse {
+ message: "<html>bad</html>".to_owned(),
+ }),
+ ] {
+ let error = grant_error(error);
+ assert!(
+ matches!(error, UpstreamGrantError::Failed(_)),
+ "got {error:?}"
+ );
+ }
+}
diff --git a/services/mcp_auth_proxy/src/test_support.rs b/services/mcp_auth_proxy/src/test_support.rs
index 3b52cb207f..f7e9ef65f8 100644
--- a/services/mcp_auth_proxy/src/test_support.rs
+++ b/services/mcp_auth_proxy/src/test_support.rs
@@ -19,7 +19,7 @@ use crate::domain::{
},
ports::{
ClientRegistrationStore, GrantRevokedFuture, OAuthProvider, RefreshTokenBindingFuture,
- RefreshTokenBindingStore, RegisteredClientFuture, StoreWriteFuture,
+ RefreshTokenBindingStore, RegisteredClientFuture, StoreWriteFuture, UpstreamGrantError,
UpstreamRevocationFuture, UpstreamTokensFuture,
},
redirect_uri::RedirectUriPolicy,
@@ -230,10 +230,15 @@ impl RefreshTokenBindingStore for FakeClientRegistry {
}
}
+/// Builds the failure a fake upstream grant answers with.
+type GrantFailure = Box<dyn Fn() -> UpstreamGrantError + Send + Sync>;
+
/// Upstream provider that hands back fixed tokens, standing in for FusionAuth.
pub struct FakeOAuthProvider {
rotated_refresh_token: Option<String>,
revoked_refresh_tokens: Mutex<HashSet<String>>,
+ refresh_failure: Option<GrantFailure>,
+ code_exchange_failure: Option<GrantFailure>,
}
impl FakeOAuthProvider {
@@ -243,9 +248,30 @@ impl FakeOAuthProvider {
Self {
rotated_refresh_token: None,
revoked_refresh_tokens: Mutex::default(),
+ refresh_failure: None,
+ code_exchange_failure: None,
}
}
+ /// This provider, with every refresh grant failing with `failure()`.
+ pub fn failing_refresh(
+ mut self,
+ failure: impl Fn() -> UpstreamGrantError + Send + Sync + 'static,
+ ) -> Self {
+ self.refresh_failure = Some(Box::new(failure));
+ self
+ }
+
+ /// This provider, with every authorization code grant failing with
+ /// `failure()`.
+ pub fn failing_code_exchange(
+ mut self,
+ failure: impl Fn() -> UpstreamGrantError + Send + Sync + 'static,
+ ) -> Self {
+ self.code_exchange_failure = Some(Box::new(failure));
+ self
+ }
+
/// Returns whether the provider was asked to revoke `refresh_token`.
pub fn revoked(&self, refresh_token: &str) -> bool {
self.revoked_refresh_tokens
@@ -258,7 +284,7 @@ impl FakeOAuthProvider {
pub fn rotating(rotated_refresh_token: &str) -> Self {
Self {
rotated_refresh_token: Some(rotated_refresh_token.to_owned()),
- revoked_refresh_tokens: Mutex::default(),
+ ..Self::new()
}
}
}
@@ -278,6 +304,9 @@ impl OAuthProvider for FakeOAuthProvider {
fn exchange_authorization_code<'a>(&'a self, _code: &'a str) -> UpstreamTokensFuture<'a> {
Box::pin(async move {
+ if let Some(failure) = &self.code_exchange_failure {
+ return Err(failure());
+ }
Ok(UpstreamTokens {
access_token: AccessToken::from(UPSTREAM_ACCESS_TOKEN),
refresh_token: RefreshToken::from(UPSTREAM_REFRESH_TOKEN),
@@ -291,13 +320,18 @@ impl OAuthProvider for FakeOAuthProvider {
refresh_token: &'a RefreshToken,
) -> UpstreamTokensFuture<'a> {
Box::pin(async move {
+ if let Some(failure) = &self.refresh_failure {
+ return Err(failure());
+ }
if self
.revoked_refresh_tokens
.lock()
.expect("revoked refresh tokens lock")
.contains(refresh_token.as_str())
{
- anyhow::bail!("refresh token was revoked upstream");
+ return Err(UpstreamGrantError::InvalidGrant {
+ detail: "invalid_grant (refresh_token_not_found)".to_owned(),
+ });
}
let next = self
.rotated_refresh_token