diff --git a/FEDERATION.md b/FEDERATION.md index e5e72bf..f3b56e6 100644 --- a/FEDERATION.md +++ b/FEDERATION.md @@ -539,6 +539,90 @@ The technical details: #### (5) Object capability authorization tokens +Allows actors to delegate resource access to other actors, by sending them an +authorization token. There are many kinds of authorization tokens, and many of +them are good relevant candidates here, for example: + +- OCAP-LD +- Macaroons +- JWT + +This proposal, however, describes the current implementation in Vervis, which +uses a simple HMAC to authenticate the authorization token. Vervis on purpose +uses a minimal approach, so that it's easy to keep track of what its minimal +needs really are. It's totally possible and acceptable though, that this +proposal switches to a standard auth token format such as the ones listed +above. Until this proposal gets feedback and discussion, it describes the +minimal HMAC approach. + +Aviva manages a yoga school. Luke is a new yoga teacher in the school, and +Aviva would like to give him access to open and lock all the rooms in the +school building. Aviva posts a `Delegate` activity to her server: + +```json +{ "@context": + [ "https://www.w3.org/ns/activitystreams" + , { "ext": "https://peers.community/as2-ext#" + , "Delegate": "ext:Delegate" + , "Role": "ext:Role" + } + ] +, "type": "Delegate" +, "to": + [ "https://meditation.space/users/luke" + , "https://yoga.dev/school-staff" + ] +, "target": "https://meditation.space/users/luke" +, "context": "https://yoga.dev/places/school-building" +, "object": + { "id": "https://yoga.dev/roles/teacher" + , "type": "Role" + } +} +``` + +Aviva's server assigns an ID to the activity, and also attaches a cryptographic +proof. When Luke will later try to open doors in the school, the proof will be +used to validate his authorization token. The `proof` field maps to a Base64 +encoding of the HMAC-SHA256 of the activity's ID, where the key used for the +HMAC is a secret key the server holds. + +```json +{ "@context": + [ "https://www.w3.org/ns/activitystreams" + , { "ext": "https://peers.community/as2-ext#" + , "Delegate": "ext:Delegate" + , "Role": "ext:Role" + } + ] +, "id": "https://yoga.dev/users/aviva/outbox/m10d6" +, "type": "Delegate" +, "to": + [ "https://meditation.space/users/luke" + , "https://yoga.dev/school-staff" + ] +, "target": "https://meditation.space/users/luke" +, "context": "https://yoga.dev/places/school-building" +, "object": + { "id": "https://yoga.dev/roles/teacher" + , "type": "Role" + } +, "proof": "bDMCcPFntgpMoEG6SSFkXCBRm2K96h0ecFsbr11hFx0=" +} +``` + +Later, when Luke wants to open a door, he publishes an activity and attaches +the `proof` field. Aviva's server then: + +- Verifies the HMAC +- Finds the Delegation in the database +- Finds out that delegation gives Luke access as a teacher +- Verifies the HTTP Signature of the activity, thus verifying the sender is + indeed Luke +- Checks that the door Luke wants to open can be opened by people holding a + teacher role +- If all checks pass, Luke can open the door + #### (6) Managing actor Allows an object to specify which actor manages it. For example, if you'd like