Connect Azure

Zaysa connects to an Azure subscription without a client secret. You register an Entra ID app with a federated credential that trusts Zaysa's issuer, https://zaysa.io, for exactly one subject tied to your Zaysa user and the app's client ID. Azure issues a temporary access token for each scan. Zaysa stores no long-lived cloud secret for this connection.

Choose how to connect

Before you start

• A Zaysa account. New here? Start with Getting started.
• Permission to register applications in Entra ID, such as Application Developer or higher, and Owner or User Access Administrator rights to assign roles on the subscription.
• Access to Azure Cloud Shell in Bash, with the subscription you want to scan selected. You can also follow the portal steps below.

What Zaysa gets

See the Permissions reference for each feature's exact grants and what happens without them. The default subscription roles are Reader Cost Management Reader .

Connect with keyless access

Option A: Cloud Shell script

1. Choose Azure and name the account

   In Zaysa, open Resources → Cloud Accounts and click Connect account. (1) Choose Microsoft Azure under Cloud Provider. (2) Fill Account Name. (3) Leave Keyless selected.

   

2. Run the script in Azure Cloud Shell

   Under Run this once in Azure Cloud Shell (Bash), click Open Cloud Shell (1) and choose Bash if asked. Check the selected subscription with az account show. Back in Zaysa, click Copy (2), paste the entire block into Cloud Shell and press Enter.

   

   The script creates or reuses the app and service principal, adds the federated credential, and grants Reader and Cost Management Reader on the selected subscription. At the end, it prints Application (client) ID, Directory (tenant) ID, and Subscription ID, each with its label for pasting into Zaysa.

3. Enter the three IDs and connect

   Paste those values into Application (client) ID, Directory (tenant) ID, and Subscription ID. Click Connect Account. Zaysa first says Cloud account connected — verifying the cloud trust…, then Cloud trust verified — scans & deploys will authenticate when Azure accepts its token. A new federated credential can take a minute to propagate; click Verify again if the first check fails.

   Asked to sign in again?

   Connecting a cloud account is a sensitive action. If you signed in more than 30 minutes ago, Zaysa asks you to sign in again with your email and password (and your authenticator code, if you use one), then brings you back to Cloud accounts. Open Connect account again and repeat the last two steps: the app and roles in Azure are already there.

Option B: Console, click by click

Choose Console, click by click (1) in Zaysa. The credential's subject depends on the app's client ID, so enter that ID in Zaysa before copying the subject.

1. Register the app and copy its IDs

   Open App registrations → New registration. Set Name to Zaysa, Supported account types to Accounts in this organizational directory only, and leave Redirect URI empty. Click Register. On Overview, copy Application (client) ID and Directory (tenant) ID into Zaysa.

2. Add the federated credential

   In the app, open Certificates & secrets → Federated credentials → + Add credential. Choose Other issuer. Copy Issuer, Subject identifier, Name, and Audience from the guide in Zaysa. The subject appears only after you enter the app's client ID. If the portal shows Type, choose Explicit subject identifier and paste the subject into Value. Click Add.

3. Grant the two subscription roles

   Open Subscriptions, select your subscription and copy its Subscription ID into Zaysa. In the subscription, open Access control (IAM) → + Add → Add role assignment. On the Role tab, choose Reader. On Members, set Assign access to to User, group, or service principal, choose + Select members, find Zaysa, and click Select → Review + assign. Repeat for Cost Management Reader, then click Connect Account in Zaysa.

Beam also needs

For just-in-time human access, Beam creates a separate app and service principal for each grant and deletes them when the grant ends. The subscription must be enabled. The connected app needs permission to write role assignments on that subscription and the admin-consented Microsoft Graph permission Application.ReadWrite.OwnedBy. Beam › Connections › Check readiness checks these requirements and gives the exact fix.

Connect with a client secret

Choose Access Keys / Secret (1) only when keyless access is unavailable. Zaysa stores the secret encrypted. It expires after a year, so you must replace it before then. A stored secret carries standing access risk.

Option A: Cloud Shell script

1. Create the app, roles and secret

   In the client-secret guide, click Copy. Open Azure Cloud Shell in Bash, check the selected subscription with az account show, paste the block and press Enter. It creates or reuses Zaysa, creates its service principal if needed, grants Reader and Cost Management Reader, and adds one secret valid for one year without replacing existing secrets. It prints four values: Directory (tenant) ID, Application (client) ID, Client secret and Subscription ID. Copy the secret when it appears.

2. Paste and test the four values

   Enter the IDs into Tenant ID, Client ID (App ID), and Subscription ID. Paste the secret into Client Secret. Click Test Connection, then Connect Account. If a new role assignment has not propagated yet, use Verify again.

Option B: Azure portal

1. Register the app and create its secret

   Open App registrations → New registration. Register Zaysa for Accounts in this organizational directory only, with no redirect URI. On Overview, copy the client and tenant IDs. Open Certificates & secrets → Client secrets → + New client secret. Set Description to Zaysa, Expires to 365 days (12 months) and click Add. Copy Value now, not Secret ID.

2. Grant access and connect

   Open Subscriptions. Copy the Subscription ID, then use Access control (IAM) → Add role assignment to grant Reader and Cost Management Reader to the Zaysa service principal. Enter the four values in Zaysa, click Test Connection, then Connect Account.

Rotate a secret

Create a new client secret in Entra ID. In Zaysa, open FinOps → Optimization. Under Connected cloud accounts, open the account's ⋮ menu and click Edit account & billing. Paste the new secret into Client Secret and click Save Credentials. Then delete the old secret in Entra ID.

Add the billing export (optional)

Choose Cost Management API for real invoiced cost without a storage account. It uses the connected identity and needs Cost Management Reader on the subscription. The keyless script already grants this role.

Cost Management API

If you connected through the portal and skipped the role, use the billing guide's Cloud Shell script or open Subscriptions → your subscription → Access control (IAM) → + Add → Add role assignment. Grant Cost Management Reader to Zaysa. There are no billing fields to fill. Click Save & Continue while connecting, or Save Billing Config for an existing account, then Test. Zaysa starts a daily cost sync immediately; a subscription created in the last 48 hours may not have cost data yet.

Export to blob storage for EA or MCA billing scopes

Choose Billing Export if you use the EA or MCA export path. Fill Storage Account Name, Storage Container, Storage Directory, and Export Name before copying the guide script. Its suggested export name is zaysa-export. If the storage account field is empty, the script generates a name from the subscription ID, creates it in zaysa-billing in East US, and prints the name to enter in Zaysa.

For the script path, click Copy and run the block in Azure Cloud Shell (Bash). It creates a daily month-to-date actual cost export as CSV, grants the app Storage Blob Data Reader on the storage account, and starts one export run.

For the portal path, open Cost Management → Exports → + Create. Choose Create your own export → Next. On Datasets, click + Add export, choose Cost and usage details (actual) and Daily export of month-to-date costs, and set the export name to match Zaysa. Click Add → Next. Under Destination, choose Azure blob storage and Use existing, then enter the storage account, container and directory. Set Format to CSV and Compression type to None or Gzip. Finish with Review + create. On the storage account, grant Storage Blob Data Reader to Zaysa through Access control (IAM).

Enter the storage values in Zaysa and click Save & Continue or Save Billing Config, then Test. Zaysa reads the newest CSV for the current and previous month. A new export can take up to 24 hours to deliver its first file, though the script starts one run right away.

Check it worked

Click Check permissions on the card to see which features are ready in this connection; the Check permissions guide explains the results.

The connected account card shows Keyless, Connected, and the subscription. Use Run scan to scan it. The first scan guide explains the results.

If something goes wrong

Subscription is disabled

The keyless script was run on a disabled subscription and stopped safely with this output:

→ Setting up keyless access for subscription 00000000-0000-0000-0000-000000000000…
❌ Subscription 00000000-0000-0000-0000-000000000000 is DISABLED (read-only) — Azure refuses every change until billing re-enables it: portal → Cost Management + Billing → this subscription → Reactivate. Then paste this block again.

No subscription selected

The script prints this message if Cloud Shell has no selected subscription:

❌ No Azure subscription is selected in this shell. Run:  az account list -o table   then:  az account set --subscription YOUR_SUBSCRIPTION_ID   and paste this block again.

Could not create the service principal

The script prints "Could not create the service principal for app" followed by the app ID and "Your account needs permission to register applications (Application Developer or higher)." Ask your Entra ID administrator for that permission, then run the block again.

Several apps are named Zaysa

The script stops if several app registrations share the name Zaysa and none trusts the Zaysa issuer. It prints the count and IDs, then says "Rename the ones that are not for Zaysa (Entra ID → App registrations), then paste this block again." Rename them, then paste the block again.

Could not assign a role

If the script says it could not assign Reader or Cost Management Reader, your account needs Owner or User Access Administrator on that subscription. If trust verification fails just after setup, wait a minute and click Verify again.

Remove access

In Entra ID → App registrations, delete the Zaysa app registration to end this connection, or remove only its federated credential if the app serves another purpose. Remove the app's Reader and Cost Management Reader role assignments from the subscription. For a client-secret connection, delete its secret too. To remove the account from Zaysa, click the bin icon on its card.

Next steps