Managing Microsoft 365 tenants

Overview

A tenant in Tenant Manager is a connected Microsoft 365 tenant. After you connect one, you manage it from the Tenants page and from the tenant's context menu in the tree view.

This article shows you how to review your connected tenants, edit a tenant, replace its client secret, move it to another tenant group, and delete it. To connect a tenant, see Connect a Microsoft 365 tenant. To refresh a tenant's data, see Syncing a Microsoft 365 tenant.

Business value

When a client secret expires in Microsoft, syncs for the tenant start failing and its data goes stale. The Tenants page shows every tenant's secret expiry and last sync in one grid, so you can renew secrets before data goes stale.

Prerequisites

Before you start, make sure you have at least one connected tenant. See Connect a Microsoft 365 tenant.

Required permissions

You need the Manage tenants permission on the tenant. The Owner and Contributor roles include it. The Reader role doesn't. Without it, the Tenants entry in the settings menu is disabled. For details, see Roles and permissions in Tenant Manager.

If your access is limited to some tenant groups or tenants, you can manage only the tenants in your scope. Moving a tenant follows the grant nearest to the tenant. To move a tenant, you also need access to the destination tenant group.

How it works

Each tenant has a credential, a place in the tenant group tree, and a sync history. This section covers what the Tenants page shows and what each action changes.

The Tenants page

The Tenants page lists every tenant you can see. Open it from the gear icon in the tree view, which is named Settings, by selecting Tenants. The grid has the columns below.

You can't add a tenant from this page. Tenants are added from a tenant group's context menu in the tree view.

The client secret

The client secret can be replaced from Edit. The Microsoft Entra ID and client ID can't be changed after the tenant is added. To connect a different directory, add a new tenant. When you save a new secret, the tenant syncs right away with it. The secret is saved with the tenant's service principal, so replacing it also gives the new secret to any other Turbo360 module that uses the same service principal. A sync doesn't check the expiry date you enter, so it still runs after that date passes. The sync stops working once Microsoft rejects the secret, and it shows Microsoft's own error. The date drives the Client secret expiry alert and the Expired badge.

Moving and deleting

Moving and deleting affect where the tenant's numbers count and whether Tenant Manager keeps them. Moving counts the tenant's seats and licenses under the new tenant group straight away and changes who can see it. Deleting removes the tenant's Tenant Manager data, but its service principal stays saved in your account.

Every change is recorded in the Tenant Manager user activity log.

Steps

You manage tenants from the Tenants page or from the tenant's context menu ( ⋮ ) in the tree view. Both open the same dialogs.

Review your connected tenants

This procedure shows you each tenant's secret expiry and sync status.

1. In the tree view of Tenant Manager, select the gear icon, and then select Tenants.
2. Check the Client secret expiration date and Last synced columns.
3. Select Edit on any tenant whose secret has expired or is about to expire.

When you open the page from an Overview finding, the page narrows to the matching tenants. A note names the filter, such as tenants that are not syncing or tenants whose client secret expires soon. Clear the note to see every tenant.

Edit a tenant

This procedure renames a tenant or changes its description.

1. Open Edit from the Tenants page, or from the tenant's context menu in the tree view. The Edit tenant dialog opens with the current values.
2. Change the Name, the Description, or both.
3. Select Update.

Update stays disabled, with the tooltip "Nothing has changed yet", until you change something.

Replace a client secret

This procedure gives a tenant a new client secret before the old one expires, or after it has expired.

1. Open Edit for the tenant.
2. In Client secret, enter the new secret value. Use the secret value, not the secret ID.
3. Select Validate. Tenant Manager checks the secret against the tenant's own directory and reads the expiry date from the app registration when it can.
4. Check Client secret expiration. If it is empty or wrong, enter the correct date.
5. Select Update.

Tenant Manager saves the secret and starts a sync right away with the new secret. Leave Client secret empty to keep the saved one.

Move a tenant

This procedure moves a tenant to a different tenant group.

1. Open the tenant's context menu ( ⋮ ) in the tree view, and select Move. The Move tenant dialog opens.
2. Select the destination tenant group in the tree. The dialog shows the From and To paths, and marks the tenant's current tenant group with a current tag. You can search for a tenant group by name. When the destination is valid, the dialog says "You can move the tenant here. Click 'Move' to continue."
3. Select Move.
4. Read the confirmation, and select Continue.

The confirmation explains the effect. Users whose access was given on the current tenant group no longer see the tenant. Users with access to the destination tenant group can see it. The tenant's seat and license numbers count under the new tenant group straight away, and the tenant's own data doesn't change.

Delete a tenant

This procedure stops syncing a tenant and removes its data from Tenant Manager.

1. Select Delete on the Tenants page, or in the tenant's context menu.
2. Read the confirmation.
3. Select Continue. To keep the tenant, select Cancel.

If the tenant was open, Tenant Manager selects its parent tenant group. Deleting a tenant removes it from Tenant Manager only. Its service principal stays in Settings > Service principals and in the Add tenant list, so you can reuse it.

Configuration

The Edit tenant dialog uses these fields.

Permission behavior

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

• The Tenants entry in Settings needs Manage tenants on at least one tenant group or tenant. Without it, the entry is faded. Hover over it to see "You are not authorized to perform this operation".
• Without Manage tenants on a tenant, Edit and Delete on the Tenants page are disabled, and the context menu entries are faded. Hover over them to see "You are not authorized to perform this operation".
• The Tenants page lists only tenants where your role can read at least one page.
• In the Move tenant dialog, you can select a tenant group you have no access to, but the selection clears right away and the dialog shows "You do not have access to {name}. It is shown only because you have access to something inside it." Move stays disabled because nothing is selected.

Example scenario

Hannah Lindqvist runs IT operations at Tailspin Toys. She sees an Expires in badge next to the Tailspin Toys production tenant on the Tenants page. The Microsoft 365 admin has created a new client secret in the app registration.

Hannah selects Edit for the tenant, pastes the new secret value into Client secret, and selects Validate. Tenant Manager accepts the secret and fills in the new expiry date. She selects Update, and the tenant syncs with the new secret.

Limitations

• You can't change a tenant's Microsoft Entra ID or client ID.
• You can't clear the expiry date. You can only replace it with a valid date.
• You can't add a tenant from the Tenants page.
• Replacing a secret updates the saved service principal, so any other Turbo360 module that uses it gets the new secret too.
• You can't restore a deleted tenant. Connecting it again starts from a new sync.

Troubleshooting

1. Update stays disabled.
   Cause: a typed client secret is not validated, the expiry date is missing, the name is already taken, or nothing has changed.
   Fix: validate the secret, enter the expiry date, choose a unique name, or change a field.

2. Edit shows "Enter the client secret's expiry date."
   Cause: the expiry date is empty.
   Fix: enter the date the secret expires. Azure shows it under Certificates & secrets in the app registration.

3. A tenant shows an Expired badge, or its syncs stop working.
   Cause: the expiry date you entered has passed. Syncs don't check that date, so they keep running until Microsoft rejects the secret. The sync then stops working, and the icon next to Last synced shows Microsoft's error.
   Fix: create a new secret in the app registration, then replace it in Edit and validate it.

4. Move shows that the tenant is already in the tenant group.
   Cause: you chose the tenant's current tenant group.
   Fix: choose a different tenant group.

5. Delete is disabled for a service principal in Settings.
   Cause: a tenant in Tenant Manager still uses the service principal. Hovering over Delete shows "Used by Tenant Manager. Delete the tenants that use it in Tenant Manager first."
   Fix: to replace its client secret, edit the tenant in Tenant Manager or edit the service principal in Settings. To delete the service principal, delete the tenants that use it first. Delete is then enabled.

FAQs

1. Does renaming a tenant rename it in Microsoft 365?
   No. The name only changes how the tenant appears in Turbo360.

2. What happens to the service principal when I delete a tenant?
   It stays saved in your account. When no tenant uses it any more, Delete is enabled for it in Settings > Service principals. You can reuse it for another tenant, or delete it there.

3. Does moving a tenant change its data?
   No. Only the tenant group it counts under changes, which also changes who can see it.

Related articles

• Understanding tenant groups
• Connect a Microsoft 365 tenant
• Managing tenant groups
• Syncing a Microsoft 365 tenant
• How data sync works
• Roles and permissions in Tenant Manager
• Alert types and thresholds
• Tenant connection issues