Roles and permissions in Azure Documenter

Overview

Azure Documenter uses a combination of system-defined and user-defined roles to control which users can perform which actions within the module.

Business value

Restricting access to only what each user needs reduces the risk of accidental or unauthorized changes. Teams can grant broad access to trusted administrators while limiting others — such as users who should only generate documents — to a narrow set of permissions.

How it works

An organization can add any number of employees or external contractors as users of its Turbo360 account.

The first user to sign up for Turbo360 is assigned the Account owner role, which grants full access to the account. That user can add an unlimited number of users to Azure Documenter and assign them system-defined or user-defined roles.

Note:

This article explains role management in Azure Documenter. For role management in other Turbo360 modules, see:

System-defined roles

Azure Documenter has three system-defined roles:

Role	Access
Owner	Complete access to the module, including managing users and roles. Only Account owner and Owner can manage users and roles.
Contributor	Access to manage everything at the scope it's assigned to.
Reader	Access to read everything at the scope it's assigned to.

Scope

The scope of a role determines the level in the module at which a user has the permissions specified for that role. A role's scope in Azure Documenter can be either:

The entire module
A specific group

The Users list within any group shows which users have access to that group and at what scope.

Specify custom permissions

When adding a user, you can assign them a system-defined or user-defined role at a specific node level — an individual group — rather than across the entire module. This lets you grant precise access without giving the user visibility into unrelated document configuration groups.

The Specify custom permissions dialog lists all available groups. Each group can be individually enabled or disabled using the Revoke / Grant access toggle. A Role dropdown next to each entry lets you assign either a system-defined or user-defined role at that specific scope.

You can assign different roles to different groups in a single operation — for example, Contributor on a test group and Reader on a production group.
Users with specified access cannot see groups they have not been explicitly granted.
The role assigned at the group level applies only to that group and does not affect the user's access to other groups.

User-defined roles

Account owners and Owners can add any number of custom roles to the module. A user-defined role specifies permissions in the context of a document configuration — who can do what within a document configuration.

A user-defined role contains three sets of permissions:

Account permissions — controls whether the role can manage notification channels.
Management permissions — controls whether the role can manage users and their role assignments.
Feature permissions — controls read or full management access to Documentation and Diagrams.

For example, if a group of users only needs to generate documents and shouldn't be able to configure diagrams or manage notification channels, a role can be created with read-only or no access to those features and assigned to those users.

Steps

Use the following steps to add or delete a user-defined role. Go to the Roles tab in Azure Documenter to get started.

Add a role

Adding a role lets you define a custom set of permissions to assign to users.

Select Add role under the Roles tab.
Provide a name and an optional description for the role.
Configure the account, management, and feature permissions for the role.

Delete a role

Deleting a role requires reassigning a replacement role first, so affected users don't lose access.

In the Actions column under the Roles tab, click Delete role for the role you want to remove.
Provide a replacement role to apply to all users currently assigned the role being deleted.

Export user details with permissions

Exporting user details gives you an offline record of who has access to what, across every scope in the account.

Use the export option to download Turbo360 account user details, along with their permissions, as a CSV file.

The exported file lets you review the permissions granted to each user at every level within the account.

Permission behavior

System-defined and user-defined roles behave differently: user-defined roles specify permissions in the context of a document configuration, while operations on a configuration itself — such as deleting it, or managing service principals in the module — require at least a Contributor role.

For example, a user suited to managing a test document configuration but not a production one can be assigned Contributor on the test group and a more restricted role on the production group using Specify custom permissions. A user suited to managing the entire module but not to managing users and roles can be assigned Contributor across the module.

Example scenario

A team lead needs broad access to manage document configurations across the module, but shouldn't manage users or roles. They're assigned the Contributor role at the module level, which grants full management access to configurations while excluding user and role management, which remains limited to Account owner and Owner.

Troubleshooting

A user can't manage users or roles despite having a role assigned
Cause: Only Account owner and Owner can manage users and roles — no other role, including Contributor, has this access.
Fix: Assign the user the Owner role if they need to manage users and roles.
Deleting a role isn't allowed
Cause: A replacement role must be provided to reassign the users currently on the role being deleted.
Fix: Select a replacement role when deleting, so affected users don't lose access to the module.
A user-defined role doesn't grant the expected level of access to a feature
Cause: Each feature permission in a user-defined role is set independently to read or manage access.
Fix: Review the role's feature permissions and adjust the read/manage setting for the specific feature.

FAQs

What's the difference between a system-defined and a user-defined role?
System-defined roles (Owner, Contributor, Reader) are built in. User-defined roles are custom roles you create to specify permissions for a document configuration.
Can I limit a role to just document generation?
Yes. A user-defined role can be scoped to read-only access for Documentation, with notification channel and user management permissions disabled.
What happens to users when I delete a role they're assigned?
You must provide a replacement role when deleting. Affected users are reassigned to that replacement role rather than losing access.
Can I get a record of which users have which permissions?
Yes. You can export Turbo360 account user details along with their permissions as a CSV file.