Configure Azure RBAC roles by using Azure CLI and REST API
In this article, you learn how to grant permissions to client applications and users to access Azure Health Data Services by using the Azure Command-Line Interface (CLI) and REST API. This step is referred to as role assignment or Azure role-based access control (RBAC). For more information, see Configure Azure RBAC role.
View and download the CLI scripts and REST API scripts from Azure Health Data Services samples.
Note
To perform the role assignment operation, the user (or the client application) must be granted with RBAC permissions. Contact your Azure subscription administrators for assistance.
Role assignments with CLI
You can list application roles by using role names or GUID IDs. Include the role name in double quotes when there are spaces in it. For more information, see List Azure role definitions.
az role definition list --name "FHIR Data Contributor"
az role definition list --name 5a1fc7df-4bf1-4951-a576-89034ee01acd
az role definition list --name "DICOM Data Owner"
az role definition list --name 58a3b984-7adf-4c20-983a-32417c86fbc8
Azure Health Data Services role assignment
The role assignments for Azure Health Data Services require these values:
- Application role name or GUID ID.
- Service principal ID for the user or client application.
- Scope for the role assignment, that is, the Azure Health Data Services service instance. It includes subscription, resource group, workspace name, and FHIR or DICOM service name. You can use the absolute or relative URL for the scope. Note that "/" isn’t added at the beginning of the relative URL.
#Azure Health Data Services role assignment
fhirrole="FHIR Data Contributor"
dicomrole="DICOM Data Owner"
clientid=xxx
subscriptionid=xxx
resourcegroupname=xxx
workspacename=xxx
fhirservicename=xxx
dicomservicename=xxx
fhirrolescope="subscriptions/$subscriptionid/resourceGroups/$resourcegroupname/providers/Microsoft.HealthcareApis/workspaces/$workspacename/fhirservices/$fhirservicename"
dicomrolescope="subscriptions/$subscriptionid/resourceGroups/$resourcegroupname/providers/Microsoft.HealthcareApis/workspaces/$workspacename/dicomservices/$dicomservicename"
#find client app service principal id
spid=$(az ad sp show --id $clientid --query objectId --output tsv)
#assign the specified role
az role assignment create --assignee-object-id $spid --assignee-principal-type ServicePrincipal --role "$fhirrole" --scope $fhirrolescope
az role assignment create --assignee-object-id $spid --assignee-principal-type ServicePrincipal --role "$dicomrole" --scope $dicomrolescope
You can verify the role assignment status from the command-line response or in the Azure portal.
Azure API for FHIR role assignment
Role assignments for Azure API for FHIR work similarly. The difference is that the scope contains the FHIR service only and the workspace name isn’t required.
#azure api for fhir role assignment
fhirrole="FHIR Data Contributor"
clientid=xxx
subscriptionid=xxx
resourcegroupname=xxx
fhirservicename=xxx
fhirrolescope="subscriptions/$subscriptionid/resourceGroups/$resourcegroupname/providers/Microsoft.HealthcareApis/services/$fhirservicename"
#find client app service principal id
spid=$(az ad sp show --id $clientid --query objectId --output tsv)
#assign the specified role
az role assignment create --assignee-object-id $spid --assignee-principal-type ServicePrincipal --role "$fhirrole" --scope $fhirrolescope
Role assignments with REST API
Alternatively, you can send a Put request to the role assignment REST API directly. For more information, see Assign Azure roles using the REST API.
Note
The REST API scripts in this article are based on the REST Client extension. You need to revise the variables if you are in a different environment.
The API requires these values:
- Assignment ID, which is a GUID value that uniquely identifies the transaction. You can use tools such as Visual Studio or Visual Studio Code extension to get a GUID value. Also, you can use online tools such as UUID Generator to get it.
- API version supported by the API.
- Scope for Azure Health Data Services to which you grant access permissions. It includes subscription ID, resource group name, and the FHIR or DICOM service instance name.
- Role definition ID for roles such as FHIR Data Contributor or DICOM Data Owner. Use
az role definition list --name "<role name>"to list the role definition IDs. - Service principal ID for the user or the client application.
- Microsoft Entra access token to the
https://management.azure.com/, not Azure Health Data Services. You can get the access token using an existing tool or using Azure CLI command,az account get-access-token --resource "https://management.azure.com/" - For Azure Health Data Services, the scope includes workspace name and FHIR/DICOM service instance name.
### Create a role assignment - Azure Health Data Services (DICOM)
@roleassignmentid=xxx
@roleapiversion=2021-04-01
@roledefinitionid=58a3b984-7adf-4c20-983a-32417c86fbc8
dicomservicename-xxx
@scope=/subscriptions/{{subscriptionid}}/resourceGroups/{{resourcegroupname}}/providers/Microsoft.HealthcareApis/workspaces/{{workspacename}}/dicomservices/{{dicomservicename}}
#get service principal id
@spid=xxx
#get access token
@token=xxx
PUT https://management.azure.com/{{scope}}/providers/Microsoft.Authorization/roleAssignments/{{roleassignmentid}}?api-version={{roleapiversion}}
Authorization: Bearer {{token}}
Content-Type: application/json
Accept: application/json
{
"properties": {
"roleDefinitionId": "/subscriptions/{{subscriptionid}}/providers/Microsoft.Authorization/roleDefinitions/{{roledefinitionid}}",
"principalId": "{{spid}}"
}
}
For Azure API for FHIR, the scope is defined differently as it supports the FHIR service only, and no workspace name is required.
### Create a role assignment - Azure API for FHIR
@roleassignmentid=xxx
@roleapiversion=2021-04-01
@roledefinitionid=5a1fc7df-4bf1-4951-a576-89034ee01acd
fhirservicename-xxx
@scope=/subscriptions/{{subscriptionid}}/resourceGroups/{{resourcegroupname}}/providers/Microsoft.HealthcareApis/services/{{fhirservicename}}
#get service principal id
@spid=xxx
#get access token
@token=xxx
PUT https://management.azure.com/{{scope}}/providers/Microsoft.Authorization/roleAssignments/{{roleassignmentid}}?api-version={{roleapiversion}}
Authorization: Bearer {{token}}
Content-Type: application/json
Accept: application/json
{
"properties": {
"roleDefinitionId": "/subscriptions/{{subscriptionid}}/providers/Microsoft.Authorization/roleDefinitions/{{roledefinitionid}}",
"principalId": "{{spid}}"
}
}
List service instances of Azure Health Data Services
Optionally, you can get a list of Azure Health Data Services services, or Azure API for FHIR. The API version is based on Azure Health Data Services, not the version for the role assignment REST API.
For Azure Health Data Services, specify the subscription ID, resource group name, workspace name, FHIR or DICOM services, and the API version.
### Get Azure Health Data Services DICOM services
@apiversion=2021-06-01
@subscriptionid=xxx
@resourcegroupname=xxx
@workspacename=xxx
GET https://management.azure.com/subscriptions/{{subscriptionid}}/resourceGroups/{{resourcegroupname}}/providers/Microsoft.HealthcareApis/workspaces/{{workspacename}}/dicomservices?api-version={{apiversion}}
Authorization: Bearer {{token}}
Content-Type: application/json
Accept: application/json
For Azure API for FHIR, specify the subscription ID and the API version.
### Get a list of Azure API for FHIR services
@apiversion=2021-06-01
@subscriptionid=xxx
GET https://management.azure.com/subscriptions/{{subscriptionid}}/providers/Microsoft.HealthcareApis/services?api-version={{apiversion}}
Authorization: Bearer {{token}}
Content-Type: application/json
Accept: application/json
After you grant proper permissions to the client application, you can access Azure Health Data Services in your applications.