sanoptis-auth

Microsoft SSO + Postgres-broker credential management for Sanoptis Claude Code plugins.

A single library that any Sanoptis plugin can use to fetch its API secrets, gated by the user's normal Microsoft sign-in. No per-plugin dotfiles, no chmod gymnastics, no hand-rolled credential bootstrap docs.

Install

pip install sanoptis-auth

What it does

• Fetches secrets from the Sanoptis admin broker (a Reflex/FastAPI app with a Postgres backend that stores Fernet-encrypted secret values).
• Authenticates the user via Microsoft SSO on first use: reuses an existing az login session if present, otherwise opens a browser tab for one-click sign-in. Refresh token cached in the OS-native secure store (DPAPI/Keychain/libsecret) for ~90 days.
• Enforces access policy at the broker, per-plugin:
  • public plugins — any authenticated Sanoptis user may read.
  • restricted plugins — only users added as members (in the admin UI) may read.

Use it in a plugin

Add to your plugin's requirements.txt:

sanoptis-auth>=0.5.0,<0.6

Replace any per-plugin credential loading with:

from sanoptis_auth import get_secret

api_key = get_secret("yokoy/api-key")
api_secret = get_secret("yokoy/api-secret")

Do not register the sanoptis-auth MCP server in your own plugin's .mcp.json. The separate sanoptis-auth plugin in the Sanoptis marketplace registers it once for every Claude Code session; your plugin just imports the Python library.

First-time login (end user)

1. Install the plugin in Claude Code.
2. Use any tool that needs a secret. If no MSAL cache exists, Claude will call start_sanoptis_login for you (or you can call it directly).
3. A browser tab opens at the Microsoft sign-in page. If your browser already holds an M365 cookie (the typical case inside Sanoptis), the redirect is instant.
4. Done — the next ~90 days of plugin usage are automatic.

Headless environments (SSH, Docker, CI) have no browser, so the SDK's credential chain falls through to an explicit error pointing at az login. Run az login --tenant <tenant-id> once and the AzureCliCredential step picks it up on the next call.

Local dev override

For working offline or before your admin-broker membership is set up:

export SANOPTIS_AUTH_LOCAL_OVERRIDE_FILE=~/.sanoptis-auth-overrides.env
cat > ~/.sanoptis-auth-overrides.env <<'EOF'
yokoy/api-key=dev-key
yokoy/api-secret=dev-secret
EOF
chmod 600 ~/.sanoptis-auth-overrides.env

get_secret() checks this file first when the env var is set.

Admin app

The sanoptis_admin/ package is a Reflex web app that is the primary tool for managing plugins, secrets, and memberships. Admins sign in with their Sanoptis Microsoft account and can:

• Create plugins — adds a row to the admin DB and auto-enrols the creator as first member.
• Add/rotate/delete secrets — Fernet-encrypts the plaintext and stores the ciphertext in Postgres.
• Manage members — add/remove users (by UPN) from a plugin's membership set.
• Flip access policy — per-plugin, between public and restricted.
• Audit — every mutation and every successful secret read is logged with actor UPN, action, and target.

All operations run under the admin's own delegated token — no elevated service principal, no app-permission scopes. Non-admins (absent from ADMIN_UPNS) see a "Not authorized" page.

Deployed to Azure Container Apps via infra/azure/admin_app.tf. Container image built and pushed by .github/workflows/deploy-admin.yml on pushes to main that touch sanoptis_admin/**.

Local dev:

cd sanoptis_admin
SANOPTIS_ADMIN_CONFIG=$(pwd)/web.yaml \
DATABASE_URL=sqlite:///admin.db \
ENTRA_CLIENT_SECRET=... \
SESSION_SECRET=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") \
DATA_ENCRYPTION_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") \
ADMIN_UPNS=you@sanoptis.com \
pixi run -e admin reflex run

See sanoptis_admin/web.yaml.example for the config schema.

Adding a new secret to a plugin

Preferred: use the admin app — "Add/rotate secret" writes to Postgres under the admin's own identity and records the rotation in the audit log.

Break-glass: the gha service principal has Key Vault Secrets Officer on the shared KV (see infra/entra/gha_app.tf) which lets an operator rotate container-level secrets (DATA_ENCRYPTION_KEY etc.) — but plugin secrets live in Postgres, not KV, so the admin app is the only route for those.

Adding a new plugin

Preferred: use the admin app — "Create plugin" registers it and auto-enrols you as first member. "Add secret" then creates each secret and (for restricted plugins) "Add member" grants access.

In your plugin's code, unchanged from above:

get_secret("myplugin/api-key")

Repo layout

Architecture decisions

• Postgres broker over direct KV. Plugin users never touch Key Vault. The admin app owns memberships + audit; KV is used only for container-level secrets (Fernet DEK, OAuth client secret, session key, admin UPN list, DB DSN).
• Public client (no client secret) for the plugin app. The plugin Entra app uses delegated access — tokens are minted on behalf of the signed-in user via the browser popup. Nothing to leak or rotate at the app level.
• Per-user MSAL cache. Token cache lives in ${CLAUDE_PLUGIN_DATA}/msal_cache.bin when running inside a Claude Code plugin, otherwise ~/.sanoptis-auth/msal_cache.bin. Shared across all plugins on the same user account — one sign-in, many plugins.
• No device-code fallback. Headless environments use az login --tenant <tenant> beforehand; AzureCliCredential then produces tokens silently. This keeps the chain predictable and never blocks on an invisible prompt.
• Entra for sign-in only. No Graph group lookups, no per-secret KV RBAC, no ARM role assignments at plugin lifecycle time. Membership lives in the admin's own Postgres.
• Terraform over Bicep. Reviewable, multi-cloud-portable, standard Sanoptis-BI infra tool. Runs via OIDC federated identity in CI — no stored service principal secret.

Provisioning new infrastructure

See infra/README.md for the one-time Azure bootstrap procedure.

Source of truth

This repo is the only place credentials for Sanoptis Claude Code plugins should be managed. If you find a plugin reading secrets from a dotfile or environment variable, file an issue — it should be migrated to sanoptis_auth.get_secret.