Permissions.adoc

Rules & Permissions

With Operations and Users established, we’ve got everything we need to start creating other resources.

However, in practice, it is cumbersome to have to update Operations every time we want to authorize a new User to perform an Operation. This is where Permissions come in.

Permissions are separate Documents that represent a specific authorization. A document can be put into the database to represent a permission when it is granted, and (just as easily) deleted from the database when the authorization is revoked.

Tip	Permissions are straight-forward to grant and revoke, as they are represented as XTDB documents, so granting and revoking a permission can be done with XTDB’s respective :xtdb.api/put and :xtdb.api/delete operations.

An Operation’s Rules specify how Permissions determine the outcome of authorization decisions.

By writing Rules in terms of Permissions, as opposed to Users, grants and revocations are easier to manage and report on.

Document structure of a Permission

Document structure of a Permission lists the attributes found in Permission documents.

Table 1. Document structure of a Permission

Attribute	Value	Required?
:xt/id	Permssions are resources, so this is a URI.	Required
:juxt.site.alpha/type	"https://meta.juxt.site/pass/permission"	Required
:juxt.pass.alpha/operation	The URI of the Operation this Permission grants access to.	Required
:juxt.pass.alpha/purpose	The purpose of the Permission. Can be nil.	Required

Creating a permission

We must install a Permission which will allow our user to call our create-operation Operation.

This gives us an opportunity to inspect the document structure of a real Permission.

Permitting the create-operation operation demonstrates creating a Permission that works with the Operation we created in [example-create-operation].

Example 1. Permitting the create-operation operation

link:../../test/juxt/book.clj[role=include]

1. Permissions are individual resources, and must have unique URIs.

2. Each Permission must have a :juxt.site.alpha/type attribute of “Permission”.

3. The Permission must be tied to a specific Operation.

4. The Permission can be granted for a particular purpose, but if not, this attribute must be nil.

5. In this case, the Permission references the Administrator role. All Users with this Administrator role will be able to call the https://site.test/_site/operations/create-operation operation.

Note	In future we might allow different users using the same REPL to identify themselves. Of course, REPL users have no restrictions to what they can do, so this is just for audit purposes among trusted users.

Warning

Access to the REPL must be restricted to a very limited set of authorized users.

Important

Grant your user the Permission to invoke the create-operation function you created in [example-create-operation]: Copy the code in Permitting the create-operation operation to an editor. Update it according to the Base URI you have chosen. Copy the modified code into the REPL. Evaluate!

Creating the grant-permssion operation

We have now created a create-operation Operation and granted a Permission for our User to invoke it. Let’s invoke this operation to create a new grant-permission operation.

Creating the grant-permission operation demonstrates how this is achieved.

Example 2. Creating the grant-permission operation

link:../../test/juxt/book.clj[role=include]

Important

Create the grant-permission operation by following these steps: Copy the code from Creating the grant-permission operation into an editor Make appropriate changes Copy into the REPL Evaluate

Finally, we need to permit our REPL user to invoke this grant-permission operation, and this permission too needs to be put directly into the database since we don’t yet have a way of granting permissions!

This is shown in Permitting the grant-permission operation.

Example 3. Permitting the grant-permission operation

link:../../test/juxt/book.clj[role=include]

Important

Permit the grant-permission operation by following these steps: Copy the code from Permitting the grant-permission operation into an editor Make appropriate changes Copy into the REPL Evaluate

Now that we have the ability to create actions, and grant permissions to invoke them, we have the building blocks we need to start creating Resources.