Authentication

Overview

ZopNight authenticates in two directions:

1. To your cloud: using the cloud’s native identity primitive (IAM role, service principal, workload identity). Credentials are AES-256-GCM encrypted at rest with per-account envelope keys and decrypted only at the call site.
2. From your tools to ZopNight: using personal access tokens (PATs) for the REST API and the MCP server.

ZopNight is read-only by default. Write permissions are opt-in, per rule category, and can be scoped to a single resource group.

Authenticating to AWS

ZopNight supports several AWS connect modes: WIF-Assume Role (recommended; a keyless cross-account IAM role), IAM User / Static Keys, and Temporary Credentials (STS). See Cloud accounts for how to pick and switch between them.

WIF-Assume Role (recommended)

The wizard generates a trust policy that allows ZopNight’s audit account to call sts:AssumeRole with an external ID. The external ID is unique per workspace and is shown only once in the wizard.

The read-only policy attaches the AWS-managed ReadOnlyAccess policy plus a small inline policy for resource discovery on services that aren’t covered by the managed policy. The full document is shown in the wizard and can be downloaded as JSON. This is the broad, simplest grant; for the exact policy and the least-privilege alternative, see Cloud permissions.

Rotation cadence: the external ID rotates only on user request. The trust policy itself does not expire; if you remove the role on your side, the connection moves to unreachable and the account is flagged in Settings → Cloud accounts. Recheck the role and external ID, then re-verify, or contact support.

IAM User / Static Keys

Supported for organisations that haven’t adopted WIF-Assume Role. Keys are encrypted at rest. We strongly recommend rotating these every 90 days and migrating to WIF-Assume Role when possible.

Authenticating to GCP

ZopNight supports two GCP connect modes: One-Click Connect (recommended) and Service Account Key.

One-Click Connect (recommended)

Sign in with Google and grant consent; ZopNight provisions and manages a dedicated read-only service account in your project. No long-lived keys are created or stored on your side.

Service Account Key

Supported for accounts where One-Click Connect isn’t possible. You provide a service-account JSON key; it is encrypted at rest and never logged.

The simplest grant is roles/viewer on the project (or organisation, for org-scope connects). For the exact least-privilege roles (roles/monitoring.viewer plus roles/cloudasset.viewer), see Cloud permissions. For billing you also need:

• roles/billing.viewer if billing exports are not yet wired to BigQuery
• roles/bigquery.dataViewer on the billing export dataset

Authenticating to Azure

ZopNight supports two Azure connect modes: Service Principal (recommended; app registration plus client secret) and Workload Identity Federation (OIDC, no secret).

Service Principal (recommended)

The wizard generates a service principal (an app registration plus client secret) that ZopNight uses to authenticate to your subscription. The client secret is encrypted at rest and never logged.

Workload Identity Federation

Supported for subscriptions that can issue federated credentials. ZopNight’s tenant acts as a configured app registration through a federated credential, so no client secret is stored.

The simplest grant is the built-in Reader role on the subscription (or management group, for tenant-scope connects). For the least-privilege role (Monitoring Reader), see Cloud permissions. For billing you also need:

• Cost Management Reader for cost queries
• Storage Blob Data Reader on the storage account that hosts the billing export (Azure-EA / MCA exports)

Personal access tokens (PATs)

Use PATs to authenticate to the REST API and the MCP server from your own tools. Mint a PAT from Settings → Access tokens.

• Scope tokens to the read-only scope unless you specifically need write.
• Tokens are shown once at creation. Store them in your secret manager.
• Tokens are tied to your user; rotate or revoke them when your role changes.
• The MCP server rejects every write request at the protocol layer regardless of token scope.

API request example

curl https://api.zop.dev/v1/recommendations \
  -H "Authorization: Bearer $ZOPNIGHT_PAT" \
  -H "Content-Type: application/json"

Token rotation

PATs do not expire by default. Enable Token rotation policy on the Enterprise tier to enforce 90-day rotation. Expired tokens move to a 7-day grace state with a banner in the UI; revoked tokens fail immediately.

Audit trail

Every authentication event (connect, role assumption, PAT issuance, PAT use) is captured in the audit log with actor, action, timestamp, and request body. The trail is append-only and can be forwarded to your SIEM on the Enterprise tier.