Zum Hauptinhalt springen

2. Client-Metadaten

Registrierte Clients verfügen über einen Satz von Metadatenwerten, die ihrer Client-ID auf einem Autorisierungsserver zugeordnet sind, wie z. B. eine Liste gültiger Umleitungs-URIs oder einen Anzeigenamen.

Diese Client-Metadatenwerte werden auf zwei Arten verwendet:

  • als Eingabewerte für Registrierungsanfragen und

  • als Ausgabewerte in Registrierungsantworten.

Die folgenden Client-Metadatenfelder werden durch diese Spezifikation definiert. Die Implementierung und Verwendung aller Client-Metadatenfelder ist OPTIONAL, sofern nicht anders angegeben. Alle Datenelementtypen (Strings, Arrays, Zahlen) werden in Bezug auf ihre JSON [RFC7159] Repräsentationen definiert.

redirect_uris Array von Umleitungs-URI-Strings zur Verwendung in umleitungsbasierten Flows wie dem Authorization Code Flow und dem Implicit Flow. Wie in OAuth 2.0 [RFC6749], Abschnitt 2 gefordert, MÜSSEN Clients, die Flows mit Umleitung verwenden, ihre Umleitungs-URI-Werte registrieren. Autorisierungsserver, die dynamische Registrierung für umleitungsbasierte Flows unterstützen, MÜSSEN die Unterstützung für diesen Metadatenwert implementieren.

token_endpoint_auth_method String-Indikator für die angeforderte Authentifizierungsmethode für den Token-Endpunkt. Werte, die durch diese Spezifikation definiert werden, sind:

  • "none": Der Client ist ein öffentlicher Client gemäß OAuth 2.0 Abschnitt 2.1 und besitzt kein Client-Secret.

  • "client_secret_post": Der Client verwendet die HTTP POST Parameter gemäß OAuth 2.0 Abschnitt 2.3.1.

  • "client_secret_basic": Der Client verwendet HTTP Basic gemäß OAuth 2.0 Abschnitt 2.3.1.

Zusätzliche Werte können über das in Abschnitt 4.2 eingerichtete IANA-Register "OAuth Token Endpoint Authentication Methods" definiert werden. Absolute URIs können auch als Werte für diesen Parameter verwendet werden, ohne registriert zu werden. Wenn nicht angegeben oder weggelassen, ist der Standardwert "client_secret_basic", was das HTTP Basic Authentifizierungsschema gemäß OAuth 2.0 Abschnitt 2.3.1 bezeichnet.

grant_types Array von OAuth 2.0 Granttyp-Strings, die der Client am Token-Endpunkt verwenden kann. Diese Granttypen sind wie folgt definiert:

  • "authorization_code": Der Authorization Code Granttyp definiert in OAuth 2.0, Abschnitt 4.1.

  • "implicit": Der Implicit Granttyp definiert in OAuth 2.0, Abschnitt 4.2.

  • "password": Der Resource Owner Password Credentials Granttyp definiert in OAuth 2.0, Abschnitt 4.3.

  • "client_credentials": Der Client Credentials Granttyp definiert in OAuth 2.0, Abschnitt 4.4.

  • "refresh_token": Der Refresh Token Granttyp definiert in OAuth 2.0, Abschnitt 6.

  • "urn:ietf:params:oauth:grant-type:jwt-bearer": Der JWT Bearer Token Granttyp definiert in OAuth JWT Bearer Token Profiles [RFC7523].

  • "urn:ietf:params:oauth:grant-type:saml2-bearer": Der SAML 2.0 Bearer Assertion Grant definiert in OAuth SAML 2 Bearer Token Profiles [RFC7522].

Wenn der Token-Endpunkt im Granttyp verwendet wird, MUSS der Wert dieses Parameters derselbe sein wie der Wert des "grant_type" Parameters, der an den in der Granttyp-Definition definierten Token-Endpunkt übergeben wird. Autorisierungsserver KÖNNEN andere Werte zulassen, wie im Granttyp-Erweiterungsprozess in OAuth 2.0, Abschnitt 4.5 beschrieben. Wenn weggelassen, ist das Standardverhalten, dass der Client nur den "authorization_code" Granttyp verwendet.

response_types Array von OAuth 2.0 Antworttyp-Strings, die der Client am Autorisierungsendpunkt verwenden kann. Diese Antworttypen sind wie folgt definiert:

  • "code": Der Authorization Code Antworttyp definiert in OAuth 2.0, Abschnitt 4.1.

  • "token": Der Implicit Antworttyp definiert in OAuth 2.0, Abschnitt 4.2.

Wenn der Autorisierungsendpunkt vom Granttyp verwendet wird, MUSS der Wert dieses Parameters derselbe sein wie der Wert des "response_type" Parameters, der an den in der Granttyp-Definition definierten Autorisierungsendpunkt übergeben wird. Autorisierungsserver KÖNNEN andere Werte zulassen, wie im Antworttyp-Erweiterungsprozess in OAuth 2.0, Abschnitt 4.5 beschrieben. Wenn weggelassen, ist der Standardwert, dass der Client nur den "code" Antworttyp verwendet.

client_name Menschenlesbarer String-Name des Clients, der dem Endbenutzer während der Autorisierung präsentiert wird. Wenn weggelassen, KANN der Autorisierungsserver stattdessen den rohen "client_id" Wert dem Endbenutzer anzeigen. Es wird EMPFOHLEN, dass Clients dieses Feld immer senden. Der Wert dieses Feldes KANN internationalisiert werden, wie in Abschnitt 2.2 beschrieben.

client_uri URL-String einer Webseite, die Informationen über den Client bereitstellt. Wenn vorhanden, SOLLTE der Server diese URL dem Endbenutzer in anklickbarer Form anzeigen. Es wird EMPFOHLEN, dass Clients dieses Feld immer senden. Der Wert dieses Feldes MUSS auf eine gültige Webseite verweisen. Der Wert dieses Feldes KANN internationalisiert werden, wie in Abschnitt 2.2 beschrieben.

logo_uri URL-String, der auf ein Logo für den Client verweist. Wenn vorhanden, SOLLTE der Server dieses Bild dem Endbenutzer während der Genehmigung anzeigen. Der Wert dieses Feldes MUSS auf eine gültige Bilddatei verweisen. Der Wert dieses Feldes KANN internationalisiert werden, wie in Abschnitt 2.2 beschrieben.

scope String, der eine durch Leerzeichen getrennte Liste von Scope-Werten enthält (wie in OAuth 2.0 [RFC6749], Abschnitt 3.3 beschrieben), die der Client bei der Anforderung von Zugriffstoken verwenden kann. Die Semantik der Werte in dieser Liste ist dienste-spezifisch. Wenn weggelassen, KANN ein Autorisierungsserver einen Client mit einem Standard-Scope-Satz registrieren.

contacts Array von Strings, die Wege darstellen, um die für diesen Client verantwortlichen Personen zu kontaktieren, typischerweise E-Mail-Adressen. Der Autorisierungsserver KANN diese Kontaktadressen Endbenutzern für Supportanfragen für den Client zur Verfügung stellen. Siehe Abschnitt 6 für Informationen zu Datenschutzüberlegungen.

tos_uri URL-String, der auf ein menschenlesbares Nutzungsbedingungen-Dokument für den Client verweist, das eine vertragliche Beziehung zwischen dem Endbenutzer und dem Client beschreibt, die der Endbenutzer akzeptiert, wenn er den Client autorisiert. Der Autorisierungsserver SOLLTE diese URL dem Endbenutzer anzeigen, wenn sie bereitgestellt wird. Der Wert dieses Feldes MUSS auf eine gültige Webseite verweisen. Der Wert dieses Feldes KANN internationalisiert werden, wie in Abschnitt 2.2 beschrieben.

policy_uri URL-String, der auf ein menschenlesbares Datenschutzrichtlinien-Dokument verweist, das beschreibt, wie die bereitstellende Organisation personenbezogene Daten sammelt, verwendet, speichert und offenlegt. Der Autorisierungsserver SOLLTE diese URL dem Endbenutzer anzeigen, wenn sie bereitgestellt wird. Der Wert dieses Feldes MUSS auf eine gültige Webseite verweisen. Der Wert dieses Feldes KANN internationalisiert werden, wie in Abschnitt 2.2 beschrieben.

jwks_uri URL-String, der auf das JSON Web Key (JWK) Set [RFC7517] Dokument des Clients verweist, das die öffentlichen Schlüssel des Clients enthält. Der Wert dieses Feldes MUSS auf ein gültiges JWK Set Dokument verweisen. Diese Schlüssel können von Protokollen höherer Ebene verwendet werden, die Signierung oder Verschlüsselung nutzen. Zum Beispiel könnten diese Schlüssel von einigen Anwendungen verwendet werden, um signierte Anfragen an den Token-Endpunkt zu validieren, wenn JWTs für die Client-Authentifizierung [RFC7523] verwendet werden. Die Verwendung dieses Parameters wird gegenüber dem "jwks" Parameter bevorzugt, da er eine einfachere Schlüsselrotation ermöglicht. Die Parameter "jwks_uri" und "jwks" DÜRFEN NICHT beide in derselben Anfrage oder Antwort vorhanden sein.

jwks Wert des JSON Web Key Set [RFC7517] Dokuments des Clients, das die öffentlichen Schlüssel des Clients enthält. Der Wert dieses Feldes MUSS ein JSON-Objekt sein, das ein gültiges JWK Set enthält. Diese Schlüssel können von Protokollen höherer Ebene verwendet werden, die Signierung oder Verschlüsselung nutzen. Dieser Parameter ist für Clients gedacht, die den "jwks_uri" Parameter nicht verwenden können, wie z. B. native Clients, die keine öffentlichen URLs hosten können. Die Parameter "jwks_uri" und "jwks" DÜRFEN NICHT beide in derselben Anfrage oder Antwort vorhanden sein.

software_id Ein eindeutiger Identifikator-String (z. B. eine Universally Unique Identifier, UUID), der vom Client-Entwickler oder Software-Herausgeber zugewiesen wird und von Registrierungsendpunkten verwendet wird, um die dynamisch zu registrierende Client-Software zu identifizieren. Im Gegensatz zur "client_id", die vom Autorisierungsserver ausgegeben wird und zwischen Instanzen variieren SOLLTE, SOLLTE die "software_id" für alle Instanzen der Client-Software gleich bleiben. Die "software_id" SOLLTE über mehrere Updates oder Versionen derselben Software hinweg gleich bleiben. Der Wert dieses Feldes ist nicht dazu gedacht, von Menschen gelesen zu werden, und ist für den Client und den Autorisierungsserver normalerweise opak.

software_version Ein Versionsidentifikator-String für die durch "software_id" identifizierte Client-Software. Der Wert der "software_version" SOLLTE sich bei jedem Update der durch dieselbe "software_id" identifizierten Client-Software ändern. Der Wert dieses Feldes ist für den Vergleich mittels exakter String-Übereinstimmung gedacht, und es wird keine andere Vergleichssemantik durch diese Spezifikation definiert. Der Wert dieses Feldes liegt außerhalb des Geltungsbereichs dieser Spezifikation, ist jedoch nicht dazu gedacht, von Menschen gelesen zu werden, und ist für den Client und den Autorisierungsserver normalerweise opak. Die Definition dessen, was ein Update der Client-Software darstellt, das eine Änderung dieses Wertes auslösen würde, ist spezifisch für die Software selbst und liegt außerhalb des Geltungsbereichs dieser Spezifikation.

Erweiterungen und Profile dieser Spezifikation können diese Liste um Metadatennamen und Beschreibungen erweitern, die gemäß den IANA-Überlegungen in Abschnitt 4 dieses Dokuments registriert sind. Der Autorisierungsserver MUSS alle vom Client gesendeten Client-Metadaten ignorieren, die er nicht versteht (z. B. durch stillschweigendes Entfernen der unbekannten Metadaten aus dem Client-Registrierungsdatensatz während der Verarbeitung). Der Autorisierungsserver KANN angeforderte Client-Metadatenwerte ablehnen, indem er die angeforderten Werte durch geeignete Standardwerte ersetzt, wie in Abschnitt 3.2.1 beschrieben, oder indem er eine Fehlerantwort zurückgibt, wie in Abschnitt 3.2.2 beschrieben.

Client-Metadatenwerte können direkt im Körper einer Registrierungsanfrage übermittelt werden, wie in Abschnitt 3.1 beschrieben, oder als Claims in einem Software Statement enthalten sein, wie in Abschnitt 2.3 beschrieben; eine Mischung aus beidem ist ebenfalls möglich. Wenn derselbe Client-Metadatenname an beiden Orten vorhanden ist und dem Software Statement vom Autorisierungsserver vertraut wird, MUSS der Wert eines Claims im Software Statement Vorrang haben.

2.1. Beziehung zwischen Granttypen und Antworttypen​

Die oben beschriebenen Werte für "grant_types" und "response_types" sind teilweise orthogonal, da sie sich auf Argumente beziehen, die an verschiedene Endpunkte im OAuth-Protokoll übergeben werden. Sie sind jedoch insofern verwandt, als die einem Client zur Verfügung stehenden "grant_types" die "response_types" beeinflussen, die der Client verwenden darf, und umgekehrt. Zum Beispiel impliziert ein "grant_types" Wert, der "authorization_code" enthält, einen "response_types" Wert, der "code" enthält, da beide Werte als Teil des OAuth 2.0 Authorization Code Grants definiert sind. Daher SOLLTEN Server, die diese Felder unterstützen, Maßnahmen ergreifen, um sicherzustellen, dass sich ein Client nicht in einen inkonsistenten Zustand registrieren kann, z. B. durch Rückgabe einer "invalid_client_metadata" Fehlerantwort auf eine inkonsistente Registrierungsanfrage.

Die Korrelation zwischen den beiden Feldern ist in der folgenden Tabelle aufgeführt.

grant_types Wert enthält:response_types Wert enthält:
authorization_codecode
implicittoken
password(keine)
client_credentials(keine)
refresh_token(keine)
urn:ietf:params:oauth:grant-type:jwt-bearer(keine)
urn:ietf:params:oauth:grant-type:saml2-bearer(keine)

Erweiterungen und Profile dieses Dokuments, die neue Werte für den Parameter "grant_types" oder "response_types" einführen, MÜSSEN alle Korrespondenzen zwischen diesen beiden Parametertypen dokumentieren.

2.2. Menschenlesbare Client-Metadaten​

Menschenlesbare Client-Metadatenwerte und Client-Metadatenwerte, die auf menschenlesbare Werte verweisen, KÖNNEN in mehreren Sprachen und Skripten dargestellt werden. Zum Beispiel könnten Werte für Felder wie "client_name", "tos_uri", "policy_uri", "logo_uri" und "client_uri" in einigen Client-Registrierungen mehrere länderspezifische Werte haben, um die Verwendung an verschiedenen Orten zu erleichtern.

Um Sprachen und Skripte anzugeben, werden BCP 47 [RFC5646] Sprachtags zu den Client-Metadaten-Mitgliedsnamen hinzugefügt, getrennt durch ein "#" Zeichen. Da JSON [RFC7159] Mitgliedsnamen case-sensitive (groß-/kleinschreibungssensitiv) sind, wird EMPFOHLEN, dass Sprachtagwerte, die in Claim-Namen verwendet werden, mit der Zeichenschreibweise geschrieben werden, mit der sie im "IANA Language Subtag" Register [IANA.Language] registriert sind. Insbesondere werden Sprachnamen normalerweise klein geschrieben, Regionenamen groß geschrieben und Sprachen in gemischter Schreibweise. Da BCP 47 Sprachtagwerte jedoch case-insensitive (groß-/kleinschreibungsunabhängig) sind, SOLLTEN Implementierungen die bereitgestellten Sprachtagwerte case-insensitive interpretieren. Im Einklang mit den Empfehlungen in BCP 47 sollten Sprachtagwerte, die in Metadaten-Mitgliedsnamen verwendet werden, nur so spezifisch wie nötig sein. Zum Beispiel könnte die Verwendung von "fr" in vielen Kontexten ausreichend sein, anstatt "fr-CA" oder "fr-FR".

Zum Beispiel könnte ein Client seinen englischen Namen als "client_name#en": "My Client" und seinen japanischen Namen als "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D" in derselben Registrierungsanfrage darstellen. Der Autorisierungsserver KANN einen oder alle dieser Namen dem Ressourcenbesitzer während des Autorisierungsschritts anzeigen, wobei er basierend auf der Systemkonfiguration, Benutzereinstellungen oder anderen Faktoren auswählt, welcher Name angezeigt wird.

Wenn ein menschenlesbares Feld ohne Sprachtag gesendet wird, DÜRFEN die Parteien, die es verwenden, KEINE Annahmen über die Sprache, den Zeichensatz oder das Skript des String-Wertes treffen, und der String-Wert MUSS so wie er ist verwendet werden, wo immer er in einer Benutzeroberfläche präsentiert wird. Um die Interoperabilität zu fördern, wird EMPFOHLEN, dass Clients und Server zusätzlich zu sprachspezifischen Feldern ein menschenlesbares Feld ohne jegliches Sprachtag verwenden, und es wird EMPFOHLEN, dass jedes menschenlesbare Feld, das ohne Sprachtag gesendet wird, Werte enthält, die für die Anzeige auf einer Vielzahl von Systemen geeignet sind.

Hinweis für Implementierer: Viele JSON-Bibliotheken ermöglichen es, Mitglieder eines JSON-Objekts als Mitglieder eines Objektkonstrukts in der nativen Programmierumgebung der Bibliothek zu referenzieren. Obwohl das "#" Zeichen ein gültiges Zeichen innerhalb von JSON-Objekt-Mitgliedsnamen ist, ist es in vielen Programmierumgebungen kein gültiges Zeichen zur Verwendung in einem Objekt-Mitgliedsnamen. Daher müssen Implementierungen alternative Zugriffsformen verwenden, um auf diese Claims zuzugreifen. Zum Beispiel könnte in JavaScript, wenn JSON wie folgt geparst wird: "var j = JSON.parse(json);", als Workaround auf das Mitglied "client_name#en-us" unter Verwendung der JavaScript-Syntax "j["client_name#en-us"]" zugegriffen werden.

2.3. Software Statement​

Ein Software Statement ist ein JSON Web Token (JWT) [RFC7519], das Metadatenwerte über die Client-Software als Bündel behauptet. Ein Satz von Claims, die in einem Software Statement verwendet werden können, ist in Abschnitt 2 definiert. Wenn es dem Autorisierungsserver als Teil einer Client-Registrierungsanfrage vorgelegt wird, MUSS das Software Statement digital signiert oder mittels JSON Web Signature (JWS) [RFC7515] MAC-gesichert sein und MUSS einen "iss" (Issuer / Aussteller) Claim enthalten, der die Partei angibt, die die Claims im Software Statement attestiert. Es wird EMPFOHLEN, dass Software Statements mit dem "RS256" Signaturalgorithmus digital signiert werden, obwohl bestimmte Anwendungen die Verwendung anderer Algorithmen angeben KÖNNEN. Es wird EMPFOHLEN, dass Software Statements den "software_id" Claim enthalten, um Autorisierungsservern zu ermöglichen, verschiedene Softwareinstanzen zu korrelieren, die dasselbe Software Statement verwenden.

Zum Beispiel könnte ein Software Statement die folgenden Claims enthalten:

  {
   "software_id": "4NRB1-0XZABZI9E6-5SM3R",
   "client_name": "Example Statement-based Client",
   "client_uri": "https://client.example.net/"
  }

Das folgende nicht-normative Beispiel-JWT enthält diese Claims und wurde asymmetrisch mit "RS256" signiert (mit Zeilenumbrüchen nur zu Darstellungszwecken):

  eyJhbGciOiJSUzI1NiJ9.
  eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll
  bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs
  aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ.
  GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa
  zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0
  5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY
  fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk
  U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf
  IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA

Das Software Statement wird typischerweise mit allen Instanzen einer Client-Anwendung verteilt. Die Mittel, mit denen ein Client oder Entwickler ein Software Statement erhält, liegen außerhalb des Geltungsbereichs dieser Spezifikation. Einige gängige Methoden könnten beinhalten, dass ein Client-Entwickler, der ein kundenspezifisches JWT generiert, indem er sich bei einem Software-API-Herausgeber registriert, ein Software Statement für eine Klasse von Clients erhält.

Die Kriterien, nach denen Autorisierungsserver bestimmen, ob sie den Informationen in einem Software Statement vertrauen und diese nutzen, liegen außerhalb des Geltungsbereichs dieser Spezifikation.

In einigen Fällen KÖNNEN Autorisierungsserver wählen, einen Software Statement Wert direkt als Client-ID in einer Autorisierungsanfrage zu akzeptieren, ohne dass zuvor eine dynamische Client-Registrierung durchgeführt wurde. Die Umstände, unter denen ein Autorisierungsserver dies tun würde, und die spezifischen Software Statement Eigenschaften, die in diesem Fall erforderlich wären, liegen außerhalb des Geltungsbereichs dieser Spezifikation.

Letztes Update am