Merge pull request #11 from osodevops/feat/default-auth-diagnostics

Improve default auth and token diagnostics

Author: sionsmith

README.md

@@ -162,6 +162,12 @@ can still bring their own Entra app by passing `--client-id` and `--tenant-id`
 or configuring a profile; see
 [`docs/auth-implementation-plan.md`](docs/auth-implementation-plan.md).
 
+This CLI calls Microsoft Graph. Every token used by Graph commands must be a
+Microsoft Graph access token. Tokens captured from the Microsoft Teams web or
+desktop client, including `fossteams/teams-token` files such as
+`~/.config/fossteams/token-teams.jwt`, are issued for Teams-specific audiences
+and will fail against Graph with `InvalidAuthenticationToken: Invalid audience`.
+
 ```bash
 # Browser-based login with OSO's public client app
 teams auth login
@@ -187,7 +193,7 @@ export TEAMS_CLI_CLIENT_SECRET=<client-secret>
 export TEAMS_CLI_TENANT_ID=<tenant-id>
 teams auth login --client-credentials
 
-# Pass a pre-obtained token directly
+# Pass a pre-obtained Microsoft Graph token directly
 export TEAMS_CLI_ACCESS_TOKEN=<access-token>
 teams team list  # no login step needed
 
@@ -200,6 +206,20 @@ Tokens are cached in the OS keyring — subsequent commands reuse the session wi
 
 **Credential resolution order**: CLI flags > environment variables > config file profiles.
 
+### Why not import Teams client tokens?
+
+Tools such as `fossteams/teams-token` are attractive because they avoid Entra
+app registration and consent setup, especially in tenants where users cannot
+approve third-party apps themselves. That is a real usability signal: `teams
+auth login` should be easy to diagnose, should support browser and device-code
+flows clearly, and should not make users reverse-engineer token audiences.
+
+The supported fix is better Graph-native auth, not reusing Teams client tokens.
+A Teams, Skype, ChatSvcAgg, or ID token cannot be converted into a Graph token
+by this CLI. Use delegated login, device-code login, client credentials for
+supported app-only Graph operations, or `TEAMS_CLI_ACCESS_TOKEN` only when the
+token was explicitly acquired for Microsoft Graph.
+
 ## Agent Workflow Patterns
 
 ### Pattern 1: Read-Act-Respond
@@ -509,7 +529,7 @@ auth_flow = "device-code"
 | `TEAMS_CLI_CLIENT_ID` | Azure AD application (client) ID |
 | `TEAMS_CLI_CLIENT_SECRET` | Azure AD client secret |
 | `TEAMS_CLI_TENANT_ID` | Azure AD tenant ID |
-| `TEAMS_CLI_ACCESS_TOKEN` | Pre-obtained access token (skips login entirely) |
+| `TEAMS_CLI_ACCESS_TOKEN` | Pre-obtained Microsoft Graph access token (skips login entirely) |
 | `RUST_LOG` | Tracing filter (e.g., `debug`, `teams=trace`) |
 
 ## Verbosity

src/api/client.rs

@@ -37,6 +37,40 @@ impl GraphClient {
         })
     }
 
+    fn auth_error_message(&self, body: &str) -> String {
+        let mut message = if body.trim().is_empty() {
+            "Authentication failed (401)".to_string()
+        } else {
+            format!("Authentication failed (401): {body}")
+        };
+
+        if body.contains("Invalid audience") || body.contains("InvalidAuthenticationToken") {
+            let audience = self
+                .token
+                .unverified_claims()
+                .and_then(|claims| claims.audience())
+                .unwrap_or_else(|| "unknown or opaque token".to_string());
+
+            message.push_str(&format!(
+                "\nHint: Microsoft Graph rejected this token audience. This CLI requires a Microsoft Graph access token; observed audience: {audience}. Run `teams auth login`, `teams auth login --device-code`, or provide a Graph token via `TEAMS_CLI_ACCESS_TOKEN`. Teams client tokens such as `~/.config/fossteams/token-teams.jwt` are not supported."
+            ));
+        }
+
+        message
+    }
+
+    fn error_for_status(&self, status: StatusCode, body: String) -> TeamsError {
+        match status {
+            StatusCode::UNAUTHORIZED => TeamsError::AuthError(self.auth_error_message(&body)),
+            StatusCode::FORBIDDEN => TeamsError::PermissionDenied(body),
+            StatusCode::NOT_FOUND => TeamsError::NotFound(body),
+            _ => TeamsError::ApiError {
+                status: status.as_u16(),
+                message: body,
+            },
+        }
+    }
+
     /// GET request with retry logic.
     pub async fn get<T: DeserializeOwned>(&self, url: &str, query: &[(&str, &str)]) -> Result<T> {
         self.request_with_retry(|this| {
@@ -170,10 +204,7 @@ impl GraphClient {
 
             if !status.is_success() && status != StatusCode::ACCEPTED {
                 let body = resp.text().await.unwrap_or_default();
-                return Err(TeamsError::ApiError {
-                    status: status.as_u16(),
-                    message: body,
-                });
+                return Err(self.error_for_status(status, body));
             }
 
             let location = resp
@@ -250,10 +281,7 @@ impl GraphClient {
 
             if !status.is_success() {
                 let body = resp.text().await.unwrap_or_default();
-                return Err(TeamsError::ApiError {
-                    status: status.as_u16(),
-                    message: body,
-                });
+                return Err(self.error_for_status(status, body));
             }
 
             let bytes = resp.bytes().await.map_err(TeamsError::NetworkError)?;
@@ -320,18 +348,6 @@ impl GraphClient {
             return Err(TeamsError::RateLimited { retry_after });
         }
 
-        if status == StatusCode::UNAUTHORIZED {
-            return Err(TeamsError::AuthError(
-                "Authentication failed (401)".to_string(),
-            ));
-        }
-        if status == StatusCode::FORBIDDEN {
-            return Err(TeamsError::PermissionDenied("Forbidden (403)".to_string()));
-        }
-        if status == StatusCode::NOT_FOUND {
-            return Err(TeamsError::NotFound("Not found (404)".to_string()));
-        }
-
         if status.is_server_error() {
             if attempt < max_retries {
                 let delay = backoff_base.pow(attempt);
@@ -403,9 +419,7 @@ impl GraphClient {
             // Auth errors
             if status == StatusCode::UNAUTHORIZED {
                 let body = resp.text().await.unwrap_or_default();
-                return Err(TeamsError::AuthError(format!(
-                    "Authentication failed (401): {body}"
-                )));
+                return Err(TeamsError::AuthError(self.auth_error_message(&body)));
             }
             if status == StatusCode::FORBIDDEN {
                 let body = resp.text().await.unwrap_or_default();
@@ -515,9 +529,7 @@ impl GraphClient {
 
             if status == StatusCode::UNAUTHORIZED {
                 let body = resp.text().await.unwrap_or_default();
-                return Err(TeamsError::AuthError(format!(
-                    "Authentication failed (401): {body}"
-                )));
+                return Err(TeamsError::AuthError(self.auth_error_message(&body)));
             }
             if status == StatusCode::FORBIDDEN {
                 let body = resp.text().await.unwrap_or_default();

src/auth/token.rs

@@ -2,6 +2,12 @@ use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
+const GRAPH_AUDIENCES: &[&str] = &[
+    "https://graph.microsoft.com",
+    "https://graph.microsoft.com/",
+    "00000003-0000-0000-c000-000000000000",
+];
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TokenInfo {
     pub access_token: String,
@@ -49,6 +55,18 @@ impl TokenClaims {
             "unknown"
         }
     }
+
+    pub fn audience(&self) -> Option<String> {
+        match self.aud.as_ref()? {
+            serde_json::Value::String(audience) => Some(audience.clone()),
+            other => Some(other.to_string()),
+        }
+    }
+
+    pub fn is_graph_audience(&self) -> Option<bool> {
+        let audience = self.audience()?;
+        Some(GRAPH_AUDIENCES.iter().any(|expected| *expected == audience))
+    }
 }
 
 impl TokenInfo {
@@ -164,6 +182,7 @@ mod tests {
     #[test]
     fn decodes_delegated_jwt_claims() {
         let payload = serde_json::json!({
+            "aud": "https://graph.microsoft.com",
             "tid": "tenant-id",
             "oid": "user-id",
             "scp": "User.Read ChatMessage.Send"
@@ -177,6 +196,26 @@ mod tests {
 
         assert_eq!(claims.tid.as_deref(), Some("tenant-id"));
         assert_eq!(claims.auth_type(), "delegated");
+        assert_eq!(
+            claims.audience().as_deref(),
+            Some("https://graph.microsoft.com")
+        );
+        assert_eq!(claims.is_graph_audience(), Some(true));
+    }
+
+    #[test]
+    fn identifies_non_graph_audience() {
+        let payload = serde_json::json!({
+            "aud": "5e3ce6c0-2b1f-4285-8d4b-75ee78787346"
+        });
+        let token = format!(
+            "header.{}.signature",
+            URL_SAFE_NO_PAD.encode(payload.to_string())
+        );
+
+        let claims = decode_unverified_claims(&token).unwrap();
+
+        assert_eq!(claims.is_graph_audience(), Some(false));
     }
 
     #[test]

src/cli/auth.rs

@@ -80,6 +80,36 @@ pub enum AuthCommand {
     },
 }
 
+fn token_diagnostics(claims: Option<&auth::token::TokenClaims>) -> Option<serde_json::Value> {
+    claims.map(|claims| {
+        serde_json::json!({
+            "audience": claims.audience(),
+            "is_graph_audience": claims.is_graph_audience(),
+            "auth_type": claims.auth_type(),
+            "tenant_id": claims.tid,
+            "app_id": claims.appid.clone().or_else(|| claims.azp.clone()),
+            "user": claims.preferred_username.clone().or_else(|| claims.upn.clone()),
+        })
+    })
+}
+
+fn token_warnings(claims: Option<&auth::token::TokenClaims>) -> Vec<String> {
+    let mut warnings = Vec::new();
+
+    if let Some(claims) = claims {
+        if claims.is_graph_audience() == Some(false) {
+            let audience = claims
+                .audience()
+                .unwrap_or_else(|| "unknown audience".into());
+            warnings.push(format!(
+                "Token audience is '{audience}', not Microsoft Graph. Graph commands require a Microsoft Graph access token."
+            ));
+        }
+    }
+
+    warnings
+}
+
 pub async fn run(
     cmd: AuthCommand,
     config: &ConfigFile,
@@ -189,17 +219,21 @@ pub async fn run(
 
             let token = auth::resolve_token(profile).ok();
             let claims = token.as_ref().and_then(|t| t.unverified_claims());
+            let warnings = token_warnings(claims.as_ref());
             let msg = serde_json::json!({
                 "profile": profile,
                 "auth_app": auth_app,
                 "client_id": client_id,
                 "tenant_id": tenant_id,
                 "admin_consent_url": format!("https://login.microsoftonline.com/{tenant_id}/adminconsent?client_id={client_id}"),
                 "authenticated": token.is_some(),
+                "warnings": warnings,
                 "token": token.as_ref().map(|t| serde_json::json!({
                     "expires_at": t.expires_at.map(|e| e.to_rfc3339()),
                     "scope": t.scope,
                     "auth_type": claims.as_ref().map(|c| c.auth_type()).unwrap_or("unknown"),
+                    "audience": claims.as_ref().and_then(|c| c.audience()),
+                    "is_graph_audience": claims.as_ref().and_then(|c| c.is_graph_audience()),
                     "tenant_id": claims.as_ref().and_then(|c| c.tid.clone()),
                     "app_id": claims.as_ref().and_then(|c| c.appid.clone()).or_else(|| claims.as_ref().and_then(|c| c.azp.clone())),
                     "user": claims.as_ref().and_then(|c| c.preferred_username.clone()).or_else(|| claims.as_ref().and_then(|c| c.upn.clone())),
@@ -213,11 +247,14 @@ pub async fn run(
             let start = Instant::now();
             match auth::resolve_token(profile) {
                 Ok(token) => {
+                    let claims = token.unverified_claims();
                     let msg = serde_json::json!({
                         "authenticated": true,
                         "profile": profile,
                         "expires_at": token.expires_at.map(|e| e.to_rfc3339()),
                         "scope": token.scope,
+                        "token_diagnostics": token_diagnostics(claims.as_ref()),
+                        "warnings": token_warnings(claims.as_ref()),
                     });
                     output::print_success(format, &msg, start);
                     Ok(())
@@ -297,10 +334,12 @@ pub async fn run(
             let token = auth::resolve_token(profile)?;
             match token_format.as_str() {
                 "json" => {
+                    let claims = token.unverified_claims();
                     let msg = serde_json::json!({
                         "access_token": token.access_token,
                         "token_type": token.token_type,
                         "expires_at": token.expires_at.map(|e| e.to_rfc3339()),
+                        "token_diagnostics": token_diagnostics(claims.as_ref()),
                     });
                     let start = Instant::now();
                     output::print_success(format, &msg, start);

tests/cli.rs

@@ -1,4 +1,5 @@
 use assert_cmd::Command;
+use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
 use predicates::prelude::*;
 use std::fs;
 
@@ -80,6 +81,29 @@ fn auth_doctor_reports_oso_default_without_login() {
         );
 }
 
+#[test]
+fn auth_doctor_reports_token_audience() {
+    let payload = serde_json::json!({
+        "aud": "https://graph.microsoft.com",
+        "tid": "tenant-1",
+        "scp": "User.Read"
+    });
+    let token = format!(
+        "header.{}.signature",
+        URL_SAFE_NO_PAD.encode(payload.to_string())
+    );
+
+    teams()
+        .args(["auth", "doctor", "--output", "json"])
+        .env("TEAMS_CLI_ACCESS_TOKEN", token)
+        .assert()
+        .success()
+        .stdout(
+            predicate::str::contains("https://graph.microsoft.com")
+                .and(predicate::str::contains("\"is_graph_audience\": true")),
+        );
+}
+
 #[test]
 fn completions_generates_output() {
     teams()