Hygiara
Sign In
Documentation / Connections And Credentials

Connections And Credentials

Azure Permissions

What Azure role Hygiara needs, how to create a service principal, and where to find the credentials.

What this page is for

This page explains what Azure access Hygiara needs and how to set it up. If you are about to add a saved connection and are not sure where to get the credentials, start here.

What Hygiara needs

Hygiara uses a service principal to authenticate against the Azure Management API.

The minimum requirement is:

  • an App Registration in Microsoft Entra ID (formerly Azure AD)
  • a client secret on that app registration
  • the Reader role assigned to that service principal on each subscription you want to review (or at a management group level to cover multiple subscriptions)

If you plan to enable Landing Zone assessment, the service principal also needs visibility of your management group hierarchy. Assign the Reader role at the root management group, or at the highest management group that covers the subscriptions in scope.

Step 1 — Create an App Registration

  1. Sign in to the Azure portal.
  2. Go to Microsoft Entra ID (search for it in the top bar).
  3. In the left menu, click App registrations.
  4. Click New registration.
  5. Give it a name — for example: hygiara-reviewer.
  6. Leave the redirect URI blank.
  7. Click Register.

Once registered, you land on the app overview page. This is where you will find your Tenant ID and Client ID.

Step 2 — Note your Tenant ID and Client ID

On the app registration overview page:

  • Application (client) ID → this is your Client ID
  • Directory (tenant) ID → this is your Tenant ID

Copy both values. You will enter them into the Hygiara connection form.

Step 3 — Create a Client Secret

  1. In the left menu of the app registration, click Certificates & secrets.
  2. Click New client secret.
  3. Give it a description (for example: hygiara) and set an expiry.
  4. Click Add.

Important: Copy the secret Value immediately. It is only shown once. After you leave this screen, you cannot retrieve it again.

Step 4 — Assign the Reader role

The service principal needs the Reader role on each subscription you want Hygiara to review.

To assign at subscription level:

  1. Go to Subscriptions in the Azure portal.
  2. Open the subscription.
  3. Click Access control (IAM) in the left menu.
  4. Click Add role assignment.
  5. Select Reader.
  6. On the Members tab, click Select members.
  7. Search for the app registration name you created (for example: hygiara-reviewer).
  8. Select it and click Review + assign.

To assign at management group level (covers multiple subscriptions):

Follow the same steps but navigate to Management groups instead of Subscriptions, and assign the Reader role there. This is the right approach if you want to review many subscriptions with a single connection.

What to enter in Hygiara

When you add a saved connection in Hygiara, enter:

Field Value
Name A friendly label for this connection
Tenant ID Directory (tenant) ID from the app registration overview
Client ID Application (client) ID from the app registration overview
Client Secret The secret value you copied in Step 3

What the validation step checks

When you save the connection, Hygiara validates it by:

  1. Authenticating against Microsoft Entra ID using the client credentials you provided
  2. Calling the Azure Management API to list accessible subscriptions

If validation succeeds, Hygiara shows you how many subscriptions it can see. If it fails, the most common causes are:

  • The tenant ID or client ID is wrong
  • The client secret has expired or was entered incorrectly
  • The Reader role has not been assigned yet (or the assignment has not propagated — allow a few minutes)

Common mistakes

  • Copying the Object ID instead of the Application (client) ID — they are different fields on the same page
  • Letting the client secret expire without updating the saved connection
  • Assigning the Reader role to a different service principal than the one you registered
  • Expecting subscription visibility before the role assignment has propagated

Next step