Connect a Microsoft 365 tenant

Overview

Connecting a tenant gives Tenant Manager read access to a Microsoft 365 tenant through an app registration in Microsoft Entra ID. You enter the app registration's details, Tenant Manager checks them against Microsoft, and then it starts the tenant's first sync.

This article covers both ways to connect a tenant: the Set up Tenant Manager dialog for your first tenant, and Add tenant for every tenant after that.

Business value

A connected tenant is what fills Tenant Manager with real data. After the first sync you can see who holds which license, what is idle, and what it costs. Tenant Manager reads the tenant and never changes anything in it without an approval or an automation you switch on.

Prerequisites

Before you connect a tenant, make sure you have:

• Tenant Manager switched on for your account. Once the Turbo360 team approves your access request, the Request access button on the Home page changes to Get started. If you haven't requested access yet, see Request access to Tenant Manager.
• An app registration in the tenant's Microsoft Entra ID, with its Directory (tenant) ID, Application (client) ID, and a client secret. Copy the secret value, not the secret ID.
• The required Microsoft Graph permission listed under Dependencies, granted to the app registration as an Application permission with admin consent. You can add the optional permissions now or later.
• AuditLog.Read.All and RoleManagement.Read.Directory, if you want reports and automations to run for the tenant. Without them, each sync logs an issue and the tenant is marked as failing. Reports on it are abandoned, and automations remove nothing.

Alternatively, you can reuse a service principal that is already saved in your account, including one added in another module, and not yet connected to a tenant.

Required permissions

You need the Manage tenants permission, which the Owner and Contributor roles include. For details, see Roles and permissions in Tenant Manager.

• To connect your first tenant, select Get started on the Home page. The button shows on the Home card only until your top-level tenant group exists, not while the tenant count is zero. If you delete every tenant later, it doesn't come back, and the Home card shows zeros. Select Add tenant on the empty tenant group instead. The Owner and Contributor roles can use it. With a custom product-wide role, the button is disabled with the tooltip "You are not authorized to perform this operation". Users whose access is limited to specific tenant groups or tenants can't use Get started. Adding a tenant at the top level needs access to the whole module.
• To add a tenant to a tenant group, you need Manage tenants on that tenant group. The Owner and Contributor roles always include it, so this affects only custom roles.

Dependencies

Tenant Manager checks the app registration against Microsoft Graph. The first permission is required. The others are optional and switch on specific features. You can grant an optional permission at any time. After you grant an optional read permission, sync the tenant so Tenant Manager picks it up.

For approved changes, the permission you need depends on the type of change. For each type, any one of the permissions listed is enough. If none of them is granted, ask your Microsoft Entra administrator to grant one of them.

Turbo360 notices a granted or removed write permission within about 5 minutes, so Approve and automation can lag a short time behind a change in Microsoft Entra ID. Syncing the tenant does not speed this up.

Network access matters if your private hosted Turbo360 instance sends outbound traffic through a proxy or firewall. Allow outbound HTTPS (443) to login.microsoftonline.com, graph.microsoft.com, management.azure.com, download.microsoft.com, and reports.office.com. The last host serves the Microsoft 365 usage-report downloads that Microsoft Graph redirects to. If your proxy inspects traffic, allow the redirect from graph.microsoft.com to reports.office.com. The download link carries its own short-lived authorization.

How it works

Connecting a tenant has three stages: you validate the credential, Tenant Manager stores it, and the first sync starts.

Validation

Validation tries the credential against the real directory before anything is stored. Tenant Manager signs in with the app registration, reads the directory name, and checks each permission in the table above. The success message reads "Connected to {name}." and says nothing about Microsoft Entra ID P1 or usage reports. If the tenant doesn't have Microsoft Entra ID P1, Microsoft doesn't provide its sign-in data. Optimization and the user record then show a note about it. Without sign-in data, Inactive and Never signed in list nobody, and usage reports do not stand in for them. Idle Copilot and swap license recommendations still use usage reports, which record only email, Teams, SharePoint, and OneDrive use. If the app registration has Application.Read.All, Tenant Manager also reads the client secret's expiry date for you.

Connecting and saved service principals

Connecting stores the client secret in encrypted form and adds the tenant to a tenant group. The tenant group depends on how you connect. Your first tenant goes into the tenant group you name in the Set up Tenant Manager dialog, and that tenant group becomes the top-level tenant group. Get started never adds a second one. Later, Add tenant puts the tenant into the tenant group whose context menu you opened. You can't pick a different tenant group in the dialog, but you can move the tenant afterward.

A service principal you add in Tenant Manager also appears in the existing service principal lists of Business Applications, the setup wizard, Cost Analyzer, Business Activity Monitoring, and Azure Documenter. You can't add the same Microsoft Entra ID and client ID pair twice. If a saved service principal already uses the pair, Tenant Manager shows its friendly name. Clear Add new service principal and select the saved one instead.

Going the other way, the Select a service principal list shows every saved service principal that has a stored client secret, including ones added in other modules. It leaves out service principals that are only for Power Automate. In Set up Tenant Manager, service principals that a tenant already uses are shown with "(already connected)" and can't be selected. In Add tenant, they aren't listed.

First sync

The first sync starts as soon as the tenant is connected, without asking for confirmation. Until it finishes, figures on the Home card and in the module are empty.

If Tenant Manager can't queue the first sync, the tenant is still connected. A message says it will sync at the next scheduled time. To get data sooner, select Sync on the tenant.

A directory can't be connected twice through the same app registration, because it would sync one tenant as two and count every seat and cost twice. You can connect a directory through a second app registration, but Tenant Manager warns you that its seats would be counted twice in the totals.

Steps

You can connect your first tenant from the Home page, and further tenants from the tree view in Tenant Manager. In both cases, you validate the credential before you connect.

Connect your first tenant

This procedure creates your first tenant group, connects your first tenant, and queues its first sync.

1. On the Home page, select Get started on the Tenant Manager card. The Set up Tenant Manager dialog opens.
2. In Group details, enter a Name for the tenant group and, optionally, a Description. Select Next.
3. In Tenant details, enter a Tenant name. It is required, and Validate stays disabled until you enter one.
4. Optionally, select Show the permissions to grant to see the Microsoft Graph permissions to give the app registration.
5. Choose the credential. To reuse a saved one, select it in Select a service principal. Service principals that a tenant already uses are shown with "(already connected)" and can't be selected. To add a new one, select Add new service principal and enter Friendly name, Microsoft Entra ID, Client id, and Client secret.
6. Select Validate. Read the result and the permission list. If every required permission is granted, a message confirms the connection.
7. If Client secret expiration is empty, enter the date the secret expires. Azure shows it under Certificates & secrets in the app registration.
8. Select Connect and sync.

When the tenant is connected, a message confirms it and that its first sync is queued. Tenant Manager opens. If the first sync can't be queued, the message says the tenant is connected and will sync at the next scheduled time.

Connect another tenant

This procedure adds a tenant to a tenant group you choose and starts its first sync.

1. In Tenant Manager, open the context menu ( ⋮ ) of the tenant group in the tree view, and select Add tenant. In an empty tenant group, you can also select Add tenant on the page.
2. Enter a Name for the tenant and, optionally, a Description.
3. Under Service principal details, choose the credential. To reuse a saved service principal, select it in Select a service principal. Service principals that are already connected to a tenant aren't listed. A saved service principal always connects its own directory. To connect a different directory, or to add a new credential, select Add new service principal and enter Friendly name (optional), Microsoft Entra ID, Client id, and Client secret for that directory's app registration.
4. Select Validate and read the result.
5. If Client secret expiration is empty, enter the date the secret expires.
6. Select Connect and sync.

The dialog closes, and Tenant Manager confirms that the tenant is connected and syncing.

Configuration

The dialogs use the fields below. Where the Set up Tenant Manager dialog and Add tenant differ, the table says so.

Permission behavior

What you can do depends on your role and your scope.

• Get started on the Home page is available to the Owner and Contributor roles. A custom product-wide role sees it disabled with the tooltip "You are not authorized to perform this operation".
• A user whose access is limited to specific tenant groups or tenants can't run Get started.
• Add tenant is faded in the context menu for users without Manage tenants on that tenant group. Hover over it to see "You are not authorized to perform this operation". The Owner and Contributor roles always include Manage tenants, so this affects only custom roles.
• If a user without Manage tenants reaches the Validate step anyway, Tenant Manager refuses it and opens the Unauthorized page.
• A user with access to only some tenant groups or tenants can add tenants only to tenant groups in their scope.

Example scenario

Marta Kowalski is the Microsoft 365 administrator at Fabrikam. She registered an app in Fabrikam's Microsoft Entra ID, granted it Directory.Read.All, Application.Read.All, AuditLog.Read.All, and RoleManagement.Read.Directory, and gave admin consent. She has the directory ID, client ID, and a secret value.

On the Home page, she selects Get started. She names the tenant group "Fabrikam" and selects Next. She enters "Fabrikam" as the tenant name, selects Add new service principal, and enters the directory ID, client ID, and secret. She selects Validate, and the message confirms the connection and fills in the secret's expiry date. She selects Connect and sync. Tenant Manager opens, and the first sync starts.

Later, Fabrikam takes over a smaller company that runs its own tenant. Marta opens the context menu of the "Fabrikam" tenant group, selects Add tenant, and repeats the procedure with the new app registration.

Limitations

• A directory can't be connected twice through the same app registration.
• The tenant name must be unique across Tenant Manager.
• Tenant Manager supports Microsoft 365 commercial and GCC tenants, wherever Turbo360 is hosted. GCC High, DoD, and China tenants aren't supported.
• Tenant Manager doesn't change anything in your tenant without an approval or an automation you switch on. Approved changes need the optional write permissions.

Troubleshooting

1. Validate shows "The client secret works, but it cannot see any directory. Check that admin consent was granted."
   Cause: Microsoft returned no directory for the app registration.
   Fix: in Microsoft Entra ID, select Grant admin consent for the app registration's API permissions, then validate again.

2. Validate shows that some required permissions are not granted.
   Cause: the message reads "Connected to {directory}, but {n} of the {m} required permissions is not granted", followed by the missing names.
   Fix: in the app registration, add the permission under API permissions as a Microsoft Graph Application permission, then select Grant admin consent.

3. Validate shows "This directory is already connected through this same app registration."
   Cause: the directory and app registration are already connected as a tenant.
   Fix: use the existing tenant. To connect the directory a second time, use a different app registration, and note that its seats would be counted twice.

4. Add tenant shows that a service principal with the same Microsoft Entra ID and client id already exists.
   Cause: you selected Add new service principal for a credential that is already saved in your account.
   Fix: clear Add new service principal and select the saved service principal from the list.

5. Validate shows "Microsoft did not respond within 45 seconds, which usually means this app registration is being throttled."
   Cause: Microsoft is throttling requests from the app registration.
   Fix: wait a minute and select Validate again.

6. Validate shows a message about the client secret, client ID, or Microsoft Entra ID.
   Cause: Microsoft Entra ID refused the sign-in. The message says why:

   • "The client secret is wrong. The secret ID was probably copied instead of the secret value."
   • "The client secret has expired. Create a new one. An expired secret cannot be recovered."
   • "The client id does not exist in that Microsoft Entra ID, or admin consent was never granted."
   • "The Microsoft Entra ID is wrong."
   • "The app registration is disabled in that Microsoft Entra ID."

   Fix: in the app registration, copy the secret Value (not the secret ID) from Certificates & secrets, or create a new secret if it expired. Check that the Microsoft Entra ID and Client id belong to the same app registration, that it is enabled, and that admin consent is granted. Then select Validate again.

7. Connect asks you to "Enter the client secret's expiry date."
   Cause: no expiry date was entered, and Tenant Manager could not read it from the app registration because Application.Read.All is not granted. A variant of the message says the secret could not be found on the app registration, which usually means the app is registered in another directory.
   Fix: enter Client secret expiration by hand (Azure shows it under Certificates & secrets), or grant Application.Read.All and validate again. Without the date, the Client secret expiry alert can't warn you in time.

Related articles

• What is Tenant Manager?
• Understanding tenant groups
• How data sync works
• Request access to Tenant Manager
• Tenant Manager quick start
• Managing Microsoft 365 tenants
• Syncing a Microsoft 365 tenant
• Roles and permissions in Tenant Manager
• Tenant connection issues
• License tasks