Tutorial 6 - Adding access control rules

/users

public

This endpoint’s GET request remains public, so that anyone can attempt to retrieve this collection’s documents.

When requesting all documents inside a collection, Datastore uses the x-datastore-acl rule defined in the document’s get request block to ensure that the user has access to the document.

For a document to be included within a collection (from a GET request), the user (represented by the JWT’s userid value) would also need to satisfy the x-datastore-acl rule defined on the document’s get request block. Any documents to which the user does not satisfy the document’s x-datastore-acl rule are excluded from the collection.

Although the event app does not use this path, making a request to it (based on the x-datastore-acl rule of its document endpoint in the next row below) will only ever return the currently authenticated user’s user document, or an empty collection if a user is not authenticated.

/users/{userid}

jwt.userid === document.userid

This endpoint’s GET request only allows the request if the userid value in its JWT matches the userid property of the user document.

From the users.json schema utilized by this endpoint as defined in tutorial 5, which in turn utilizes the user.json schema (also defined in tutorial 5), the userid property uses the x-datastore-source JSON schema Datastore extension property value of document.$id.

Therefore, this rule ensures that the userid in the app’s JWT object matches the unique ID of the app’s user document, represented by {userid} in the URL path. The same result could also be achieved by specifying the rule as
jwt.userid === document.$id.

Once a user has been successfully authenticated to the authentication service (e.g. Matrix) registered with your Datastore service, the JWT representing this user can then be sent in the request as part of the payload to the Datastore service (via the JS SDK). For the request to succeed, this JWT received in the request by the Datastore service, must match that of the the JWT which Datastore also retrieves directly from this the authentication service. Therefore, this rule ensures that the user must be logged in to the registered authentication service, with the same user account represented by the JWT sent in the request.

jwt.userid === document.userid

The same endpoint’s PUT request uses the same rule as its GET request. However, this rule only allows a new user document to be created when the userid value in its JWT matches the userid value for the user document being created.

Following on from the additional explanations above, this rule ensures that to create a new user document (with the revised API specification), the JWT must represent the same user, who must already be logged in to the registered authentication service. This is why the JS SDK simulator function call in callout 4 of the createUser() function description in tutorial 5 is made to retrieve the JWT (from the simulated Datastore service) of the newly 'logged in' user, just before their user document is created in Datastore.

This rule prevents a user from creating a user document as anyone else except themselves, and prevents one user from overriding another user’s account.

/users/{userid}/events

jwt.userid === parent.userid

This rule only allows the request if the userid value in its JWT matches the {userid} component’s value (for the user document) in the request’s URL. This component of the URL is the parent of this request URL’s endpoint.

/users/{userid}/events/{eventid}

jwt.userid === parent.userid

This rule only allows the request if the userid value in its JWT matches the {userid} component’s value (for the user document) in the request’s URL.

Although this component of the URL is theoretically the grandparent of this request URL’s endpoint, the parent. syntax in the rule value only applies to the immediate ancestral URL components that contain properties. Since collections themselves do not contain properties, Datastore is aware of this and ignores any collection in the URL path.