Authentifzierung

Bevor gesicherte Anfragen durchgeführt werden können, ist ein gültiges Authentifizierungs-Merkmal- künftig Token genannt - erforderlich. Die Authentifizierung erfolgt über API Aufruf mit Benutzername sowie Passwort-Schlüssel und gibt im Erfolgsfall ein JWT Token zurück.

Das Token muss bei allen Anfragen außer der Anmeldung übergeben werden. Für die Verwendung des Token siehe Token verwenden

Für die Authentifzierung sind folgende Informationen notwendig:

• Server-URL
• Benutzername / Email
• Passwort

Weiterhin werden folgende Informationen für weitere Aufrufe benötigt.

• Gemeinde-ID(s)
• Objekt-ID(s)

Diese Informationen lassen sich nach der Authentifizierung direkt über den get_config Aufrufen.

Token erzeugen

POST api /token/

Besonderheit

Die Authentifzierung kann zusätzlich zur Übergabe als JSON oder XML ebenfalls als application/x-www-form-urlencoded übergeben. werden - eher bekannt als Formular-Daten.

Somit ist eine interaktive Anmeldung im System über z.B. ein HTML Formular oder eine Dritt-Anwendung möglich.

Beispiele

Request

{
  "username": "m.mustermann",
  "password": "5bed8a17a5f780aa3b541e41c62416a64"
}

Response

{
  "token": "eJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ...<abgeschnitten>"
}

Token verwenden

Das Token wird bei jeder Abfrage im HTTP Header "Authorization" übergeben. Vor das im ersten Schritt erzeugte Token

HTTP Header Authorization
Prefix: JWT

Beispiel:

Authorization: JWT eyJhbGciOiJIUzI1NiIeyJ4554dscvd499dfcc....

Bitte auf das Präfix JWT sowie die Leerstelle zwischen dem Präfix und dem eigentlich Token achten. [PRÄFIX|LEERSTELLE|TOKEN]

Alternativ kann das JWT Token auch als GET-Parameter "jwt" übergeben werden:  https://.../?jwt=<token>

Code-Beispiele

Token abfragen

# pip3 install requests 
import requests
payload = {
    'username':'demo',
    'password':'demo',
}

r = requests.post('https://<API_URL>/api/token/',data=payload)
server_response_json = r.json()

jwt_token = server_response_json.get('token') # Aus dem server_response objekt den String-Wert aus "token" extrahieren
print(jwt_token)
# <str>: eJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Token in Header übergeben

# pip3 install requests
import requests
payload = {
    # Beliebige Daten
}

# variable jwt_token aus vorherigem Beispiel
headers = {
  'authorization': 'JWT %s' % jwt_token # Ergibt "JWT eJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

#Hier wird der Header mit übergeben
r = requests.post('https://<API_URL>/<anfrage>/',data=payload,headers=headers) 
server_response_json = r.json()
# ...

Meta-Object

Zusätzlich zu einem passenden Auth-Token wird eine meta Objekt für alle authentifzierten Anfragen benötigt. Dieses Objekt identifiziert die Abfrage und übergibt einen Kontext für den Aufruf.

So geben gemeinde, vermieter und objekt an, für welche Gemeinde sowie welchen Vermieter und Objekt der Gemeinde der Aufruf verwendet wird.

JSON-Schema: /api/meldeschein/schema/meta/

Das Meta Objekt kann nicht alleine übergeben werden. Es gehört immer zu einem weiteren Aufruf (siehe entspr. Kapitel)

Parameter

Beispiele

Request

<?xml version="1.0" encoding="utf-8"?>
<meta>
    <description>Eine Beispielbuchung</description>
    <vermieter>1</vermieter>
    <objekt>1</objekt>
    <gemeinde>1</gemeinde>
</meta>
<!-- weitere Daten -->