Roles and permissions in Tenant Manager

Overview

Tenant Manager uses role-based access control to decide who can view, change, and approve things in the module. A module owner can add users to Tenant Manager and assign them a system-defined or a custom role. This article explains role management in Tenant Manager.

Business value

Limiting each person to the access they need reduces the risk of unintended license changes. You can let one team review recommendations while a smaller group approves the changes that are applied in Microsoft 365.

Prerequisites

You need to be a module owner to manage roles. The permissions below decide who can manage roles and users.

Required permissions

Role and user management depends on the role type and, for custom roles, on the Manage users permission.

Role	Access
Owner	Full access to Tenant Manager. Create, edit, and delete custom roles, and manage users.
Contributor	Manage tenants, tenant groups, and licenses. Can open User management to view it, but Add user and Edit permission are disabled. No role management.
Reader	Read-only access. No access to user or role management.
Custom role with Manage users on	Add users and assign existing roles. Cannot create, edit, or delete roles.
Custom role with Manage users off	No access to user or role management.

How it works

Every user in Tenant Manager has a role that is assigned at a scope. The role defines what the user can do, and the scope defines where. This section covers the system-defined roles, scope, and custom roles.

System-defined roles

Tenant Manager has three system-defined roles. The table shows the access each role has.

Permission	Owner	Contributor	Reader
Overview	Read	Read	Read
Explore	Read and Manage	Read and Manage	Read
Optimization	Read and Manage	Read and Manage	Read
Alerts	Read and Manage	Read and Manage	Read
Reports	Read and Manage	Read and Manage	Read
Manage users	Yes	No	No
Manage tenants	Yes	Yes	No
Manage groups	Yes	Yes	No
Approve license tasks	Yes	Yes	No
Manage escalation policies	Yes	Yes	No
Use AI agents	Yes	Yes	No

Owner has full access to Tenant Manager, including user management. Contributor can manage tenants, tenant groups, and licenses. It can open User management to view it, but it cannot add users or edit permissions. Reader has read-only access. You cannot give a custom role the name Owner, Contributor, or Reader.

Scope and custom permissions

The scope of a role sets the level in the module where the role applies. A role can apply to the entire module, to a tenant group together with everything beneath it, or to a single tenant. Assigning a role at a tenant group or tenant lets you grant precise access without exposing unrelated tenants.

The assignment nearest to a tenant group or tenant decides what a user can do there. This includes renaming a license and moving a tenant. Users with access to only part of the tree cannot open anything else. Parent tenant groups that they cannot access still appear in the tree view, grayed out and not selectable, with the message "You do not have access to this item. It is shown because you have access to something inside it." You can also open Users and User activities from the context menu of any tenant group or tenant to work with that node. User activities shows only the entries for the tenant groups and tenants you can access. Entries that are not tied to a tenant group or tenant are shown only to people with access to the whole module.

User-defined roles

Module owners can create any number of custom roles. A custom role contains three sets of permissions. Account permissions let a role manage notification channels. Feature permissions give Read or Manage access to each of the five pages. Management permissions turn on individual administrative actions. For example, a role for a service desk can have Read on Overview, Explore, and Optimization and Manage on Optimization, without the Approve license tasks permission.

Steps

Use these steps to add and manage custom roles and to give users access. Select the gear icon in the Tenant Manager sidebar header, and then select User management to get started. To work with the users of one tenant group or tenant only, open Security > Users from the context menu of that node.

Add a custom role

Adding a custom role lets you grant exactly the feature and management permissions that a group of people needs.

Open User management and select the Roles tab.
Select Add role.
Enter a Name and an optional Description, and then select Next. The name is required, can contain letters, numbers, and spaces, and can be up to 100 characters long. The description can be up to 300 characters long.
Under Specify account permissions, turn on Manage notification channels if the role needs it. Its tooltip reads "Manage permission allows users to perform operations such as add, update or remove notification channels."
Under Specify management permissions, turn on the management permissions the role needs.
Under Specify feature permissions, set Read and Manage for each page. Overview has Read only.
Select Save.

A new role starts with Read on every page and every management permission off. On a user's profile card, the same section is named Account permissions. If you use the name Owner, Contributor, or Reader, Tenant Manager shows "Role name already exists. Please provide a different name."

Edit or delete a custom role

Editing a role changes the access of everyone who holds it, and deleting a role moves those users to another role.

Open User management and select the Roles tab.
In the Actions column of the role, select Edit role or Delete role. Built-in roles show None and cannot be edited or deleted.
To edit, change the permissions and confirm Update role.
To delete, choose a role under Switch role of users who are assigned the role, and then select Delete. Owner is not offered, and the default is Contributor.

You can delete a role that is in use. Its users and Microsoft Entra ID groups, including their tenant group and tenant grants, move to the role you choose.

Add a user

Adding a user gives a person access to Tenant Manager at the scope you choose.

Open User management and select the Users tab.
Select Add user.
For a new user, enter the First name, Last name, and Email address. For an existing user, select the user. With Microsoft Entra ID sign-in, you pick users from a list, and Add group works the same way.
Under Role assignment, choose Direct role assignment to give one role for the whole module, or Specify custom permissions to limit access to tenant groups or tenants. Direct role assignment defaults to Owner.
Confirm to add the user. Tenant Manager shows "User added to Tenant Manager successfully".

Limit a user to a tenant group or tenant

Limiting a user keeps unrelated tenants out of reach.

In Role assignment, choose Specify custom permissions.
In the tree, use the switch in the Revoke / Grant access column to grant access to a tenant group or tenant.
Choose a role in the Role column. Owner is not offered, and the default is Reader.
Select Done.

Granting a node, or choosing its role, copies down to everything beneath it. Nodes that you cannot manage are disabled with the message "You can not manage users in this tenant" or "You can not manage users in this group". You can also open the Security menu of a tenant group or tenant and select Assign user role or Assign group role. In that case Owner is not offered, and the default is Contributor.

Edit or remove a user

Editing a user changes their role or scope, and removing a user ends their access to Tenant Manager.

Open User management and select the Users tab.
To change access, select Edit permission for the user, change the Role assignment, and select Update. You can also edit several users at once.
To remove access, select the remove action for the user and confirm Remove user.

Your own user and users who have access through a Microsoft Entra ID group show None in Actions.

Configuration

The tables below list what a custom role can set. Read lets a user view a page. Manage lets a user act on it.

Feature	Read	Manage
Overview	View tenant and tenant group figures.	Not available. Overview offers no action.
Explore	Browse users, Microsoft Entra ID groups, licenses, and change tracking.	Add tasks from Explore and exclude users from removals.
Optimization	View recommendations, tasks, and automations.	Add to tasks, ignore and restore recommendations, change recommendation settings, trigger notifications, generate PowerShell scripts, mark tasks as done, and move tasks back to not done.
Alerts	View the alert types and their history.	Enable, disable, and configure alerts, and acknowledge, close, or reopen incidents.
Reports	View reports and their history.	Configure reports, switch them on or off, and generate them on demand.

Management permissions are on or off.

Permission	What it allows
Manage users	Add, edit, and remove users, assign roles, and change a user's permissions.
Manage groups	Create, edit, move, and delete tenant groups. Deleting a tenant group also removes every tenant inside it, so turning it on also turns on Manage tenants.
Manage tenants	Connect, edit, sync, move, and delete tenants, and rename licenses. Turning it off also turns off Manage groups.
Approve license tasks	Approve or decline proposed license changes in Optimization, and change automations. Turning it on also turns on Read on Optimization and locks it. Turn Approve license tasks off first if you need to remove Read on Optimization.
Manage escalation policies	Add, edit, and delete escalation policies.
Manage notification channels	Add, update, and remove notification channels. You set it under Specify account permissions.
Use AI agents	Use the AI agents that explain a user, a license, or a recommendation. The AI agents switch for the account must also be on.

Permission behavior

A missing permission shows up in a few consistent ways.

Pages: a role without Read on a page cannot open it. The page shows "You do not have access to this page" and "Your role in Tenant Manager does not include it. Ask an account owner if you need it."
Controls: a control that needs Manage stays visible but is faded or disabled. Its tooltip reads "You are not authorized to perform this operation".
Settings menu: the entries in the settings menu follow your role. Tenants is disabled without Manage tenants, and a disabled entry shows "You are not authorized to perform this operation". Escalation policies needs Manage escalation policies. For the Contributor role, User management opens as view-only, with Add user and Edit permission disabled. Global price catalog and User activities are open to everyone, and they show only your own tenants and tenant groups.
Approvals: Approve and Decline need the Approve license tasks permission. Without it, the tooltip reads "You need the task decision permission in Tenant Manager to approve or decline tasks."
Explore: without Manage on Explore, the Actions items on records are disabled, including Exclude from removals and Include in removals. Without Manage tenants, the pencil and reset icons for renaming a license are hidden instead of disabled.
Optimization: without Manage on Optimization, Add to tasks, Ignore, Restore, and the Actions menu are disabled, and the Recommendation settings field cannot be changed.
Automation: without Approve license tasks, the automation switch and Configure automation are disabled. View run history stays available.
Alerts and reports: with Read but not Manage on Alerts or Reports, the switch and Configure stay visible but disabled, and Generate now is disabled on reports. Alert history and Generation history stay open to read.
Sync and Add tenant: without Manage tenants, the Sync button in the tenant header is disabled. The Add tenant button on an empty tenant group is disabled too, and its hint says that someone whose Tenant Manager role can manage tenants can add one.
Whole-module actions: adding a tenant at the root and creating a top-level tenant group need access to the whole module. A role that applies only to a tenant group or tenant cannot do them.
Outside your access: if you try to act on a tenant group or tenant outside the access you were given, Tenant Manager refuses with "This group is outside your Tenant Manager access." or "This tenant is outside your Tenant Manager access."
Data banners: if your role or scope does not include some of the data a page reads, a banner says "Your Tenant Manager access doesn't include this data. Ask an account owner to check your role and scope."
Global price catalog: everyone can read the catalog, but only the Turbo360 account owner or a module owner can set or clear a price. Everyone sees only their own tenants and tenant groups.
Raising and approving: anyone who holds the Approve license tasks permission can approve or decline a task, including the person who raised it.

Example scenario

Hiroshi Tanaka is a module owner at Northern Lights Energy and manages Microsoft 365 licenses for two tenants in a tenant group named NLE-Nordics. He wants Astrid, the service desk lead, to review recommendations and raise tasks, but not to approve them.

Hiroshi creates a custom role named License reviewer. He sets Read on Overview, Explore, and Optimization and Manage on Optimization, and he leaves Approve license tasks off. He then assigns the role to Astrid at the NLE-Nordics tenant group. Astrid can open the recommendations in that tenant group and select Add to tasks. Approve and Decline stay disabled for Astrid until someone with the Approve license tasks permission decides each task.

Limitations

A few constraints apply to roles in Tenant Manager.

Only a module owner can create, edit, or delete custom roles.
Overview has a Read level only.
A role cannot reuse the names Owner, Contributor, or Reader.

Troubleshooting

Add to tasks, Ignore, and the Actions menu are disabled
Cause: the role does not have Manage on Optimization.
Fix: ask a module owner to add Manage on Optimization to the role.
Approve and Decline are disabled
Cause: the role does not have the Approve license tasks permission.
Fix: ask a module owner to turn on Approve license tasks for the role.
A page shows "You do not have access to this page"
Cause: the role does not include Read on that page.
Fix: ask a module owner to add Read for the page.
Adding a tenant or creating a top-level tenant group fails with a message about access to the whole module
Cause: the role applies only to a tenant group or a tenant.
Fix: ask for a role at the module level, or add the tenant or tenant group inside a tenant group you can manage.
A tenant group appears grayed out in the tree view
Cause: the tenant group is shown only because you have access to something inside it.
Fix: no action is needed. Ask a module owner for access to the tenant group if you need it.