You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Documentation - More details Database policy references and explanation (#1215)
* Update config/authorization documentation to detail database policies better and more visibly. Also fixes up grammar and styling.
* Update docs/configuration-file.md
* Add limitation of db policy for only update read delete.
* updates to supported database policy actions.
* Update to config doc mentioning SWA auth limitations and correcting malformed explanation sentence for a database policy.
* Changed wording.
* adding known issue
* Update docs/configuration-file.md
Copy file name to clipboardexpand all lines: docs/authorization.md
+29-1
Original file line number
Diff line number
Diff line change
@@ -125,9 +125,37 @@ As by default there are no pre-defined permission for the `anonymous` or `authen
125
125
"source": "dbo.books",
126
126
"permissions": [{
127
127
"role": "administrator",
128
-
"actions": [* ]
128
+
"actions": ["*"]
129
129
}]
130
130
}
131
131
```
132
132
133
133
In the above configuration sample, only request carrying the `administrator` role in the authentication token and specifying the `administrator` value in the `X-MS-API-ROLE` HTTP header, will be able to operate on the `book` entity.
134
+
135
+
### Item level security
136
+
137
+
Database policy expressions enable results to be restricted even further. Database policies translate OData expressions to query predicates executed against the database. Database policy expressions are supported for the read, update, and delete actions. See the [configuration file](./configuration-file.md#policies) documentation for a detailed explanation of database policies.
@@ -441,43 +448,47 @@ The `role` string contains the name of the role to which the defined permission
441
448
442
449
##### Actions
443
450
444
-
The `actions` array is a mixed-type array that details what actions are allowed to related roles. When the entity is either a table or view, roles can be configured with the following actions: `create`, `read`, `update`, `delete`.
445
-
In case of stored procedures, the roles can only be configured with `execute` action.
451
+
The `actions` array details what actions are allowed on the associated role. When the entity is either a table or view, roles can be configured with a combination of the actions: `create`, `read`, `update`, `delete`.
446
452
447
-
For example:
453
+
The following example tells Data API builder that the contributor role permits the `read` and `create` actions on the entity:
448
454
449
455
```json
450
456
{
457
+
"role": "contributor",
451
458
"actions": ["read", "create"]
452
459
}
453
460
```
454
461
455
-
tells Data API builder that the related role can perform `read` and `create` actions on the related entity.
456
-
457
-
In case all actions are allowed, it is possible to use the wildcard character `*` to indicate that. For example:
462
+
In case all actions are allowed, the wildcard character `*` can be used as a shortcut to represent all actions supported for the type of entity:
458
463
459
464
```json
460
465
{
466
+
"role": "editor",
461
467
"actions": ["*"]
462
468
}
463
469
```
464
-
`*` action expands based on the type of the entity. For tables and views, it expands to `create, read, update, delete` actions. For stored-procedures, it translates to `execute` action.
465
470
466
-
Another option is to specify an object with also details on what fields - defined in the `fields` object, are allowed and what are not:
471
+
For stored procedures, roles can only be configured with `execute` action and the wildcard `*` action will expand to `execute`.
472
+
For tables and views, the wildcard `*` action expands to the actions `create, read, update, delete`.
473
+
474
+
##### Fields
475
+
476
+
Role configuration supports granularly defining which database columns (fields) are permitted to be accessed in the section `fields`:
467
477
468
478
```json
469
479
{
480
+
"role": "read-only",
470
481
"action": "read",
471
-
"fields: {
482
+
"fields": {
472
483
"include": ["*"],
473
484
"exclude": ["field_xyz"]
474
485
}
475
486
}
476
487
```
477
488
478
-
That will indicate to Data API builder that the related role can `read` from all fields except from `field_xyz`.
489
+
That will indicate to Data API builder that the role*read-only* can `read` from all fields except from `field_xyz`.
479
490
480
-
Both the simple and the more complex definition can be used at the same time, for example, to limit the `read` action to specific fields, while allowing create to operate on all fields:
491
+
Both the simplified and granular `action` definitions can be used at the same time. For example, the following configuration limits the `read` action to specific fields, while implicitly allowing the `create` action to operate on all fields:
481
492
482
493
```json
483
494
{
@@ -491,46 +502,64 @@ Both the simple and the more complex definition can be used at the same time, fo
491
502
}
492
503
},
493
504
"create"
494
-
]
495
-
}
505
+
]
496
506
}
497
507
```
498
508
499
-
In the `fields` objects, the `*` can be used as the wildcard character to indicate all fields. Exclusions have precedence over inclusions.
509
+
In the `fields` section above, the wildcard `*` in the `include` section indicates all fields. The fields noted in the `exclude` section have precedence over fields noted in the `include` section. The definition translates to *include all fields except for the field 'last_updated'*.
510
+
511
+
##### Policies
512
+
513
+
The `policy` section, defined per `action`, defines item-level security rules (database policies) which limit the results returned from a request. The sub-section `database` denotes the database policy expression that will be evaluated during request execution.
514
+
515
+
```json
516
+
"policy": {
517
+
"database": "<Expression>"
518
+
}
519
+
```
520
+
521
+
-`database` policy: an OData expression that is translated into a query predicate that will be evaluated by the database.
522
+
- e.g. The policy expression `@item.OwnerId eq 2000` is translated to the query predicate `WHERE Table.OwnerId = 2000`
500
523
501
-
The `policy` section contains detail about item-level security rules.
524
+
> A *predicate* is an expression that evaluates to TRUE, FALSE, or UNKNOWN. Predicates are used in the search condition of [WHERE](https://learn.microsoft.com/sql/t-sql/queries/where-transact-sql) clauses and [HAVING](https://learn.microsoft.com/sql/t-sql/queries/select-having-transact-sql) clauses, the join conditions of [FROM](https://learn.microsoft.com/sql/t-sql/queries/from-transact-sql) clauses, and other constructs where a Boolean value is required.
+`database` policy: define a rule - a predicate - that will be injected in the query sent to the database
527
+
In order for results to be returned for a request, the request's query predicate resolved from a database policy must evaluate to `true` when executing against the database.
504
528
505
-
In order for an request or item to be returned, the policies must be evaluated to `true`.
529
+
Two types of directives can be used when authoring a database policy expression:
506
530
507
-
Two types of directives can be used when configuring a database policy:
531
+
-`@claims`: access a claim within the validated access token provided in the request.
532
+
-`@item`: represents a field of the entity for which the database policy is defined.
508
533
509
-
+`@claims`: access a claim stored in the authentication token
510
-
+`@item`: access an entity's field in the underlying database.
534
+
> [!NOTE]
535
+
> When Azure Static Web Apps authentication (EasyAuth) is configured, a limited number of claims types are available for use in database policies: `identityProvider`, `userId`, `userDetails`, and `userRoles`. See Azure Static Web App's [Client principal data](https://learn.microsoft.com/azure/static-web-apps/user-information?tabs=javascript#client-principal-data) documentation for more details.
511
536
512
-
For example a policy could be the following:
537
+
For example, a policy that utilizes both directive types, pulling the UserId from the access token and referencing the entity's OwnerId field would look like:
513
538
514
539
```json
515
540
"policy": {
516
541
"database": "@claims.UserId eq @item.OwnerId"
517
542
}
518
543
```
519
544
520
-
Data API Builder will take the value of the claim named `UserId` and it will compare it with the value of the field `OwnerId` existing in the entity where the policy has been defined. Only those elements for which the expression will result to be true, will be allowed to be accessed.
545
+
Data API Builder will compare the value of the `UserId` claim to the value of the database field `OwnerId`. The result payload will only include records that fulfill **both** the request metadata and the database policy expression.
546
+
547
+
##### Limitations
521
548
522
-
*PLEASE NOTE* that at the moment support for policies is limited to:
549
+
Database policies are supported for tables and views. Stored procedures cannot be configured with policies.
523
550
524
-
+ Tables and Views. Stored Procedures cannot be configured with policies.
525
-
+ Binary operators [BinaryOperatorKind - Microsoft Learn](https://learn.microsoft.com/dotnet/api/microsoft.odata.uriparser.binaryoperatorkind?view=odata-core-7.0) such as `and`, `or`, `eq`, `gt`, `lt`, and more.
526
-
+ Unary operators [UnaryOperatorKind - Microsoft Learn](https://learn.microsoft.com/dotnet/api/microsoft.odata.uriparser.unaryoperatorkind?view=odata-core-7.0) such as the negate (`-`) and `not` operators.
551
+
Database policies are only supported for the `actions`**read**, **update**, and **delete**.
552
+
553
+
Database policy OData expression syntax supports:
554
+
555
+
- Binary operators [BinaryOperatorKind - Microsoft Learn](https://learn.microsoft.com/dotnet/api/microsoft.odata.uriparser.binaryoperatorkind?view=odata-core-7.0) such as `and`, `or`, `eq`, `gt`, `lt`, and more.
556
+
- Unary operators [UnaryOperatorKind - Microsoft Learn](https://learn.microsoft.com/dotnet/api/microsoft.odata.uriparser.unaryoperatorkind?view=odata-core-7.0) such as the negate (`-`) and `not` operators.
527
557
528
558
#### Mappings
529
-
The `mappings` section enables configuring aliases, or exposed names, for database object fields. The configured exposed names apply to both the GraphQL and REST endpoints. For entities with GraphQL enabled, the configured exposed name **must** meet GraphQL naming requirements. [GraphQL - October 2021 - Names ](https://spec.graphql.org/October2021/#sec-Names)
530
559
531
-
The format is:
560
+
The `mappings` section enables configuring aliases, or exposed names, for database object fields. The configured exposed names apply to both the GraphQL and REST endpoints. For entities with GraphQL enabled, the configured exposed name **must** meet GraphQL naming requirements. [GraphQL - October 2021 - Names ](https://spec.graphql.org/October2021/#sec-Names)
532
561
533
-
`<database_field>: <entity_field>`
562
+
The format is: `<database_field>: <entity_field>`
534
563
535
564
For example:
536
565
@@ -540,4 +569,5 @@ For example:
540
569
"sku_status": "status"
541
570
}
542
571
```
572
+
543
573
means the `sku_title` field in the related database object will be mapped to the exposed name `title` and `sku_status` will be mapped to `status`. Both GraphQL and REST will require using `title` and `status` instead of `sku_title` and `sku_status` and will additionally use those mapped values in all response payloads.
0 commit comments