role

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

Manages user roles in tenants for role-based access control (RBAC).

Operation description
add Adds a role for a user.
delete Removes a user role.
list Displays a list of users and their roles.
show Returns roles assigned to a particular user account.
show-types Displays a list of roles supported for this tenant.

add

Adds a role to a user.

  • An Administrator has full access to all devices and operations within the tenant, including the permission to add or delete other users. The Administrator role is assigned by default to the user who creates the tenant.
  • A Contributor can add devices and create and change deployments. Software and hardware developers who create applications, manage connected devices, and update deployments, but are not responsible for managing tenant access, should have the Contributor role.
  • A Reader has access to information about the tenant, including the claimed devices, deployments, and, when available, any error reporting data from the devices. This role is appropriate for maintenance and operations personnel who are responsible for tracking connected device performance at end-user installations.

Note

This command will automatically register the user's Microsoft account with Azure Sphere, if they are not yet registered. Previously, the register-user command was used to register a new user with Azure Sphere; this is now automatically done when adding a user to a new role within an existing tenant, and the register-user command is now deprecated.

Required parameters

Parameter Type Description
-u, --user String Specifies the name of the user (email address).
-r, --role String Specifies the role to assign to the selected user. Possible roles are: Administrator, Contributor, and Reader.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

azsphere role add --user john@contoso.com --role Administrator

delete

Removes a role from a user in the current or selected Azure Sphere tenant.

Required parameters

Parameter Type Description
-u, --user String Specifies the user's ID or email to identify the user from whom the role is being deleted.
-r, --role Enum Specifies the role to be deleted. Possible roles are: Administrator, Contributor, and Reader.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.

Note

The Administrator role of the current user can be deleted only by another administrator.

Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

azsphere role delete --user bob@contoso.com --role contributor --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb

list

Displays a list of user roles in the current or selected tenant.

The list will truncate after the first 500 entries.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

 azsphere role list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
 --------------------- -------------
 Name                  Roles
 ===================================
 bob@contoso.com       Administrator
                       Contributor
 --------------------- -------------

show

Displays role information for a selected user.

Required parameters

Parameter Type Description
-u, --user String User name to display (email address).

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

azsphere role show --user john@contoso.com --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
 -------------
 Roles
 =============
 Administrator
 Contributor
 -------------

show-types

Displays roles that can be assigned in this tenant.

Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

azsphere role show-types
 -------------
 Result
 =============
 Administrator
 -------------
 Contributor
 -------------
 Reader
 -------------