diff --git a/docs/content/modeling/blocklists.mdx b/docs/content/modeling/blocklists.mdx index 14b44fe0d8..2f5b2fb937 100644 --- a/docs/content/modeling/blocklists.mdx +++ b/docs/content/modeling/blocklists.mdx @@ -39,14 +39,10 @@ This is useful when: Before you start this guide, make sure you're familiar with some and know how to develop the things listed below. -
- You will start with the __ below, it represents a `document` __ that can have users **** as `editor`, and `team` type that can have users related as `member`. -Let us also assume that we have a `document` called "planning", shared for editing within the product `team` (comprised of becky and carl). - -The current state of the system is represented by the following relationship tuples being in the system already: - - - -
+Let us also assume that we have a `document` called "planning", shared for editing within the product `team` (comprised of becky and carl). -In addition, you will need to know the following: +```yaml + # Becky is a member of the product team + - user: user:becky + relation: member + object: team:product -### Modeling user groups + # Carl is a member of the product team + - user: user:carl + relation: member + object: team:product -You need to know how to add users to groups and grant groups access to resources. [Learn more →](.//user-groups.mdx) + # Members of the product team can edit the planning document + - user: team:product#member + relation: editor + object: document:planning +``` -### Concepts -- A : a class of objects that have similar characteristics -- A : an entity in the system that can be related to an object -- A : is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system -- An : represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model -- A : a grouping consisting of a user, a relation and an object stored in -- [Exclusion Operator](../configuration-language.mdx#the-exclusion-operator): the exclusion operator can be used to exclude certain usersets from being related to an object +
-
- ## Step by step With the above authorization model and relationship tuples, will correctly respond with `{"allowed":true}` when is called to see if Carl and Becky can edit this `document`. -We can verify that by issuing two check requests: - - - - - +We can verify that with these two tests which will pass: + +```yaml +tests: + - name: "Becky can edit the 'planning' document" + check: + - user: user:becky + object: document:planning + assertions: + editor: true + - name: "Carl can edit the 'planning' document" + check: + - user: user:carl + object: document:planning + assertions: + editor: true +``` We want to share a document with the product team and also have the ability to deny certain users access, even if they have the document shared with them already. We can verify this by blocking Carl (who we have seen already has edit access) from editing the document. In order to do that, we need to: @@ -149,11 +134,9 @@ In order to do that, we need to: 2. [Modify our model to indicate that users who are blocked can no longer edit the document](#02-modify-our-model-so-users-who-are-blocked-can-no-longer-edit-the-document) 3. [Verify that our solution works](#03-verify-our-solution-works): -a. [Indicate that Carl is blocked from the planning document](#a-indicate-that-carl-is-blocked-from-the-planning-document) - -b. [Carl (now blocked) can no longer edit the document](#b-carl-now-blocked-can-no-longer-edit-the-document) - -c. [Becky still has edit access](#c-becky-still-has-edit-access) + a. [Indicate that Carl is blocked from the planning document](#a-indicate-that-carl-is-blocked-from-the-planning-document) + + b. [Carl (now blocked) can no longer edit the document](#b-carl-now-blocked-can-no-longer-edit-the-document), but Becky still has edit access ### 01. Modify our model so users can be blocked from accessing a document @@ -266,34 +249,33 @@ To check if our new model works, we'll add a relationship tuple with Carl as `bl With our modified authorization model, we can indicate that Carl is blocked by adding this __. - +```yaml + # Carl is blocked from the planning document + - user: user:carl + relation: blocked + object: document:planning +``` #### b. Carl (now blocked) can no longer edit the document We have modified the authorization model and added relationship tuples to indicate that Carl is `blocked`. Now let's make sure our solution works as expected. -To check if Carl still has access to the document, we can issue a check request with Carl as the user. - - - -The response is `false`, so our solution is working as expected. - -#### c. Becky still has edit access - -To check if Becky still has access to the document, we'll issue another check request with Becky as the user. - - - -The response is `true`, indicating our model change did not inadvertently deny access for users who have access but are not blocked. +With these tuples, Carl will not be able to edit the document, but Becky will: +```yaml +tests: + - name: "Carl can edit the 'planning' document" + check: + - user: user:carl + object: document:planning + assertions: + editor: false + - name: "Becky can edit the 'planning' document" + check: + - user: user:becky + object: document:planning + assertions: + editor: true +``` :::caution When creating tuples for make sure to use unique ids for each object and user within your application domain. We are using first names and human-readable identifiers to make this task easier to read.