fix(auth): omit scope on refresh unless caller sets one

crates/rmcp/src/transport/auth.rs

@@ -1266,6 +1266,8 @@ pub struct AuthorizationManager {
     application_type: Option<String>,
     allow_missing_issuer: bool,
     allow_private_metadata_addresses: bool,
+    /// Scopes the caller asked to send on refresh. `None` omits the parameter.
+    refresh_scopes: Option<Vec<String>>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -1578,6 +1580,7 @@ impl AuthorizationManager {
             application_type: Some(DEFAULT_APPLICATION_TYPE.to_string()),
             allow_missing_issuer: false,
             allow_private_metadata_addresses: false,
+            refresh_scopes: None,
         };
 
         Ok(manager)
@@ -1588,6 +1591,25 @@ impl AuthorizationManager {
         self.scope_upgrade_config = config;
     }
 
+    /// Set the scopes to include on a refresh-token request.
+    ///
+    /// RFC 6749 §6 makes `scope` optional. Refresh omits it unless the caller
+    /// sets one here, so providers that require `scope` on refresh (e.g. Azure
+    /// AD v2) must call this. Earlier releases always sent the granted scopes.
+    ///
+    /// Only scopes from the original grant are sent. If none of the scopes set
+    /// here are in the original grant, refresh fails with
+    /// [`AuthError::TokenRefreshFailed`] instead of omitting `scope`, because
+    /// omitting it would return the full original grant. An empty list omits
+    /// the parameter again.
+    pub fn set_refresh_scopes<I, S>(&mut self, scopes: I)
+    where
+        I: IntoIterator<Item = S>,
+        S: Into<String>,
+    {
+        self.refresh_scopes = Some(scopes.into_iter().map(Into::into).collect());
+    }
+
     /// Configure whether authorization server metadata discovery tolerates a
     /// missing `issuer` field.
     ///
@@ -2123,6 +2145,39 @@ impl AuthorizationManager {
         Self::dedup_scopes(scopes)
     }
 
+    /// Scopes to put on a refresh request.
+    ///
+    /// `None` or an empty list omits the parameter. Otherwise only scopes from
+    /// the original grant are kept. When that grant was not recorded, the
+    /// caller-provided scopes are used as-is. Errors when the caller set scopes
+    /// but none of them are in the original grant: omitting `scope` then would
+    /// silently return the full grant instead of the narrower one asked for.
+    fn refresh_request_scopes(
+        explicit: Option<&[String]>,
+        granted: &[String],
+    ) -> Result<Vec<String>, AuthError> {
+        let Some(explicit) = explicit.filter(|scopes| !scopes.is_empty()) else {
+            return Ok(Vec::new());
+        };
+        if granted.is_empty() {
+            return Ok(Self::dedup_scopes(explicit.to_vec()));
+        }
+        let granted_set: HashSet<&str> = granted.iter().map(String::as_str).collect();
+        let kept = Self::dedup_scopes(
+            explicit
+                .iter()
+                .filter(|scope| granted_set.contains(scope.as_str()))
+                .cloned()
+                .collect(),
+        );
+        if kept.is_empty() {
+            return Err(AuthError::TokenRefreshFailed(format!(
+                "none of the refresh scopes {explicit:?} are in the original grant {granted:?}"
+            )));
+        }
+        Ok(kept)
+    }
+
     /// deduplicate scopes preserving first-seen order (SEP-2350: stable for testability)
     fn dedup_scopes(scopes: Vec<String>) -> Vec<String> {
         let mut seen = std::collections::HashSet::new();
@@ -2561,10 +2616,23 @@ impl AuthorizationManager {
             .exchange_refresh_token(&refresh_token_value)
             // RFC 8707: the resource indicator is required on token requests, including refreshes
             .add_extra_param("resource", self.oauth_resource().await);
-        let requested_scopes = stored_credentials.granted_scopes.clone();
-        for scope in requested_scopes.iter().cloned() {
+        // RFC 6749 §6: `scope` is optional on refresh and must not exceed the
+        // original grant. Omit it unless the caller set scopes explicitly.
+        let granted_scopes = stored_credentials.granted_scopes.clone();
+        let original_grant = granted_scopes.clone();
+        let scopes_to_send =
+            Self::refresh_request_scopes(self.refresh_scopes.as_deref(), &granted_scopes)?;
+        for scope in scopes_to_send.iter().cloned() {
             refresh_request = refresh_request.add_scope(Scope::new(scope));
         }
+        // Omitting `scope` asks for the original grant. Keep that as the
+        // fallback when the token response also omits `scope` (RFC 6749 §5.1).
+        let asked_for_subset = !scopes_to_send.is_empty();
+        let requested_scopes = if scopes_to_send.is_empty() {
+            granted_scopes
+        } else {
+            scopes_to_send
+        };
         let mut token_result = match refresh_request
             .request_async(&OAuth2HttpClient {
                 client: self.http_client.as_ref(),
@@ -2610,11 +2678,22 @@ impl AuthorizationManager {
 
         *self.current_scopes.write().await = granted_scopes.clone();
 
+        // RFC 6749 §6: a refresh never changes the refresh token's scope, even
+        // when the access token comes back narrower. Keep the original grant so
+        // later refreshes can still ask for any of it. An unknown grant (imported
+        // or legacy credentials) stays unknown after a refresh that asked for a
+        // subset, since that response only shows the subset.
+        let stored_grant = if original_grant.is_empty() && !asked_for_subset {
+            granted_scopes
+        } else {
+            original_grant
+        };
+
         let client_id = oauth_client.client_id().to_string();
         let stored = StoredCredentials {
             client_id,
             token_response: Some(token_result.clone()),
-            granted_scopes,
+            granted_scopes: stored_grant,
             token_received_at: Some(Self::now_epoch_secs()),
             issuer: self.metadata_issuer(),
         };
@@ -9975,6 +10054,15 @@ mod tests {
     }
 
     async fn start_token_server() -> (String, Arc<std::sync::Mutex<Option<String>>>) {
+        start_token_server_with_body(
+            r#"{"access_token":"new-token","token_type":"Bearer","expires_in":3600}"#,
+        )
+        .await
+    }
+
+    async fn start_token_server_with_body(
+        response_body: &'static str,
+    ) -> (String, Arc<std::sync::Mutex<Option<String>>>) {
         use axum::{Router, body::Body, http::Response, routing::post};
         let captured: Arc<std::sync::Mutex<Option<String>>> = Arc::new(std::sync::Mutex::new(None));
         let captured_clone = Arc::clone(&captured);
@@ -9984,14 +10072,11 @@ mod tests {
             post(move |body: axum::body::Bytes| {
                 let cap = Arc::clone(&captured_clone);
                 async move {
-                    *cap.lock().unwrap() =
-                        Some(String::from_utf8(body.to_vec()).unwrap());
+                    *cap.lock().unwrap() = Some(String::from_utf8(body.to_vec()).unwrap());
                     Response::builder()
                         .status(200)
                         .header("content-type", "application/json")
-                        .body(Body::from(
-                            r#"{"access_token":"new-token","token_type":"Bearer","expires_in":3600}"#,
-                        ))
+                        .body(Body::from(response_body))
                         .unwrap()
                 }
             }),
@@ -10015,6 +10100,7 @@ mod tests {
         }))
         .await;
         manager.configure_client(test_client_config()).unwrap();
+        manager.set_refresh_scopes(["read", "write"]);
 
         let stored = StoredCredentials {
             client_id: "my-client".to_string(),
@@ -10091,6 +10177,7 @@ mod tests {
         }))
         .await;
         manager.configure_client(test_client_config()).unwrap();
+        manager.set_refresh_scopes(["read"]);
 
         let stored = StoredCredentials {
             client_id: "my-client".to_string(),
@@ -10130,6 +10217,7 @@ mod tests {
         }))
         .await;
         manager.configure_client(test_client_config()).unwrap();
+        manager.set_refresh_scopes(["read", "offline_access"]);
 
         let stored = StoredCredentials {
             client_id: "my-client".to_string(),
@@ -10193,6 +10281,169 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn refresh_token_omits_scope_unless_caller_sets_one() {
+        let (base_url, captured) = start_token_server().await;
+
+        let mut manager = manager_with_metadata(Some(AuthorizationMetadata {
+            authorization_endpoint: format!("{}/authorize", base_url),
+            token_endpoint: format!("{}/token", base_url),
+            ..Default::default()
+        }))
+        .await;
+        manager.configure_client(test_client_config()).unwrap();
+
+        // The token response recorded these scopes. That must not put `scope`
+        // on the refresh by itself: Salesforce rejects the parameter, and
+        // RFC 6749 §6 says omitting it keeps the original grant.
+        let stored = StoredCredentials {
+            client_id: "my-client".to_string(),
+            token_response: Some(make_token_response_with_refresh(
+                "old-token",
+                "my-refresh-token",
+            )),
+            granted_scopes: vec!["mcp_api".to_string(), "refresh_token".to_string()],
+            token_received_at: Some(AuthorizationManager::now_epoch_secs()),
+            issuer: None,
+        };
+        manager.credential_store.save(stored).await.unwrap();
+
+        manager.refresh_token().await.unwrap();
+
+        let body = captured.lock().unwrap().take().unwrap();
+        let params: std::collections::HashMap<_, _> = url::form_urlencoded::parse(body.as_bytes())
+            .into_owned()
+            .collect();
+        assert!(
+            !params.contains_key("scope"),
+            "scope should be absent when the caller did not set one, body: {body}"
+        );
+    }
+
+    async fn manager_with_grant(base_url: &str, grant: &[&str]) -> AuthorizationManager {
+        let mut manager = manager_with_metadata(Some(AuthorizationMetadata {
+            authorization_endpoint: format!("{}/authorize", base_url),
+            token_endpoint: format!("{}/token", base_url),
+            ..Default::default()
+        }))
+        .await;
+        manager.configure_client(test_client_config()).unwrap();
+        let stored = StoredCredentials {
+            client_id: "my-client".to_string(),
+            token_response: Some(make_token_response_with_refresh(
+                "old-token",
+                "my-refresh-token",
+            )),
+            granted_scopes: grant.iter().map(|s| s.to_string()).collect(),
+            token_received_at: Some(AuthorizationManager::now_epoch_secs()),
+            issuer: None,
+        };
+        manager.credential_store.save(stored).await.unwrap();
+        manager
+    }
+
+    #[tokio::test]
+    async fn refresh_fails_when_no_refresh_scope_is_in_the_grant() {
+        let (base_url, captured) = start_token_server().await;
+        let mut manager = manager_with_grant(&base_url, &["read", "write"]).await;
+        manager.set_refresh_scopes(["admin"]);
+
+        let err = manager.refresh_token().await.unwrap_err();
+        assert!(
+            matches!(err, AuthError::TokenRefreshFailed(_)),
+            "unexpected error: {err:?}"
+        );
+        assert!(
+            captured.lock().unwrap().is_none(),
+            "no refresh request should be sent"
+        );
+    }
+
+    #[tokio::test]
+    async fn server_narrowed_refresh_keeps_original_grant() {
+        let (base_url, _captured) = start_token_server_with_body(
+            r#"{"access_token":"new-token","token_type":"Bearer","expires_in":3600,"scope":"read"}"#,
+        )
+        .await;
+        let manager = manager_with_grant(&base_url, &["read", "write"]).await;
+
+        manager.refresh_token().await.unwrap();
+
+        let saved = manager.credential_store.load().await.unwrap().unwrap();
+        assert_eq!(
+            saved.granted_scopes,
+            vec!["read".to_string(), "write".to_string()]
+        );
+        assert_eq!(
+            *manager.current_scopes.read().await,
+            vec!["read".to_string()]
+        );
+    }
+
+    #[tokio::test]
+    async fn subset_refresh_keeps_unknown_grant_unknown() {
+        let (base_url, _captured) = start_token_server_with_body(
+            r#"{"access_token":"new-token","token_type":"Bearer","expires_in":3600,"scope":"read"}"#,
+        )
+        .await;
+        let mut manager = manager_with_grant(&base_url, &[]).await;
+        manager.set_refresh_scopes(["read"]);
+
+        manager.refresh_token().await.unwrap();
+
+        let saved = manager.credential_store.load().await.unwrap().unwrap();
+        assert!(saved.granted_scopes.is_empty(), "{:?}", saved.granted_scopes);
+
+        // a later refresh for a different scope is still sent, not rejected locally
+        manager.set_refresh_scopes(["write"]);
+        manager.refresh_token().await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn narrowed_refresh_keeps_original_grant() {
+        let (base_url, captured) = start_token_server().await;
+
+        let mut manager = manager_with_metadata(Some(AuthorizationMetadata {
+            authorization_endpoint: format!("{}/authorize", base_url),
+            token_endpoint: format!("{}/token", base_url),
+            ..Default::default()
+        }))
+        .await;
+        manager.configure_client(test_client_config()).unwrap();
+        manager.set_refresh_scopes(["read"]);
+
+        let stored = StoredCredentials {
+            client_id: "my-client".to_string(),
+            token_response: Some(make_token_response_with_refresh(
+                "old-token",
+                "my-refresh-token",
+            )),
+            granted_scopes: vec!["read".to_string(), "write".to_string()],
+            token_received_at: Some(AuthorizationManager::now_epoch_secs()),
+            issuer: None,
+        };
+        manager.credential_store.save(stored).await.unwrap();
+
+        manager.refresh_token().await.unwrap();
+        captured.lock().unwrap().take();
+
+        let saved = manager.credential_store.load().await.unwrap().unwrap();
+        assert_eq!(
+            saved.granted_scopes,
+            vec!["read".to_string(), "write".to_string()],
+            "a narrowed refresh must not shrink the stored grant"
+        );
+
+        // A later refresh can still ask for the full grant.
+        manager.set_refresh_scopes(["read", "write"]);
+        manager.refresh_token().await.unwrap();
+        let body = captured.lock().unwrap().take().unwrap();
+        let params: std::collections::HashMap<_, _> = url::form_urlencoded::parse(body.as_bytes())
+            .into_owned()
+            .collect();
+        assert_eq!(params.get("scope").map(String::as_str), Some("read write"));
+    }
+
     #[tokio::test]
     async fn refresh_token_preserves_existing_refresh_token_when_response_omits_it() {
         use oauth2::TokenResponse;

docs/OAUTH_SUPPORT.md

@@ -452,9 +452,23 @@ cargo run -p mcp-client-examples --example clients_client_credentials -- \
 6. **Authorization Request**: Build authorization URL with PKCE (S256) and RFC 8707 resource parameter
 7. **Authorization Code Exchange**: After user authorization, exchange code for access token (with resource parameter)
 8. **Token Usage**: Use access token for API calls via `AuthClient` or `AuthorizedHttpClient`
-9. **Token Refresh**: Automatically use refresh token to get new access token when current one expires; previously granted scopes are forwarded in the refresh request so providers that require them (e.g. Azure AD v2) work correctly
+9. **Token Refresh**: Automatically use refresh token to get new access token when current one expires; `scope` is omitted by default, which keeps the original grant (RFC 6749 §6). See [Refresh scopes](#refresh-scopes)
 10. **Scope Upgrade**: On 403 insufficient_scope, compute scope union and re-authorize with upgraded scopes
 
+## Refresh scopes
+
+Refresh requests leave out `scope` by default. RFC 6749 §6 makes it optional, and leaving it out keeps the original grant. Some providers (e.g. Salesforce) reject `scope` on refresh.
+
+**Behaviour change:** earlier releases always sent the granted scopes on refresh. If your provider requires `scope` on refresh (e.g. Azure AD v2), you now need to set it:
+
+```rust,ignore
+auth_manager.set_refresh_scopes(["https://graph.microsoft.com/.default", "offline_access"]);
+```
+
+- Only scopes from the original grant are sent.
+- If none of the scopes you set are in the original grant, refresh fails with `AuthError::TokenRefreshFailed` instead of leaving `scope` out, since that would hand back the full grant.
+- A refresh never shrinks the stored grant, even when the provider returns a narrower access token.
+
 ## Security Considerations
 
 - **PKCE S256 always enforced**: never falls back to `plain` or no challenge. OAuth 2.1 mandates S256 as Mandatory To Implement for servers.