Skip to content

auth.md

Latest commit

 

History

History
133 lines (99 loc) · 5.36 KB

auth.md

File metadata and controls

133 lines (99 loc) · 5.36 KB
Raw

Authentication Commands

Login, logout, and check authentication status. These commands manage OAuth2 tokens for Microsoft Graph API access.

Every auth command accepts global options (--account, --format, --json, --output, --verbose).

auth login

Authenticate with Microsoft and cache tokens locally. Opens a browser for the OAuth2 PKCE flow (default) or displays a device code for headless environments.

# First-time login (requires client ID)
outlook-cli auth login --client-id YOUR_CLIENT_ID

# Login to a specific account (uses stored client ID)
outlook-cli auth login --account work

# Device code flow (for SSH sessions, containers, servers)
outlook-cli auth login --device-code

# Work/school account with specific tenant
outlook-cli auth login --client-id YOUR_CLIENT_ID --tenant contoso.onmicrosoft.com
Option Description Default
--client-id <id> Azure app registration client ID. Required on first login for an account; stored afterwards. Can also be set via OUTLOOK_CLI_CLIENT_ID environment variable. Stored client ID or env var
--device-code Use device code flow instead of browser. Displays a code and URL — you authenticate on any device with a browser. Essential for headless servers, SSH sessions, and containers. Interactive browser flow
--tenant <id> Azure AD / Entra ID tenant. Use common for personal Microsoft accounts (default). For work/school accounts, use the tenant domain (contoso.onmicrosoft.com) or tenant ID (GUID). common

How Login Works

Browser flow (default):

  1. The CLI starts a temporary local HTTP server on a random port
  2. Opens your browser to Microsoft's login page
  3. You sign in and grant permissions
  4. Microsoft redirects back to the local server with an authorization code
  5. The CLI exchanges the code for tokens and caches them encrypted

Device code flow (--device-code):

  1. The CLI requests a device code from Microsoft
  2. Displays a URL (https://microsoft.com/devicelogin) and a code
  3. You visit the URL on any device, enter the code, and sign in
  4. The CLI polls until authentication completes
  5. Tokens are cached encrypted

Token Storage

After login, tokens are encrypted and stored in ~/.outlook-cli/cache-{alias}.enc using AES-256-GCM with PBKDF2-SHA512 key derivation (310,000 iterations). The encryption is interoperable — tokens encrypted by Node.js decrypt in C# and vice versa.

Tokens include:

  • Access token — valid for 1 hour, used for Graph API calls
  • Refresh token — valid for 90 days (personal accounts), used to get new access tokens silently

What Happens When Tokens Expire

  • Access token (1 hour): Automatically refreshed using the refresh token. You won't notice this.
  • Refresh token (90 days): You'll need to auth login again. The CLI shows a clear message: No valid token for account "X". Fix: Run outlook-cli auth login --account X.
  • Revoked permissions: If you remove the app from your Microsoft account, all tokens become invalid immediately.

auth logout

Clear cached tokens for the current or specified account. Deletes the encrypted cache file (~/.outlook-cli/cache-{alias}.enc).

outlook-cli auth logout                    # Logout from default account
outlook-cli auth logout --account work     # Logout from specific account

After logout, any command that requires authentication will show:

✗ No valid token for account "work".
   Fix: Run `outlook-cli auth login --account work` to authenticate.

Note: Logout only removes local tokens. It does not revoke the app's access on Microsoft's side. To fully revoke access, go to Microsoft Account > Apps and remove the app.

auth status

Show authentication status and token information for the current or specified account.

outlook-cli auth status
outlook-cli auth status --account work
outlook-cli auth status --json

Example output (text):

Account:       personal
Email:         john@outlook.com
Authenticated: ✓ yes
Tenant:        common

Example output (JSON):

outlook-cli auth status --json
{
  "account": "personal",
  "authenticated": true,
  "email": "john@outlook.com",
  "tenant": "common"
}

When not authenticated:

Account:       work
Authenticated: ✗ no
Fix:           Run `outlook-cli auth login --account work` to authenticate.

Troubleshooting

Symptom Cause Fix
Login opens browser but CLI hangs Browser didn't redirect properly Close the browser tab and try again. Check that no firewall is blocking localhost.
"AADSTS7000218: request body must contain client_assertion" Wrong client ID or app type Ensure your Azure app is registered as a Public client (not confidential).
"AADSTS50011: reply url does not match" Redirect URI not configured Add http://localhost as a Mobile/Desktop redirect URI in Azure portal.
Login works but commands fail Insufficient permissions Check API permissions in Azure portal. Required: User.Read, Mail.Read, Mail.ReadWrite, Calendars.Read.
"No valid token" after working previously Refresh token expired (90 days) Run auth login again.
Device code flow times out Code expired (15 minutes) Run auth login --device-code again and enter the new code promptly.