Security & Authentication¶

This page covers the authentication layer that gates the HTTP front door (orrery_core.serving.server) and the secrets-management seam that keeps API keys out of environment variables.

The Slack and Google Chat transports authenticate at their own layer (Slack signing-secret + Google OIDC tokens) and are unaffected by the settings here.

Threat model¶

Configuration¶

Settings¶

The HTTP front door (ServerConfig.from_env(), JWTConfig.from_env()) reads:

Minimal HS256 setup (single-binary deployments)¶

AUTH_ENABLED=true
JWT_ALGORITHM=HS256
JWT_SECRET=$(openssl rand -hex 32)    # 32+ bytes for HS256 (48 for HS384, 64 for HS512)
JWT_AUDIENCE=orrery
JWT_ISSUER=https://your-gateway

Issue tokens from your gateway (or jwt.io for testing) with at least:

{
  "sub": "alice@example.com",
  "aud": "orrery",
  "iss": "https://your-gateway",
  "exp": 1234567890,
  "roles": ["operator"]
}

Production RS256/JWKS setup (IdP-fronted deployments)¶

AUTH_ENABLED=true
JWT_ALGORITHM=RS256
JWT_JWKS_URL=https://your-tenant.auth0.com/.well-known/jwks.json
JWT_AUDIENCE=https://orrery.your-org.com
JWT_ISSUER=https://your-tenant.auth0.com/
JWT_ROLE_CLAIM=https://orrery.your-org.com/roles    # Auth0 custom claim

Common JWKS endpoints:

Role mapping¶

extract_role() reads the JWT_ROLE_CLAIM claim and returns one of viewer / operator / admin using these rules:

1. The claim may be a list (["operator", "billing"]) or a single space/comma-separated string ("operator,billing").
2. Any token matching admin (or the aliases orrery-admin, orrery_admin) returns admin. Matching ignores case.
3. Otherwise, any token matching operator (or orrery-operator, orrery_operator) returns operator.
4. Otherwise, viewer.

JWT_ROLE_CLAIM may be a dotted path into nested claims, because the providers people actually deploy nest their roles — Keycloak uses realm_access.roles for realm roles and resource_access.<client>.roles for client roles, neither of which a flat lookup reaches:

JWT_ROLE_CLAIM=realm_access.roles

A path that doesn't resolve is treated as "no roles" and yields viewer — it fails closed. The console reads the same claim for its role badge (ORRERY_CONSOLE_OIDC_ROLE_CLAIM defaults to JWT_ROLE_CLAIM).

Custom role names are supported by passing admin_values= / operator_values= when calling extract_role directly. The HTTP path uses the defaults and has no setting for other names, so map your IdP's roles onto the names above in the IdP. (RolePolicy is a different thing: it sets the minimum role per tool.)

Autonomy levels¶

RBAC decides who may call a tool; the autonomy level decides what this process may do at all, whoever asks. AutonomyPlugin reads ORRERY_AUTONOMY_LEVEL:

Unset (or off/none), no process-wide level applies; the plugin still pins service principals to L2 per request (ADR-006). An unrecognised value is treated as L2. A refused call returns {"status": "BLOCKED"}. Per-tool exceptions (an L2 whitelist, an L3 blacklist) are code-only: default_plugins(autonomy_l2_whitelist=…, autonomy_l3_blacklist=…). Pin unattended runs such as the triage sweep to L2 unless you want them to act.

People, agents and services (ADR-006)¶

A guarded action waits for a human decision, and only the person who raised it may approve it. That only holds if the caller is a person. Orrery classifies every verified token:

ORRERY_HUMAN_CLIENTS=orrery-console,orrery-cli          # clients people sign in through
ORRERY_SERVICE_CLIENTS=ci-bot=viewer,partner-agent=operator  # machine clients and their ceilings

A machine caller's message is never recorded as a decision, whatever it says. To approve an action an agent raised for you, use the console or:

curl -X POST https://orrery.example.com/confirmations/<action_id>/decision \
  -H "Authorization: Bearer $YOUR_TOKEN" -d '{"decision": "approve"}'

Approve works only for your own action (anything else is a 404, the same as an unknown id); deny is open to anyone. The approval applies when the agent retries the same call with the same arguments, within two minutes.

Wiring the AuthPlugin¶

AuthPlugin consumes the _auth payload the HTTP front door stashes into session state. Enable it on the plugin stack:

from orrery_core import default_plugins
from orrery_core.serving.server import ServerConfig, create_app

plugins = default_plugins(enable_auth=True)
app = create_app(
    root_agent=root_agent,
    app_name="orrery",
    plugins=plugins,
    config=ServerConfig.from_env(),
)

With enable_auth=True and require_auth=True (default), a session that reaches the agent without a verified _auth payload has its role forced to viewer and a warning is logged. This makes privilege escalation impossible even if a future transport forgets to wire the auth dependency.

Secrets management¶

SecretsManager resolves keys in this order:

1. Explicitly registered backends (e.g. Vault adapter).
2. FileBackend(ORRERY_SECRETS_DIR) — auto-installed when the env var points at a real directory.
3. Environment variables.
4. The caller's default (or None).

Recommended Kubernetes pattern:

volumeMounts:
  - name: orrery-secrets
    mountPath: /var/run/secrets/orrery
    readOnly: true
env:
  - name: ORRERY_SECRETS_DIR
    value: /var/run/secrets/orrery
volumes:
  - name: orrery-secrets
    secret:
      secretName: orrery-secrets   # contains JWT_SECRET, GOOGLE_API_KEY, …

Each key in the Secret becomes a file under /var/run/secrets/orrery/. Application code stays the same — read through default_secrets.get("JWT_SECRET") rather than os.getenv("JWT_SECRET") to pick up the volume transparently.

Runtime hardening plugins (AEP-013)¶

Three content-level defenses ship in default_plugins(), all on by default with env off-switches:

Prompt-injection screening¶

SafetyScreenPlugin runs before the model does (before_run_callback — the one plugin hook that can halt the runner). Messages matching overt override phrasings ("ignore previous instructions", "reveal your system prompt", "bypass the guardrails", ...) are refused before they cost a token or reach a tool; the attempt is logged for audit visibility. The patterns are deliberately narrow — an SRE pasting incident logs must not trip false positives — and this is a baseline: the real security boundary remains the deterministic layer underneath (RBAC, confirmations, autonomy gates, input validation), which holds even when a novel paraphrase gets past the screen.

ORRERY_SAFETY_SCREEN=false   # disable (default: on)

PII / secret redaction of tool outputs¶

PIIRedactionPlugin scrubs credentials from every tool result before the model, the session store, and the audit log see them (it registers ahead of AuditPlugin). Two layers: dict keys that name a credential (password, access_token, api_key, ...) have their values replaced outright, and string values are scanned for secret shapes (password=... pairs in log lines, PEM private-key blocks, AWS/GitHub/Slack/OpenAI token prefixes, JWTs). Pagination cursors (next_page_token) are allowlisted.

IP addresses are not redacted by default — an SRE agent that cannot see pod or broker IPs cannot diagnose much. Compliance-bound deployments can opt in:

ORRERY_PII_REDACTION=false   # disable credential scrubbing (default: on)
ORRERY_REDACT_IPS=true       # also redact IPv4 addresses (default: off)

What the audit log keeps of a tool result¶

Every tool call leaves two audit entries (tool_attempt, then tool_call) with the tool, its sanitized arguments, the caller and the session. What the outcome entry keeps of the result is set by ORRERY_AUDIT_RESPONSES:

A tool result is infrastructure output (alert payloads, log lines, index documents) that often names people, and an audit trail is usually kept longer and read more widely than a session, so the default keeps the outcome rather than the payload. A failure message is kept because it is what an operator needs, and it can quote up to 200 characters of backend text (an error body, a resource name). A gate's refusal is not copied: its message can repeat the refused arguments. Use full while debugging a tool.

Gemini content-safety filters¶

create_agent() attaches GenerateContentConfig safety settings (dangerous content, harassment, hate speech, sexually explicit) to every Gemini model. The default threshold is BLOCK_ONLY_HIGH: SRE conversations legitimately talk about killing pods and destroying volumes all day, and stricter thresholds trip on that. LiteLLM-routed providers (Claude, OpenAI, Ollama) do not consume the genai config and are unaffected.

GEMINI_SAFETY_FILTERS=false                     # disable (default: on)
GEMINI_SAFETY_THRESHOLD=BLOCK_MEDIUM_AND_ABOVE  # default: BLOCK_ONLY_HIGH

Acting as the user (impersonation)¶

Kubernetes and Elasticsearch calls can carry the verified requester, so those systems' own permissions apply too. Full guide: Acting as the user.

Per-user tokens (token exchange)¶

MCP servers with auth: {type: token_exchange} receive a token the identity provider issued for the requesting user (RFC 8693, ADR-004). Full guide: MCP servers.

What this does not cover (intentionally)¶

• Vault / GCP Secret Manager / AWS Secrets Manager adapters — SecretsManager exposes the SecretsBackend protocol; concrete adapters will ship as separate modules so each provider's SDK is optional.
• Supply-chain security (image signing, SBOMs, admission policy) — see Supply Chain Security.