Skip to main content

Connect an Azure subscription

Connecting Azure lets Retrievy's CSPM scanner audit your subscriptions, your Entra ID tenant, and your Microsoft 365 posture in one shot. Findings flow into the Command Center and feed your Retrievy Index the moment the first scan lands.

Azure has two onboarding paths. Quick Connect is the recommended path for most workspaces. Manual app registration is for organisations whose security policy forbids third-party multi-tenant apps in their Entra tenant.

Before you start​

You need:

  • An Azure tenant where you (or a tenant admin) can grant admin consent and assign RBAC roles.
  • A Retrievy workspace with CSPM enabled (every plan).
  • The manage-cloud-accounts permission in Retrievy.
  • One free data-source slot on your plan. See plan feature matrix for slot counts per plan.

Pick one of the two paths below.

Path A — Quick Connect (recommended)​

Quick Connect uses Retrievy's multi-tenant Entra app. You click through an admin-consent screen on Microsoft's side, then assign the Reader role on each subscription you want scanned. No secrets to copy, no app registration to maintain.

Step A1. Start the Quick Connect flow​

In Retrievy:

  1. Open Settings → Cloud Integrations. Click Add Cloud Account.
  2. On the IDENTIFY TARGET step, pick Azure, then click Connect with Azure in the panel that appears.
  3. Retrievy redirects you to Microsoft's login.microsoftonline.com consent screen. Sign in with a tenant-admin account.
  4. The consent screen lists the permissions Retrievy is requesting (see the table below). Click Accept.
PermissionTypeWhy Retrievy needs it
AuditLog.Read.AllMicrosoft Graph (Application)Reads sign-in logs and directory audit logs for ISPM findings.
Directory.Read.AllMicrosoft Graph (Application)Enumerates users, groups, roles for the ISPM module.
Policy.Read.AllMicrosoft Graph (Application)Reads conditional access and authentication policies.

After consent, Microsoft redirects you back to Retrievy and the wizard moves to step A2 with a green Tenant connected banner.

Step A2. Assign the Reader role on your subscriptions​

The Graph permissions cover identity. Cloud scans (resource posture, network rules, storage encryption, etc.) need Azure RBAC. Retrievy never elevates itself, so you assign the role manually.

In the Azure portal, for each subscription you want Retrievy to scan:

  1. Open Subscriptions → click the subscription name.
  2. Open Access control (IAM) → Add → Add role assignment.
  3. Search for Reader and select it. Click Next.
  4. On Members, switch to User, group, or service principal and search for Retrievy (the app name Microsoft created during consent). Pick it.
  5. Click Review + assign.

Repeat for every subscription you want scanned. Reader at the subscription level is required; resource-group-scoped Reader is not enough.

Step A3. Validate and run​

Back in Retrievy:

  1. Click Validate permissions on the wizard. Retrievy uses the consent it received to request an Azure Resource Manager token, then calls GET /subscriptions to count what's visible.
  2. If the count is greater than zero, the green Reader role confirmed on N subscription(s) message appears and the Run first scan button enables.
  3. Click Run first scan. The wizard closes; the new account card shows Scanning....

If the count is zero, see the Troubleshooting section below — most likely the role assignment hasn't propagated yet (Azure can take up to 5 minutes), the role is on the wrong scope (resource group instead of subscription), or you assigned the role to a user instead of the Retrievy service principal.

Path B — Manual app registration​

Use this path if your security policy forbids multi-tenant apps. You create your own single-tenant app registration in Entra, paste its credentials into Retrievy, and skip Microsoft's consent flow entirely.

Step B1. Create the app registration on Azure​

In the Azure portal:

  1. Open Entra ID → App registrations → New registration.
  2. Name it retrievy-cspm-reader (or anything you like). Leave Supported account types on Single tenant. Skip the redirect URI.
  3. Click Register. Copy the Application (client) ID and Directory (tenant) ID from the overview page; you'll paste them into Retrievy in step B3.

Step B2. Add Graph permissions and a client secret​

Still on the new app registration:

  1. Open API permissions → Add a permission → Microsoft Graph → Application permissions.
  2. Tick AuditLog.Read.All, Directory.Read.All, Policy.Read.All. Click Add permissions.
  3. Back on the API permissions list, click Grant admin consent for [your tenant]. The status column flips to green check marks.
  4. Open Certificates & secrets → New client secret. Give it a description (retrievy), pick an expiry (24 months is fine; Retrievy reminds you 30 days before it expires), and click Add.
  5. Copy the Value column immediately. It's only shown once.

Step B3. Assign the Reader role on your subscriptions​

Same as Path A, step A2, but search for the app name you created in step B1 instead of "Retrievy". Assign Reader at the subscription scope.

Step B4. Add the account in Retrievy​

In Retrievy:

  1. Open Settings → Cloud Integrations → Add Cloud Account.
  2. Pick Azure on the IDENTIFY TARGET step. Click Use manual credentials at the bottom of the panel.
  3. The INGEST CREDENTIALS step shows four fields:
FieldWhat to paste
Tenant IDThe Directory (tenant) ID from step B1. UUID format.
Client IDThe Application (client) ID from step B1. UUID format.
Client SecretThe secret value you copied in step B2. Masked.
Subscription IDOptional. Leave blank to scan every subscription the Reader role is assigned on; paste a single subscription ID to scope the scan to one.
  1. Click Next. Retrievy tests the credentials by requesting an ARM token. If it fails, the wizard surfaces the exact OAuth error from Microsoft.
  2. On success, the wizard moves to SYNC PROTOCOL and queues the first scan. The new account appears in the cloud accounts list as Scanning....
caution

The client secret is a long-lived credential with read access to your tenant. Treat it like a password. Rotate it before it expires (Retrievy reminds you 30 days out) and revoke it from the Azure portal the moment you remove the account from Retrievy.

What you see in the account list​

Same as every other cloud account. The Cloud Integrations page shows your Azure account as a card with:

  • Friendly account name.
  • Active or Inactive status badge.
  • Scan state pill: Scanning..., Scan Success, Scan Failed.
  • Last scan timestamp.
  • The three actions: Scan Now, Test Connection, Deactivate.

Quick Connect accounts carry a small Quick Connect badge so you can tell them apart from manual accounts at a glance.

What Retrievy scans​

The Azure CSPM module covers the standard service-by-service audit set: storage account encryption and public access, network security groups, key vault access policies, SQL database TDE, virtual machine OS disk encryption, App Service settings, Defender for Cloud recommendations, and more.

Identity scans (run by the ISPM module against the same credentials) cover: privileged role members, stale accounts, conditional access policy gaps, weak MFA enforcement, and guest user sprawl.

Every finding lands with its compliance mappings attached (CIS Azure, NIST CSF, NIST 800-53, ISO 27001, SOC 2, PCI DSS 4.0, HIPAA, MITRE ATT&CK, and more), so you can switch between the Kanban view and the Compliance Hub view of the same data.

Rotating credentials​

Quick Connect: No rotation. The OAuth grant is renewed automatically.

Manual:

  1. In Azure, App registrations → your app → Certificates & secrets → New client secret. Copy the new value.
  2. In Retrievy, open the account detail → Update credentials → paste the new secret in place of the old one. Click Save.
  3. Once Retrievy confirms it's using the new secret (a fresh Test Connection passes), delete the old secret in Azure.

Revoking access​

Quick Connect:

  1. In Retrievy, click Deactivate on the account card (pauses scans) or remove the account entirely (deletes the record).
  2. In Azure, Entra ID → Enterprise applications, find Retrievy, and either remove the role assignments or delete the service principal.

Manual:

  1. Remove the account from Retrievy.
  2. In Azure, delete the app registration (this removes its client secrets and all role assignments).

Troubleshooting​

Symptom: Consent screen shows the Need admin approval message and won't let me continue. → Fix: Quick Connect requires a tenant admin to grant consent for the Application permissions. Either ask your Entra admin to run the wizard with you, or send them the consent URL Retrievy generated and have them complete it; your account picks up the granted state next time you open the wizard.

Symptom: Validate permissions says No subscriptions visible, but I assigned Reader on two subscriptions. → Fix: Three things to check, in order. (1) Wait 5 minutes; Azure RBAC propagation isn't instant. (2) Open the subscription in Azure, Access control (IAM) → Role assignments, and confirm the assignment is Reader at the subscription scope, not at a resource group. (3) Confirm you assigned the role to the right service principal — for Quick Connect, search for Retrievy; for manual, search for the app name you registered.

Symptom: Test Connection on a manual account fails with AADSTS7000215: Invalid client secret provided. → Fix: The secret was pasted incorrectly, has expired, or was rotated in Azure without updating Retrievy. Open Certificates & secrets in Azure; if the Expires column is in the past, create a new secret and update Retrievy.

Symptom: First scan succeeds but every Defender for Cloud finding is empty. → Fix: Reader at subscription scope is enough to read Defender recommendations only if Defender is enabled on the subscription. Enable Microsoft Defender for Cloud in the relevant subscription (any plan tier works for visibility) and re-scan.

Symptom: The account card shows Inactive even though I just connected it. → Fix: The first scan likely failed. Click the account name to open the detail, scroll to Scan history, and read the last failure reason. Most common cause: the service principal lost its Reader role (someone removed it from the subscription) or the client secret expired.

Symptom: Wizard step IDENTIFY TARGET doesn't show the Connect with Azure button. → Fix: Quick Connect is enabled on every plan today but requires the CSPM module to be active. If your workspace was created with a custom feature set, contact support to confirm CSPM is on.