Skip to content

Commit 261f77d

Browse files
Albertyang0Albertyang0
authored
Merge pull request #284646 from MicrosoftDocs/release-deid
[Scheduled Publish] Release deid --> main -- 08/15 - 10:00AM PST
2 parents d72e2f3 + 9a18dff commit 261f77d

File tree

9 files changed

+690
-9
lines changed

9 files changed

+690
-9
lines changed

‎articles/healthcare-apis/deidentification/index.yml

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
### YamlMime:Landing
2+
3+
title: De-identification service documentation
4+
summary: Documentation for the Azure Health Data Services de-identification service.
5+
6+
metadata:
7+
title: Azure Health Data Services de-identification service
8+
description: Documentation for the Azure Health Data Services de-identification service.
9+
ms.service: azure-health-data-services
10+
ms.subservice: deidentification-service
11+
ms.topic: landing-page
12+
13+
author: msjasteppe
14+
ms.author: jasteppe
15+
ms.date: 08/08/2024
16+
17+
# linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new
18+
19+
landingContent:
20+
- title: About the de-identification service
21+
linkLists:
22+
- linkListType: overview
23+
links:
24+
- text: What is the de-identification service?
25+
url: overview.md
26+
27+
- title: Get started
28+
linkLists:
29+
- linkListType: quickstart
30+
links:
31+
- text: Deploy the de-identification service
32+
url: quickstart.md
33+
- text: Azure Health De-identification client library for .NET
34+
url: quickstart-sdk-net.md
35+
36+
- title: How-to
37+
linkLists:
38+
- linkListType: how-to-guide
39+
links:
40+
- text: Manage access with Azure role-based access control (RBAC)
41+
url: manage-access-rbac.md
42+
- text: Use managed identities
43+
url: managed-identities.md

‎articles/healthcare-apis/deidentification/manage-access-rbac.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: Manage access to the de-identification service (preview) with Azure role-based access control (RBAC) in Azure Health Data Services
3+
description: Learn how to manage access to the de-identification service (preview) using Azure role-based access control.
4+
author: jovinson-ms
5+
ms.author: jovinson
6+
ms.service: azure-health-data-services
7+
ms.subservice: deidentification-service
8+
ms.topic: how-to
9+
ms.date: 07/16/2024
10+
---
11+
12+
# Use Azure role-based access control with the de-identification service (preview)
13+
14+
Microsoft Entra ID authorizes access rights to secured resources through Azure role-based access control (RBAC). The de-identification service (preview) defines a set of
15+
built-in roles that encompass common sets of permissions used to access de-identification functionality.
16+
17+
Microsoft Entra ID uses the concept of a security principal, which can be a user, a group, an application service principal, or a [managed identity for Azure resources](/entra/identity/managed-identities-azure-resources/overview).
18+
19+
When an Azure role is assigned to a Microsoft Entra ID security principal over a specific scope, Azure grants access to that scope for that security principal. For more information about scopes, see
20+
[Understand scope for Azure RBAC](/azure/role-based-access-control/scope-overview).
21+
22+
## Prerequisites
23+
24+
- A de-identification service (preview) in your Azure subscription. If you don't have a de-identification service, follow the steps in [Quickstart: Deploy the de-identification service](quickstart.md).
25+
26+
## Available built-in roles
27+
28+
The de-identification service (preview) has the following built-in roles available:
29+
30+
|Role |Description |
31+
|-----|------------|
32+
|DeID Data Owner |Full access to de-identification functionality. |
33+
|DeID Real-time Data User |Execute requests against de-identification API endpoints. |
34+
|DeID Batch Owner |Create and manage de-identification batch jobs. |
35+
|DeID Batch Reader |Read-only access to de-identification batch jobs. |
36+
37+
## Assign a built-in role
38+
39+
Keep in mind the following points about Azure role assignments with the de-identification service (preview):
40+
41+
- When you create a de-identification service, you aren't automatically assigned permissions to access data via Microsoft Entra ID. You need to explicitly assign yourself an applicable Azure role. You can assign it at the level of your subscription, resource group, or de-identification service.
42+
- When roles are assigned, it can take up to 10 minutes for changes to take effect.
43+
- When the de-identification service is locked with an [Azure Resource Manager read-only lock](/azure/azure-resource-manager/management/lock-resources), the lock prevents the assignment of Azure roles that are scoped to the de-identification service.
44+
- When Azure deny assignments have been applied, your access might be blocked even if you have a role assignment. For more information, see [Understand Azure deny assignments](/azure/role-based-access-control/deny-assignments).
45+
46+
You can use different tools to assign built-in roles.
47+
48+
# [Azure portal](#tab/azure-portal)
49+
50+
To use the de-identification service (preview), with Microsoft Entra ID credentials, a security principal must be assigned one of the built-in roles. To learn how to assign these roles to a security
51+
principal, follow the steps in [Assign Azure roles using the Azure portal](/azure/role-based-access-control/role-assignments-portal).
52+
53+
# [Azure PowerShell](#tab/azure-powershell)
54+
55+
To assign an Azure role to a security principal with PowerShell, call the [New-AzRoleAssignment](/powershell/module/az.resources/new-azroleassignment) command. In order to run the command, you must have a role that includes **Microsoft.Authorization/roleAssignments/write** permissions assigned to you at the corresponding scope or higher.
56+
57+
The format of the command can differ based on the scope of the assignment, but `ObjectId` and `RoleDefinitionName` are required parameters. While the `Scope` parameter is optional, you should set it to retain the principle of least privilege. By limiting roles and scopes, you limit the resources that are at risk if the security principal is ever compromised.
58+
59+
The scope for a de-identification service (preview) is in the form `/subscriptions/<Subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.HealthDataAIServices/deidServices/<Deidentification Service Name>`
60+
61+
The example assigns the **DeID Data Owner** built-in role to a user, scoped to a specific de-identification service. Make sure to replace the placeholder values
62+
in angle brackets `<>` with your own values:
63+
64+
```azurepowershell
65+
New-AzRoleAssignment
66+
-SignInName <Email> `
67+
-RoleDefinitionName "DeID Data Owner" `
68+
-Scope "/subscriptions/<Subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.HealthDataAIServices/deidServices/<Deidentification Service Name>"
69+
```
70+
71+
A successful response should look like:
72+
73+
```
74+
75+
console
76+
RoleAssignmentId : /subscriptions/<Subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.HealthDataAIServices/deidServices/<Deidentification Service Name>/providers/Microsoft.Authorization/roleAssignments/<Role Assignment ID>
77+
Scope : /subscriptions/<Subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.HealthDataAIServices/deidServices/<Deidentification Service Name>
78+
DisplayName : Mark Patrick
79+
SignInName : [email protected]
80+
RoleDefinitionName : DeID Data Owner
81+
RoleDefinitionId : <Role Definition ID>
82+
ObjectId : <Object ID>
83+
ObjectType : User
84+
CanDelegate : False
85+
86+
```
87+
88+
For more information, see [Assign Azure roles using Azure PowerShell](/azure/role-based-access-control/role-assignments-powershell).
89+
90+
# [Azure CLI](#tab/azure-pcli)
91+
92+
To assign an Azure role to a security principal with Azure CLI, use the [az role assignment create](/cli/azure/role/assignment) command. In order to run the command, you must have a role that includes
93+
**Microsoft.Authorization/roleAssignments/write** permissions assigned to you at the corresponding scope or higher.
94+
95+
The format of the command can differ based on the type of security principal, but `role` and `scope` are required parameters.
96+
97+
The scope for a de-identification service (preview) is in the form `/subscriptions/<Subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.HealthDataAIServices/deidServices/<Deidentification Service Name>`
98+
99+
The following example assigns the **DeID Data Owner** built-in role to a user, scoped to a specific de-identification service. Make sure to replace the placeholder values
100+
in angle brackets `<>` with your own values:
101+
102+
```azurecli
103+
az role assignment create \
104+
--assignee <Email> \
105+
--role "DeID Data Owner" \
106+
--scope "/subscriptions/<Subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.HealthDataAIServices/deidServices/<Deidentification Service Name>"
107+
```
108+
109+
For more information, see [Assign Azure roles using Azure PowerShell](/azure/role-based-access-control/role-assignments-cli).
110+
111+
# [ARM template](#tab/azure-resource-manager)
112+
113+
To learn how to use an Azure Resource Manager template to assign an Azure role, see [Assign Azure roles using Azure Resource Manager templates](/azure/role-based-access-control/role-assignments-template).
114+
115+
---
116+
117+
## Related content
118+
119+
- [What is Azure role-based access control (Azure RBAC)?](/azure/role-based-access-control/overview)
120+
- [Best practices for Azure RBAC](/azure/role-based-access-control/best-practices)

‎articles/healthcare-apis/deidentification/managed-identities.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
title: Use managed identities with the de-identification service (preview) in Azure Health Data Services
3+
description: Learn how to use managed identities with the Azure Health Data Services de-identification service (preview) using the Azure portal and ARM template.
4+
author: jovinson-ms
5+
ms.author: jovinson
6+
ms.service: azure-health-data-services
7+
ms.subservice: deidentification-service
8+
ms.topic: how-to
9+
ms.date: 07/17/2024
10+
---
11+
12+
# Use managed identities with the de-identification service (preview)
13+
14+
Managed identities provide Azure services with a secure, automatically managed identity in Microsoft Entra ID. Using managed identities eliminates the need for developers having to manage credentials by providing an identity. There are two types of managed identities: system-assigned and user-assigned. The de-identification service supports both.
15+
16+
Managed identities can be used to grant the de-identification service (preview) access to your storage account for batch processing. In this article, you learn how to assign a managed identity to your de-identification service.
17+
18+
## Prerequisites
19+
20+
- Understand the differences between **system-assigned** and **user-assigned** described in [What are managed identities for Azure resources?](/entra/identity/managed-identities-azure-resources/overview)
21+
- A de-identification service (preview) in your Azure subscription. If you don't have a de-identification service, follow the steps in [Quickstart: Deploy the de-identification service](quickstart.md).
22+
23+
## Create an instance of the de-identification service (preview) in Azure Health Data Services with a system-assigned managed identity
24+
25+
# [Azure portal](#tab/portal)
26+
27+
1. Access the de-identification service (preview) settings in the Azure portal under the **Security** group in the left navigation pane.
28+
1. Select **Identity**.
29+
1. Within the **System assigned** tab, switch **Status** to **On** and choose **Save**.
30+
31+
# [ARM template](#tab/azure-resource-manager)
32+
33+
Any resource of type ``Microsoft.HealthDataAIServices/deidServices`` can be created with a system-assigned identity by including the following block in
34+
the resource definition:
35+
36+
```json
37+
"identity": {
38+
"type": "SystemAssigned"
39+
}
40+
```
41+
42+
---
43+
44+
## Assign a user-assigned managed identity to a service instance
45+
46+
# [Azure portal](#tab/portal)
47+
48+
1. Create a user-assigned managed identity resource according to [these instructions](/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities).
49+
1. In the navigation pane of your de-identification service (preview), scroll to the **Security** group.
50+
1. Select **Identity**.
51+
1. Select the **User assigned** tab, and then choose **Add**.
52+
1. Search for the identity you created, select it, and then choose **Add**.
53+
54+
# [ARM template](#tab/azure-resource-manager)
55+
56+
Any resource of type ``Microsoft.HealthDataAIServices/deidServices`` can be created with a user-assigned identity by including the following block in
57+
the resource definition, replacing **resource-id** with the Azure Resource Manager (ARM) resource ID of the desired identity:
58+
59+
```json
60+
"identity": {
61+
"type": "UserAssigned",
62+
"userAssignedIdentities": {
63+
"<resource-id>": {}
64+
}
65+
}
66+
```
67+
68+
---
69+
70+
## Supported scenarios using managed identities
71+
72+
Managed identities assigned to the de-identification service (preview) can be used to allow access to Azure Blob Storage for batch de-identification jobs. The service acquires a token as
73+
the managed identity to access Blob Storage and de-identify blobs that match a specified pattern. For more information, including how to grant access to your managed identity,
74+
see [Quickstart: Azure Health De-identification client library for .NET](quickstart-sdk-net.md).
75+
76+
## Clean-up steps
77+
78+
When you remove a system-assigned identity, you delete it from Microsoft Entra ID. System-assigned identities are also automatically removed from Microsoft Entra ID
79+
when you delete the de-identification service (preview).
80+
81+
# [Azure portal](#tab/portal)
82+
83+
1. In the navigation pane of your de-identification service (preview), scroll down to the **Security** group.
84+
1. Select **Identity**, then follow the steps based on the identity type:
85+
- **System-assigned identity**: Within the **System assigned** tab, switch **Status** to **Off**, and then choose **Save**.
86+
- **User-assigned identity**: Select the **User assigned** tab, select the checkbox for the identity, and select **Remove**. Select **Yes** to confirm.
87+
88+
# [ARM template](#tab/azure-resource-manager)
89+
90+
Any resource of type ``Microsoft.HealthDataAIServices/deidServices`` can have system-assigned identities deleted and user-assigned identities unassigned by
91+
including this block in the resource definition:
92+
93+
```json
94+
"identity": {
95+
"type": "None"
96+
}
97+
```
98+
99+
---
100+
101+
## Related content
102+
103+
- [What are managed identities for Azure resources?](/azure/active-directory/managed-identities-azure-resources/overview)

‎articles/healthcare-apis/deidentification/overview.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: Overview of the de-identification service (preview) in Azure Health Data Services
3+
description: Learn how the de-identification service (preview) in Azure Health Data Services anonymizes clinical data, ensuring HIPAA compliance while retaining data relevance for research and analytics.
4+
author: kimiamavon
5+
ms.service: azure-health-data-services
6+
ms.subservice: deidentification-service
7+
ms.topic: overview
8+
ms.date: 7/17/2024
9+
ms.author: kimiamavon
10+
---
11+
12+
# What is the de-identification service (preview)?
13+
14+
The de-identification service (preview) in Azure Health Data Services enables healthcare organizations to anonymize clinical data so that the resulting data retains its clinical relevance and distribution while also adhering to the Health Insurance Portability and Accountability Act of 1996 (HIPAA) Privacy Rule. The service uses state-of-the-art machine learning models to automatically extract, redact, or surrogate 28 entities, including the HIPAA 18 Protected Health Information (PHI) identifiers – from unstructured text such as clinical notes, transcripts, messages, or clinical trial studies.
15+
16+
## Use de-identified data in research, analytics, and machine learning
17+
18+
The de-identification service (preview) unlocks data that was previously difficult to de-identify so organizations can conduct research and derive insights from analytics. The de-identification service supports three operations: **tag**, **redact**, or **surrogate PHI**. The de-identification service offers many benefits, including:
19+
20+
- **Surrogation**: Surrogation, or replacement, is a best practice for PHI protection. The service can replace PHI elements with plausible replacement values, resulting in data that is most representative of the source data. Surrogation strengthens privacy protections as any false-negative PHI values are hidden within a document.
21+
22+
- **Consistent replacement**: Consistent surrogation results enable organizations to retain relationships occurring in the underlying dataset, which is critical for research, analytics, and machine learning. By submitting data in the same batch, our service allows for consistent replacement across entities and preserves the relative temporal relationships between events.
23+
24+
- **Expanded PHI coverage**: The service expands beyond the 18 HIPAA Identifiers to provide stronger privacy protections and more fine-grained distinctions between entity types, such as distinguishing between Doctor and Patient.
25+
26+
## De-identify clinical data securely and efficiently
27+
28+
The de-identification service (preview) offers many benefits, including:
29+
30+
- **PHI compliance**: The de-identification service is designed for protected health information (PHI). The service uses machine learning to identify PHI entities, including HIPAA’s 18 identifiers, using the “TAG” operation. The redaction and surrogation operations replace these identified PHI values with a tag of the entity type or a surrogate, or pseudonym. The service also meets all regional compliance requirements including HIPAA, GDPR, and the California Consumer Privacy Act (CCPA).
31+
32+
- **Security**: The de-identification service is a stateless service. Customer data stays within the customer’s tenant.
33+
34+
- **Role-based Access Control (RBAC)**: Azure role-based access control (RBAC) enables you to manage how your organization's data is processed, stored, and accessed. You determine who has access to de-identify datasets based on roles you define for your environment.
35+
36+
## Synchronous or asynchronous endpoints
37+
38+
The de-identification service (preview) offers two ways to interact with the REST API or Client library (Azure SDK).
39+
40+
- Directly submit raw unstructured text for analysis. The API output is returned in your application.
41+
- Submit a job to asynchronously endpoint process files in bulk from Azure Blob Storage using tag, redact, or surrogation with consistency within a job.
42+
43+
## Input requirements and service limits
44+
45+
The de-identification service (preview) is designed to receive unstructured text. To de-identify data stored in the FHIR&reg; service, see [Export deidentified data](/azure/healthcare-apis/fhir/deidentified-export).
46+
47+
The following service limits are applicable during preview:
48+
- Requests can't exceed 50 KB.
49+
- Jobs can process no more than 1,000 documents.
50+
- Each document processed by a job can't exceed 2 MB.
51+
52+
## Pricing
53+
As with other Azure Health Data Services, you pay only for what you use. You have a monthly allotment that enables you to try the product for free.
54+
55+
| Transformation Operation (per MB) | Up to 50 MB | Over 50 MB |
56+
| ---------------- | ------ | ---- |
57+
| Unstructured text de-identification | $0 | $0.05 |
58+
59+
When you choose to store documents in Azure Blob Storage, you are charged based on Azure Storage pricing.
60+
61+
## Responsible use of AI
62+
63+
An AI system includes the technology, the people who use it, the people affected by it, and the environment where you deploy it. Read the transparency note for the de-identification service (preview) to learn about responsible AI use and deployment in your systems.
64+
65+
## Related content
66+
67+
[De-identification quickstart](quickstart.md)
68+
69+
[Integration and responsible use](/legal/cognitive-services/language-service/guidance-integration-responsible-use?context=%2Fazure%2Fai-services%2Flanguage-service%2Fcontext%2Fcontext)
70+
71+
[Data, privacy, and security](/legal/cognitive-services/language-service/data-privacy?context=%2Fazure%2Fai-services%2Flanguage-service%2Fcontext%2Fcontext)

0 commit comments

Comments
 (0)