Authentication
Choose how ZopNight authenticates to AWS, GCP, and Azure, and create personal access tokens for the REST API and MCP server.
ZopNight authenticates in two directions: to your cloud, using each provider’s native identity primitive, and from your own tools to ZopNight, using personal access tokens (PATs). This page covers both, so you can pick the most secure connect mode for each cloud account and give scripts and AI assistants the narrowest access they need.
Before you start
- Admin access on the provider side, enough to create the IAM role, service account, or app registration the connect wizard asks for. See Cloud accounts for the full per-provider checklist.
- The permissions you want to grant. Cloud permissions lists the metrics, discovery, billing, and start/stop grants per cloud.
- For PATs: access to Settings → API & MCP → API Tokens in the organisation you want to call.
How it works
- To your cloud: ZopNight uses the cloud’s native identity primitive (IAM role, service account, service principal, workload identity). Stored credentials are encrypted at rest with AES-256-GCM in ZopNight’s credential vault.
- From your tools to ZopNight: personal access tokens authenticate the REST API and the MCP server. For MCP specifically, OAuth 2.1 is the recommended path; see the MCP setup guide.
You choose what ZopNight may do per cloud account: each account carries a permission level, Read-only or Read + Write, and only a Read + Write account can have resources started, stopped, or remediated. See Read-only vs read + write.
| Cloud | Connect modes | Recommended | Long-lived secret stored? |
|---|---|---|---|
| AWS | WIF-Assume Role, IAM User / Static Keys, Temporary Credentials (STS) | WIF-Assume Role | No, with WIF-Assume Role |
| GCP | One-Click Connect, Service Account Key | One-Click Connect | ZopNight mints and holds the managed service account’s key; you never handle one |
| Azure | Service Principal, Workload Identity Federation | Service Principal | No, with Workload Identity Federation |
Authenticating to AWS
ZopNight supports three 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)
You create an IAM role in your account, and ZopNight assumes it through Workload Identity Federation (sts:AssumeRoleWithWebIdentity). There is no external ID and no long-lived secret to store: you grant the role, and ZopNight assumes it. The account is identified from the role ZopNight actually assumed, not from the ARN you typed.
The wizard’s setup guide shows the role and policies to create. Cloud permissions lists the metrics, discovery, and billing policies. For a least-privilege, describe-only discovery list, contact support.
Rotation: there is no secret to rotate. If you remove the role on your side, ZopNight can no longer read the account. Recreate the role, or open the account in Settings → Cloud Accounts and use Update credentials to point it at a new one.
IAM User / Static Keys
Supported for organisations that haven’t adopted WIF-Assume Role. Keys are encrypted at rest. Rotate them regularly with Update credentials (ZopNight verifies the new keys resolve to the same AWS account before saving them), and move to WIF-Assume Role when you can.
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 then provisions and manages a dedicated service account in your project and binds the roles for the permission level you chose (Read-only or Read + Write). ZopNight mints and holds that service account’s key, so you never download or handle one. The Google user who signs in must be able to administer the project’s IAM.
Service Account Key
Supported for accounts where One-Click Connect isn’t possible. You provide a service-account JSON key. The key is encrypted at rest.
The simplest grant is roles/viewer on the project. For the narrower roles (roles/monitoring.viewer plus roles/cloudasset.viewer), see Cloud permissions. For billing, you also need roles/bigquery.dataViewer and roles/bigquery.jobUser on the billing project.
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)
You create an app registration with a client secret and give ZopNight its client ID, secret, and tenant. ZopNight uses it to authenticate to your subscription. The client secret is encrypted at rest.
Workload Identity Federation
Supported for subscriptions that can issue federated credentials. The app registration trusts ZopNight through federated OIDC credentials, so there is no client secret to store.
The simplest grant is the built-in Reader role on the subscription. For the narrower role (Monitoring Reader), see Cloud permissions. For billing, you also need Cost Management Reader for cost queries.
Sign-in methods
People sign in to ZopNight with GitHub, Google, SSO, or email. SSO uses SAML, with your IdP configured per email domain by the ZopNight team; domain matching at the sign-in page routes each user to the right IdP. See the Quickstart for the sign-in and first-run flow.
Personal access tokens (PATs)
Use PATs to authenticate to the REST API and the MCP server from your own tools. For MCP specifically, OAuth 2.1 is the recommended path; see the MCP setup guide.
Open API Tokens
Go to Settings → API & MCP → API Tokens.
Scope the token
Limit the token to the organisations and write capabilities it needs. A token with no write capabilities can only read.
Copy and store it
Copy the token when it is created and store it in your secret manager; the list shows only its prefix afterwards.
- Every token has an expiry date, shown in the Expires column. Expired tokens are marked Expired and stop working.
- Tokens are tied to your user; rotate or revoke them from the row’s actions when your role changes.
- MCP writes are gated three ways: an admin enables writes for the organisation, the token carries a matching write capability, and your role allows the underlying action. If any of the three is missing, the call is refused. See the MCP setup guide for the full flow.
API request example
Every route is scoped to an organisation. Replace $ZOPNIGHT_API with your ZopNight API host and $ORG_ID with your organisation ID:
curl "$ZOPNIGHT_API/orgs/$ORG_ID/recommendations?status=open" \ -H "Authorization: Bearer $ZOPNIGHT_PAT"See Compute API and Cost query API for the routes.
Audit trail
Every mutating request (create, update, delete), including those made with a PAT, is captured in the audit log with actor, action, timestamp, and request body. MCP tool reads are logged too, with the request only. Browse it under Activity → Audit Logs. The trail can be forwarded to your SIEM.
Troubleshooting
ZopNight can no longer read an AWS account
With WIF-Assume Role, ZopNight loses access as soon as the role is removed on your side. Recreate the role, or open the account in Settings → Cloud Accounts and use Update credentials to point it at a new one.
Update credentials rejects new AWS keys
ZopNight verifies that new keys resolve to the same AWS account before saving them. Keys from a different account are refused and nothing changes. See Rotate credentials or switch auth method.
A token stopped working
Check the Expires column in Settings → API & MCP → API Tokens. Expired tokens are marked Expired and stop working; create a new one.
An MCP write call is refused
All three gates must pass: writes enabled for the organisation by an admin, a matching write capability on the token, and a role that allows the action. Check each one; see the MCP setup guide.