carlobeltrame/hitobito-service-accounts.md Secret

## hitobito-service-accounts.md

      
    Raw
  

              hitobito-service-accounts.md
            
          
    Acceptance Criteria


  For every layer you can create/delete impersonal API Tokens
  A token can be described by a name and a description
  A token is attached to a certain layer, its rights are derived from said layer the token's settings
  API Token can only be created and edited by people with :layer_and_below_full and :layer_full permissions
  per Token I can configure whether a specific API token can

  read People on Layer
  read People on Layer and below
  read Groups (API to be extended)
  read Events (API to come)


 Events and courses can be filtered by year
 UI matches Mockup more or less
 Last accessed date works
 The token value stays the same when changing permissions, description or name
 A token can not be used anymore once it has been deleted
 When deleting an existing token and then recreating it with the exact same settings, the token value is different
 API should always return JSON, and return the same for parameters style and headers style calls
 The events permission should be called "Events and courses", and in German "Anlässe und Kurse". (Note the term Anlass instead of Event)
 API Documentation should be updated
 All API endpoints work the way they are documented
 Additional requirement / future work: CORS header Access-Control-Allow-Origin should be set on all status 200 API responses

Explanations of unmet criteria

❌ API should always return JSON, and return the same for parameters style and headers style calls

Under all circumstances, using parameters style (.json + token query param) and headers style (X-Token + Accept JSON) requests should give the same responses. However currently, for authenticated but unauthorized parameters style requests, the API returns HTML responses with a login form. The corresponding responses when using headers style requests are a simple JSON object { "email": null, "password": null }, which is not beautiful but okay if documented.
Steps to reproduce

GET https://pbs.puzzle.ch/groups/3
Accept: application/json
X-Token: soPFCnKNN5HNeLWAP59PYsRBsaExN_RSezyFrRR7jknxC1ofzQ

yields the response:
{
  "email": null,
  "password": null
}

while
GET https://pbs.puzzle.ch/groups/3.json?token=soPFCnKNN5HNeLWAP59PYsRBsaExN_RSezyFrRR7jknxC1ofzQ

yields the response:
<!DOCTYPE html> <html lang='de'> <head> <meta charset='utf-8'> <title>MiData PBS/MSdS/MSS - Anmelden</title> <meta...

❌ The events permission should be called "Events and courses", and in German "Anlässe und Kurse". (Note the term Anlass instead of Event)

Either this permission should be renamed or a separate permission type for courses should be created.
❌ API Documentation should be updated

The exact required parameters for querying the API with a service account token is not documented at https://github.com/hitobito/hitobito/blob/master/doc/development/05_rest_api.md yet.
Expected

Add something like the following to the documentation:

There are two possible styles for querying the API with a service account token.
Headers style:
GET https://[hitobito domain]/groups/1
X-Token: [service account token]
Accept: application/json

Parameters style:
GET https://[hitobito domain]/groups/1.json?token=[service account token]


Also document which permissions are necessary for which operations (unclear to me was only that the groups permission not only disables access to subgroups, but also to the group to which the token belongs).
All API endpoints work the way they are documented

The following is a list of all cases where the API does not work as expected, when using service account tokens to access it.
❌ Root group endpoint does not work

Accessing the root group endpoint /groups yields the same result as authorization failures regardless of token permissions and even if the token is defined on the root group. In case this is by design, remove the endpoint.
Steps to reproduce

GET https://pbs.puzzle.ch/groups.json?token=wfZPuvZBugipVHeBdWzsbsoLNcasc1xQ-zQKwhyHy5_jAy1hBg

❌ Course endpoint does not work

All requests to the /groups/{id}/events/course endpoint yield the same result as authorization failures regardless of token permissions and even if the token is defined on the root group.
Steps to reproduce

Accessing courses with a token with full permissions:
GET https://pbs.puzzle.ch/groups/1/events/course.json?token=jF4ozjEsSjk12dqFacx9yu4stmbzryy38QyM9PdRNeLfanJwSg

Caution when testing manually: Use an incognito window or make sure that your browser is not logged in to the hitobito instance you are testing. The API currently also reads any active session cookies.
❌ Additional requirement / future work: CORS header Access-Control-Allow-Origin should be set on all status 200 API responses

This is necessary so the API can be used from JavaScript applications in browsers.
Proposition / Expected

Each token could have a list of allowed accessing sources (protocol + (sub)domain + port) for CORS, and the CORS header Access-Control-Allow-Origin is set by the server.