diff options
Diffstat (limited to 'doc/000.yarn')
| -rw-r--r-- | doc/000.yarn | 172 |
1 files changed, 0 insertions, 172 deletions
diff --git a/doc/000.yarn b/doc/000.yarn deleted file mode 100644 index 2bfff88..0000000 --- a/doc/000.yarn +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Effireg architecture -author: Lars Wirzenius -... - -# Introduction - -Effireg is a web-based membership register for the Effi non-profit -association. See <https://effi.org/> for more information about Effi. - -Effireg is written for Effi, but it is free software, released under -the Affero GPL v3 license, and may be used by others. No guarantees of -quality. - -# Architecture overview - -## Assumptions - -The architecture has been designed under the following assumptions: - -* Privacy is important, and should be the default. People should only - have access to the information they are authorized to access. - -* Members should be able to see their own information, without having - to go through the Effi membership register admin. - -* It's not practical to have every member have a password. - Authentication can be done by sending the member a unique, - single-use link when they want to log in. - -## Components - - - -Effireg consists of four main components: - -* **effiapi** provides a RESTful HTTP API for managing the membership - data, and for doing things with or to the data. All operations go - via the API. - -* **effiweb** provides the frontend for the web application to use the - membership register. It renders HTML to the user, is accesses via a - web browser, and generally is the user-visible part of Effireg. - -* **Qvisqve** provides authentication of end-users (the members, and - admins). It lets users log in, and keeps track of what each user is - allowed to do. - -* **Muck-POC** stores the actual membership register data, and - controls access to it, based on access tokens from Qvisqve. - -## Authentication - -[OpenID Connect]: https://openid.net/specs/openid-connect-core-1_0.html -[OAuth2]: https://oauth.net/2/ - -End-users are authenticated using the [OpenID Connect][] protocol, -specifically the authorization code flow. In this flow, Qvisqve -provides cryptographically signed access tokens, which identify the -user and specify a list of things the user may do. The signature -guarantees the token comes from Qvisqve. - -Non-interactive API clients are authenticated using the [OAuth2][] -protocol, specifically using client credential grants. This also -provides an access token, similar to the one from end-user -authentication. - -# Data model - -The membership register stores data as "resources" in Muck-POC. Each -resource is a JSON object. The following types of objects are -supported: - -* **subject** represents a person who is allowed to use the register; - it it used to identify the user for authentication -* **password** stores the encrypted password for a subject -* **memb** represets a subject's membership in Effi - -### Subject resource - -A subject resource has the following fields: - -* `username` — the username of the subject; this can change, the - subject is identified by the resource identifier in the register, - not by the username - -The subject resource does not have any data that isn't needed for -end-user identification. Effiapi manages and Qvisqve uses the subject -resource. - -### Password resource - -A password resource has the following fields: - -* `subject_id` — resource id of the subject whose password this - is -* `version` — version of the password resource (identifies - algorithm); must be 1 -* `hash` — the password, encrypted with the scrypt algorithm -* `salt` — a random string to prevent dictionary attacks -* `key_len` — parameter for scrypt -* `N` — parameter for scrypt -* `r` — parameter for scrypt -* `p` — parameter for scrypt - -Effiapi manages and Qvisqve uses the password resource. - -### Member resource (memb) - -A membership resource has the following fields: - -* `subject-id` — the resource id of the subject resource for - the member -* `fullname` — the full name of the member -* `primary-email` — the primary email address for the member - (and currently the only one) -* `years-paid` — list of integers for the years for which the - member has paid their membership - -Effiapi manages and uses the memb resource. Effiweb renders it for the -user. - -# effiapi - -[yarn]: https://liw.fi/cmdtest/ - -This chapter descibes the effiapi API, as a [yarn][] automated -scenario test. It is meant to be understandable to Effi sysadmins, as -well as be an executable test suite for the API. - -The API is a simple RESTful HTTP API using JSON. This means that: - -* each API call is an HTTP request, with a response - -* all data is represented as JSON in the body of the request of - response - -* metadata about the data is represeneted as HTTP headers - -* standard HTTP verbs (POST, PUT, GET, DELETE) are used to indicate - the action - -* standard HTTP status codes are used to indicate result of the - request (200 = OK, 404 = not found, etc) - -## Manage memberships - -This section shows the API calls to manage a memberhip: to create the -member, to update and retrieve it, and to search memberships. - -~~~ -SCENARIO Manage memberships - -GIVEN An effiapi instance -WHEN admin requests POST /memb with body { "fullname": "James Bond" } -THEN the member id is ID - -WHEN admin requests GET /memb with header Muck-Id: ${ID} -THEN HTTP status 200 -AND HTTP body matches { "fullname": "James Bond" } -~~~ - -TODO: - -* update -* delete -* search -* members can see their own data, and can't see each others' -* member follows authn link emailed to them - -# Appendix: Yarn scenario step implementations - |