Preserve MCP authentication challenges on tool calls (#42552)

## Why

When silent OAuth refresh cannot recover a rejected MCP tool call, the caller
needs the server's authentication challenge to initiate interactive login. The
rejected call must not be replayed automatically after refresh has failed.

## What changed

- Convert `401 Unauthorized` responses with `WWW-Authenticate` headers into an
  MCP tool error containing `mcp/www_authenticate` metadata.
- Preserve multiple authentication challenges by combining all
  `WWW-Authenticate` header values.
- Keep successful silent refresh behavior while avoiding replay when refresh
  fails.

## Testing

Added coverage for successful and failed refresh, multiple authentication
headers, propagation through agent tool-call events, and no-replay behavior.

GitOrigin-RevId: c560cff6286d7ab09b1f5c6cf3618d4650cde47d
This commit is contained in:
Alex Kotliarskyi
2026-09-03 15:12:02 +00:00
committed by copyberry
parent 6d7f6dcd22
commit 0650d6d1ca
5 changed files with 365 additions and 11 deletions
@@ -1,7 +1,8 @@
//! Covers OAuth connection replacement when a running thread refreshes its feature config.
//! Covers OAuth recovery and authentication challenges in running MCP connections.
use super::EnvVarGuard;
use super::OAuthCredentialExpiry;
use super::read_only_user_turn;
use super::write_fallback_oauth_tokens;
use std::sync::Arc;
@@ -9,16 +10,23 @@ use codex_config::DEFAULT_MCP_SERVER_ENVIRONMENT_ID;
use codex_config::McpServerConfig;
use codex_config::types::OAuthCredentialsStoreMode;
use codex_features::Feature;
use codex_protocol::items::McpToolCallStatus;
use codex_protocol::items::TurnItem;
use codex_protocol::mcp::CallToolResult;
use codex_protocol::protocol::EventMsg;
use core_test_support::apps_test_server::AppsTestServer;
use core_test_support::responses;
use core_test_support::skip_if_no_network;
use core_test_support::test_codex::test_codex;
use core_test_support::wait_for_event;
use core_test_support::wait_for_mcp_server;
use pretty_assertions::assert_eq;
use serde_json::json;
use serial_test::serial;
use test_case::test_case;
use wiremock::Mock;
use wiremock::ResponseTemplate;
use wiremock::matchers::body_partial_json;
use wiremock::matchers::method;
use wiremock::matchers::path;
@@ -27,6 +35,107 @@ enum ConfigRefreshPath {
Mcp,
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn http_auth_challenge_reaches_agent_tool_call_events_without_replay() -> anyhow::Result<()> {
skip_if_no_network!(Ok(()));
let responses_server = responses::start_mock_server().await;
let mcp_server = responses::start_mock_server().await;
let http_server = AppsTestServer::mount(&mcp_server).await?;
let challenge = r#"Bearer error="invalid_token", scope="calendar:read", resource_metadata="https://example.com/.well-known/oauth-protected-resource""#;
Mock::given(method("POST"))
.and(path("/api/codex/ps/mcp"))
.and(body_partial_json(json!({"method": "tools/call"})))
.respond_with(
ResponseTemplate::new(/*s*/ 401)
.append_header("www-authenticate", r#"Basic realm="proxy, login""#)
.append_header("www-authenticate", challenge),
)
.with_priority(/*p*/ 1)
.expect(1)
.mount(&mcp_server)
.await;
let call_id = "auth-challenge-call";
let model_requests = responses::mount_sse_sequence(
&responses_server,
vec![
responses::sse(vec![
responses::ev_response_created("resp-1"),
responses::ev_function_call_with_namespace(
call_id,
"mcp__reauth",
"calendar_list_events",
"{}",
),
responses::ev_completed("resp-1"),
]),
responses::sse(vec![
responses::ev_response_created("resp-2"),
responses::ev_assistant_message("msg-1", "Please reconnect the MCP server."),
responses::ev_completed("resp-2"),
]),
],
)
.await;
let server_config: McpServerConfig = serde_json::from_value(json!({
"url": format!("{}/api/codex/ps/mcp", http_server.chatgpt_base_url),
"environment_id": DEFAULT_MCP_SERVER_ENVIRONMENT_ID,
}))?;
let fixture = test_codex()
.with_config(move |config| {
config
.mcp_servers
.set([("reauth".to_string(), server_config)].into())
.expect("test config should allow the MCP server");
})
// The mock MCP endpoint stays on the host when the executor is remote.
.build_with_remote_and_local_env(&responses_server)
.await?;
wait_for_mcp_server(&fixture.codex, "reauth").await?;
fixture
.codex
.start_or_steer_turn(read_only_user_turn(&fixture, "List calendar events."))
.await?;
let mut end_results = Vec::new();
let mut completed_results = Vec::new();
wait_for_event(&fixture.codex, |event| {
match event {
EventMsg::McpToolCallEnd(event) if event.call_id == call_id => {
end_results.push(event.result.clone());
}
EventMsg::ItemCompleted(event) => {
if let TurnItem::McpToolCall(item) = &event.item
&& item.id == call_id
{
completed_results.push((item.status, item.result.clone(), item.error.clone()));
}
}
_ => {}
}
matches!(event, EventMsg::TurnComplete(_))
})
.await;
let expected = CallToolResult {
content: vec![json!({"type": "text", "text": "Authentication required"})],
structured_content: None,
is_error: Some(true),
meta: Some(json!({
"mcp/www_authenticate": [format!(r#"Basic realm="proxy, login", {challenge}"#)],
})),
};
assert_eq!(end_results, vec![Ok(expected.clone())]);
assert_eq!(
completed_results,
vec![(McpToolCallStatus::Failed, Some(expected), None)]
);
assert_eq!(model_requests.requests().len(), 2);
mcp_server.verify().await;
fixture.codex.shutdown_and_wait().await?;
Ok(())
}
#[test_case(ConfigRefreshPath::Runtime; "runtime configuration refresh")]
#[test_case(ConfigRefreshPath::Mcp; "MCP configuration refresh")]
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
@@ -275,12 +275,19 @@ impl StreamableHttpClient for StreamableHttpClientAdapter {
StreamableHttpClientAdapterError::SessionExpired404,
));
}
if response.status == StatusCode::UNAUTHORIZED.as_u16()
&& let Some(header) = response_header(&response.headers, WWW_AUTHENTICATE)
{
return Err(StreamableHttpError::AuthRequired(AuthRequiredError::new(
header,
)));
if response.status == StatusCode::UNAUTHORIZED.as_u16() {
let challenges = response
.headers
.iter()
.filter(|header| header.name.eq_ignore_ascii_case(WWW_AUTHENTICATE.as_str()))
.map(|header| header.value.as_str())
.collect::<Vec<_>>();
if !challenges.is_empty() {
// RFC 9110 allows combining these list-based fields; keep challenges after the first.
return Err(StreamableHttpError::AuthRequired(AuthRequiredError::new(
challenges.join(", "),
)));
}
}
if response.status == StatusCode::FORBIDDEN.as_u16()
&& let Some(challenge) = insufficient_scope_challenge(&response.headers)
+34 -4
View File
@@ -29,6 +29,7 @@ use rmcp::model::CallToolRequestParams;
use rmcp::model::CallToolResult;
use rmcp::model::ClientNotification;
use rmcp::model::ClientRequest;
use rmcp::model::ContentBlock;
use rmcp::model::CustomNotification;
use rmcp::model::CustomRequest;
use rmcp::model::ElicitRequestParams;
@@ -39,6 +40,7 @@ use rmcp::model::InitializeRequestParams;
use rmcp::model::ListResourceTemplatesResult;
use rmcp::model::ListResourcesResult;
use rmcp::model::ListToolsResult;
use rmcp::model::MetaObject;
use rmcp::model::PaginatedRequestParams;
use rmcp::model::ProtocolVersion;
use rmcp::model::ReadResourceRequestParams;
@@ -54,6 +56,7 @@ use rmcp::service::ClientServiceExt;
use rmcp::service::RequestHandle;
use rmcp::service::RoleClient;
use rmcp::service::RunningService;
use rmcp::service::ServiceError;
use rmcp::transport::AuthorizationManager;
use rmcp::transport::StreamableHttpClientTransport;
use rmcp::transport::auth::AuthClient;
@@ -811,7 +814,7 @@ impl RmcpClient {
let mut rmcp_params = CallToolRequestParams::new(name);
rmcp_params.arguments = arguments;
let requested_modern = self.protocol_mode == McpProtocolMode::V20260728;
let result = self
match self
.run_service_operation("tools/call", timeout, move |service| {
let mut rmcp_params = rmcp_params.clone();
let meta = meta.clone();
@@ -844,9 +847,36 @@ impl RmcpClient {
}
.boxed()
})
.await?;
self.persist_oauth_tokens().await;
Ok(result)
.await
{
Ok(result) => {
self.persist_oauth_tokens().await;
Ok(result)
}
Err(error) => {
let Some(ClientOperationError::Service(ServiceError::TransportSend(transport))) =
error.downcast_ref()
else {
return Err(error);
};
let Some(StreamableHttpError::AuthRequired(challenge)) =
transport
.error
.downcast_ref::<StreamableHttpError<StreamableHttpClientAdapterError>>()
else {
return Err(error);
};
// The transport has already handled automatic refresh. Preserve the challenge
// for interactive login without replaying the rejected tool call.
let mut result =
CallToolResult::error(vec![ContentBlock::text("Authentication required")]);
result.meta = Some(MetaObject::from(serde_json::Map::from_iter([(
"mcp/www_authenticate".to_string(),
serde_json::json!([challenge.www_authenticate_header]),
)])));
Ok(result)
}
}
}
pub async fn send_custom_notification(
@@ -60,6 +60,7 @@ const CHILD_HELPER_COMMAND_ENV: &str = "MCP_TEST_OAUTH_STARTUP_HELPER_COMMAND";
const CHILD_RESOURCE_API_KEY_ENV: &str = "MCP_TEST_OAUTH_STARTUP_RESOURCE_API_KEY";
const CHILD_STORED_ISSUER_ENV: &str = "MCP_TEST_OAUTH_STARTUP_STORED_ISSUER";
const CHILD_ACCESS_TOKEN_EXPIRY_ENV: &str = "MCP_TEST_OAUTH_STARTUP_ACCESS_TOKEN_EXPIRY";
const CHILD_REFRESH_SUCCEEDS_ENV: &str = "MCP_TEST_REFRESH_SUCCEEDS";
const LEGACY_REFRESHABLE_SERVER_URL: &str = "https://legacy-refreshable.example/mcp";
const UNEXPIRED_SERVER_URL: &str = "https://unexpired.example/mcp";
const REFRESHABLE_SERVER_URL: &str = "https://refreshable.example/mcp";
@@ -78,6 +79,173 @@ enum IssuerMismatchAccessToken {
Unexpired,
}
#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
async fn tool_call_preserves_challenge_only_after_silent_refresh_fails() -> anyhow::Result<()> {
for refresh_succeeds in [true, false] {
let server = MockServer::start().await;
let server_url = format!("{}/mcp", server.uri());
Mock::given(method("GET"))
.and(path("/.well-known/oauth-authorization-server/mcp"))
.respond_with(ResponseTemplate::new(/*s*/ 200).set_body_json(json!({
"issuer": server_url,
"authorization_endpoint": format!("{}/authorize", server.uri()),
"token_endpoint": format!("{}/token", server.uri()),
})))
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path("/token"))
.and(body_string_contains("grant_type=refresh_token"))
.and(body_string_contains(format!(
"refresh_token={REFRESH_TOKEN}"
)))
.respond_with(if refresh_succeeds {
ResponseTemplate::new(/*s*/ 200).set_body_json(json!({
"access_token": REFRESHED_ACCESS_TOKEN,
"token_type": "Bearer",
"expires_in": 7200,
"refresh_token": REFRESH_TOKEN,
}))
} else {
ResponseTemplate::new(/*s*/ 400).set_body_json(json!({"error": "invalid_grant"}))
})
.expect(1)
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path("/mcp"))
.respond_with(|request: &Request| {
let body: Value = request.body_json().unwrap();
let result = match body["method"].as_str() {
Some("initialize") => json!({
"protocolVersion": body["params"]["protocolVersion"],
"capabilities": {},
"serverInfo": {"name": "oauth-tool-call-test", "version": "1"},
}),
Some("notifications/initialized") => {
return ResponseTemplate::new(/*s*/ 202);
}
Some("tools/call") => {
if request.headers.get("authorization").unwrap()
!= format!("Bearer {REFRESHED_ACCESS_TOKEN}").as_str()
{
return ResponseTemplate::new(/*s*/ 401).insert_header(
"www-authenticate",
r#"Bearer error="invalid_token""#,
);
}
json!({"content": [{"type": "text", "text": "refreshed"}]})
}
_ => return ResponseTemplate::new(/*s*/ 400),
};
ResponseTemplate::new(/*s*/ 200).set_body_json(json!({
"jsonrpc": "2.0", "id": body["id"], "result": result,
}))
})
.mount(&server)
.await;
// The child owns its credential store; the parallel test runner's environment is unchanged.
let codex_home = TempDir::new()?;
let status = Command::new(std::env::current_exe()?)
.args([
"oauth_tool_call_child",
"--exact",
"--ignored",
"--nocapture",
])
.env("CODEX_HOME", codex_home.path())
.env(CHILD_SERVER_URL_ENV, server_url)
.env(CHILD_REFRESH_SUCCEEDS_ENV, refresh_succeeds.to_string())
.status()
.await?;
assert!(status.success(), "OAuth tool call child failed: {status}");
server.verify().await;
let tool_calls = server
.received_requests()
.await
.unwrap()
.into_iter()
.filter(|request| {
request
.body_json::<Value>()
.ok()
.is_some_and(|body| body["method"] == "tools/call")
})
.count();
assert_eq!(tool_calls, if refresh_succeeds { 2 } else { 1 });
}
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
#[ignore = "spawned by tool_call_preserves_challenge_only_after_silent_refresh_fails"]
async fn oauth_tool_call_child() -> anyhow::Result<()> {
let server_url = std::env::var(CHILD_SERVER_URL_ENV)?;
let refresh_succeeds = std::env::var(CHILD_REFRESH_SUCCEEDS_ENV)? == "true";
let mut response = OAuthTokenResponse::new(
AccessToken::new(EXPIRED_ACCESS_TOKEN.to_string()),
BasicTokenType::Bearer,
VendorExtraTokenFields::default(),
);
response.set_refresh_token(Some(RefreshToken::new(REFRESH_TOKEN.to_string())));
response.set_expires_in(Some(&Duration::from_secs(/*secs*/ 7200)));
save_oauth_tokens(
SERVER_NAME,
&StoredOAuthTokens {
server_name: SERVER_NAME.to_string(),
url: server_url.clone(),
issuer: Some(server_url.clone()),
client_id: "test-client-id".to_string(),
token_response: WrappedOAuthTokenResponse(response),
expires_at: Some(
(SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis() + 7_200_000) as u64,
),
},
OAuthCredentialsStoreMode::File,
AuthKeyringBackendKind::default(),
)
.await?;
let client = RmcpClient::new_streamable_http_client(
SERVER_NAME,
&server_url,
/*bearer_token*/ None,
/*http_headers*/ None,
/*env_http_headers*/ None,
OAuthCredentialsStoreMode::File,
AuthKeyringBackendKind::default(),
Environment::default_for_tests().get_http_client(),
/*auth_provider*/ None,
)
.await?;
initialize_client(&client).await?;
let result = client
.call_tool(
"probe".to_string(),
/*arguments*/ None,
/*meta*/ None,
Some(Duration::from_secs(/*secs*/ 5)),
)
.await?;
if refresh_succeeds {
assert_eq!(
serde_json::to_value(result)?,
json!({
"content": [{"type": "text", "text": "refreshed"}],
})
);
} else {
assert_eq!(result.is_error, Some(true));
assert_eq!(
serde_json::to_value(result.meta)?,
json!({
"mcp/www_authenticate": [r#"Bearer error="invalid_token""#],
})
);
}
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
async fn refreshes_expired_persisted_token_before_initialize() -> anyhow::Result<()> {
assert_expired_token_refresh(
@@ -14,7 +14,11 @@ use codex_exec_server::HttpResponseBodyStream;
use futures::FutureExt as _;
use futures::future::BoxFuture;
use pretty_assertions::assert_eq;
use rmcp::model::CallToolResult;
use rmcp::model::ContentBlock;
use rmcp::model::MetaObject;
use serde_json::Value;
use serde_json::json;
use streamable_http_test_support::arm_initialize_post_failure;
use streamable_http_test_support::arm_initialize_post_json_rpc_failure;
@@ -301,6 +305,42 @@ async fn streamable_http_401_does_not_trigger_recovery() -> anyhow::Result<()> {
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
async fn streamable_http_401_challenge_is_a_tool_error_without_replay() -> anyhow::Result<()> {
let challenge = r#"Bearer error="invalid_token", resource_metadata="https://example.com/.well-known/oauth-protected-resource""#;
for challenges in [
vec![challenge],
vec![r#"Basic realm="proxy, login""#, challenge],
] {
let (_server, base_url) = spawn_streamable_http_server().await?;
let client = create_client(&base_url).await?;
arm_session_post_failure(
&base_url,
/*status*/ 401,
/*remaining*/ 1,
&challenges,
)
.await?;
let result = call_echo_tool(&client, "rejected").await?;
let mut expected =
CallToolResult::error(vec![ContentBlock::text("Authentication required")]);
expected.meta = Some(MetaObject::from(serde_json::Map::from_iter([(
"mcp/www_authenticate".to_string(),
json!([challenges.join(", ")]),
)])));
assert_eq!(result, expected);
// A retry inside the failed call would consume the single rejection and return success.
assert_eq!(
call_echo_tool(&client, "next-user-call").await?,
expected_echo_result("next-user-call"),
);
}
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
async fn streamable_http_403_scope_challenge_returns_insufficient_scope() -> anyhow::Result<()> {
let (_server, base_url) = spawn_streamable_http_server().await?;