Zum Hauptinhalt springen

2. Anforderungsparameter "authorization_details"

Der Anforderungsparameter authorization_details enthält in JSON-Notation ein Array von Objekten. Jedes JSON-Objekt enthält die Daten zur Spezifizierung der Autorisierungsanforderungen für einen bestimmten Ressourcentyp. Der Typ der Ressource oder Zugriffsanforderung wird durch das Feld type bestimmt, das wie folgt definiert ist:

type: Ein Bezeichner für den Autorisierungsdetail-Typ als Zeichenkette. Der Wert des type-Feldes bestimmt den zulässigen Inhalt des Objekts, das es enthält. Der Wert ist eindeutig für die beschriebene API im Kontext des AS. Dieses Feld ist ERFORDERLICH (REQUIRED).

Ein authorization_details-Array KANN mehrere Einträge desselben Typs enthalten.

Abbildung 2 zeigt ein authorization_details vom Typ payment_initiation unter Verwendung der oben gezeigten Beispieldaten:

[
  {
    "type": "payment_initiation",
    "actions": [
      "initiate",
      "status",
      "cancel"
    ],
    "locations": [
      "https://example.com/payments"
    ],
    "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
      "iban": "DE02100100109307118603"
    },
    "remittanceInformationUnstructured": "Ref Number Merchant"
  }
]

Abbildung 3 zeigt eine kombinierte Anfrage, die Zugriff auf Kontoinformationen und die Berechtigung zur Initiierung einer Zahlung anfordert:

[
  {
    "type": "account_information",
    "actions": [
      "list_accounts",
      "read_balances",
      "read_transactions"
    ],
    "locations": [
      "https://example.com/accounts"
    ]
  },
  {
    "type": "payment_initiation",
    "actions": [
      "initiate",
      "status",
      "cancel"
    ],
    "locations": [
      "https://example.com/payments"
    ],
    "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
      "iban": "DE02100100109307118603"
    },
    "remittanceInformationUnstructured": "Ref Number Merchant"
  }
]

Die JSON-Objekte mit Typfeldern account_information und payment_initiation repräsentieren die verschiedenen Autorisierungsdetails, die vom AS verwendet werden, um nach Zustimmung zu fragen.

Hinweis: Der AS wird diese Daten anschließend den jeweiligen RSs zur Verfügung stellen (siehe Abschnitt 9).

2.1. Autorisierungsdetail-Typen (Authorization Details Types)​

Der AS kontrolliert die Interpretation des Wertes des type-Parameters sowie die Objektfelder, die der type-Parameter zulässt. Der Wert des type-Parameters ist jedoch in der Regel auch dokumentiert und für die Verwendung durch Entwickler vorgesehen. Es wird EMPFOHLEN (RECOMMENDED), dass API-Designer Typwerte wählen, die ohne Mehrdeutigkeit einfach kopiert werden können. Beispielsweise haben einige Glyphen mehrere Unicode-Codepunkte für dasselbe visuelle Zeichen, und ein Entwickler könnte möglicherweise ein anderes Zeichen eingeben als das vom AS definierte. Mögliche Mittel zur Verringerung potenzieller Verwirrung sind die Beschränkung des Wertes auf ASCII [RFC0020]-Zeichen, die Bereitstellung einer maschinenlesbaren Auflistung von Datentypwerten oder die Anweisung an Entwickler, direkt aus der Dokumentation zu kopieren und einzufügen.

Wenn erwartet wird, dass eine Anwendung oder API auf verschiedenen Servern bereitgestellt wird, wie im Fall eines offenen Standards, wird dem API-Designer EMPFOHLEN (RECOMMENDED), einen kollisionsresistenten Namensraum unter seiner Kontrolle zu verwenden, wie z.B. einen URI, den der API-Designer kontrolliert.

Das folgende Beispiel zeigt, wie eine Implementierung den Namensraum https://scheme.example.org/ nutzen könnte, um kollisionsresistente Typwerte zu gewährleisten:

{
  "type": "https://scheme.example.org/files",
  "locations": [
    "https://example.com/files"
  ],
  "permissions": [
    {
      "path": "/myfiles/A",
      "access": [
        "read"
      ]
    },
    {
      "path": "/myfiles/A/X",
      "access": [
        "read",
        "write"
      ]
    }
  ]
}

2.2. Gemeinsame Datenfelder (Common Data Fields)​

Diese Spezifikation definiert eine Reihe gemeinsamer Datenfelder, die so konzipiert sind, dass sie über verschiedene Arten von APIs hinweg verwendbar sind. Diese Spezifikation erfordert nicht die Verwendung dieser gemeinsamen Felder durch eine API-Definition, sondern stellt sie stattdessen als wiederverwendbare generische Komponenten zur Verfügung, die API-Designer nutzen können. Die zulässigen Werte aller Felder werden durch die geschützte API bestimmt, wie durch einen bestimmten "type"-Wert definiert.

locations: Ein Array von Zeichenketten, die den Standort der Ressource oder des RS darstellen. Diese Zeichenketten sind typischerweise URIs, die den Standort des RS identifizieren. Dieses Feld kann es einem Client ermöglichen, einen bestimmten RS anzugeben, wie in Abschnitt 12 besprochen.

actions: Ein Array von Zeichenketten, die die Arten von Aktionen darstellen, die an der Ressource durchgeführt werden sollen.

datatypes: Ein Array von Zeichenketten, die die Arten von Daten darstellen, die von der Ressource angefordert werden.

identifier: Ein Zeichenketten-Bezeichner, der eine spezifische Ressource angibt, die an der API verfügbar ist.

privileges: Ein Array von Zeichenketten, die die Arten oder Ebenen von Privilegien darstellen, die an der Ressource angefordert werden.

Wenn verschiedene gemeinsame Datenfelder in Kombination verwendet werden, sind die vom Client angeforderten Berechtigungen das Produkt aller Werte. Das Objekt stellt eine Anfrage dar, dass alle im Objekt aufgelisteten actions-Werte an allen im Objekt aufgelisteten locations-Werten für alle im Objekt aufgelisteten datatypes-Werte verwendet werden.

Im folgenden Beispiel fordert der Client Lese- und Schreibzugriff sowohl auf die Kontakte als auch auf die Fotos an, die zu Kunden in einer customer_information-API gehören. Wenn diese Anfrage gewährt wird, würde der Client davon ausgehen, dass er jede Kombination von Rechten verwenden kann, die von der API definiert sind, wie z.B. Lesezugriff auf die Fotos und Schreibzugriff auf die Kontakte.

[
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "read",
      "write"
    ],
    "datatypes": [
      "contacts",
      "photos"
    ]
  }
]

Wenn der Client eine feinere Kontrolle über seinen Zugriff wünscht, kann er mehrere Objekte senden. In diesem Beispiel fordert der Client Lesezugriff auf die Kontakte und Schreibzugriff auf die Fotos im selben API-Endpunkt an. Wenn diese Anfrage gewährt wird, wäre der Client nicht in der Lage, auf die Kontakte zu schreiben.

[
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "read"
    ],
    "datatypes": [
      "contacts"
    ]
  },
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "write"
    ],
    "datatypes": [
      "photos"
    ]
  }
]

Eine API KANN ihre eigenen Erweiterungen definieren, abhängig vom Typ des jeweiligen Autorisierungsobjekts. Es wird erwartet, dass API-Designer eine Kombination aus gemeinsamen Datenfeldern verwenden werden, die in dieser Spezifikation definiert sind, sowie Felder, die spezifisch für die API selbst sind.

Letztes Update am