From 74e8445529c7cc64d0f858878b7d39ca42e06f00 Mon Sep 17 00:00:00 2001 From: John Coffey Date: Fri, 30 Oct 2026 14:28:33 -0700 Subject: [PATCH] exchange-graph: app-only sign-in with --app-only The app signs in as itself with its client secret (client credentials, scope .default) and reads the mailbox --user names, so a whole tenant moves in a plan with no one signing in. --app-only needs --user and a real tenant, and reads $INBUXA_MIGRATE_CLIENT_SECRET or prompts. The token has no refresh token; the refresher signs in again before it runs out. Token requests share one retrying helper with refresh. A plan's clientSecret now also sets INBUXA_MIGRATE_CLIENT_SECRET, so it reaches Graph as well as EWS. --- CHANGELOG.md | 7 + docs/usage.md | 27 +++- src/cli.rs | 64 +++++++++ src/exchange_graph/oauth.rs | 48 ++++++- src/migrate/plan.rs | 38 ++++++ src/sync/import_exchange_graph/coordinator.rs | 58 ++++++-- tests/mock_exchange_graph.rs | 129 ++++++++++++++++++ 7 files changed, 351 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d2aea92..51a3707 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ candidates before a series ships (`27.1-rc.1`). The tag is the version with a ## [Unreleased] +### Added +- `import exchange-graph --app-only` signs in as the app itself, with its + client secret, and reads the mailbox `--user` names. With an Entra app + granted application permissions, a whole Microsoft 365 tenant moves in a + plan with no one signing in. The token is renewed before it runs out. A + plan's `clientSecret` now reaches Graph as well as EWS. + ## [27.1-rc.5] The fifth release candidate of the 27.1 series: the guided mode. A move diff --git a/docs/usage.md b/docs/usage.md index e44ca39..ea89afc 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -208,7 +208,7 @@ For Exchange Online, use `exchange-graph` instead. Microsoft is retiring EWS in ``` inbuxa-migrate import exchange-graph \ - (--client-id [--tenant ] | --access-token [TOKEN]) \ + (--client-id [--tenant ] [--app-only] | --access-token [TOKEN]) \ [--user ] \ [--mailbox-kind primary|archive] \ [--objects mail,calendar,contacts] \ @@ -220,6 +220,24 @@ inbuxa-migrate import exchange-graph \ Imports a mailbox from Exchange Online through Microsoft Graph. Without `--access-token` it signs in with the interactive device-code flow. `public-folders` is rejected here: Graph does not expose public folders, so they can only be imported with `exchange-ews`, which for Exchange Online is subject to the retirement described above. +With `--app-only` the app signs in as itself, with its client secret, and +reads the mailbox `--user` names. No one signs in, so a whole tenant moves +with one app, in a [plan](#migrate-many-accounts) with `--user {email}`. + +- **The app.** Register it in Microsoft Entra, add a client secret, and + grant it these Microsoft Graph *application* permissions with admin + consent: `User.Read.All`, `Mail.Read`, `MailboxSettings.Read`, + `Calendars.Read` and `Contacts.Read`, and `Files.Read.All` for files. + To keep it to some mailboxes, scope it with Exchange Online's RBAC for + Applications or an application access policy. +- **The tenant.** `--tenant` names it, as its id or + `name.onmicrosoft.com`; the shared `common` and `organizations` are + refused. +- **The secret** is read from `$INBUXA_MIGRATE_CLIENT_SECRET`, or asked + for. In a plan, the step names it as `clientSecret`. +- Its token lasts about an hour and is renewed the same way before it + runs out. + ## Export ``` @@ -598,15 +616,16 @@ account, the state a later run resumes from, and the report. for the users that `export-directory` wrote. - **Secrets stay out of the plan.** A step names the environment variable that holds each secret it needs: `password`, `token`, `clientSecret` - (EWS) or `graphToken`. A step sees only the secrets it names. A plan that + (EWS, or Graph with `--app-only`) or `graphToken`. A step sees only the secrets it names. A plan that writes a password or token into `args` is refused. A step that needs a secret it doesn't name fails at once instead of waiting for a prompt. - **Signing in for each account.** Each step signs in the way its command does, so the plan decides how. To avoid collecting every user's password, use a login that can act for each account. The example uses Dovecot's master user, `{email}*master`. Use the source's own form where it has - one: Exchange impersonation through `--mailbox {email}`, or an - administrator on a JMAP source with `--account-name {email}`. + one: Exchange impersonation through `--mailbox {email}`, a Graph app + with `--app-only --user {email}`, or an administrator on a JMAP source + with `--account-name {email}`. - **One account at a time, several at once.** `--parallel` (default 4) sets how many accounts run at the same time. Each step runs as its own process. Its output goes to `//.log`, and one account diff --git a/src/cli.rs b/src/cli.rs index 746418a..f1d417e 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -1702,6 +1702,14 @@ pub struct ExchangeGraphImportArgs { )] access_token: Option>, + #[arg( + long, + conflicts_with = "access_token", + requires = "user", + help = "Sign in as the app itself, with its client secret ($INBUXA_MIGRATE_CLIENT_SECRET or prompt), and read the mailbox --user names; needs --tenant" + )] + app_only: bool, + #[arg( long, value_name = "LIST", @@ -1801,6 +1809,7 @@ fn resolve_exchange_graph_import(args: ExchangeGraphImportArgs) -> Result>, client_id: Option<&str>, tenant: &str, + app_only: bool, ) -> Result { if let Some(slot) = access_token { let token = secret::resolve( @@ -1854,6 +1864,22 @@ fn resolve_graph_auth( })? .to_owned(); let authority = crate::exchange_graph::oauth::default_authority(tenant); + if app_only { + // An app signs in to one tenant: the shared authorities are for + // people choosing theirs. + if ["common", "organizations", "consumers"].contains(&tenant.to_ascii_lowercase().as_str()) + { + return Err(Error::Usage( + "--app-only needs the tenant: --tenant ".to_owned(), + )); + } + let client_secret = secret::resolve(None, "INBUXA_MIGRATE_CLIENT_SECRET", "client secret")?; + return Ok(GraphAuth::ClientCredentials { + authority, + client_id, + client_secret, + }); + } Ok(GraphAuth::DeviceCode { authority, client_id, @@ -2044,4 +2070,42 @@ mod tests { other => panic!("expected Usage error, got {:?}", other.map(|_| ())), } } + + #[test] + fn graph_app_only_needs_a_tenant_and_a_mailbox_and_reads_its_secret() { + let _g = lock(); + let parse = |extra: &[&str]| { + let mut argv = vec![ + "inbuxa-migrate", + "import", + "exchange-graph", + "--client-id", + "app-1", + "--app-only", + ]; + argv.extend_from_slice(extra); + argv.push("archive.sqlite"); + Cli::try_parse_from(argv) + }; + assert!(parse(&["--tenant", "contoso.onmicrosoft.com"]).is_err()); + assert!(parse(&["--user", "a@x", "--access-token", "t"]).is_err()); + let cli = parse(&["--user", "a@x"]).unwrap(); + match cli.resolve() { + Err(Error::Usage(m)) => assert!(m.contains("--tenant"), "{m}"), + _ => panic!("the shared authority is refused"), + } + unsafe { env::set_var("INBUXA_MIGRATE_CLIENT_SECRET", "s3cret") }; + let resolved = parse(&["--user", "a@x", "--tenant", "contoso.onmicrosoft.com"]) + .unwrap() + .resolve(); + unsafe { env::remove_var("INBUXA_MIGRATE_CLIENT_SECRET") }; + match resolved { + Ok(Action::ImportExchangeGraph(_, config)) => assert!(matches!( + config.auth, + GraphAuth::ClientCredentials { ref authority, ref client_secret, .. } + if client_secret == "s3cret" && authority.ends_with("/contoso.onmicrosoft.com") + )), + _ => panic!("expected an app-only exchange-graph import"), + } + } } diff --git a/src/exchange_graph/oauth.rs b/src/exchange_graph/oauth.rs index e5e698d..078776d 100644 --- a/src/exchange_graph/oauth.rs +++ b/src/exchange_graph/oauth.rs @@ -18,6 +18,9 @@ use crate::net::{tls, with_timeouts}; pub const SCOPES: &str = "offline_access User.Read Mail.Read MailboxSettings.Read Calendars.Read Contacts.Read"; +/// App-only: the application permissions an administrator granted the app. +pub const APP_ONLY_SCOPE: &str = "https://graph.microsoft.com/.default"; + const JWT_SEGMENT: Base64 = URL_SAFE.with_padding(Padding::Optional).any_alphabet(); pub fn default_authority(tenant: &str) -> String { @@ -41,6 +44,11 @@ pub enum OAuthFlow { authority: String, client_id: String, }, + ClientCredentials { + authority: String, + client_id: String, + client_secret: String, + }, } #[derive(Debug, Clone, Default)] @@ -96,6 +104,11 @@ pub fn acquire(flow: &OAuthFlow) -> Result { authority, client_id, } => device_code_flow(authority, client_id), + OAuthFlow::ClientCredentials { + authority, + client_id, + client_secret, + } => client_credentials(authority, client_id, client_secret), } } @@ -286,20 +299,40 @@ pub fn refresh_access_token( client_id: &str, refresh_token: &str, ) -> Result { - let agent = build_agent(); let body = form_encode(&[ ("client_id", client_id), ("grant_type", "refresh_token"), ("refresh_token", refresh_token), ("scope", SCOPES), ]); - let endpoint = token_endpoint(authority); + token_request(&token_endpoint(authority), &body, "refresh") +} + +/// A token for the app itself, from its client secret. It carries no +/// refresh token: a new one is asked for the same way before it expires. +pub fn client_credentials( + authority: &str, + client_id: &str, + client_secret: &str, +) -> Result { + let body = form_encode(&[ + ("client_id", client_id), + ("client_secret", client_secret), + ("grant_type", "client_credentials"), + ("scope", APP_ONLY_SCOPE), + ]); + token_request(&token_endpoint(authority), &body, "app-only sign-in") +} + +/// POSTs a token request, retrying a dropped connection or a 5xx. +fn token_request(endpoint: &str, body: &str, what: &str) -> Result { + let agent = build_agent(); let mut delay = Duration::from_millis(500); let mut attempts: u32 = 0; loop { attempts += 1; let send = agent - .post(&endpoint) + .post(endpoint) .header("Content-Type", "application/x-www-form-urlencoded") .send(body.as_bytes()); let mut resp = match send { @@ -307,10 +340,10 @@ pub fn refresh_access_token( Err(e) if attempts < 4 => { std::thread::sleep(delay); delay = (delay * 2).min(Duration::from_secs(8)); - eprintln!("graph token refresh transport error: {e}; retrying"); + eprintln!("graph {what} transport error: {e}; retrying"); continue; } - Err(e) => return Err(GraphError::OAuth(format!("refresh endpoint: {e}"))), + Err(e) => return Err(GraphError::OAuth(format!("{what} endpoint: {e}"))), }; let status = resp.status().as_u16(); let payload: Value = resp.body_mut().read_json().unwrap_or(Value::Null); @@ -321,8 +354,11 @@ pub fn refresh_access_token( } return match parse_token_response(status, &payload) { TokenResponse::Ok(t) => Ok(t), + TokenResponse::Other { error, description } => Err(GraphError::OAuth(format!( + "{what} failed (http {status}): {error}: {description}" + ))), other => Err(GraphError::OAuth(format!( - "refresh failed (http {status}): {other:?}" + "{what} failed (http {status}): {other:?}" ))), }; } diff --git a/src/migrate/plan.rs b/src/migrate/plan.rs index d03f714..1482a51 100644 --- a/src/migrate/plan.rs +++ b/src/migrate/plan.rs @@ -28,6 +28,7 @@ pub const SECRET_VARS: &[&str] = &[ "INBUXA_MIGRATE_API_KEY", "INBUXA_MIGRATE_TOKEN", "INBUXA_MIGRATE_EWS_CLIENT_SECRET", + "INBUXA_MIGRATE_CLIENT_SECRET", "INBUXA_MIGRATE_GRAPH_TOKEN", ]; @@ -218,6 +219,14 @@ fn step_of(raw: RawStep, per_account: bool, names: &mut HashSet) -> Resu } } } + // A client secret is EWS's or Graph's, by the step's command; each + // reads its own variable. + if let Some((_, value)) = env + .iter() + .find(|(var, _)| *var == "INBUXA_MIGRATE_EWS_CLIENT_SECRET") + { + env.push(("INBUXA_MIGRATE_CLIENT_SECRET", value.clone())); + } Ok(Step { name, args: raw.args, @@ -369,6 +378,35 @@ mod tests { .unwrap(); } + #[test] + fn a_client_secret_reaches_ews_and_graph_alike() { + unsafe { std::env::set_var("PLAN_TEST_CLIENT_SECRET", "cs") }; + let raw = RawStep { + name: "mail".into(), + args: args(&[ + "import", + "exchange-graph", + "--app-only", + "--user", + "{email}", + "{archive}", + ]), + secrets: Secrets { + client_secret: Some("PLAN_TEST_CLIENT_SECRET".into()), + ..Secrets::default() + }, + }; + let step = step_of(raw, true, &mut HashSet::new()).unwrap(); + let vars: Vec<_> = step.env.iter().map(|(v, s)| (*v, s.as_str())).collect(); + assert_eq!( + vars, + [ + ("INBUXA_MIGRATE_EWS_CLIENT_SECRET", "cs"), + ("INBUXA_MIGRATE_CLIENT_SECRET", "cs") + ] + ); + } + #[test] fn steps_run_the_commands_they_are_for() { let e = err(&["import-directory", "dir"], true); diff --git a/src/sync/import_exchange_graph/coordinator.rs b/src/sync/import_exchange_graph/coordinator.rs index b3c5b25..a163078 100644 --- a/src/sync/import_exchange_graph/coordinator.rs +++ b/src/sync/import_exchange_graph/coordinator.rs @@ -15,7 +15,7 @@ use crate::exchange_graph::api::{DEFAULT_API_BASE, Endpoints}; use crate::exchange_graph::client::GraphClient; use crate::exchange_graph::error::GraphError; use crate::exchange_graph::oauth::{ - AcquiredToken, OAuthFlow, acquire, default_authority, refresh_access_token, + AcquiredToken, OAuthFlow, acquire, client_credentials, default_authority, refresh_access_token, }; use crate::exchange_graph::types::{EventBodyFormat, MailboxKind, Surfaces, synthetic_account_id}; use crate::jmap::http::RetryPolicy; @@ -32,6 +32,13 @@ pub enum GraphAuth { authority: String, client_id: String, }, + /// The app signs in as itself, with what an administrator granted it, + /// and reads the mailbox `user_target` names. + ClientCredentials { + authority: String, + client_id: String, + client_secret: String, + }, } #[derive(Debug, Clone)] @@ -67,6 +74,11 @@ pub struct GraphCoordinator<'a> { pub fn run(common: CommonConfig, config: GraphImportConfig) -> Result { let logger = common.logger; + if matches!(config.auth, GraphAuth::ClientCredentials { .. }) && config.user_target.is_none() { + return Err(Error::Usage( + "app-only sign-in has no mailbox of its own: name one with --user".to_owned(), + )); + } let mut conn = db::init::open(&common.archive)?; let acquired = acquire_with_flow(&config.auth)?; @@ -289,6 +301,15 @@ fn acquire_with_flow(auth: &GraphAuth) -> Result { authority: authority.clone(), client_id: client_id.clone(), }, + GraphAuth::ClientCredentials { + authority, + client_id, + client_secret, + } => OAuthFlow::ClientCredentials { + authority: authority.clone(), + client_id: client_id.clone(), + client_secret: client_secret.clone(), + }, }; acquire(&flow).map_err(Error::from) } @@ -360,7 +381,8 @@ fn resolve_principal( fn canonical_session_url(config: &GraphImportConfig) -> String { let authority = match &config.auth { - GraphAuth::DeviceCode { authority, .. } => authority.clone(), + GraphAuth::DeviceCode { authority, .. } + | GraphAuth::ClientCredentials { authority, .. } => authority.clone(), GraphAuth::PreAcquired { .. } => default_authority("common"), }; format!( @@ -376,17 +398,36 @@ fn spawn_token_refresher( initial: &AcquiredToken, logger: crate::logging::Logger, ) -> Option { - let (authority, client_id) = match auth { + // A delegated token is renewed with its refresh token, which may be + // replaced each time; an app-only one by signing in again. + let mut renew: Box Result + Send> = match auth { GraphAuth::DeviceCode { authority, client_id, - } => (authority.clone(), client_id.clone()), + } => { + let (authority, client_id) = (authority.clone(), client_id.clone()); + let mut refresh_token = initial.refresh_token.clone()?; + Box::new(move || { + let tok = refresh_access_token(&authority, &client_id, &refresh_token)?; + if let Some(new_refresh) = &tok.refresh_token { + refresh_token.clone_from(new_refresh); + } + Ok(tok) + }) + } + GraphAuth::ClientCredentials { + authority, + client_id, + client_secret, + } => { + let (authority, client_id, client_secret) = + (authority.clone(), client_id.clone(), client_secret.clone()); + Box::new(move || client_credentials(&authority, &client_id, &client_secret)) + } GraphAuth::PreAcquired { .. } => return None, }; - let refresh = initial.refresh_token.clone()?; let mut deadline_unix = initial_deadline_unix(initial)?; let client = client.clone(); - let mut refresh_token = refresh; let shutdown = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)); let shutdown_signal = shutdown.clone(); let handle = std::thread::Builder::new() @@ -410,12 +451,9 @@ fn spawn_token_refresher( break; } } - match refresh_access_token(&authority, &client_id, &refresh_token) { + match renew() { Ok(tok) => { client.set_bearer(tok.access_token.clone()); - if let Some(new_refresh) = tok.refresh_token { - refresh_token = new_refresh; - } deadline_unix = unix_now() + tok.expires_in.unwrap_or_else(|| { crate::exchange_graph::oauth::decode_jwt_claims(&tok.access_token) diff --git a/tests/mock_exchange_graph.rs b/tests/mock_exchange_graph.rs index ab7a6b1..645fba1 100644 --- a/tests/mock_exchange_graph.rs +++ b/tests/mock_exchange_graph.rs @@ -3021,3 +3021,132 @@ fn contact_photo_categories_and_im_addresses_are_imported() { "the type is sniffed from the bytes, not taken from Graph's jpeg header" ); } + +#[test] +fn app_only_signs_in_as_the_app_and_reads_the_named_mailbox() { + let mut server = Server::new(); + let token = make_jwt(9999999999, ""); + let _token = server + .mock("POST", "/contoso.example/oauth2/v2.0/token") + .match_body(Matcher::AllOf(vec![ + Matcher::Regex("grant_type=client_credentials".to_owned()), + Matcher::Regex("client_id=app-1".to_owned()), + Matcher::Regex("client_secret=s3cret".to_owned()), + Matcher::Regex(r"scope=https%3A%2F%2Fgraph\.microsoft\.com%2F\.default".to_owned()), + ])) + .with_status(200) + .with_header("content-type", "application/json") + .with_body(json!({"access_token": token, "expires_in": 3599}).to_string()) + .expect(1) + .create(); + let bearer = format!("Bearer {token}"); + let get = |server: &mut Server, path: &str, body: &str| { + server + .mock("GET", path) + .match_header("authorization", bearer.as_str()) + .with_status(200) + .with_header("content-type", "application/json") + .with_body(body) + .create() + }; + let mut mocks = vec![ + get( + &mut server, + "/users/alice@x.com?$select=id,userPrincipalName", + r#"{"id":"uid-1","userPrincipalName":"alice@x.com"}"#, + ), + get( + &mut server, + "/users/uid-1?$select=id,userPrincipalName,displayName,mail", + r#"{"id":"uid-1","userPrincipalName":"alice@x.com"}"#, + ), + get( + &mut server, + "/users/uid-1/mailFolders?$top=100&includeHiddenFolders=true", + r#"{"value":[{"id":"FMAIL","displayName":"Inbox","isHidden":false}]}"#, + ), + get( + &mut server, + "/users/uid-1/mailFolders/FMAIL/childFolders?$top=100&includeHiddenFolders=true", + r#"{"value":[]}"#, + ), + get( + &mut server, + "/users/uid-1/mailFolders/FMAIL/messages?$top=100&$select=id,isRead,isDraft,isReadReceiptRequested,flag,categories", + r#"{"value":[{"id":"MSG-1"}]}"#, + ), + ]; + for name in [ + "inbox", + "drafts", + "sentitems", + "deleteditems", + "junkemail", + "archive", + ] { + let body = if name == "inbox" { + r#"{"id":"FMAIL"}"# + } else { + r#"{"id":"OTHER"}"# + }; + mocks.push(get( + &mut server, + &format!("/users/uid-1/mailFolders/{name}?$select=id"), + body, + )); + } + let _value = server + .mock("GET", "/users/uid-1/messages/MSG-1/$value") + .match_header("authorization", bearer.as_str()) + .with_status(200) + .with_header("content-type", "text/plain") + .with_body("From: a@x\r\nTo: b@x\r\nSubject: hi\r\nMessage-ID: \r\n\r\nhello") + .create(); + + let tmp = tempfile::NamedTempFile::new().unwrap(); + let archive = tmp.path().to_owned(); + let common = || inbuxa_migrate::sync::CommonConfig { + archive: archive.clone(), + threads: 2, + dry_run: false, + max_retries: 0, + allow_invalid_certs: false, + logger: inbuxa_migrate::logging::Logger::new(0), + }; + let auth = inbuxa_migrate::sync::import_exchange_graph::GraphAuth::ClientCredentials { + authority: format!("{}/contoso.example", server.url()), + client_id: "app-1".to_owned(), + client_secret: "s3cret".to_owned(), + }; + let mut config = inbuxa_migrate::sync::import_exchange_graph::GraphImportConfig { + auth, + api_base: server.url(), + user_target: None, + mailbox_kind: inbuxa_migrate::exchange_graph::types::MailboxKind::Primary, + surfaces: surfaces("mail"), + event_body_format: inbuxa_migrate::exchange_graph::types::EventBodyFormat::Text, + graph_connections: 2, + top: 100, + exception_window_years: 5, + contact_photos: false, + event_attachments: true, + allow_source_change: false, + }; + + // The app has no mailbox of its own. + let err = inbuxa_migrate::sync::import_exchange_graph::run(common(), config.clone()) + .unwrap_err() + .to_string(); + assert!(err.contains("--user"), "{err}"); + + config.user_target = Some("alice@x.com".to_owned()); + drop(tmp); + let summary = inbuxa_migrate::sync::import_exchange_graph::run(common(), config).unwrap(); + let emails = summary + .per_type + .iter() + .find(|(t, _)| *t == "email") + .map_or(0, |(_, c)| c.created); + assert_eq!(emails, 1); + _token.assert(); +} -- 2.54.0