guide: Microsoft 365 and Google Workspace as sources #46

Merged
jcoffey-dev merged 1 commits from feat/guide-cloud-sources into main 2026-10-30 21:54:12 +00:00
11 changed files with 299 additions and 35 deletions

No files matched your search

+4
View File
@@ -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]
+8 -4
View File
@@ -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
+24
View File
@@ -57,6 +57,8 @@ pub struct JwtClaims {
pub upn: Option<String>,
pub name: Option<String>,
pub exp: Option<u64>,
/// An app-only token's application permissions, such as `Mail.Read`.
pub roles: Vec<String>,
}
pub fn decode_jwt_claims(token: &str) -> Option<JwtClaims> {
@@ -73,6 +75,14 @@ pub fn decode_jwt_claims(token: &str) -> Option<JwtClaims> {
.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}"#;
+96 -3
View File
@@ -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!["[email protected]".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);
+67
View File
@@ -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<PathBuf> {
fs::read_dir(dir)
+8 -1
View File
@@ -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 || "";
+20 -2
View File
@@ -26,6 +26,8 @@
<label><input type="radio" name="kind" value="imap" checked> An IMAP server</label>
<label><input type="radio" name="kind" value="jmap"> A JMAP server (Stalwart or inbuxa)</label>
<label><input type="radio" name="kind" value="maildir"> Maildir folders on this machine</label>
<label><input type="radio" name="kind" value="microsoft"> Microsoft 365</label>
<label><input type="radio" name="kind" value="google"> Google Workspace (Gmail)</label>
</fieldset>
<div data-kind="imap jmap">
@@ -44,10 +46,26 @@
<p class="note">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.</p>
</div>
<div data-kind="imap jmap">
<label>Password or API key <input id="src-secret" type="password" autocomplete="off"></label>
<div data-kind="microsoft">
<label>Tenant <input id="src-tenant" placeholder="contoso.onmicrosoft.com" autocomplete="off"></label>
<label>App (client) id <input id="src-client-id" autocomplete="off"></label>
<p class="note">An app registered in Microsoft Entra reads every mailbox, so no one signs in.
Give it a client secret and these Microsoft Graph <em>application</em> permissions, with
admin consent: <code>User.Read.All</code>, <code>Mail.Read</code>,
<code>MailboxSettings.Read</code>, <code>Calendars.Read</code> and <code>Contacts.Read</code>.
Check tells you if any are missing.</p>
</div>
<div data-kind="imap jmap microsoft">
<label><span id="src-secret-label">Password or API key</span> <input id="src-secret" type="password" autocomplete="off"></label>
<p class="note" id="src-secret-kept" hidden>Already given; leave empty to keep it.</p>
</div>
<div data-kind="google">
<label>Service account's key file <input id="src-key-file" placeholder="/home/me/sa-key.json" autocomplete="off"></label>
<p class="note">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 <code>https://mail.google.com/</code>. Keep the key
file to yourself, and delete the key once the move is done. This moves the mail.</p>
</div>
<div data-kind="maildir">
<label>Each account's folder <input id="src-path" value="/var/vmail/{domain}/{local}/Maildir" autocomplete="off"></label>
<p class="note">Dovecot keeps one Maildir per account. <code>{domain}</code> and
+32
View File
@@ -0,0 +1,32 @@
/*
* SPDX-FileCopyrightText: 2026 Coffey Labs LLC <[email protected]>
*
* 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<u8>) {
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": "[email protected]",
"private_key": pem, "token_uri": token_uri,
});
(key.to_string(), pair.public_key().as_ref().to_vec())
}
+1
View File
@@ -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;
+36
View File
@@ -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": ["[email protected]"],
}})
};
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 [email protected]"),
"{found}"
);
}
+3 -25
View File
@@ -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<u8>) {
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": "[email protected]",
"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")