Skip to content

Setup & Authentication

Jump to bottom
BrewingCoder edited this page Jun 5, 2026 · 2 revisions

Setup & Authentication

First Run

outpost setup

This walks you through:

  1. Optional features — enable/disable Teams access (requires additional permissions)
  2. Timezone — set your IANA timezone for calendar events (e.g. America/New_York)
  3. Microsoft login — interactive browser sign-in

Signing In Without the Wizard

To authenticate (or re-authenticate) without re-running the full setup wizard:

outpost auth login            # browser sign-in (default)
outpost auth login --device   # device-code flow (headless / no browser)

How Authentication Works

Outpost uses MSAL interactive authentication (authorization code flow with PKCE) against a pre-registered multi-tenant Azure AD app. During login:

  1. Your default browser opens to the Microsoft sign-in page
  2. You sign in with your Microsoft account and consent to the requested permissions
  3. Microsoft redirects to a local loopback address (http://localhost), which Outpost captures automatically
  4. Outpost receives a token and stores it securely

You never copy a code by hand — the browser round-trip is automatic.

Device-Code Flow (fallback)

outpost auth login --device uses the older device-code flow: you're shown a code and https://microsoft.com/devicelogin to enter it in any browser. This is useful on headless machines with no local browser.

Note: Many organizations block the device-code flow via Conditional Access ("Your sign-in was successful but does not meet the criteria to access this resource… an authentication flow that is restricted by your admin", AADSTS error). If device-code is blocked in your tenant, use the default browser flow instead — it is not affected by that policy.

Token Storage

Tokens are cached using OS-level encryption where available:

  • Windows — DPAPI (Data Protection API)
  • macOS — Keychain
  • Linux — libsecret (falls back to file-based cache)

Tokens auto-refresh using refresh tokens, so you rarely need to re-authenticate. Refresh tokens do expire after 90 days of inactivity — when that happens, run outpost auth login to sign in again.

Re-running Setup

You can re-run outpost setup at any time to:

  • Enable or disable Teams access
  • Change your timezone
  • Re-authenticate (e.g. after token expiry or scope changes)

For a quick re-auth only, prefer outpost auth login.

Checking Auth Status

outpost auth status
outpost auth status --output json

auth status validates your cached token. If your session has expired it reports the expiry and tells you to run outpost auth login to re-authenticate.

See Also

Clone this wiki locally