Improve default auth and token diagnostics

Author: sionsmith

README.md

@@ -74,6 +74,16 @@ cargo install --git https://github.com/osodevops/ms-teams-cli
 
 ## Agent Authentication
 
+This CLI calls Microsoft Graph. Every token used by 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`.
+
+For normal delegated use, the CLI defaults to the OSO public client app and the `organizations` authority:
+
+```bash
+teams auth login                # Browser-based login
+teams auth login --device-code  # SSH, containers, and remote terminals
+teams auth doctor --output json # Inspect client, tenant, token source, and token audience
+```
+
 For AI agents and automation, use **client credentials** (fully headless, no browser):
 
 ```bash
@@ -83,7 +93,7 @@ export TEAMS_CLI_CLIENT_SECRET=your-secret
 export TEAMS_CLI_TENANT_ID=your-tenant-id
 teams auth login --client-credentials
 
-# Option 2: Pass a pre-obtained token directly
+# Option 2: Pass a pre-obtained Microsoft Graph token directly
 export TEAMS_CLI_ACCESS_TOKEN=eyJ0eXAi...
 teams team list  # no login step needed
 
@@ -98,14 +108,25 @@ Tokens are cached in the OS keyring — subsequent commands reuse the session wi
 
 ```bash
 # Browser-based login (Authorization Code + PKCE)
-teams auth login --client-id <client-id> --tenant-id <tenant-id>
+teams auth login
 
 # Device code flow (headless/SSH, still requires a human to approve once)
-teams auth login --device-code --client-id <client-id> --tenant-id <tenant-id>
+teams auth login --device-code
 ```
 
 **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 one of these paths instead:
+
+- Delegated login with an approved Entra app for human-driven commands.
+- Device-code login for SSH, containers, and remote terminals.
+- Client credentials for app-only Microsoft Graph operations that support application permissions.
+- `TEAMS_CLI_ACCESS_TOKEN` only when the token was explicitly acquired for Microsoft Graph.
+
 ## Agent Workflow Patterns
 
 ### Pattern 1: Read-Act-Respond
@@ -413,7 +434,7 @@ auth_flow = "client-credentials"
 | `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 diagnostics = self.token.diagnostics();
+            let audience = diagnostics
+                .audience
+                .as_deref()
+                .unwrap_or("unknown or opaque token");
+
+            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/mod.rs

@@ -7,6 +7,10 @@ pub mod token;
 use crate::error::{Result, TeamsError};
 use token::TokenInfo;
 
+/// Default multi-tenant public client app for delegated CLI auth.
+pub const DEFAULT_PUBLIC_CLIENT_ID: &str = "fba1b5d0-fdd0-4fe2-9729-9ccdc38f9595";
+pub const DEFAULT_TENANT_ID: &str = "organizations";
+
 /// Resolve an access token using the priority chain:
 /// 1. TEAMS_CLI_ACCESS_TOKEN env var
 /// 2. Keyring (stored token, check expiry)

src/auth/token.rs

@@ -1,6 +1,13 @@
+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,
@@ -25,6 +32,98 @@ impl TokenInfo {
     pub fn bearer_header(&self) -> String {
         format!("Bearer {}", self.access_token)
     }
+
+    pub fn diagnostics(&self) -> TokenDiagnostics {
+        TokenDiagnostics::from_access_token(&self.access_token)
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct TokenDiagnostics {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub audience: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tenant_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub app_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub scopes: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub roles: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expires_at: Option<DateTime<Utc>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub is_graph_audience: Option<bool>,
+    pub decoded: bool,
+}
+
+impl TokenDiagnostics {
+    fn from_access_token(token: &str) -> Self {
+        let Some(payload) = decode_jwt_payload(token) else {
+            return Self {
+                audience: None,
+                tenant_id: None,
+                app_id: None,
+                scopes: None,
+                roles: None,
+                expires_at: None,
+                is_graph_audience: None,
+                decoded: false,
+            };
+        };
+
+        let audience = payload
+            .get("aud")
+            .and_then(|v| v.as_str())
+            .map(str::to_string);
+        let tenant_id = payload
+            .get("tid")
+            .and_then(|v| v.as_str())
+            .map(str::to_string);
+        let app_id = payload
+            .get("appid")
+            .or_else(|| payload.get("azp"))
+            .and_then(|v| v.as_str())
+            .map(str::to_string);
+        let scopes = payload.get("scp").and_then(|v| v.as_str()).map(|s| {
+            s.split_whitespace()
+                .map(str::to_string)
+                .collect::<Vec<String>>()
+        });
+        let roles = payload
+            .get("roles")
+            .and_then(|v| v.as_array())
+            .map(|roles| {
+                roles
+                    .iter()
+                    .filter_map(|role| role.as_str().map(str::to_string))
+                    .collect::<Vec<String>>()
+            });
+        let expires_at = payload
+            .get("exp")
+            .and_then(|v| v.as_i64())
+            .and_then(|ts| DateTime::<Utc>::from_timestamp(ts, 0));
+        let is_graph_audience = audience
+            .as_deref()
+            .map(|aud| GRAPH_AUDIENCES.iter().any(|expected| *expected == aud));
+
+        Self {
+            audience,
+            tenant_id,
+            app_id,
+            scopes,
+            roles,
+            expires_at,
+            is_graph_audience,
+            decoded: true,
+        }
+    }
+}
+
+fn decode_jwt_payload(token: &str) -> Option<serde_json::Value> {
+    let payload = token.split('.').nth(1)?;
+    let decoded = URL_SAFE_NO_PAD.decode(payload).ok()?;
+    serde_json::from_slice(&decoded).ok()
 }
 
 /// Raw token response from Microsoft Identity Platform
@@ -57,6 +156,12 @@ impl MsTokenResponse {
 mod tests {
     use super::*;
 
+    fn jwt_with_payload(payload: serde_json::Value) -> String {
+        let header = URL_SAFE_NO_PAD.encode(r#"{"alg":"none"}"#);
+        let payload = URL_SAFE_NO_PAD.encode(payload.to_string());
+        format!("{header}.{payload}.")
+    }
+
     fn make_token(expires_at: Option<DateTime<Utc>>) -> TokenInfo {
         TokenInfo {
             access_token: "test-token".into(),
@@ -92,6 +197,65 @@ mod tests {
         assert_eq!(token.bearer_header(), "Bearer test-token");
     }
 
+    #[test]
+    fn diagnostics_identifies_graph_audience() {
+        let token = TokenInfo {
+            access_token: jwt_with_payload(serde_json::json!({
+                "aud": "https://graph.microsoft.com",
+                "tid": "tenant-1",
+                "appid": "app-1",
+                "scp": "User.Read Team.ReadBasic.All",
+                "exp": 1_893_456_000i64
+            })),
+            expires_at: None,
+            token_type: "Bearer".into(),
+            scope: None,
+            refresh_token: None,
+            profile: "default".into(),
+        };
+
+        let diagnostics = token.diagnostics();
+        assert!(diagnostics.decoded);
+        assert_eq!(
+            diagnostics.audience.as_deref(),
+            Some("https://graph.microsoft.com")
+        );
+        assert_eq!(diagnostics.tenant_id.as_deref(), Some("tenant-1"));
+        assert_eq!(diagnostics.app_id.as_deref(), Some("app-1"));
+        assert_eq!(diagnostics.is_graph_audience, Some(true));
+        assert_eq!(
+            diagnostics.scopes,
+            Some(vec!["User.Read".into(), "Team.ReadBasic.All".into()])
+        );
+    }
+
+    #[test]
+    fn diagnostics_identifies_non_graph_audience() {
+        let token = TokenInfo {
+            access_token: jwt_with_payload(serde_json::json!({
+                "aud": "5e3ce6c0-2b1f-4285-8d4b-75ee78787346",
+                "roles": ["Some.Role"]
+            })),
+            expires_at: None,
+            token_type: "Bearer".into(),
+            scope: None,
+            refresh_token: None,
+            profile: "default".into(),
+        };
+
+        let diagnostics = token.diagnostics();
+        assert_eq!(diagnostics.is_graph_audience, Some(false));
+        assert_eq!(diagnostics.roles, Some(vec!["Some.Role".into()]));
+    }
+
+    #[test]
+    fn diagnostics_handles_opaque_tokens() {
+        let token = make_token(None);
+        let diagnostics = token.diagnostics();
+        assert!(!diagnostics.decoded);
+        assert_eq!(diagnostics.is_graph_audience, None);
+    }
+
     #[test]
     fn ms_token_response_conversion() {
         let resp = MsTokenResponse {