Skip to content
Ed Freeman By Ed Freeman Software Engineer II
How to use the Azure CLI to manage access to Synapse Studio

Synapse Studio is the online development area for developers working in Azure Synapse Analytics. To get access, one needs to be assigned to one of the pre-defined Synapse Studio roles. These are "Workspace Admins", "Spark Admins" and "SQL Admins".

At the time of writing, the only visual way to assign someone to one of these roles is through Synapse Studio itself, but of course, this means that the person assigning the role needs to already have access to Synapse Studio themselves. A bit chicken-and-egg.

If someone creates an Azure Synapse Analytics workspace under their identity, they'll be initialized as a Workspace Admin, allowing them full access to Synapse Studio and granting them the ability to manage further role assignments. However, if you create a workspace under a service principal's identity, or someone else (other than yourself) has created a workspace to which you know you need access, there is no visual way that you can grant yourself access to the Studio.*

However, if you are an Owner or Contributor on the Synapse workspace resource (easy to check through the portal), you can grant yourself access to Synapse Studio programmatically. This is either through the core Azure Synapse REST APIs, the Az.Synapse PowerShell module, or through the Azure Synapse CLI.

Let's see how to use the Azure CLI to manage access to Synapse Studio (the Azure Synapse Analytics development area).

* There is a hint at the top of this page on access control in Synapse, however, that new Synapse-specific Azure RBAC roles will be coming when Synapse reaches GA, so maybe this might not always be the case.


You'll need the Azure CLI version 2.11.0 or later installed. The version at the time of writing is Azure CLI version 2.12.1, which is what I'm using for this blog. See the Azure CLI installation docs for details on how to install for your machine.*

* Version 2.11.0 of the CLI added the az upgrade command, so upgrading the tool has become much easier than it used to be.


Once we have a correct version of the CLI installed, we can crack on.


As ever, to work with Azure resources, we need to login:

az login

Or, if you work with subscriptions associated with multiple Azure AD tenants, you can specify the tenant:

az login --tenant <tenant_id>

For other ways of authenticating (including Service Principal and Managed Identity auth), see the docs about Azure CLI authentication methods.

Role assignments and definitions

Once we've signed in, we can go ahead and explore the az synapse CLI commands. The ones we're particularly interested in are the az synapse role CLI commands, which are split into assignment commands and definition commands commands. The definition commands provide details of the Synapse Studio roles. Running the following:

az synapse role definition list --workspace-name <synapseWorkspaceName>

returns this:

    "id": "6e4bf58a-b8e1-4cc3-bbf9-d73143322b78",
    "isBuiltIn": true,
    "name": "Workspace Admin"
    "id": "c3a6d2f1-a26f-4810-9b0f-591308d5cbf1",
    "isBuiltIn": true,
    "name": "Apache Spark Admin"
    "id": "7af0c69a-a548-47d6-aea3-d00e69bd83aa",
    "isBuiltIn": true,
    "name": "Sql Admin"
    "id": "24fa9e0a-d130-4536-9f92-8b976b16986b",
    "isBuiltIn": true,
    "name": "Scope Admin"

We can see the aforementioned Workspace, Spark and SQL roles, along with a "Scope Admin" role of which I know nothing (and neither does the rest of the internet, apparently).

The best hour you can spend to refine your own data strategy and leverage the latest capabilities on Azure to accelerate your road map.

To see the current role assignments set in the workspace, we can run the following command:

az synapse role assignment list --workspace-name <synapseWorkspaceName>

which returns something like this:

    "id": "6e4bf58a-b8e1-4cc3-bbf9-d73143322b78-<aadObjectIdOfPrincipal>",
    "principalId": <aadObjectIdOfPrincipal>,
    "roleId": "6e4bf58a-b8e1-4cc3-bbf9-d73143322b78"

Here, id is the unique identifier of the role assignment (which is simply a concatenation of the role ID and principal ID), the principalId which is the AAD object ID of the principal which has been assigned to the role, and roleId is the id of the role you saw in the previous code snippet.

Create a role assignment

Assigning someone to a role is as easy as running the following command:

az synapse role assignment create --workspace-name <synapseWorkspaceName> --role <roleNameOrId> --assignee <aadPrincipalId>

Azure Weekly is a summary of the week's top Microsoft Azure news from AI to Availability Zones. Keep on top of all the latest Azure developments!

If the command is successful, you'll see a response body similar to the output of the role assignment list command shown above.

Once someone has been assigned to one of these roles, and provided there aren't any firewall rules preventing users from accessing the Synapse workspace, they should be able to access Synapse Studio.

Want to get started with Synapse but not sure where to start?

If you'd like to know more about Azure Synapse, we offer a free 1 hour, 1-2-1 Azure Data Strategy Briefing aimed at CxO's. Please book a call and then we'll confirm the time and send you a meeting invite.

We also have created number of talks about Azure Synapse:

Finally, if you are interested in more content about Azure Synapse, we have a dedicated editions page which collates all our blog posts.


How do I programmatically manage roles within Azure Synapse Analytics Studio? You can use the Azure CLI, Azure PowerShell or the core REST APIs to manage roles within Azure Synapse Analytics' development area, which is otherwise known as Synapse Studio. There are currently 3 primary roles - Workspace Admin, Spark Admin and SQL admin. These can be assigned to security principals using some simple programmatic commands.

Ed Freeman

Software Engineer II

Ed Freeman

Ed is a Data Engineer helping to deliver projects for clients of all shapes and sizes, providing best of breed technology solutions to industry specific challenges. He focusses primarily on cloud technologies, data analytics and business intelligence, though his Mathematical background has also led to a distinct interest in Data Science, Artificial Intelligence, and other related fields.

He also curates a weekly newsletter, Power BI Weekly, where you can receive all the latest Power BI news, for free.

Ed won the Cloud Apprentice of the Year at the Computing Rising Star Awards 2019.