Skip to content

Commit d92eb34

Browse files
jborsecnikjborsecnik
authored
Merge pull request #217635 from inward-eye/main
how to fetch policies
2 parents e2c89d6 + 235cbfc commit d92eb34

File tree

2 files changed

+151
-0
lines changed

2 files changed

+151
-0
lines changed

‎articles/purview/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -433,6 +433,8 @@ items:
433433
href: tutorial-purview-audit-logs-diagnostics.md
434434
- name: ABAP function deployment guide
435435
href: abap-functions-deployment-guide.md
436+
- name: Troubleshooting access policies
437+
href: troubleshoot-policy-distribution.md
436438
- name: Frequently asked questions (FAQ)
437439
href: ./frequently-asked-questions.yml
438440
- name: Resources

‎articles/purview/troubleshoot-policy-distribution.md

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: Troubleshoot distribution of Microsoft Purview access policies
3+
description: Learn how to troubleshoot the enforcement of access policies that were created in Microsoft Purview
4+
author: inward-eye
5+
ms.author: vlrodrig
6+
ms.service: purview
7+
ms.subservice: purview-data-policies
8+
ms.topic: tutorial
9+
ms.date: 11/08/2022
10+
---
11+
12+
# Tutorial: troubleshoot distribution of Microsoft Purview access policies (preview)
13+
14+
[!INCLUDE [feature-in-preview](includes/feature-in-preview.md)]
15+
16+
In this tutorial, learn how to programmatically fetch access policies that were created in Microsoft Purview. This can be used to troubleshoot the communication of policies between Microsoft Purview, where policies are created and updated and the data sources on which these policies are enforced.
17+
This guide will use Arc-enabled SQL Server as an example of data source.
18+
19+
To get the necessary context about Microsoft Purview policies, see concept guides listed in [next-steps](#next-steps).
20+
21+
## Prerequisites
22+
23+
* If you don't have an Azure subscription, [create a free one](https://azure.microsoft.com/free/?ref=microsoft.com&utm_source=microsoft.com&utm_medium=docs&utm_campaign=visualstudio) before you begin.
24+
* You must have an existing Microsoft Purview account. If you don't have one, see the [quickstart for creating a Microsoft Purview account](create-catalog-portal.md).
25+
* To register a data source, enable *Data use management*, and create a policy [follow this guide](how-to-policies-devops-arc-sql-server.md)
26+
* To establish a bearer token and to call any data plane APIs, see [the documentation about how to call REST APIs for Microsoft Purview data planes](tutorial-using-rest-apis.md). In order to be authorized to fetch policies, you need to be Policy Author, Data Source Admin or Data Curator at root-collection level. You can assign those roles by following the guide on [managing Microsoft Purview role assignments](catalog-permissions.md#assign-permissions-to-your-users).
27+
28+
## Overview
29+
There are two ways to fetch access policies from Microsoft Purview
30+
- Full pull: Provides a complete set of policies for a particular data resource scope.
31+
- Delta pull: Provides an incremental view of policies, that is, what has changed since the last pull request, whether that one was a full pull or a delta pull.
32+
33+
Microsoft Purview policy model is described using [JSON syntax](https://datatracker.ietf.org/doc/html/rfc8259)
34+
35+
The policy distribution endpoint can be constructed from the Microsoft Purview account name as:
36+
`{endpoint} = https://<account-name>.purview.azure.com/pds`
37+
38+
## Full pull
39+
40+
### Request
41+
To fetch policies via full pull, send a `GET` request to /policyElements as follows:
42+
43+
```
44+
GET {{endpoint}}/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProvider}/{resourceType}/{resourceName}/policyelements?api-version={apiVersion}
45+
```
46+
47+
### Response status codes
48+
49+
|Http Code|Http Code Description|Type|Description|Response|
50+
|---------|---------------------|----|-----------|--------|
51+
|200|Success|Success|Request processed successfully|Policy data|
52+
|404|Not Found|Error|The request path is invalid or not registered|Error data|
53+
|401|Unauthenticated|Error|No bearer token passed in request or invalid token|Error data|
54+
|403|Forbidden|Error|Other authentication errors|Error data|
55+
|500|Internal server error|Error|Backend service unavailable|Error data|
56+
|503|Backend service unavailable|Error|Backend service unavailable|Error data|
57+
58+
### Example for Arc-enabled SQL Server
59+
60+
##### Example parameters:
61+
- resourceProvider = Microsoft.AzureArcData
62+
- resourceType = sqlServerInstances
63+
- apiVersion = 2021-01-01-preview
64+
65+
##### Example request:
66+
```
67+
GET https://relecloud-pv.purview.azure.com/pds/subscriptions/b285630c-8185-456b-80ae-97296561303e/resourceGroups/Finance-rg/providers/Microsoft.AzureArcData/sqlServerInstances/vm-finance/policyelements?api-version=2021-01-01-preview
68+
```
69+
70+
##### Example response:
71+
72+
```json
73+
{
74+
"count": 2,
75+
"syncToken": "808:0",
76+
"elements": [
77+
{
78+
"id": "9912572d-58bc-4835-a313-b913ac5bef97",
79+
"kind": "policy",
80+
"updatedAt": "2022-11-04T20:57:20.9389522Z",
81+
"version": 1,
82+
"elementJson": "{\"id\":\"9912572d-58bc-4835-a313-b913ac5bef97\",\"name\":\"Finance-rg_sqlsecurityauditor\",\"kind\":\"policy\",\"version\":1,\"updatedAt\":\"2022-11-04T20:57:20.9389522Z\",\"decisionRules\":[{\"kind\":\"decisionrule\",\"effect\":\"Permit\",\"updatedAt\":\"11/04/2022 20:57:20\",\"cnfCondition\":[[{\"attributeName\":\"resource.azure.path\",\"attributeValueIncludedIn\":[\"/subscriptions/b285630c-8185-456b-80ae-97296561303e/resourceGroups/Finance-rg/**\"]}],[{\"fromRule\":\"purviewdatarole_builtin_sqlsecurityauditor\",\"attributeName\":\"derived.purview.role\",\"attributeValueIncludes\":\"purviewdatarole_builtin_sqlsecurityauditor\"}],[{\"attributeName\":\"principal.microsoft.groups\",\"attributeValueIncludedIn\":[\"b29c1676-8d2c-4a81-b7e1-365b79088375\"]}]]},{\"kind\":\"decisionrule\",\"effect\":\"Permit\",\"id\":\"auto_0235e4df-0d3f-41ca-98ed-edf1b8bfcf9f\",\"updatedAt\":\"11/04/2022 20:57:20\",\"cnfCondition\":[[{\"attributeName\":\"resource.azure.path\",\"attributeValueIncludedIn\":[\"/subscriptions/b285630c-8185-456b-80ae-97296561303e/resourceGroups/Finance-rg/**\"]}],[{\"attributeName\":\"request.azure.dataAction\",\"attributeValueIncludedIn\":[\"Microsoft.Sql/sqlservers/Connect\"]}],[{\"attributeName\":\"principal.microsoft.groups\",\"attributeValueIncludedIn\":[\"b29c1676-8d2c-4a81-b7e1-365b79088375\"]}]]},{\"kind\":\"decisionrule\",\"effect\":\"Permit\",\"id\":\"auto_45fa5236-a2a3-4291-9f0a-813b2883f118\",\"updatedAt\":\"11/04/2022 20:57:20\",\"cnfCondition\":[[{\"attributeName\":\"resource.azure.path\",\"attributeValueIncludedIn\":[\"/subscriptions/b285630c-8185-456b-80ae-97296561303e/resourceGroups/Finance-rg/**\"]}],[{\"attributeName\":\"request.azure.dataAction\",\"attributeValueIncludedIn\":[\"Microsoft.Sql/sqlservers/databases/Connect\"]}],[{\"attributeName\":\"principal.microsoft.groups\",\"attributeValueIncludedIn\":[\"b29c1676-8d2c-4a81-b7e1-365b79088375\"]}]]}]}"
83+
},
84+
{
85+
"id": "f1f2ecc0-c8fa-473f-9adf-7f7bd53ffdb4",
86+
"scopes": [
87+
"/subscriptions/b285630c-8185-456b-80ae-97296561303e/resourceGroups/Finance-rg"
88+
],
89+
"kind": "policyset",
90+
"updatedAt": "2022-11-04T20:57:20.9389456Z",
91+
"version": 1,
92+
"elementJson": "{\"id\":\"f1f2ecc0-c8fa-473f-9adf-7f7bd53ffdb4\",\"name\":\"f1f2ecc0-c8fa-473f-9adf-7f7bd53ffdb4\",\"kind\":\"policyset\",\"version\":1,\"updatedAt\":\"2022-11-04T20:57:20.9389456Z\",\"preconditionRules\":[{\"dnfCondition\":[[{\"attributeName\":\"resource.azure.path\",\"attributeValueIncludedIn\":[\"/subscriptions/b285630c-8185-456b-80ae-97296561303e/resourceGroups/Finance-rg/**\"]}]]}],\"policyRefs\":[\"9912572d-58bc-4835-a313-b913ac5bef97\"]}"
93+
}
94+
]
95+
}
96+
```
97+
98+
## Policy constructs
99+
There are 3 top-level policy constructs used within the full pull (/policyElements) and delta pull (/policyEvents) requests: PolicySet, Policy and AttributeRule.
100+
101+
### PolicySet
102+
103+
PolicySet associates Policy to a resource scope. Purview policy decision compute starts with a list of PolicySets. PolicySet evaluation triggers evaluation of Policy referenced in the PolicySet.
104+
105+
106+
### Policy
107+
108+
Policy specifies decision that should be emitted if the policy is applicable for the request provided request context attributes satisfy attribute predicates specified in the policy. Evaluation of policy triggers evaluation of AttributeRules referenced in the Policy.
109+
110+
### AttributeRule
111+
112+
AttributeRule produces derived attributes and add them to request context attributes. Evaluation of AttributeRule triggers evaluation of additional AttributeRules referenced in the AttributeRule.
113+
114+
115+
## Common sub-constructs used in PolicySet, Policy, AttributeRule
116+
117+
#### AttributePredicate
118+
AttributePredicate checks whether predicate specified on an attribute is satisfied. AttributePredicate can specify the following properties:
119+
- attributeName: specifies attribute name on which attribute predicate needs to be evaluated.
120+
- matcherId: Identifier of matcher function that is used to compare the attribute value looked up in request context by the attribute name to the attribute value literal specified in the predicate. At present we support 2 matcherId(s): ExactMatcher, GlobMatcher. If matcherId isn't specified, it defaults to GlobMatcher.
121+
- fromRule: optional property specifying the identifier of an AttributeRule that needs to be evaluated to populate the request context with attribute values that would be compared in this predicate.
122+
- attributeValueIncludes: scalar literal value that should match the request context attribute values.
123+
- attributeValueIncludedIn: array of literal values that should match the request context attribute values.
124+
- attributeValueExcluded: scalar literal value that should not match the request context attribute values.
125+
- attributeValueExcludedIn: array of literal values that should not match the request context attribute values.
126+
127+
#### CNFCondition
128+
Array of array of AttributePredicates that have to be satisfied with the semantic of ANDofORs.
129+
130+
#### DNFCondition
131+
Array of array of AttributePredicates that have to be satisfied with the semantic of ORofANDs.
132+
133+
#### PreConditionRule
134+
- A PreConditionRule can specify at most one each of CNFCondition, DNFConition, Condition.
135+
- All of the specified CNFCondition, DNFCondition, Condition should evaluate to “true” for the PreConditionRule to be satisfied for the current request.
136+
- If any of the precondition rules is not satisfied, containing PolicySet or Policy is considered not applicable for the current request and skipped.
137+
138+
#### Condition
139+
- A Condition allows specifying a complex condition of predicates that can nest functions from library of functions.
140+
- At decision compute time the Condition evaluates to “true” or “false” and also could emit optional Obligation(s).
141+
- If the Condition evaluates to “false” the containing DecisionRule is considered Not Applicable to the current request.
142+
143+
144+
## Next steps
145+
146+
Concept guides for Microsoft Purview access policies:
147+
- [DevOps policies](concept-policies-devops.md)
148+
- [Self-service access policies](concept-self-service-data-access-policy.md)
149+
- [Data owner policies](concept-policies-data-owner.md)

0 commit comments

Comments
 (0)