3. Client-Registrierungsendpunkt

Der Client-Registrierungsendpunkt ist ein in diesem Dokument definierter OAuth 2.0 Endpunkt, der es einem Client ermöglichen soll, beim Autorisierungsserver registriert zu werden. Der Client-Registrierungsendpunkt MUSS HTTP POST Nachrichten mit Anfrageparametern akzeptieren, die im Entity-Body im Format "application/json" codiert sind. Der Client-Registrierungsendpunkt MUSS durch einen Transport-Layer-Sicherheitsmechanismus geschützt sein, wie in Abschnitt 5 beschrieben.

Der Client-Registrierungsendpunkt KANN eine geschützte OAuth 2.0 [RFC6749] Ressource sein und er KANN ein initiales Zugriffstoken in Form eines OAuth 2.0 Zugriffstokens akzeptieren, um die Registrierung nur auf zuvor autorisierte Parteien zu beschränken. Die Methode, mit der das initiale Zugriffstoken vom Client oder Entwickler erhalten wird, ist im Allgemeinen out-of-band und liegt außerhalb des Geltungsbereichs dieser Spezifikation. Die Methode, mit der das initiale Zugriffstoken vom Client-Registrierungsendpunkt überprüft und validiert wird, liegt außerhalb des Geltungsbereichs dieser Spezifikation.

Um eine offene Registrierung zu unterstützen und eine breitere Interoperabilität zu ermöglichen, SOLLTE der Client-Registrierungsendpunkt Registrierungsanfragen ohne Autorisierung (d. h. ohne initiales Zugriffstoken in der Anfrage) zulassen. Diese Anfragen KÖNNEN ratenbegrenzt oder anderweitig eingeschränkt werden, um einen Denial-of-Service-Angriff auf den Client-Registrierungsendpunkt zu verhindern.

3.1. Client-Registrierungsanfrage

Dieser Vorgang registriert einen Client beim Autorisierungsserver. Der Autorisierungsserver weist diesem Client einen eindeutigen Client-Identifikator zu, weist optional ein Client-Secret zu und verknüpft die in der Anfrage bereitgestellten Metadaten mit dem ausgegebenen Client-Identifikator. Die Anfrage enthält alle Client-Metadatenparameter, die während der Registrierung für den Client spezifiziert werden. Der Autorisierungsserver KANN Standardwerte für alle in den Client-Metadaten weggelassenen Elemente bereitstellen.

Um sich zu registrieren, sendet der Client oder Entwickler einen HTTP POST an den Client-Registrierungsendpunkt mit einem Content-Type von "application/json". Die HTTP Entity Payload ist ein JSON [RFC7159] Dokument, das aus einem JSON-Objekt und allen angeforderten Client-Metadatenwerten als Top-Level-Mitglieder dieses JSON-Objekts besteht.

Wenn der Server beispielsweise eine offene Registrierung (ohne initiales Zugriffstoken) unterstützt, könnte der Client die folgende Registrierungsanfrage an den Client-Registrierungsendpunkt senden.

Das Folgende ist eine nicht-normative Beispielanfrage, die kein initiales Zugriffstoken verwendet:

POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: server.example.com

{
 "redirect_uris": [
   "https://client.example.org/callback",
   "https://client.example.org/callback2"],
 "client_name": "My Example Client",
 "client_name#ja-Jpan-JP":
    "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D",
 "token_endpoint_auth_method": "client_secret_basic",
 "logo_uri": "https://client.example.org/logo.png",
 "jwks_uri": "https://client.example.org/my_public_keys.jwks",
 "example_extension_parameter": "example_value"
}

Alternativ, wenn der Server eine autorisierte Registrierung unterstützt, wird dem Entwickler oder dem Client ein initiales Zugriffstoken bereitgestellt. (Die Methode, mit der das initiale Zugriffstoken erhalten wird, liegt außerhalb des Geltungsbereichs dieser Spezifikation.) Der Entwickler oder Client sendet die folgende autorisierte Registrierungsanfrage an den Client-Registrierungsendpunkt. Beachten Sie, dass das in diesem Beispiel gesendete initiale Zugriffstoken ein OAuth 2.0 Bearer Token [RFC6750] ist, aber jeder OAuth 2.0 Tokentyp von einem Autorisierungsserver verwendet werden könnte.

Das Folgende ist eine nicht-normative Beispielanfrage, die ein initiales Zugriffstoken verwendet und ein JWK Set per Wert registriert (mit Zeilenumbrüchen innerhalb von Werten nur zu Darstellungszwecken):

POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer ey23f2.adfj230.af32-developer321
Host: server.example.com

{
 "redirect_uris": ["https://client.example.org/callback",
    "https://client.example.org/callback2"],
 "client_name": "My Example Client",
 "client_name#ja-Jpan-JP":
    "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D",
 "token_endpoint_auth_method": "client_secret_basic",
 "policy_uri": "https://client.example.org/policy.html",
 "jwks": {"keys": [{
    "e": "AQAB",
    "n": "nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG
HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk
lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p
RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe
2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve
qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ",
    "kty": "RSA"
 }]},
 "example_extension_parameter": "example_value"
}

3.1.1. Client-Registrierungsanfrage unter Verwendung eines Software Statements

Zusätzlich zu JSON-Elementen KÖNNEN Client-Metadatenwerte auch in einem Software Statement bereitgestellt werden, wie in Abschnitt 2.3 beschrieben. Der Autorisierungsserver KANN das Software Statement ignorieren, wenn er diese Funktion nicht unterstützt. Wenn der Server Software Statements unterstützt, MÜSSEN Client-Metadatenwerte, die im Software Statement übermittelt werden, Vorrang vor denen haben, die unter Verwendung einfacher JSON-Elemente übermittelt werden.

Software Statements werden unter Verwendung dieses OPTIONALEN Mitglieds in das anfordernde JSON-Objekt aufgenommen:

software_statement Ein Software Statement, das Client-Metadatenwerte über die Client-Software als Claims enthält. Dies ist ein String-Wert, der das gesamte signierte JWT enthält.

Im folgenden Beispiel werden einige Registrierungsparameter als Claims in einem Software Statement aus dem Beispiel in Abschnitt 2.3 übermittelt, während einige für die Client-Instanz spezifische Werte als reguläre Parameter übermittelt werden (mit Zeilenumbrüchen innerhalb von Werten nur zu Darstellungszwecken):

POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: server.example.com

{
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "software_statement": "eyJhbGciOiJSUzI1NiJ9.
eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll
bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs
aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ.
GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa
zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0
5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY
fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk
U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf
IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA",
  "scope": "read write",
  "example_extension_parameter": "example_value"
}

3.2. Antworten

Nach einer erfolgreichen Registrierungsanfrage gibt der Autorisierungsserver einen Client-Identifikator für den Client zurück. Der Server antwortet mit einem HTTP 201 Created Statuscode und einem Body vom Typ "application/json" mit Inhalt, wie in Abschnitt 3.2.1 beschrieben.

Nach einer erfolglosen Registrierungsanfrage antwortet der Autorisierungsserver mit einem Fehler, wie in Abschnitt 3.2.2 beschrieben.

3.2.1. Client-Informationsantwort

Die Antwort enthält den Client-Identifikator sowie das Client-Secret, wenn der Client ein vertraulicher Client ist. Die Antwort KANN zusätzliche Felder enthalten, wie durch Erweiterungen dieser Spezifikation festgelegt.

client_id ERFORDERLICH. OAuth 2.0 Client-Identifikator-String. Er SOLLTE derzeit für keinen anderen registrierten Client gültig sein, obwohl ein Autorisierungsserver denselben Client-Identifikator nach eigenem Ermessen an mehrere Instanzen eines registrierten Clients ausgeben KANN.

client_secret OPTIONAL. OAuth 2.0 Client-Secret-String. Wenn ausgegeben, MUSS dies für jede "client_id" eindeutig sein und SOLLTE für mehrere Instanzen eines Clients, der dieselbe "client_id" verwendet, eindeutig sein. Dieser Wert wird von vertraulichen Clients verwendet, um sich beim Token-Endpunkt zu authentifizieren, wie in OAuth 2.0 [RFC6749], Abschnitt 2.3.1 beschrieben.

client_id_issued_at OPTIONAL. Zeitpunkt, zu dem der Client-Identifikator ausgegeben wurde. Die Zeit wird als Anzahl der Sekunden ab 1970-01-01T00:00:00Z, gemessen in UTC, bis zum Datum/Uhrzeit der Ausgabe dargestellt.

client_secret_expires_at ERFORDERLICH, wenn "client_secret" ausgegeben wird. Zeitpunkt, zu dem das Client-Secret abläuft, oder 0, wenn es nicht abläuft. Die Zeit wird als Anzahl der Sekunden ab 1970-01-01T00:00:00Z, gemessen in UTC, bis zum Datum/Uhrzeit des Ablaufs dargestellt.

Zusätzlich MUSS der Autorisierungsserver alle registrierten Metadaten über diesen Client zurückgeben, einschließlich aller vom Autorisierungsserver selbst bereitgestellten Felder. Der Autorisierungsserver KANN beliebige der vom Client während der Registrierung übermittelten angeforderten Metadatenwerte ablehnen oder ersetzen und sie durch geeignete Werte ersetzen. Der Client oder Entwickler kann die Werte in der Antwort überprüfen, um festzustellen, ob die Registrierung für die Verwendung ausreichend ist (z. B. ob die registrierte "token_endpoint_auth_method" von der Client-Software unterstützt wird) und eine für die Client-Software geeignete Vorgehensweise festlegen. Die Reaktion auf eine solche Situation liegt außerhalb des Geltungsbereichs dieser Spezifikation, könnte jedoch das Einreichen eines Berichts beim Anwendungsentwickler oder Autorisierungsserver-Anbieter, den Versuch einer erneuten Registrierung mit anderen Metadatenwerten oder verschiedene andere Methoden beinhalten. Wenn der Server beispielsweise auch einen Registrierungsmanagement-Mechanismus unterstützt, wie er in [RFC7592] definiert ist, könnte der Client oder Entwickler versuchen, die Registrierung mit anderen Metadatenwerten zu aktualisieren. Dieser Prozess könnte auch durch ein Service-Discovery-Protokoll wie [OpenID.Discovery] unterstützt werden, das die Fähigkeiten eines Servers auflisten kann und es einem Client ermöglicht, eine fundiertere Registrierungsanfrage zu stellen. Die Verwendung eines solchen Management- oder Discovery-Systems ist optional und liegt außerhalb des Geltungsbereichs dieser Spezifikation.

Die erfolgreiche Registrierungsantwort verwendet einen HTTP 201 Created Statuscode mit einem Body vom Typ "application/json", der aus einem einzelnen JSON-Objekt [RFC7159] besteht, wobei alle Parameter als Top-Level-Mitglieder des Objekts enthalten sind.

Wenn ein Software Statement als Teil der Registrierung verwendet wurde, MUSS sein Wert in der Antwort zusammen mit anderen Metadaten unter Verwendung des Mitgliedsnamens "software_statement" unverändert zurückgegeben werden. Client-Metadaten-Elemente, die aus dem Software Statement verwendet wurden, MÜSSEN auch direkt als Top-Level-Client-Metadatenwerte in der Registrierungsantwort zurückgegeben werden (möglicherweise mit anderen Werten, da die angeforderten Werte und die verwendeten Werte unterschiedlich sein können).

Das Folgende ist eine nicht-normative Beispielantwort einer erfolgreichen Registrierung:

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
 "client_id": "s6BhdRkqt3",
 "client_secret": "cf136dc3c1fc93f31185e5885805d",
 "client_id_issued_at": 2893256800,
 "client_secret_expires_at": 2893276800,
 "redirect_uris": [
   "https://client.example.org/callback",
   "https://client.example.org/callback2"],
 "grant_types": ["authorization_code", "refresh_token"],
 "client_name": "My Example Client",
 "client_name#ja-Jpan-JP":
    "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D",
 "token_endpoint_auth_method": "client_secret_basic",
 "logo_uri": "https://client.example.org/logo.png",
 "jwks_uri": "https://client.example.org/my_public_keys.jwks",
 "example_extension_parameter": "example_value"
}

3.2.2. Client-Registrierungsfehlerantwort

Wenn eine OAuth 2.0 Fehlerbedingung auftritt, z. B. wenn der Client ein ungültiges initiales Zugriffstoken vorlegt, gibt der Autorisierungsserver eine Fehlerantwort zurück, die dem OAuth 2.0 Tokentyp entspricht.

Wenn eine Registrierungsfehlerbedingung auftritt, gibt der Autorisierungsserver einen HTTP 400 Statuscode (sofern nicht anders angegeben) mit dem Content-Type "application/json" zurück, der aus einem JSON-Objekt [RFC7159] besteht, das den Fehler im Antwort-Body beschreibt.

Zwei Mitglieder sind für die Aufnahme in das JSON-Objekt definiert:

error ERFORDERLICH. Einzelner ASCII-Fehlercodestring.

error_description OPTIONAL. Menschenlesbare ASCII-Textbeschreibung des Fehlers, die zum Debuggen verwendet wird.

Andere Mitglieder KÖNNEN ebenfalls enthalten sein, und wenn sie nicht verstanden werden, MÜSSEN sie ignoriert werden.

Diese Spezifikation definiert die folgenden Fehlercodes:

invalid_redirect_uri Der Wert eines oder mehrerer Umleitungs-URIs ist ungültig.

invalid_client_metadata Der Wert eines der Client-Metadatenfelder ist ungültig und der Server hat diese Anfrage abgelehnt. Beachten Sie, dass ein Autorisierungsserver wählen KANN, einen gültigen Wert für jeden angeforderten Parameter der Metadaten eines Clients zu ersetzen.

invalid_software_statement Das vorgelegte Software Statement ist ungültig.

unapproved_software_statement Das vorgelegte Software Statement ist für die Verwendung durch diesen Autorisierungsserver nicht genehmigt.

Das Folgende ist ein nicht-normatives Beispiel für eine Fehlerantwort, die aus einem Umleitungs-URI resultiert, der vom Autorisierungsserver auf die schwarze Liste gesetzt wurde (mit Zeilenumbrüchen innerhalb von Werten nur zu Darstellungszwecken):

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
 "error": "invalid_redirect_uri",
 "error_description": "The redirection URI
   http://sketchy.example.com is not allowed by this server."
}

Das Folgende ist ein nicht-normatives Beispiel für eine Fehlerantwort, die aus einer inkonsistenten Kombination von "response_types" und "grant_types" Werten resultiert (mit Zeilenumbrüchen innerhalb von Werten nur zu Darstellungszwecken):

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
 "error": "invalid_client_metadata",
 "error_description": "The grant type 'authorization_code' must be
   registered along with the response type 'code' but found only
  'implicit' instead."
}