diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d42a29..a1f85e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ candidates before a series ships (`27.1-rc.1`). The tag is the version with a names. A whole Workspace domain moves in a plan with one key and no one's password. The JWT is signed with the key itself (RS256), and each connection takes a fresh token when the last is close to running out. +- The guide offers Microsoft 365 (an Entra app, app-only) and Google + Workspace (a service account) as sources. Its check signs the app in and + names any permission it lacks, or asks Google for a token for the first + account. ## [27.1-rc.5] diff --git a/docs/usage.md b/docs/usage.md index 75a7ff9..e54c1fe 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -679,10 +679,14 @@ browser. `guide` serves a page on 127.0.0.1 from the binary itself and opens it. The page asks five things in turn: 1. **Where the mail is now:** an IMAP server, a JMAP server (Stalwart or - inbuxa), or Maildir folders on this machine. It also asks for a login - that can act for every account. On IMAP that's a master user, such as - Dovecot's `{email}*master`. On JMAP it's an administrator, with a - password or an API key. + inbuxa), Maildir folders on this machine, Microsoft 365 or Google + Workspace. It also asks for a login that can act for every account. On + IMAP that's a master user, such as Dovecot's `{email}*master`. On JMAP + it's an administrator, with a password or an API key. On Microsoft 365 + it's an Entra app with application permissions (`--app-only`), and on + Google Workspace a service account's key (`--google-key`). Check signs + the app in and says which permissions it lacks, or asks Google for a + token for the first account. 2. **Which accounts:** pasted one per line or as a CSV, or read from a JMAP server's account list. The list can be edited before anything runs. 3. **Where to:** the inbuxa server and an administrator's API key, and diff --git a/src/exchange_graph/oauth.rs b/src/exchange_graph/oauth.rs index 078776d..458ff66 100644 --- a/src/exchange_graph/oauth.rs +++ b/src/exchange_graph/oauth.rs @@ -57,6 +57,8 @@ pub struct JwtClaims { pub upn: Option, pub name: Option, pub exp: Option, + /// An app-only token's application permissions, such as `Mail.Read`. + pub roles: Vec, } pub fn decode_jwt_claims(token: &str) -> Option { @@ -73,6 +75,14 @@ pub fn decode_jwt_claims(token: &str) -> Option { .or_else(|| value.get("preferred_username").and_then(Value::as_str)) .map(str::to_owned), name: value.get("name").and_then(Value::as_str).map(str::to_owned), + roles: value + .get("roles") + .and_then(Value::as_array) + .into_iter() + .flatten() + .filter_map(Value::as_str) + .map(str::to_owned) + .collect(), exp: value.get("exp").and_then(Value::as_u64), }) } @@ -461,6 +471,20 @@ mod tests { assert_eq!(claims.exp, Some(9999999999)); } + #[test] + fn an_app_only_tokens_roles_are_its_permissions() { + let claims = r#"{"tid":"t-1","roles":["Mail.Read","User.Read.All"]}"#; + let token = format!("h.{}.", URL_SAFE_NO_PAD.encode(claims.as_bytes())); + let roles = decode_jwt_claims(&token).unwrap().roles; + assert_eq!(roles, ["Mail.Read", "User.Read.All"]); + assert!( + decode_jwt_claims(&make_jwt("t", "u", 1)) + .unwrap() + .roles + .is_empty() + ); + } + #[test] fn jwt_payload_decodes_in_either_alphabet_with_or_without_padding() { let claims = r#"{"tid":"t-3","upn":"??>>@xy","exp":1}"#; diff --git a/src/guide/form.rs b/src/guide/form.rs index b03cf5b..9e8b4f8 100644 --- a/src/guide/form.rs +++ b/src/guide/form.rs @@ -21,6 +21,7 @@ pub const SOURCE_SECRET_VAR: &str = "MIGRATE_SOURCE_SECRET"; pub const TARGET_TOKEN_VAR: &str = "MIGRATE_INBUXA_TOKEN"; /// The directory the setup step reads, relative to the guide's directory. pub const DIRECTORY: &str = "directory"; +const GMAIL_IMAP: &str = "imaps://imap.gmail.com"; #[derive(Deserialize, Serialize, Clone, Default)] #[serde(rename_all = "camelCase", default)] @@ -40,6 +41,18 @@ pub enum SourceKind { Imap, Jmap, Maildir, + /// Microsoft 365, through Graph, as an app with application permissions. + Microsoft, + /// Google Workspace's Gmail, as a service account with domain-wide + /// delegation. + Google, +} + +impl SourceKind { + /// Whether the source signs in with a secret typed into the page. + fn has_secret(self) -> bool { + matches!(self, Self::Imap | Self::Jmap | Self::Microsoft) + } } #[derive(Deserialize, Serialize, Clone, Default)] @@ -55,6 +68,12 @@ pub struct Source { pub path: String, /// IMAP: credentials on `imap://` without STARTTLS. pub cleartext: bool, + /// Microsoft 365: the Entra tenant and the app's client id. + pub tenant: String, + pub client_id: String, + /// Google: the service account's JSON key file. + pub key_file: String, + /// The password, API key or client secret. #[serde(skip_serializing)] pub secret: String, } @@ -71,7 +90,7 @@ impl Form { /// The secrets a run needs, by variable. pub fn env(&self) -> Vec<(&'static str, String)> { let mut env = vec![(TARGET_TOKEN_VAR, self.target.token.clone())]; - if self.source.kind != SourceKind::Maildir { + if self.source.kind.has_secret() { env.push((SOURCE_SECRET_VAR, self.source.secret.clone())); } env @@ -103,10 +122,22 @@ impl Form { SourceKind::Maildir if !names_account(&s.path) => { return Err("The Maildir path has to name the account: {email} or {local}.".into()); } + SourceKind::Microsoft + if s.tenant.trim().is_empty() || s.client_id.trim().is_empty() => + { + return Err("Give the Microsoft 365 tenant and the app's client id.".into()); + } + SourceKind::Google if s.key_file.trim().is_empty() => { + return Err("Give the service account's key file.".into()); + } _ => {} } - if s.kind != SourceKind::Maildir && s.secret.is_empty() { - return Err("Give the old server's password or API key.".into()); + if s.kind.has_secret() && s.secret.is_empty() { + return Err(if s.kind == SourceKind::Microsoft { + "Give the app's client secret.".into() + } else { + "Give the old server's password or API key.".into() + }); } if self.accounts.is_empty() { return Err("List the accounts to move.".into()); @@ -143,6 +174,16 @@ impl Form { args.extend(["--account-name", "{email}"]); } SourceKind::Maildir => args.extend(["import", "maildir", s.path.trim()]), + SourceKind::Microsoft => { + args.extend(["import", "exchange-graph", "--tenant", s.tenant.trim()]); + args.extend(["--client-id", s.client_id.trim(), "--app-only"]); + args.extend(["--user", "{email}"]); + secrets = json!({"clientSecret": SOURCE_SECRET_VAR}); + } + SourceKind::Google => { + args.extend(["import", "imap", "--url", GMAIL_IMAP]); + args.extend(["--google-key", s.key_file.trim(), "--auth-user", "{email}"]); + } } args.push("{archive}"); json!({"name": "import", "args": args, "secrets": secrets}) @@ -305,6 +346,9 @@ mod tests { login: "{email}*master".into(), path: "/var/vmail/{domain}/{local}/Maildir".into(), cleartext: false, + tenant: String::new(), + client_id: String::new(), + key_file: String::new(), secret: "s3cret".into(), }, accounts: vec!["ann@example.org".into()], @@ -388,6 +432,55 @@ mod tests { assert_eq!(f.env(), [(TARGET_TOKEN_VAR, "t0ken".to_owned())]); } + #[test] + fn microsoft_365_reads_as_the_app_and_google_as_the_service_account() { + let mut f = form(SourceKind::Microsoft); + f.source.tenant = "contoso.onmicrosoft.com".into(); + f.source.client_id = "app-1".into(); + let step = &f.plan("p.csv")["steps"][0]; + assert_eq!( + step["args"], + json!([ + "import", + "exchange-graph", + "--tenant", + "contoso.onmicrosoft.com", + "--client-id", + "app-1", + "--app-only", + "--user", + "{email}", + "{archive}" + ]) + ); + assert_eq!(step["secrets"]["clientSecret"], SOURCE_SECRET_VAR); + f.source.tenant.clear(); + assert!(f.check().unwrap_err().contains("tenant")); + + let mut f = form(SourceKind::Google); + f.source.secret.clear(); + assert!(f.check().unwrap_err().contains("key file")); + f.source.key_file = "/keys/sa.json".into(); + assert_eq!(f.check(), Ok(())); + let step = &f.plan("p.csv")["steps"][0]; + assert_eq!( + step["args"], + json!([ + "import", + "imap", + "--url", + "imaps://imap.gmail.com", + "--google-key", + "/keys/sa.json", + "--auth-user", + "{email}", + "{archive}" + ]) + ); + assert_eq!(step["secrets"], json!({})); + assert_eq!(f.env(), [(TARGET_TOKEN_VAR, "t0ken".to_owned())]); + } + #[test] fn a_form_that_cant_make_a_plan_says_why() { let mut f = form(SourceKind::Imap); diff --git a/src/guide/mod.rs b/src/guide/mod.rs index 94efd3e..f5384be 100644 --- a/src/guide/mod.rs +++ b/src/guide/mod.rs @@ -358,6 +358,28 @@ impl Guide { "ok": true, "message": "The preview signs in for each account and shows any that fail.", }), + SourceKind::Microsoft => check_microsoft(f), + SourceKind::Google => self.check_google(f), + } + } + + /// Asks Google for a token for the first account, as each run will. + fn check_google(&self, f: &Form) -> Value { + use crate::google::{MAIL_SCOPE, ServiceAccount}; + let path = self.dir.join(f.source.key_file.trim()); + let account = match ServiceAccount::load(&path) { + Ok(a) => a, + Err(e) => return json!({ "ok": false, "message": e.to_string() }), + }; + let Some(first) = f.accounts.first() else { + return json!({ "ok": false, "message": format!( + "The key is {}'s. List the accounts, and the guide will try the first.", + account.client_email()) }); + }; + match account.token_for(first, MAIL_SCOPE) { + Ok(_) => json!({ "ok": true, "message": format!( + "Google lets {} act for {first}.", account.client_email()) }), + Err(e) => json!({ "ok": false, "message": e.to_string() }), } } @@ -602,6 +624,51 @@ fn check_target(f: &Form) -> Value { } } +/// Signs the app in: what it can read shows in its token's roles. +fn check_microsoft(f: &Form) -> Value { + use crate::exchange_graph::oauth; + let s = &f.source; + if s.tenant.trim().is_empty() || s.client_id.trim().is_empty() || s.secret.is_empty() { + return json!({ "ok": false, + "message": "Give the tenant, the app's client id and its client secret." }); + } + let authority = oauth::default_authority(s.tenant.trim()); + match oauth::client_credentials(&authority, s.client_id.trim(), &s.secret) { + Err(e) => json!({ "ok": false, "message": format!("The app couldn't sign in: {e}") }), + Ok(token) => { + let roles = oauth::decode_jwt_claims(&token.access_token) + .map(|c| c.roles) + .unwrap_or_default(); + // Each need, and the permissions that cover it. + let needs: [(&str, &[&str]); 2] = [ + ( + "User.Read.All", + &[ + "User.Read.All", + "User.ReadWrite.All", + "Directory.Read.All", + "Directory.ReadWrite.All", + ], + ), + ("Mail.Read", &["Mail.Read", "Mail.ReadWrite"]), + ]; + let missing: Vec<&str> = needs + .iter() + .filter(|(_, any)| !roles.iter().any(|have| any.contains(&have.as_str()))) + .map(|(need, _)| *need) + .collect(); + if missing.is_empty() { + json!({ "ok": true, "message": format!( + "The app signed in to {} and may read: {}.", s.tenant.trim(), roles.join(", ")) }) + } else { + json!({ "ok": false, "message": format!( + "The app signed in, but it hasn't been granted {}. Add them as application \ + permissions and grant admin consent.", missing.join(" and ")) }) + } + } + } +} + /// The passwords file the last setup wrote, if it wrote one. fn newest_passwords(dir: &Path) -> Option { fs::read_dir(dir) diff --git a/src/guide/page/guide.js b/src/guide/page/guide.js index b68baf6..3e6148e 100644 --- a/src/guide/page/guide.js +++ b/src/guide/page/guide.js @@ -15,6 +15,7 @@ function showKind() { for (const el of document.querySelectorAll("[data-kind]")) { el.hidden = !el.dataset.kind.split(" ").includes(k); } + $("src-secret-label").textContent = k === "microsoft" ? "Client secret" : "Password or API key"; } function lines(text) { @@ -30,6 +31,9 @@ function form() { login: k === "imap" ? $("src-imap-login").value.trim() : $("src-jmap-login").value.trim(), path: $("src-path").value.trim(), cleartext: $("src-cleartext").checked, + tenant: $("src-tenant").value.trim(), + clientId: $("src-client-id").value.trim(), + keyFile: $("src-key-file").value.trim(), secret: $("src-secret").value, }, accounts: lines($("accounts").value), @@ -69,7 +73,7 @@ async function checkAccounts() { async function check(path, statusId) { try { - if (statusId === "source-status" && kind() === "maildir") await checkAccounts(); + if (statusId === "source-status" && ["maildir", "google"].includes(kind())) await checkAccounts(); const r = await call(path, { form: form() }); status(statusId, r.ok, r.message); await refresh(); @@ -206,6 +210,9 @@ async function load() { if (f.source.kind === "jmap") $("src-jmap-login").value = f.source.login || ""; if (f.source.path) $("src-path").value = f.source.path; $("src-cleartext").checked = !!f.source.cleartext; + $("src-tenant").value = f.source.tenant || ""; + $("src-client-id").value = f.source.clientId || ""; + $("src-key-file").value = f.source.keyFile || ""; $("accounts").value = (f.accounts || []).join("\n"); $("create").checked = f.create || !f.target.url; $("dst-url").value = f.target.url || ""; diff --git a/src/guide/page/index.html b/src/guide/page/index.html index 60b5525..23f421e 100644 --- a/src/guide/page/index.html +++ b/src/guide/page/index.html @@ -26,6 +26,8 @@ + +
@@ -44,10 +46,26 @@

An administrator can read the account list and act for each account. Leave this empty to sign in with an API key instead of a password.

-
- +
+ + +

An app registered in Microsoft Entra reads every mailbox, so no one signs in. + Give it a client secret and these Microsoft Graph application permissions, with + admin consent: User.Read.All, Mail.Read, + MailboxSettings.Read, Calendars.Read and Contacts.Read. + Check tells you if any are missing.

+
+
+
+
+ +

A service account acts for each user, so no one hands over a password. + Create one and a JSON key for it in Google Cloud, then in the Admin console allow its + client id domain-wide delegation for https://mail.google.com/. Keep the key + file to yourself, and delete the key once the move is done. This moves the mail.

+

Dovecot keeps one Maildir per account. {domain} and diff --git a/tests/integration/google.rs b/tests/integration/google.rs new file mode 100644 index 0000000..3a71e5c --- /dev/null +++ b/tests/integration/google.rs @@ -0,0 +1,32 @@ +/* + * SPDX-FileCopyrightText: 2026 Coffey Labs LLC + * + * SPDX-License-Identifier: Apache-2.0 OR MIT + */ + +//! A Google service account's key, made for the test, so no real key is +//! ever in the repository. + +/// A service account's JSON key for a new RSA key, with the token +/// endpoint at `token_uri`, and the key's public half. +pub fn service_account_key(token_uri: &str) -> (String, Vec) { + use aws_lc_rs::encoding::{AsDer, Pkcs8V1Der}; + use aws_lc_rs::signature::KeyPair as _; + let pair = aws_lc_rs::rsa::KeyPair::generate(aws_lc_rs::rsa::KeySize::Rsa2048).unwrap(); + let der: Pkcs8V1Der<'static> = pair.as_der().unwrap(); + let body = encodify::base64::STANDARD.encode(der.as_ref()); + let lines: Vec<&str> = body + .as_bytes() + .chunks(64) + .map(|c| std::str::from_utf8(c).unwrap()) + .collect(); + let pem = format!( + "-----BEGIN PRIVATE KEY-----\n{}\n-----END PRIVATE KEY-----\n", + lines.join("\n") + ); + let key = serde_json::json!({ + "type": "service_account", "client_email": "migrate@proj.iam.gserviceaccount.com", + "private_key": pem, "token_uri": token_uri, + }); + (key.to_string(), pair.public_key().as_ref().to_vec()) +} diff --git a/tests/integration/mod.rs b/tests/integration/mod.rs index 6cfcfb3..38eeafb 100644 --- a/tests/integration/mod.rs +++ b/tests/integration/mod.rs @@ -13,6 +13,7 @@ pub mod data; pub mod dav_client; pub mod dovecot; pub mod error; +pub mod google; pub mod guide; pub mod imap_client; pub mod inbuxa; diff --git a/tests/mock_guide.rs b/tests/mock_guide.rs index 48140fe..200b5e3 100644 --- a/tests/mock_guide.rs +++ b/tests/mock_guide.rs @@ -166,3 +166,39 @@ fn a_closed_stdout_doesnt_end_the_guide() { let head = format!("GET /x/ HTTP/1.1\r\nHost: {}", guide.host); assert_eq!(send(&guide, &head, "").0, 404); } + +#[test] +fn the_guide_checks_a_google_key_by_asking_for_a_token() { + let mut google = mockito::Server::new(); + let (key, _) = integration::google::service_account_key(&format!("{}/token", google.url())); + let _token = google + .mock("POST", "/token") + .match_body(mockito::Matcher::Regex("assertion=".to_owned())) + .with_status(200) + .with_body(r#"{"access_token":"ya29.x","expires_in":3599}"#) + .create(); + let dir = TempDir::new().unwrap(); + fs::write(dir.path().join("sa.json"), key).unwrap(); + let guide = start(BIN, dir.path()); + let form = |key_file: &str| { + json!({"form": { + "source": {"kind": "google", "keyFile": key_file}, + "accounts": ["ann@example.org"], + }}) + }; + let (_, missing) = post(&guide, "api/check-source", &form("nope.json")); + assert_eq!(missing["ok"], false, "{missing}"); + assert!( + missing["message"].as_str().unwrap().contains("nope.json"), + "{missing}" + ); + let (_, found) = post(&guide, "api/check-source", &form("sa.json")); + assert_eq!(found["ok"], true, "{found}"); + assert!( + found["message"] + .as_str() + .unwrap() + .contains("act for ann@example.org"), + "{found}" + ); +} diff --git a/tests/mock_imap.rs b/tests/mock_imap.rs index 258c381..42b0a24 100644 --- a/tests/mock_imap.rs +++ b/tests/mock_imap.rs @@ -5,6 +5,8 @@ * SPDX-License-Identifier: Apache-2.0 OR MIT */ +mod integration; + use std::io::{BufRead, BufReader, Write}; use std::net::{TcpListener, TcpStream}; use std::path::PathBuf; @@ -2309,35 +2311,11 @@ fn append_refused_before_the_go_ahead_sends_nothing_and_keeps_the_session() { client.noop().expect("session still usable"); } -/// A service account's JSON key for a new RSA key, with the token -/// endpoint at `token_uri`, and the key's public half. -fn google_key(token_uri: &str) -> (String, Vec) { - use aws_lc_rs::encoding::{AsDer, Pkcs8V1Der}; - use aws_lc_rs::signature::KeyPair as _; - let pair = aws_lc_rs::rsa::KeyPair::generate(aws_lc_rs::rsa::KeySize::Rsa2048).unwrap(); - let der: Pkcs8V1Der<'static> = pair.as_der().unwrap(); - let body = STANDARD.encode(der.as_ref()); - let lines: Vec<&str> = body - .as_bytes() - .chunks(64) - .map(|c| std::str::from_utf8(c).unwrap()) - .collect(); - let pem = format!( - "-----BEGIN PRIVATE KEY-----\n{}\n-----END PRIVATE KEY-----\n", - lines.join("\n") - ); - let key = serde_json::json!({ - "type": "service_account", "client_email": "migrate@proj.iam.gserviceaccount.com", - "private_key": pem, "token_uri": token_uri, - }); - (key.to_string(), pair.public_key().as_ref().to_vec()) -} - #[test] fn coordinator_signs_in_to_gmail_as_a_service_account_acting_for_the_user() { let mut google = mockito::Server::new(); let token_uri = format!("{}/token", google.url()); - let (key, public) = google_key(&token_uri); + let (key, public) = integration::google::service_account_key(&token_uri); let audience = token_uri.clone(); let _token = google .mock("POST", "/token")