Before you begin
- A deployed Atlas AVD instance (see Activate Your Trial & What to Expect)
- The Atlas AVD app registration, created for you by the setup link, or by the setup script if you used the manual fallback
- Your Entra tenant ID and the Azure subscription ID where your AVD resources live, if you enter the connection by hand
How the connection works
Atlas authenticates to Microsoft Graph and the Azure management APIs as the Atlas AVD app registration, using its application ID and client secret. There is no standing connection to a service outside your tenant. All resources stay in your subscription; Atlas reads and manages them on your behalf using the Azure roles assigned to the app registration. The client secret is encrypted with AES-256-GCM before it is stored and is never logged or shown again.
Step 1: Review the pre-filled Azure Setup step
The first time you sign in, the first-run wizard opens on Azure Setup. When you deployed from the setup link, the Azure Credentials card shows App registration configured from ARM template: the Application (Client) ID and Client Secret were passed in by your deployment, and the Azure Environment, Tenant Directory ID and Primary Subscription ID are marked from deployment. Enter an Organization Name, check the values, and click Continue.
- Azure Environment: Azure Commercial, Microsoft 365 GCC (Azure Commercial), or Azure Government (GCC High). When your deployment sets it, the field is locked to the cloud Atlas was deployed for.
- Tenant Directory ID: your Microsoft Entra directory ID (Azure Portal > Microsoft Entra ID > Overview).
- Primary Subscription ID: the subscription that holds your AVD host pools (Azure Portal > Subscriptions).
The secret shows Configured (not yet verified) until the next two steps sign in with it. Nothing is tested until you click Continue.
Step 2 (only if needed): Enter credentials by hand
If you used the setup script, created the app registration yourself, or need to use a different app registration, click Override with different credentials and confirm with Change credentials. Paste the Application (Client) ID and Client Secret from the app registration, confirm the Tenant Directory ID and Primary Subscription ID, and click Continue. The wizard warns you that the new values permanently replace the ones from your deployment; click Cancel override to go back to them.
- Application (Client) ID: App registrations > Atlas AVD > Overview.
- Client Secret: App registrations > Atlas AVD > Certificates & secrets. Copy the secret's Value, not its Secret ID.
Azure shows a client secret's value only once, when you create it. If you no longer have it, create a new secret on the app registration and paste that.
Step 3: Check permissions
On the Permissions step, Atlas signs in with the credentials and checks what the app registration has been granted: Microsoft Graph, Defender ATP, Exchange Online, Security & Compliance, Entra roles, and Azure RBAC roles. The setup link grants all of these for you, so on the normal path every tile is complete. Missing optional permissions only turn off the features that use them; you can continue and fix them later. See the First Run Wizard guide for the full permissions screen.
Authentication failed means Atlas could not sign in at all, so no permissions were checked. Click Back to Azure Setup and re-check the Tenant Directory ID, Application ID and Client Secret.
Step 4: Test the connection
The Confirm step shows a summary of the connection. Click Test Connection: Atlas connects to Azure, authenticates the app registration, and checks that it can reach the subscription. When all four validation results are green (Azure tenant connected, Service principal authenticated, Subscription accessible, Ready to manage host pools), click Continue to finish the rest of the wizard.
If your plan manages a single host pool and the subscription has several, the Confirm step also asks you to choose the one Atlas AVD will manage. The others stay in Azure, untouched.
If the connection test fails
- Re-check the Tenant Directory ID and Primary Subscription ID for typos, and that the Azure Environment matches the cloud your directory is in.
- Confirm the Application ID and Client Secret belong to the Atlas AVD app registration and that the secret has not expired.
- Subscription not reachable means the ID is wrong or the app registration has no role on that subscription. Check its role assignments under Subscriptions > Access control (IAM).
- Make sure admin consent was granted for the app registration's API permissions.
Most failures come from a client secret that was copied wrong or has expired. Creating a new secret and entering it with Override with different credentials is the quickest fix.
Testing or updating the connection later
The subscription you connect in the wizard becomes your primary tenant. To check it any time, go to Administration > Tenants > Tenant List and open the tenant's actions menu. Test Credentials signs in and reports how many resource groups it found in the subscription. Use Manage to enter a new Application ID or Client Secret, for example before the current secret expires. To see which Azure roles and Microsoft Graph permissions are in place, click the tenant's name to open its detail page and use Check IAM Roles and Check APIs.
Connecting more tenants
On Atlas AVD you can connect more Azure tenants, up to your licensed tenant quantity, with Add Tenant on the Tenant List page, which runs the same Azure Setup, Permissions and Confirm steps for the new tenant. Each tenant keeps its own isolated data. Every managed tenant counts toward the quantity, including the first one. Community manages a single tenant.