Version: Next

Admin Client

contrib/client/nauthilus-admin.py is a dependency-free Python 3 client for Nauthilus backchannel operations. It can obtain an OIDC Client Credentials token, use a pre-issued Bearer token, or authenticate with configured backchannel Basic credentials.

Run it from a Nauthilus source checkout:

python3 contrib/client/nauthilus-admin.py --help

The client supports token-cache inspection, OpenAPI download, cache flushes, brute-force administration, asynchronous job polling, OIDC session administration, JSON authentication tests, and arbitrary management requests.

Authentication Configuration

Settings can come from command-line flags, process environment variables, or an env-style file. Precedence is command line, process environment, env file, then built-in default.

OIDC Client Credentials

Create a confidential OIDC client with the client_credentials grant. Every protected backchannel request needs nauthilus:authenticate; add only the route-specific scopes the operator needs.

Example /etc/nauthilus/admin-client.env:

NAUTHILUS_URL=https://nauthilus.example.com
NAUTHILUS_TOKEN_URL=https://nauthilus.example.com/oidc/token
NAUTHILUS_CLIENT_ID=operations-client
NAUTHILUS_CLIENT_SECRET_FILE=/etc/nauthilus/secrets/operations-client-secret
NAUTHILUS_CLIENT_AUTH_METHOD=basic
NAUTHILUS_SCOPES=nauthilus:authenticate nauthilus:admin nauthilus:security

Protect both files from other users:

chmod 0600 /etc/nauthilus/admin-client.env
chmod 0600 /etc/nauthilus/secrets/operations-client-secret

NAUTHILUS_CLIENT_AUTH_METHOD accepts basic and post. Do not add openid to the client-credentials scope list.

Run a command with the file:

python3 contrib/client/nauthilus-admin.py \
  --env-file /etc/nauthilus/admin-client.env \
  openapi json

You can also set NAUTHILUS_ENV_FILE instead of repeating --env-file.

Pre-issued Bearer Token

Use --bearer-token-file or NAUTHILUS_BEARER_TOKEN_FILE to read a token without placing it in the process arguments:

NAUTHILUS_URL=https://nauthilus.example.com
NAUTHILUS_BEARER_TOKEN_FILE=/run/secrets/nauthilus-admin-token

Backchannel Basic Authentication

For deployments that use auth.backchannel.basic_auth, configure:

NAUTHILUS_URL=https://nauthilus.example.com
NAUTHILUS_BASIC_USER=operator
NAUTHILUS_BASIC_PASSWORD_FILE=/etc/nauthilus/secrets/admin-basic-password

Backchannel Basic authentication is an administrative credential and is not restricted by Bearer scopes. Prefer a least-privilege OIDC client where scope separation is required.

TLS and Address Overrides

TLS certificate verification is enabled by default. --insecure or NAUTHILUS_INSECURE=true disables it and should be limited to isolated development environments.

If the client must connect to an internal address while verifying the public certificate and preserving TLS SNI, use a resolve override:

NAUTHILUS_RESOLVE=nauthilus.example.com:443:192.0.2.10

The format is host:port:address. Multiple CLI --resolve flags or comma-separated environment values are supported.

Token Cache

OIDC access tokens are cached until shortly before expiry. The default cache path is:

$XDG_RUNTIME_DIR/nauthilus-admin-token.json when XDG_RUNTIME_DIR is available;
otherwise ~/.cache/nauthilus-admin/token.json.

The client writes the cache with mode 0600. Override it with --token-cache or NAUTHILUS_TOKEN_CACHE; use off to disable caching.

# Show metadata without printing the access token.
python3 contrib/client/nauthilus-admin.py \
  --env-file /etc/nauthilus/admin-client.env \
  token status

# Remove the cached token.
python3 contrib/client/nauthilus-admin.py \
  --env-file /etc/nauthilus/admin-client.env \
  token clear

Common Operations

The examples below omit the repeated --env-file /etc/nauthilus/admin-client.env option for readability.

OpenAPI

python3 contrib/client/nauthilus-admin.py openapi json
python3 contrib/client/nauthilus-admin.py --output body openapi yaml

Cache Flush

# Synchronous single-user flush.
python3 contrib/client/nauthilus-admin.py cache flush alice@example.test

# Enqueue and wait for an asynchronous flush.
python3 contrib/client/nauthilus-admin.py \
  cache flush alice@example.test --async --wait

# Read users from a file, show live progress, and aggregate failures.
python3 contrib/client/nauthilus-admin.py \
  cache flush-file users.txt \
  --async --wait --live --continue-on-error

Use - instead of the filename to read users from standard input. --pending-ok leaves unfinished batch jobs as PENDING instead of turning them into timeout failures.

Brute-force State

python3 contrib/client/nauthilus-admin.py \
  bruteforce list --account alice@example.test --limit 100

python3 contrib/client/nauthilus-admin.py \
  bruteforce flush \
  --ip 203.0.113.10 \
  --rule rule-a \
  --protocol imap

Add --async --wait to enqueue a brute-force flush and wait for its result.

Asynchronous Jobs

python3 contrib/client/nauthilus-admin.py async status JOB_ID
python3 contrib/client/nauthilus-admin.py async wait JOB_ID

--wait-timeout and --wait-interval control polling.

OIDC Sessions

# List token-safe session metadata for a user.
python3 contrib/client/nauthilus-admin.py oidc sessions list alice

# Delete all sessions for a user.
python3 contrib/client/nauthilus-admin.py oidc sessions delete alice

# Delete one session using the non-secret id returned by the list command.
python3 contrib/client/nauthilus-admin.py \
  oidc sessions delete alice --token "$SESSION_ID"

The option remains named --token for compatibility, but its value is the non-secret session-list id. Raw access tokens are not returned by the management API. Use the all-sessions delete operation for complete user-wide access and refresh-token revocation, including dynamic-client token families.

Reputation

The reputation commands call the management operations of the bundled reputation plugin below /api/v1/custom/reputation/. They require a bearer token or OIDC client credentials with nauthilus:admin; the client refuses to send backchannel Basic credentials for them.

# Inspect one exact subject (kinds: ip, network, asn, dns_domain, account, service).
python3 contrib/client/nauthilus-admin.py reputation lookup ip 192.0.2.8
python3 contrib/client/nauthilus-admin.py reputation lookup account --subject-file /run/private/account.txt

# Set an audited operator override; --ttl-seconds 0 means no expiry.
python3 contrib/client/nauthilus-admin.py reputation override put ip 192.0.2.8 \
  --band blocked --ttl-seconds 3600 --reason incident --origin operator --audit-id ticket-123

# Remove it; --previous-audit must name the current override's audit ID.
python3 contrib/client/nauthilus-admin.py reputation override delete ip 192.0.2.8 \
  --previous-audit ticket-123 --reason resolved --origin operator --audit-id ticket-124

# Apply the overrides of a reputation-static-import.v1 artifact; add --continue-on-error to keep going after a failure.
python3 contrib/client/nauthilus-admin.py reputation override import /run/private/static-import.json

# Inspect or drain the allocation before a manifest-key rotation.
python3 contrib/client/nauthilus-admin.py reputation allocation status
python3 contrib/client/nauthilus-admin.py reputation allocation drain \
  --reason key_rotation --origin operator --audit-id rotation-123

--band accepts blocked, trusted, or neutral, and --ttl-seconds accepts 0 to 31536000. --subject-file keeps the subject out of process arguments and shell history; it must contain 1 to 512 UTF-8 bytes, and one trailing newline is removed. Override commands address the active key generation by default; --slot previous addresses the previous one. The client never retries a mutation: after a transport error or timeout it reports that the outcome may be unknown, so inspect the state with lookup or allocation status before repeating the same change. See Reputation Operations for the operational procedures.

Authentication Test

Avoid passwords in shell history. Use --ask-pass or --password-file:

python3 contrib/client/nauthilus-admin.py \
  auth json \
  --user alice@example.test \
  --ask-pass \
  --protocol imap \
  --method plain

The same helper can test --mode no-auth or --mode list-accounts. --no-cache and --no-memory disable the corresponding lookup layers for the request.

Raw Requests

The raw command reaches a management route that does not yet have a convenience subcommand:

python3 contrib/client/nauthilus-admin.py \
  raw GET /api/v1/openapi.json

python3 contrib/client/nauthilus-admin.py \
  raw DELETE /api/v1/cache/flush \
  --data '{"user":"alice@example.test"}'

Use --data-file for sensitive or larger JSON bodies, repeat --query key=value for query parameters, and repeat --header key=value for extra headers. --no-auth deliberately suppresses the authorization header.

Output Formats

--output accepts:

pretty: formatted JSON or text, the default;
json: compact JSON;
body: response body only;
headers: status and response headers as JSON.

For route requirements and response contracts, see REST API and the generated API Reference.

Authentication Configuration​

OIDC Client Credentials​

Pre-issued Bearer Token​

Backchannel Basic Authentication​

TLS and Address Overrides​

Token Cache​

Common Operations​

OpenAPI​

Cache Flush​

Brute-force State​

Asynchronous Jobs​

OIDC Sessions​

Reputation​

Authentication Test​

Raw Requests​

Output Formats​