Bei Authentitifizierung sprechen wir von einem Nachweis einer Eigenschaft gegenüber einer Entität. Übersetzt heißt das, dass ein Request an die REST API authentifiziert werden muss. Der Absender muss ChurchTools klar machen, dass er diese Aktion ausführen kann. Im Browser passiert das mittlels eines Login. Der Nutzer muss einen Benutzernamen und ein Passwort angeben, bevor er eine Aktion in ChurchTools durchführen kann.

Die Authentifizierung über die API kann mittels Passwort oder Login Token passieren. Wir schauen uns im Folgenden beide Verfahren anhand von Beispielen  genauer an und erklären, welche wann am besten geeignet ist.

Benutzername und Passwort #

Es ist möglich, dass man sich mittels Benutzernamen und Passwort authentifiziert. Dies ist sinnvoll, wenn man eine App baut, die Nutzer individuell nutzen können. Sprich, sie müssen sich selber anmelden.

Folgender Request authentifiziert einen Nutzer mit ChurchTools:

POST /login HTTP/1.1
Host: http://churchtools.test/api
Content-Type: application/json

{
 "username": "max",
 "password": "superGeheimesPasswort"
}

Der Endpoint POST /api/login nimmt einen username und ein password entgegen und loggt den Benutzer ein. Als Antwort schickt ChurchTools ein Session-Cookie mit (lies dazu „Cookies & Session“ weiter unten). Dieser Cookie kann für Folgerequests verwendet werden, um mit der REST API zu interagieren.

Login Token #

Die zweite Variante, um sich zu authentifizieren, ist, einen Login Token mitzuschicken. Auch des öfteren API Token genannt. Dieser Token kann über den Authorization Header bei einem Request mitgeschickt werden: Authorization: Login <token> (Bei älteren ChurchTools Versionen war dies über  den Query Parameter login_token=<token> möglich). Sollte der Request unautorisiert sein, d.h. es wurde kein gültiges Session-Cookie mitgeschickt, versucht ChurchTools den Request anhand des Tokens zu authentifizieren.

Der Token ist ein langer Textstring und für jeden Nutzer individuell. Dieser String authentifiziert einen ChurchTools-User. Der Token kann entweder über die Weboberfläche abgerufen werden oder über die API direkt.

Web: In ChurchTools kann der Token unter Personen & Gruppen > Personenliste > „Person A“ > Berechtigungen > Login-Token abgerufen werden.

API: Derselbe Token kann für eine Person auch über den Endpoint GET /api/persons/<personId>/logintoken gefunden werden.

GET /persons/1/logintoken HTTP/1.1
Host: http://churchtools.test/api
Content-Type: application/json

Beispiel: Die ChurchTools-App nutzt eine Kombination aus Login und Token. Der Benutzer kann sich mit Benutzernamen und Passwort in der App einloggen. Dabei wird eine Session erstellt und das Cookie an die App geschickt. Die holt sich im Anschluss sofort den Login Token der Person über die API. Das Session-Cookie wird bei weiteren Requests mitgeschickt. Sollte die Session auslaufen (i.d.R. nach 1 Tag) wird ein 401 Unauthorized zurückgegeben und nun wird mittels des Login Token eine neue gültige Session erstellt. Der Token wird dabei einfach beim nächsten Request angehängt und ChurchTools authentifiziert den Request und erstellt eine neue Session und ein neues Cookie.

Session und Cookie #

In ChurchTools wird für jeden Nutzer eine Session erstellt. Sollte ein Request an ChurchTools gesendet werden, ist es ratsam immer ein gültiges Session Cookie mitzuschicken, sofern vorhanden. Dieses Cookie erlaubt es, auf einen bestehenden schon vorkalkulierten State zurückzugreifen und somit den ganzen Request zu beschleunigen.

Für jede Session berechnet ChurchTools die Berechtigungen für diesen Nutzer. Dieser Schritt ist rechenintensiv. Wird kein Session-Cookie mitgeschickt, würde ChurchTools die Berechtigungen bei jedem Request neu berechnen und das erfordert Zeit. Du sparst dir Zeit und gewinnst an Performance, wenn der Request mit einem gültigen Session-Cookie geschickt wird.