OAuth.md

OAuth Authentifizierung

Das folgende Dokument beschreibt wie die OAuth-basierte Authentifizierung mithilfe des FIT-Connect Commandline-Tools funktioniert. Dafür werden entweder OAuth-Credentials (Client-ID, Client-Secret) sowie die Adresse des OAuth-Token-Endpunktes oder ein Zugang zum FIT-Connect Developer Portal benötigt. Weitere Informationen dazu wie die OAuth-Authentifizierung selbst implementiert werden kann befinden sich in Authentifizierung von Fachanwendungen und Authentifizierung von Usern an Zustelldiensten - außerdem ist hier das Konzept zu Zustellberechtiungs-Scopes zu beachten.

Installation CLI-Tool

Das CLI-Tool kann über den Python Paketmanager pip installiert werden. Dafür muss Python 3.6 oder neuer installiert sein.

pip install fitconnect-cli

Nach der Installation von fitconnect-cli kann mithilfe des folgenden Kommandos eine neue FIT-Connect API-Konfiguration angelegt werden.

 fitconnect create_config --config=test_sender.json  

Hierbei muss ausgewählt werden, ob ein Sende- oder Empfangsdienst betrieben werden und ob automatisch RSA-Keys für die Generierung von JWTs angelegt werden sollen.

 fitconnect create_config --config=test_sender.json  
? Do you want to setup a config for a sender (e.g. onlineservice) or receiver?  sender
? Oauth Token URL:  https://fit-connect.de/oauth/token
? Client id:  nnXVC6DSPG9BkoMw5NXOur4RPOkEpLMMwYFbycIo
? Client secret:  Yj9PduOSsjGzwsIDXGRLrzDarZdKE4QPXuil21FqJGlVnZTDqcM7S5FruJA4kv1L3K4PCmAqAuK11y2fwu2MDVBiDUgWTBLc1e3H8tV0sD5PzlEiV7nCUAYBP7u8tG01
? Do you want to create a jwt signature key?  yes
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAv6ixhhwQm8nTAAtgSBRP
gNUuucb4e9Y0G2n8SBy4aEflIfrqKqqM1LRzLLnqvFiiiXI8heTx6AvMjQsqScHt
0SDONWliz2s+lA80xyW+nJRKI/WUxXOZX0xqQD8XL6ZksE+nhZ9bKo7o5lXwQF6C
p3BGV30kPgfGOCNPg4P5QpsP9UUfGvz1OXNNUPoMKovyXHAd7k4gI6TWZSqCbJwG
3Y3v7WZKIb/1PGhkc7oR+SJ3t0jYJByRnhTyQAoMpODBlPz27/MOkozoNaAkjf6b
pKcnasYCJHkuAcCS7pI5VZz7YNZPl3dm0g4woOsJeEdV2B2fyv4E0uYw2eRFsxlu
/TdAid6UAf1fMz4JVoJ3dsca+1zySX7S4P+pVjNXQW0cGVO4hksvQSFwhBpnEAEw
rHBdVV15UVT98cFEfhlv3utI6KdXJqpnWBm8g9K3tFSAoTNXz81XAnFnZgLqA4If
bws0R7Zu8fXYMQuGS2APzhH4QWVcqrgWizzg0P39W0f+44DIUgc6LJ344Iog3f2j
ix3WeKi/VrKfJCLCisZyDUJNze9WfWVersGVMsgnND84y9+EG2Pp/m99jF+asrDi
gJa7FZjjoXRJVhTBcGQ1eW95G+Vm/oKkAp+unFBCqNtS610vQzviM147KtIvUrpj
q1r1v0Vzj+qk9WEGVz/Gl4MCAwEAAQ==
-----END PUBLIC KEY-----

Nachdem der Assistent abgeschlossen wurde, sollte im aktuellen Verzeichnis eine JSON-Datei mit allen benötigten Konfigurationen angelegt worden sein. Diese lässt sich nun mit einem FIT-Connect-API-Client oder dem fitconnect-cli weiterbenutzten.

Generierung von JWTs

Mithilfe der fitconnect-cli können JWTs zum Abrufen von bzw. Versenden von Anträgen generiert werden. Dabei wird zuerst über das OAuth 2 Client Credentials Verfahren ein JWT abgerufen und dann falls Antreäge versendet werden sollen der sogenannte Online-Service-Token mit eingeschränkten Berechtigungen davon abgeleitet.

Für die Generierung von JWTs zum Versenden von Anträgen muss neben der Konfiguration außerdem über den Parameter destination angegeben werden, an welche Destination-IDs Anträge gesendet werden sollen.

fitconnect get_jwt --config=test_sender.json --destination "d771f1d8-6967-4740-9668-82c5a910a29b"

Bei erfolgreicher Generierung erhält man ein JSON-Objekt mit einem Token und einen Online-Service-Token zurück. Diese können dann dazu verwendet werden um mithilfe eines FIT-Connect-API-Client oder CURL einen Antrag versenden.

{
    "online-service-token": "..online-service-token...",
    "token": "...token..."
}

Der dekodierte Inhalt eines Online-Service-Tokens sieht z.B. so aus:

{
  "iss": "FITCONNECT",
  "exp": 1623275003,
  "iat": 1623260603,
  "domains": [],
  "publicKey": {
    "n": "...RSA Token...",
    "e": "AQAB",
    "kty": "RSA"
  },
  "scope": [
    "leika:991080082520",
    "region:03254021",
    "leika:991080082520+region:03254021"
  ],
  "clientType": "sender"
}

Und der eines Tokens so:

{
  "iss": "Onlineservice",
  "exp": 1623267803,
  "iat": 1623260603,
  "domains": [],
  "scope": [
    "destination:d771f1d8-6967-4740-9668-82c5a910a29b"
  ],
  "clientType": "user-sender"
}

Ein CURL-Request um dann mit diesen Tokens auf die API zuzugreifen, könnte z.B. so aussehen:

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "token: ...token..."  -H "online-service-token:  ...online-service-token..." https://fit-connect-url.einfügen

Wenn ein JWT zum Abrufen von Anträgen generiert werden soll, kann auf den Parameter destination verzichtet werden.

fitconnect get_jwt --config=test_receiver.json 

Bei erfolgreicher Generierung erhält man einen JWT Token, welchen man zur Authentifizierung gbeim Abrufen von Anträgen verwenden kann

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "token: ...token..."  https://fit-connect-url.einfügen