Authentication Workflows

Crab authenticates you against your configured OIDC identity provider and caches the resulting tokens locally. Once authenticated, credentials refresh automatically — you typically run crab login once per device and forget about it.

Two Authentication Flows

Crab automatically picks the right flow based on your environment:

Browser-based (default on desktop)

When you run crab login in a desktop terminal, Crab opens your browser to your IdP's login page. After you authenticate, the browser redirects back to a local listener and Crab captures the authorization code.

crab login
# Opens browser → authenticate → redirects back
# Authenticated as alice@corp.example.com (aws-oidc)

Device code (headless / SSH)

Over SSH or in non-TTY environments, Crab automatically falls back to the device code flow. It displays a URL and one-time code you can enter on any device — your phone, a different laptop, anything with a browser.

crab login --headless

To authenticate, open: https://login.corp.example.com/device
Enter code: ABCD-1234
Waiting for approval...
Authenticated as alice@corp.example.com (aws-oidc)

You can force device code flow with --headless even on desktop, which is useful when port forwarding isn't available.

Provider Override

By default, crab login uses the provider from your config. Override it for a one-time login to a different backend:

crab login --provider azure-entra

Available providers:

The static and none providers don't support interactive login.

Token Storage

After successful authentication, tokens are encrypted with ChaCha20-Poly1305 and stored in ~/.config/crab/tokens/:

~/.config/crab/tokens/
├── aws-oidc.json.enc
├── gcp-workload-identity.json.enc
└── azure-entra.json.enc

Each provider gets its own file. Automatic refresh happens transparently before tokens expire.

Prerequisites

Before logging in, configure at minimum:

crab config set auth.provider aws-oidc
crab config set auth.issuer_url https://login.corp.example.com
crab config set auth.client_id crab-cli-prod

See the provider-specific guides for full setup:

• AWS Credentials
• GCP Credentials
• Azure Credentials

CLI Reference

For complete command syntax and all available flags, see the crab login reference.