Pebbles Security Model (Actions)

About this document

PSM is the Pebbles Security Model. It is documented here:

https://github.com/bengler/checkpoint/wiki/Pebbles-Security-Model

This document covers PSM as it pertains to create, update or delete actions. For document visibility, read this:

https://github.com/bengler/checkpoint/wiki/Pebbles-Security-Model-(Visibility)

Actually, you should read that document first either way, as some core concepts are only explained there.

How to be a PSM compliant action-pebble

The only thing you need to do to be a PSM-compliant pebble when it comes to action, is to ask Checkpoint every time someone tries to create, update or delete an object. The way to do this is to ask this endpoint for permission:

GET /api/checkpoint/v1/callbacks/allowed/:method/:uid

Provide the parameter identity with the id of the identity wanting to perform the action. E.g. like this:

GET /api/checkpoint/v1/callbacks/allowed/update/post.comment:apdm.firda.conversations.123$456?identity=13

This will check if identity 13 is allowed to update the document post.comment:apdm.firda.conversations.123$456.

If Checpoint determines that the action is allowed, it will return this:

{"allowed": true}

This means that Checkpoint wants to override any security logic in your pebble and perform the action.

If the action is disallowed, checkpoint will also furnish a reson:

{"allowed": false, "reason": "This is not your document, and  you are not a moderator."}

If checkpoint has no opinion on the matter it will respons:

{"allowed": "default"}

This means you should use internal rules to determine whether to perform the action. In the typical case this means anyone may create, but only the owner of the document may update or delete.

This is all there is to it.

How to create custom policies

The goal of PSM is to be able to express all kinds of possibly intricate app-specific policies. The way to do this is to implement policy callbacks. You do this by implementing an endpoint in your app and register it with checkpoint. If you wanted to implement specific rules for all actions touching the documents in the subtree apdm.firda, and your callback was at http://firda.no/api/my_service/my_psm_callback, you would register it with checkpoint by issuing the following line in the Checkpoint console:

>> Callback.create!(:path => "apdm.firda", :url => "http://firda.no/api/my_service/my_psm_callback")

This specific callback would guard all actions happening in the subtree starting ag apdm.firda. So for any action touching a document with a path starting with apdm.firda, checkpoint will consult your callback. Any number of overlapping callbacks may be registered with Checkpoint. Checkpoint will make sure to consult all relevant callbacks for each action.

Checkpoint will POST to your callback with the parameters method, uid and identity. If a client has just asked for permission to perform an action with the following request to checkpoint:

GET /api/checkpoint/v1/callbacks/allowed/update/post.comment:apdm.firda.conversations.123$456?identity=13

Your callback will get the following post:

{
  "method": "update",
  "uid": "post.comment:apdm.firda.conversations.123$456",
  "identity": 13
}

If your callback has an opinion on the matter, it should return a json hash with the "allowed" key. To allow the action:

{"allowed": true}

If the action is not allowed, you must also provide a reason. Like this:

{"allowed": false, "reason": "This is not your document, and you are not a moderator"}

If you have no opinion on the matter, you may return an empty hash:

{}

That should be all. Thank you!