exchange-graph: app-only sign-in with --app-only #44

Merged
jcoffey-dev merged 1 commits from feat/graph-app-only into main 2026-10-30 21:32:21 +00:00
7 changed files with 351 additions and 20 deletions

No files matched your search

+7
View File
@@ -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
+23 -4
View File
@@ -208,7 +208,7 @@ For Exchange Online, use `exchange-graph` instead. Microsoft is retiring EWS in
```
inbuxa-migrate import exchange-graph \
(--client-id <UUID> [--tenant <ID>] | --access-token [TOKEN]) \
(--client-id <UUID> [--tenant <ID>] [--app-only] | --access-token [TOKEN]) \
[--user <UPN|UUID>] \
[--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 `<DIR>/<email>/<step>.log`, and one account
+64
View File
@@ -1702,6 +1702,14 @@ pub struct ExchangeGraphImportArgs {
)]
access_token: Option<Option<String>>,
#[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<Action
args.access_token.as_ref(),
args.client_id.as_deref(),
&args.tenant,
args.app_only,
)?;
let surfaces = args
.objects
@@ -1836,6 +1845,7 @@ fn resolve_graph_auth(
access_token: Option<&Option<String>>,
client_id: Option<&str>,
tenant: &str,
app_only: bool,
) -> Result<GraphAuth, Error> {
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 <id or name.onmicrosoft.com>".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"),
}
}
}
+42 -6
View File
@@ -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<AcquiredToken, GraphError> {
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<AcquiredToken, GraphError> {
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<AcquiredToken, GraphError> {
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<AcquiredToken, GraphError> {
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:?}"
))),
};
}
+38
View File
@@ -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<String>) -> 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);
+48 -10
View File
@@ -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<Summary, Error> {
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<AcquiredToken, Error> {
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<TokenRefresher> {
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<dyn FnMut() -> Result<AcquiredToken, GraphError> + 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)
+129
View File
@@ -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/[email protected]?$select=id,userPrincipalName",
r#"{"id":"uid-1","userPrincipalName":"[email protected]"}"#,
),
get(
&mut server,
"/users/uid-1?$select=id,userPrincipalName,displayName,mail",
r#"{"id":"uid-1","userPrincipalName":"[email protected]"}"#,
),
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: <app@x>\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("[email protected]".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();
}