Zum Hauptinhalt springen
Version: Next

Anleitung für Bezahldienste

Implementierung​

API-Aufruf​

Der API-Aufruf enthält zwei HTTP-Header:

  • Authorization: Enthält Bearer + das Access Token
  • DPoP: Enthält das DPoP Proof JWT

DPoP Proof JWT prüfen​

Die Prüfung eines DPoP Proof JWTs wird in RFC 9449, Sec. 4.3 beschrieben:

To validate a DPoP proof, the receiving server MUST ensure the following:

  1. There is not more than one DPoP HTTP request header field.
  2. The DPoP HTTP request header field value is a single and well-formed JWT.
  3. All required claims per Section 4.2 are contained in the JWT.
  4. The typ JOSE Header Parameter has the value dpop+jwt.
  5. The alg JOSE Header Parameter indicates a registered asymmetric digital signature algorithm [IANA.JOSE.ALGS], is not none, is supported by the application, and is acceptable per local policy.
  6. The JWT signature verifies with the public key contained in the jwk JOSE Header Parameter.
  7. The jwk JOSE Header Parameter does not contain a private key.
  8. The htm claim matches the HTTP method of the current request.
  9. The htu claim matches the HTTP URI value for the HTTP request in which the JWT was received, ignoring any query and fragment parts.
  10. If the server provided a nonce value to the client, the nonce claim matches the server-provided nonce value.
  11. The creation time of the JWT, as determined by either the iat claim or a server managed timestamp via the nonce claim, is within an acceptable window (see Section 11.1).
  12. If presented to a protected resource in conjunction with an access token,
    • ensure that the value of the ath claim equals the hash of that access token, and
    • confirm that the public key to which the access token is bound matches the public key from the DPoP proof.
      To reduce the likelihood of false negatives, servers SHOULD employ syntax-based normalization (Section 6.2.2 of [RFC3986]) and scheme-based normalization (Section 6.2.3 of [RFC3986]) before comparing the htu claim.
      These checks may be performed in any order.

Es wird empfohlen, die Prüfung einer geeigneten Bibliothek zu überlassen.

Access Token prüfen​

Das Access Token ist vom OAuth-Server signiert. Das JSON Web Key Set (siehe RFC 7517, Sec. 5) mit allen öffentlichen Schlüsseln des OAuth-Servers finden Sie als Datei jwks.json im obersten Verzeichnis des Servers (z.B. https://xbezahldienste-poc.fit-connect.dev/jwks.json). Der Schlüssel aus dem JWKS wird über den Key-ID (kid) Header ausgewählt.

Die Prüfung des Access Tokens wird in RFC 9449, Sec. 6 beschrieben.

Es wird empfohlen, die Prüfung einer geeigneten Bibliothek zu überlassen.

Gültigkeitsdauer der Token​

Bei beiden Token müssen die Grenzen der zeitlichen Gültigkeit "issued at" (iat) und "expires" (exp) kontrolliert werden. Der Wert "issued at" muss in der Vergangenheit liegen, "expires" in der Zukunft. Die Uhren der beteiligten Server müssen über NTP synchronisiert sein. Um Probleme mit trotz dessen unterschiedlichen Serverzeiten zu vermeiden, sollte der Wert "issued at" auch wenige Sekunden in der Zukunft liegen dürfen.

Der Gültigkeitsbereich zwischen "issued at" (iat) und "expires" (exp) muss auf einen sinnvollen Bereich beschränkt werden.

Das Access Token kann und soll für aufeinanderfolgende Zugriffe wiederverwendet werden. Die Dauer des Gültigkeitszeitraumes kontrolliert der OAuth-Server bei der Ausstellung. Üblich ist ein Gültigkeitszeitraum von 30 Minuten.

Das DPoP Proof JWT stellt sich der Onlinedienst selbst aus. Daher muss der Bezahldienst prüfen, dass der Gültigkeitszeitraum nicht zu groß gewählt wurde. Das DPoP Proof JWT wird für jeden Aufruf neu generiert. Daher kann der Gültigkeitszeitraum stark begrenzt werden. Empfohlen wird z.B. ein maximaler Zeitraum von einer Minute, was für einen HTTP-Aufruf mehr als ausreichend sein sollte.

Zugriffsprüfung​

Prüfung des Access Token und DPoP Proof JWT​

Hinweise zur Prüfung des Zugriffs sind in RFC 9449, Sec. 7 beschrieben.

Es wird empfohlen, die Prüfung einer geeigneten Bibliothek zu überlassen.

Berechtigungsprüfung​

Sind die Token korrekt, muss noch geprüft werden, ob die im Access Token angegebenen Scopes den API-Aufruf gestatten.

In der XBezahldienste OpenAPI Spezifikation ist für jeden Endpunkt spezifiziert, welcher Scope erforderlich ist.