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.}

Prerequisite

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.}

Method

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

Login

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).

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>

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:

• Serverless data prep using SQL on demand and Synapse Pipelines
• Azure Synapse - On-Demand Serverless Compute and Querying
• Detecting Anomalies in IoT Telemetry with Azure Synapse Analytics
• Custom C# Spark Jobs in Azure Synapse
• Custom Scala Spark Jobs in 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.