Bei Authentifizierung sprechen wir von einem Nachweis einer Eigenschaft gegen\u00fcber einer Entit\u00e4t. \u00dcbersetzt hei\u00dft das, dass ein Request an die REST API authentifiziert werden muss. Der Absender muss ChurchTools klarmachen, dass er diese Aktion ausf\u00fchren kann. Im Browser passiert das mittels eines Login. Der Nutzer muss einen Benutzernamen und ein Passwort angeben, bevor er eine Aktion in ChurchTools durchf\u00fchren kann.<\/p>\n\n\n\n
Die Authentifizierung \u00fcber die API kann mittels Passwort oder Login Token passieren. Wir schauen uns im Folgenden beide Verfahren anhand von Beispielen genauer an und erkl\u00e4ren, welche wann am besten geeignet ist.<\/p>\n\n\n\n
Es ist m\u00f6glich, dass man sich mittels Benutzernamen und Passwort authentifiziert. Dies ist sinnvoll, wenn man eine App baut, die Nutzer individuell nutzen k\u00f6nnen. Sprich, sie m\u00fcssen sich selbst einloggen.<\/p>\n\n\n\n
Folgender Request authentifiziert einen Nutzer mit ChurchTools:<\/p>\n\n\n\n
Der Endpoint Die zweite Variante, um sich zu authentifizieren, ist, einen Login-Token mitzuschicken. Auch des \u00f6fteren API-Token genannt. Dieser Token kann \u00fcber den Authorization Header bei einem Request mitgeschickt werden: Der Token ist ein langer Textstring und f\u00fcr jeden Nutzer individuell. Dieser String authentifiziert einen ChurchTools-User. Der Token kann entweder \u00fcber die Weboberfl\u00e4che abgerufen werden oder \u00fcber die API direkt.<\/p>\n\n\n\n Web:<\/strong> In ChurchTools kann der Token \u00fcber das Profil eines Nutzers abgerufen werden.<\/p>\n\n\n\n API:<\/strong> Derselbe Token kann f\u00fcr eine Person auch \u00fcber den Endpoint GET \/api\/persons\/<personId>\/logintoken gefunden werden.<\/p>\n\n\n\n GET \/persons\/1\/logintoken HTTP\/1.1 Beispiel:<\/strong> 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 \u00fcber die API. Das Session-Cookie wird bei weiteren Requests mitgeschickt. Sollte die Session auslaufen (i. d. R. nach 1 Tag) wird ein In ChurchTools wird f\u00fcr jeden Nutzer eine Session erstellt. Sollte ein Request an ChurchTools gesendet werden, ist es ratsam, immer ein g\u00fcltiges Session-Cookie mitzuschicken, sofern vorhanden. Dieses Cookie erlaubt es, auf einen bestehenden, schon vorkalkulierten State zur\u00fcckzugreifen und somit den ganzen Request zu beschleunigen.<\/p>\n\n\n\n F\u00fcr jede Session berechnet ChurchTools die Berechtigungen f\u00fcr diesen Nutzer. Dieser Schritt ist rechenintensiv. Wird kein Session-Cookie mitgeschickt, w\u00fcrde 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\u00fcltigen Session-Cookie geschickt wird.<\/p>\n\n\n\nPOST \/login HTTP\/1.1<\/code>Host: http:\/\/meine-gemeinde.test\/api<\/code>Content-Type: application\/json<\/code>{<\/code>\u00a0\"username\": \"max\",<\/code>\u00a0\"password\": \"superGeheimesPasswort\"<\/code>}<\/code><\/p>\n\n\n\nPOST \/api\/login<\/code> nimmt einen Benutzernamen<\/code> und ein Passwort<\/code> entgegen und loggt den Benutzer ein. Als Antwort schickt ChurchTools ein Session-Cookie mit (lies dazu \u201eSession und Cookies\u201c weiter unten). Dieser Cookie kann f\u00fcr Folgerequests verwendet werden, um mit der REST API zu interagieren.<\/p>\n\n\n\nLogin-Token<\/h3>\n\n\n\n
Authorization: Login <token><\/code>. Sollte der Request nicht autorisiert sein, d. h. es wurde kein g\u00fcltiges Session-Cookie mitgeschickt, versucht ChurchTools den Request anhand des Tokens zu authentifizieren.<\/p>\n\n\n\n
Host: http:\/\/meine-gemeinde.test\/api
Content-Type: application\/json<\/p>\n\n\n\n401 Unauthorized<\/code> zur\u00fcckgegeben und nun wird mittels des Login-Token eine neue g\u00fcltige Session erstellt. Der Token wird dabei einfach beim n\u00e4chsten Request angeh\u00e4ngt, ChurchTools authentifiziert den Request und erstellt eine neue Session und ein neues Cookie.<\/p>\n\n\n\nSession und Cookie<\/h2>\n\n\n\n